Install VM extensions by creating extension policies

This document describes how to create VM extension policies, which let you automatically install and manage extensions on a fleet of Compute Engine virtual machines (VMs). By defining a policy, you can ensure that specific extensions are installed and maintained on any VMs that match criteria you specify, such as VM labels.

Before you begin

Required IAM roles

To get the permission that you need to create an extension policy, ask your administrator to grant you the VM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin) IAM role. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the compute.vmExtensionPolicies.create permission, which is required to create an extension policy.

You might also be able to get this permission with custom roles or other predefined roles.

For more information about IAM roles and permissions in Compute Engine, see Compute Engine roles and permissions.

Create a VM extension policy

Use one of the following methods to create a VM extension policy. This policy defines which extensions to install and on which VMs.

Console

  1. In the Google Cloud console, go to the VM extension policies page.

    Go to VM extension policies

  2. Click Create extension policy.
  3. In the Name field, enter a name for the policy.
  4. Optional: In the Description field, enter a description for the policy.
  5. In the Priority field, specify a priority number to resolve conflicts between policies. Lower numbers indicate higher priority. The default value is 1000.
  6. In the Zone list, select the zone where you want to apply this policy.
  7. In the Extensions section, click Add extension and do the following for each extension that you want to install on the target VMs:
    1. From the Extension list, select an extension. See Supported extensions.
    2. From the Version list, specify the version number of the extension. Leave blank to select the latest version.
      • For Ops Agent, you can specify version 2.58.0 or later.
      • For Extension for SAP and Extension for Compute workloads, leave the field blank to select the latest version.
    3. Optional: In the Config file content field, enter configuration parameters for the extension.
  8. In the Target VM instances section, select the VMs for the policy. To select VMs with specific labels, click Add labels and add the key-value pair.
  9. Click Create.

gcloud

To create a VM extension policy and to roll out the policy to VMs in a specific zone, use the gcloud beta compute zone-vm-extension-policies create command:

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
    --zone=ZONE \
    --description="DESCRIPTION" \
    --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
    --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
    --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
    --inclusion-labels=KEY_1=VALUE_1 \
    --priority=PRIORITY

Replace the following:

  • POLICY_NAME: a name for the VM extension policy.
  • ZONE: the zone where this policy applies.
  • DESCRIPTION: an optional description for the policy.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: a comma-separated list of extensions to add to the policy. You must specify at least one extension. Valid values for the extensions are:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension

  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: a comma-separated list of key-value pairs where the key is the extension name and value is the extension version. If you don't specify a version for an extension, VM Extension Manager uses the latest available version and automatically upgrades it when new versions become available.

  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: a comma-separated list of key-value pairs where the key is the extension name and value is the path to the configuration file for that extension. This path is on the VM where you run the gcloud command, not on the VM where you install the extension.

    Alternatively, to provide configuration as inline string, use the --config flag instead of --config-from-file—for example, EXTENSION_NAME_1="CONFIG_1". You can use either --config-from-file or --config, but not both in the same command.

  • KEY_1=VALUE_1: a comma-separated list of key-value pairs that define inclusion labels for a selector. VMs must have all specified labels in a selector to be targeted. If you specify --inclusion-labels multiple times, the policy targets VMs that match any of the provided selectors (logical OR). If you omit this flag, the policy targets all VMs in the specified zone.

  • PRIORITY: an integer from 0 to 65535 that defines the policy's priority. Lower numbers indicate higher priority. The default value is 1000.

    The command fails if a policy with the specified name already exists in the zone.

Example 1

The following command creates a policy named test-extension-policy that installs the ops-agent extension in zone us-central1-f for project test-project. The --config-from-file flag specifies the path to a local file containing a YAML configuration for the Ops Agent.

gcloud beta compute zone-vm-extension-policies create test-extension-policy  \
    --project=test-project \
    --zone=us-central1-f \
    --extensions=ops-agent \
    --config-from-file=ops-agent="/usr/ops-agent-config.yaml"

Example 2

The following command creates a policy named test-extension-policy-2 that installs the ops-agent extension in zone us-central1-f for project test-project on VMs with label env=prod. The policy priority is set to 500, and the --config-from-file flag specifies the path to a local file containing a YAML configuration for the Ops Agent.

 gcloud beta compute zone-vm-extension-policies create test-extension-policy-2  \
    --project=test-project \
    --zone=us-central1-f \
    --extensions=ops-agent \
    --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
    --priority=500 \
    --inclusion-labels=env=prod

What's next