-
Notifications
You must be signed in to change notification settings - Fork 140
/
custom-vm-extensions.html.md.erb
127 lines (93 loc) · 6.45 KB
/
custom-vm-extensions.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
---
title: Managing Custom VM Extensions
owner: Ops Manager
---
This topic describes how to add, delete, apply, and list custom VM extensions using the Ops Manager API.
VM extensions allow you to specify IaaS-specific configurations for your VMs such as associated security groups and load balancers. You can use the Ops Manager API to create custom VM extensions, give them names, and associate those names with BOSH jobs.
The **Resource Config** pane in a product tile lets you configure some IaaS-specific load balancing and security properties, and creates VM extensions to support them. For examples from the <%= vars.platform_name %> product, see [Configuring Load Balancing for <%= vars.platform_name %>](./configure-lb.html).
<p class="note warning"><strong>WARNING</strong>: If you use custom VM extensions, you may override other settings. For example, if you use a custom VM extension to add tags, the default tags are removed from all instance groups. To use default tags with custom VM extensions, apply the tags manually.</p>
## <a id="prerequisites"></a> Prerequisites
To manage custom VM extensions, you need the following:
- **Access to the Ops Manager API:** For more information about the Ops Manager API, see [Using the Ops Manager API](ops-man-api.html).
- **Your UAA Access Token Value:** Follow the procedure in [Access the API](ops-man-api.html#access-api) in the _Using the Ops Manager API_ topic to retrieve your access token. In each example, replace `UAA_ACCESS_TOKEN` with the value of your access token.
- **Knowledge of your IaaS-specific configurations:** To find configurations you can set for custom VM extensions, see the _VM Types_ section of your IaaS CPI in the [BOSH documentation](http://bosh.io/docs). For example, see [VM Types](http://bosh.io/docs/aws-cpi.html#resource-pools) in the AWS CPI docs for a list of AWS VM extension options.
## <a id="create-vm-extension"></a> Create or Update a VM Extension
From the `/api/v0/staged/vm_extensions/NAME` endpoint, use `PUT` to enter your custom VM extension. Replace `NAME` in the endpoint with the name of the VM extension.
Enter the following properties:
- `name`: Enter a memorable string value as the name of your new VM extension. You later associate this name to a job.
- `cloud_properties`: Enter your IaaS-specific VM extension properties.
<p class="note"><strong>Note: </strong> If you are updating a custom VM extension rather than creating a new one, enter the name of the VM extension you want to override.</strong></p>
See the following AWS example:
<pre class="terminal">
curl "http<span>s</span>://example.com/api/v0/staged/vm_extensions/example_vm_extension_name" \
-X PUT \
-H "Authorization: Bearer UAA\_ACCESS\_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "example\_vm\_extension\_name", "cloud\_properties": { "source\_dest_check": false }}'
</pre>
For more information about this command, see [Creating a new vm extension](https://docs.pivotal.io/platform/<%= vars.current_major_version.sub('.', '-') %>/opsman-api#creating-a-new-vm-extension) in the Ops Manager API documentation.
## <a id="delete-vm-extension"></a> Delete a VM Extension
From the `/api/v0/staged/vm_extensions/NAME` endpoint, use `DELETE` to delete a custom VM extension by `name`. Replace `NAME` in the API endpoint with the name of the VM extension.
See the following example:
<pre class="terminal">
curl "https://example.com/api/v0/staged/vm_extensions/vm_ext1" \
-X DELETE \
-H "Authorization: Bearer UAA_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "vm_ext1"}'
</pre>
For more information about this command, see [Deleting a vm extension](https://docs.pivotal.io/platform/<%= vars.current_major_version.sub('.', '-') %>/opsman-api/#deleting-a-vm-extension) in the Ops Manager API docs.
## <a id="apply-vm-extensions"></a> Apply VM Extensions to a Job
From the `/api/v0/staged/products/PRODUCT_GUID/jobs/JOB_GUID/resource_config` endpoint use `PUT` to configure a job with the names of your VM extensions.
For the API endpoint, replace `PRODUCT_GUID` with the Globally Unique Identifier (GUID) of your job. You can find this value by requesting `GET /api/v0/deployed/products`. Also replace `JOB_GUID` with the GUID of your job. You can find this value by requesting `GET /api/v0/staged/products/PRODUCT_GUID/jobs`.
For the `additional_vm_extensions` property, list the names of each of the custom VM extensions you want to associate with that job.
See the following GCP example:
<pre class="terminal">
curl "https://example.com/api/v0/staged/products/product-type1-guid/jobs/example-job-guid/resource_config" \
-X PUT \
-H "Authorization: Bearer UAA_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"instances": 1,
"instance_type": {
"id": "automatic"
},
"persistent_disk": {
"size_mb": "20480"
},
"internet_connected": true,
"elb_names": ["tcp:load_balancer_1", "http:load_balancer_2"],
"additional_vm_extensions": ["vm_ext_setting_automatic_restart", "vm_ext_setting_on_host_maintenance"]
}'
</pre>
<p class="note"><strong>Note:</strong> You must apply changes in order for the new custom VM extension to take effect.</p>
For more information about this command, see [Configuring resources for a job](https://docs.pivotal.io/platform/<%= vars.current_major_version.sub('.', '-') %>/opsman-api/#configuring-resources-for-a-job) in the Ops Manager API docs.
## <a id="deployed-vm-extensions"></a> See Deployed VM Extensions
From the `/api/v0/deployed/vm_extensions` endpoint, use `GET` to see your applied custom VM extensions.
See the following example command:
<pre class="terminal">
curl "https://example.com/api/v0/deployed/vm_extensions" \
-X GET \
-H "Authorization: Bearer UAA_ACCESS_TOKEN"
</pre>
The output lists all your VM extension names and its associated custom properties defined in `cloud_properties`.
See the following example output:
<pre class="terminal">
{
"vm_extensions": [
{
"name": "vm_ext1",
"cloud_properties": {
"source_dest_check": false
}
},
{
"name": "vm_ext2",
"cloud_properties": {
"key_name": "operations_keypair"
}
}
]
}
</pre>
For more information about this command, see [Creating a new VM extension](https://docs.pivotal.io/platform/<%= vars.current_major_version.sub('.', '-') %>/opsman-api#creating-a-new-vm-extension) in the Ops Manager API documentation.