Managing custom VM extensions with the Tanzu Operations Manager API

You can use the VMware Tanzu Operations Manager API to manage VM extensions, which allow you to specify IaaS-specific configurations for your VMs such as associated security groups and load balancers. Using the Tanzu Operations Manager API, you can 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 VMware Tanzu Operations Manager product, see Configuring Load Balancing for Tanzu Operations Manager.

Caution If you use custom VM extensions, you might 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 Tanzu Operations Manager API: For more information about the Tanzu Operations Manager API, see Using the Tanzu Operations Manager API.

• Your UAA Access Token Value: Follow the procedure in Access the API in Using the Tanzu Operations Manager API 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.

  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 Managing custom VM extensions in the Tanzu Operations 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 Managing custom VM extensions in the Tanzu Operations 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"]
        }'

You must apply changes in order for the new custom VM extension to take effect.

For more information about this command, see Configuring resources for a job in the Tanzu Operations 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 Tanzu Operations Manager API documentation.