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

• Install the beta component by running the following command:

       gcloud components install beta
     

• Review the basics about VM Extension Manager.
• Review VM Extension Manager quotas.
• Enable the Compute Engine API in your Cloud de Confiance by S3NS project if it's not already enabled.

  Enable Compute Engine API

• Ensure that your VM runs the guest agent version 20241209.01 or later.
• To view debug logs for VM Extension Manager events, configure the log settings for the guest agent.
• If you haven't already, set up authentication. Authentication verifies your identity for access to Cloud de Confiance by S3NS services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Cloud de Confiance console to access Cloud de Confiance by S3NS services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity. After signing in, initialize the Google Cloud CLI by running the following command:

     gcloud init

  2. Set a default region and zone.

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.

Policy priority and conflict resolution

When multiple policies apply to the same VM, VM Extension Manager uses policy priority to resolve conflicts.

When two policies conflict for the same extension, the policy with the higher priority takes precedence. Priority values range from 0 to 65535, where a lower number signifies a higher priority. The default priority is 1000. If multiple policies have the same priority, VM Extension Manager applies the most recently updated policy to the VMs. Deleting a policy does not remove the extension if a lower-priority policy still applies to the VM.

Create a global VM extension policy

You can create a global VM extension policy to install extensions on VMs across multiple zones within your project according to a rollout plan. A global VM extension policy isn't directly applied to VMs; instead, as the policy rolls out, VM Extension Manager creates policies in each zone based on the rollout plan. These policies then manage extension installation on VMs within their respective zones.

You can either use the gcloud or the globalVmExtensionPolicies.insert method to create global extension policies.

About rollout plans

Global VM extension policies use rollout plans to manage the deployment of extensions across different locations. You can use one of the predefined rollout plans or create a custom rollout plan.

Predefined rollout plans

• slow_rollout: Rolls out the policy over five days. Slow rollout is the default rollout plan.
• fast_rollout: Rolls out the policy immediately to all zones.

Custom rollout plans

You can create custom rollout plans by using the rolloutPlans.insert method. For example, the following JSON defines a rollout plan named test-rollout-plan that targets two zones:

{
  "name": "test-rollout-plan",
  "waves": [
    {
      "selectors": [
        {
          "locationSelector": {
            "includedLocations": [
              "us-central1-a",
              "us-west1-a"
            ]
          }
        }
      ],
      "validation": {
        "type": "time",
        "timeBasedValidationMetadata": {
          "waitDuration": "0s"
        }
      },
      "orchestrationOptions": {
        "maxConcurrentResourcesPerLocation": "10",
        "maxConcurrentLocations": "10"
      }
    }
  ]
}

You can then use this custom rollout plan when creating a global policy, as shown in Example 2.

Create a global policy

Use the gcloud beta compute global-vm-extension-policies create command to create a global VM extension policy:

  gcloud beta compute global-vm-extension-policies create POLICY_NAME 

      --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 

      --rollout-predefined-plan=ROLLOUT_PLAN 

      --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR
  

Replace the following:

• POLICY_NAME: a name for the VM extension policy.
• 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 file is located on the VM where you run the gcloud command, not on the VM where you install the extension.

  Alternatively, to provide the configuration as an 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 your project across all zones.

• PRIORITY: an integer that defines the policy's priority. Larger numbers indicate higher priority. The default value is 0. If multiple policies have the same priority, the policy that was most recently updated is applied to the VMs.

• ROLLOUT_PLAN: specify slow_rollout or fast_rollout. If you need to use a custom rollout plan, use the --rollout-custom-plan flag instead of --rollout-predefined-plan and specify the plan name, for example:

    --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME
  

  Replace the following:

  • PROJECT_NUMBER: The project where the rollout plan is defined.
  • ROLLOUT_PLAN_NAME: The name of the custom rollout plan you defined. If no rollout plan flag is specified, slow_rollout is used.

• ROLLOUT_CONFLICT_BEHAVIOR: Specifies the behavior when a conflict is detected between a zonal and a global policy. Possible values are:

  • "" (empty string): The zonal policy value is used.

  • overwrite: The global policy overwrites the zonal policy.

    For more details, see the --rollout-conflict-behavior flag.

  Example 1

  The following command creates a policy named global-test-extension-policy that installs the ops-agent extension for project test-project. The --config-from-file flag specifies the path to a local file containing a YAML configuration for the Ops Agent, and --rollout-predefined-plan specifies the slow_rollout plan.

  gcloud beta compute global-vm-extension-policies create global-test-extension-policy \
      --project=test-project \
      --extensions=ops-agent \
      --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
      --rollout-predefined-plan=slow_rollout

  Example 2

  The following command creates a policy named global-test-extension-policy-2 that installs the ops-agent extension 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. The --rollout-custom-plan flag specifies a custom rollout plan.

   gcloud beta compute global-vm-extension-policies create global-test-extension-policy-2 \
      --project=test-project \
      --extensions=ops-agent \
      --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
      --priority=500 \
      --inclusion-labels=env=prod \
      --rollout-custom-plan=projects/12345678/locations/global/rolloutPlans/test-rollout-plan

Create a zonal VM extension policy

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

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

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"

 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

• Learn how to manage VM extensions.