Managing Custom VM Extensions

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.

WARNING: 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.

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.
  • Your UAA Access Token Value: Follow the procedure in Access the 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. For example, see VM Types in the AWS CPI docs for a list of AWS VM extension options.

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.

    Note: 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.

See the following AWS example:

curl "https://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 }}'

For more information about this command, see Creating a new vm extension in the Ops Manager API documentation.

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:

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"}'

For more information about this command, see Deleting a vm extension in the Ops Manager API docs.

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:

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"]
        }'

Note: You must apply changes in order for the new custom VM extension to take effect. For more information, see Applying Changes to BOSH Director.

For more information about this command, see Configuring resources for a job in the Ops Manager API docs.

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:

curl "https://example.com/api/v0/deployed/vm_extensions" \
    -X GET \
    -H "Authorization: Bearer UAA_ACCESS_TOKEN"

The output lists all your VM extension names and its associated custom properties defined in cloud_properties.

See the following example output:

{
  "vm_extensions": [
    {
      "name": "vm_ext1",
      "cloud_properties": {
        "source_dest_check": false
      }
    },
    {
      "name": "vm_ext2",
      "cloud_properties": {
        "key_name": "operations_keypair"
      }
    }
  ]
}

For more information about this command, see Creating a new VM extension in the Ops Manager API documentation.

Create a pull request or raise an issue on the source for this page in GitHub