This repository has been archived by the owner on May 11, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 101
/
migrating.html.md.erb
310 lines (267 loc) · 11 KB
/
migrating.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
---
title: Migrating from cf-release to cf-deployment on AWS
owner: Release Integration
---
This topic describes how to migrate your Cloud Foundry deployment
from `cf-release` to `cf-deployment` on AWS.
The procedures in this topic are specific to Amazon Web Services (AWS).
<p class="note warning"><strong>IMPORTANT</strong>: <code>cf-release</code> has been replaced by <code>cf-deployment</code> and moved to the <a href="https://github.com/cloudfoundry-attic/cf-release">Cloud Foundry attic</a>.
For more information, see <a href="./cf-release-eol.html">cf-release End of Life</a>.</p>
## <a id='prerequisites'></a> Migration Prerequisites
For a list of the current prerequisites, see [Migration Prerequisites](https://github.com/cloudfoundry/cf-deployment-transition/blob/master/README.md#prerequisites) in GitHub.
## <a id='configure-cli'></a> Step 1: Configure the BOSH CLI v2+
Perform the following steps:
1. Set your BOSH Director address, username, and password as environment variables:
<pre class="terminal">
$ export BOSH\_ENVIRONMENT=YOUR-DIRECTOR-ADDRESS
$ export BOSH\_CLIENT=YOUR-DIRECTOR-USERNAME
$ export BOSH\_CLIENT\_SECRET=YOUR-DIRECTOR-PASSWORD
</pre>
1. Confirm that your BOSH CLI is logged in and working:
<pre class="terminal">
$ bosh deployments
Using environment 'bosh.example.com' as client 'admin'
<br>
Name Release(s) Stemcell(s) Team(s) Cloud Config
cf cf/268 bosh-aws-xen-hvm-ubuntu-trusty-go\_agent/3421.11 - none
cf-diego garden-runc/1.9.0 bosh-aws-xen-hvm-ubuntu-trusty-go\_agent/3421.11 - none
grootfs/0.21.0
cf-networking/1.2.0
cflinuxfs3/1.138.0
diego/1.23.0
cf/268
</pre>
1. Set your Cloud Foundry deployment name as an environment variable:
<pre class="terminal">
$ export BOSH\_DEPLOYMENT=YOUR-CF-DEPLOYMENT-NAME
</pre>
1. If your BOSH Director is configured with a self-signed certificate,
perform the following steps to provide that certificate to the BOSH CLI.
1. Extract the necessary certificate
from your BOSH Director deployment manifest:
<pre class="terminal">
$ bosh interpolate \
--path=/properties/director/ssl/cert PATH-TO-YOUR-BOSH-DIRECTOR-MANIFEST > /tmp/bosh-CA.crt
</pre>
1. Configure the BOSH CLI to use the extracted certificate:
<pre class="terminal">
$ export BOSH\_CA\_CERT=/tmp/bosh-CA.crt
</pre>
## <a id='var-store-file'></a> Step 2: Build Variables Store File
You must build a variables store file from your Cloud Foundry and Diego manifests.
This file contains information that provides environment-specific or sensitive configuration
that the BOSH CLI reads and writes to. The operator uses this file when deploying Cloud Foundry
with `cf-deployment`.
Perform the following steps to build your variables store file:
1. Download your Cloud Foundry and Diego manifests from your existing `cf-release`-based deployments:
<pre class="terminal">
$ bosh download-manifest > /tmp/cf-manifest.yml
$ bosh download-manifest -d YOUR-DIEGO-DEPLOYMENT-NAME > /tmp/diego-manifest.yml
</pre>
1. Visit the [cf-deployment-transition](https://github.com/cloudfoundry/cf-deployment-transition/blob/master/README.md) GitHub repository
and use the `extract-vars-store-from-manifests.sh` script
to generate `deployment-vars.yml`.
## <a id='scale'></a> Step 3: Write Scaling Ops File
To perform a successful migration, you must ensure that your `cf-deployment` manifest
deploys components at a scale equivalent to your existing Cloud Foundry and Diego deployments.
### <a id='understand-name-changes'></a> Understand Name Changes
`cf-deployment` renames or combines some jobs in `cf-release`-based manifests.
`cf-release` had a copy of each job for each Availability Zone (AZ),
because historically,
BOSH was unaware of AZs.
`cf-deployment` no longer needs this workaround
thanks to first-class support of AZs in BOSH.
This means that several instance groups have been combined,
which has implications for scaling.
For instance, the `diego-cell` instance group replaces
both the `cell_z1` and the `cell_z2` instance groups
in your existing Diego deployment.
If you currently have 6 instances each of `cell_z1` and `cell_z2`,
you will need 12 instances of `diego-cell`,
which is configured to use both AZ1 and AZ2.
The BOSH Director will automatically
balance these instances between the AZs.
For a list of all job name changes from `cf-release`,
see the `cfr-to-cfd.yml` ops file
in the [cf-deployment-transition](https://github.com/cloudfoundry/cf-deployment-transition/blob/master/cfr-to-cfd.yml) GitHub repository.
This file does not list name changes from the Diego deployment.
However, the only job from the Diego deployment that you must scale is `diego-cells`.
### <a id='write-ops-file'></a> Write Ops File
To scale the components in `cf-deployment`, write an ops file.
An ops file is a YAML file that specifies operations to perform on the deployment manifest,
which you provide to the BOSH CLI when deploying Cloud Foundry in the following section.
The following example ops file scales to 12 instances of the `diego-cell`:
```yaml
---
- type: replace
path: /instance_groups/name=diego-cell/instances
value: 12
```
## <a id='cloud-config'></a> Step 4: Write and Upload Cloud Config
You must write a cloud config to provide certain properties for `cf-deployment`, and upload it to your BOSH Director.
Perform the following steps:
1. Write a cloud config, drawing its values from your current Cloud Foundry and Diego manifests. Use the following example as the basis for your cloud config:
```yaml
compilation:
az: z1
network: private
reuse_compilation_vms: true
vm_extensions:
- 100GB_ephemeral_disk
vm_type: c3.large
workers: 6
disk_types:
- name: 5GB
cloud_properties:
encrypted: true
type: gp2
disk_size: 5120
- name: 10GB
cloud_properties:
encrypted: true
type: gp2
disk_size: 10240
- name: 100GB
cloud_properties:
encrypted: true
type: gp2
disk_size: 102400
vm_types:
- name: t2.small
cloud_properties:
ephemeral_disk:
size: 10240
type: gp2
instance_type: t2.small
- name: c3.large
cloud_properties:
ephemeral_disk:
size: 10240
type: gp2
instance_type: c3.large
- name: m3.medium
cloud_properties:
ephemeral_disk:
size: 10240
type: gp2
instance_type: m3.medium
- name: m3.large
cloud_properties:
ephemeral_disk:
size: 10240
type: gp2
instance_type: m3.large
- name: r3.xlarge
cloud_properties:
ephemeral_disk:
size: 10240
type: gp2
instance_type: r3.xlarge
vm_extensions:
- name: 50GB_ephemeral_disk
cloud_properties:
ephemeral_disk:
size: 102400
type: gp2
- name: 100GB_ephemeral_disk
cloud_properties:
ephemeral_disk:
size: 512000
type: gp2
- name: cf-router-network-properties
cloud_properties:
elbs:
- ELB-NAME-FROM-ROUTER-RESOURCE-POOL
- name: diego-ssh-proxy-network-properties
cloud_properties:
elbs:
- ELB-NAME-FROM-DIEGO-MANIFEST-ACCESS-RESOURCE-POOL
azs:
- name: z1
cloud_properties:
availability_zone: AVAILABILITY-ZONE-FROM-LARGE-Z1-RESOURCE-POOL
- name: z1
cloud_properties:
availability_zone: AVAILABILITY-ZONE-FROM-LARGE-Z2-RESOURCE-POOL
- name: z3
cloud_properties:
availability_zone: AVAILABILITY-ZONE-FROM-LARGE-Z3-RESOURCE-POOL
networks:
- name: default
subnets:
- az: z1
cloud_properties:
security_groups:
- SECURITY-GROUP-FROM-AZ1-NETWORK
subnet: SUBNET-FROM-AZ1-NETWORK
gateway: GATEWAY-IP-FROM-AZ1-NETWORK
range: RANGE-FROM-AZ1-NETWORK
reserved:
- RESERVED-IPS-FROM-AZ1-NETWORK
static:
- STATIC-IPS-FROM-AZ1-NETWORK
- az: z2
cloud_properties:
security_groups:
- SECURITY-GROUP-FROM-AZ2-NETWORK
subnet: SUBNET-FROM-AZ2-NETWORK
gateway: GATEWAY-IP-FROM-AZ2-NETWORK
range: RANGE-FROM-AZ2-NETWORK
reserved:
- RESERVED-IPS-FROM-AZ2-NETWORK
static:
- STATIC-IPS-FROM-AZ2-NETWORK
- az: z3
cloud_properties:
security_groups:
- SECURITY-GROUP-FROM-AZ3-NETWORK
subnet: SUBNET-FROM-AZ3-NETWORK
gateway: GATEWAY-IP-FROM-AZ3-NETWORK
range: RANGE-FROM-AZ3-NETWORK
reserved:
- RESERVED-IPS-FROM-AZ3-NETWORK
static:
- STATIC-IPS-FROM-AZ3-NETWORK
type: manual
```
<br><br>
Keep in mind the following about the above example:
* Unless otherwise noted,
all values come from the Cloud Foundry manifest.
* You must include compilation configuration.
* You must include at least the VM types
and extensions from the example.
* You must have a network called `default`.
* You must configure AZs
`z1`, `z2`, and `z3`.
* This example assumes that your network setup
allows your Elastic Load Balancers (ELBs) to talk to your deployment
without additional security groups.
If not, you must add an array of `security_groups`
to the `cf-router-network-properties` and
`diego-ssh-proxy-network-properties`
`vm_extensions`.
1. Upload your cloud config to the BOSH Director:
<pre class="terminal">
$ bosh update-cloud-config PATH-TO-YOUR-CLOUD-CONFIG
</pre>
## <a id='deploy-cf'></a> Step 5: Deploy Cloud Foundry
Perform all the steps in the [Deploying Cloud Foundry](./cf-deployment/deploy-cf.html) topic. Keep in mind the following when deploying Cloud Foundry in [Step 5: Deploy](./cf-deployment/deploy-cf.html#deploy):
* You must apply the ops file for scaling your components that you created in the previous step.
* You must apply the `cfr-to-cfd.yml` ops file.
Download this ops file from the [cf-deployment-transition](https://github.com/cloudfoundry/cf-deployment-transition/blob/master/cfr-to-cfd.yml) GitHub repository.
If you are disabling `cf-deployment` features to simplify the transition,
you must also apply the appropriate ops files from the transition repository.
* The `deployment-vars.yml` file you pass with the `--vars-store` flag must be the variables store file you created above.
## <a id='delete-diego'></a> Step 6: Delete Old Diego Deployment
Delete your Diego deployment by running the following command:
<pre class="terminal">
$ bosh -d YOUR-DIEGO-DEPLOYMENT-NAME delete-deployment
</pre>
This command may take several minutes, because each Diego cell must drain its contents to the new `cf-deployment` cells.
## <a id='cleanup'></a> Step 7: (Optional) Clean Up
To delete any unused releases and stemcells from your BOSH Director,
including `cf-release`, run the following command:
<pre class="terminal">
$ bosh clean-up --all
</pre>