Install VM extensions by creating extension policies

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This document describes how to create VM extension policies, which let youautomatically install and manage extensions on a fleet of Compute Engine virtualmachines (VMs). By defining a policy, you can ensure that specificextensions are installed and maintained on any VMs that match criteria youspecify, 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 theVM Extension Policy Admin (roles/compute.vmExtensionPolicyAdmin) IAM role. For more information about granting roles, seeManage 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 withcustom roles or otherpredefined roles.

For more information about IAM roles and permissions inCompute Engine, seeCompute Engine roles and permissions.

Policy priority and conflict resolution

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

When two policies conflict for the same extension, the policy with the higherpriority takes precedence. Priority values range from 0 to 65535, where a lowernumber signifies a higher priority. The default priority is 1000. If multiplepolicies have the same priority, VM Extension Manager applies the mostrecently updated policy to the VMs. Deleting a policy does not remove the extension if alower-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 acrossmultiple 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 createspolicies in each zone based on the rollout plan. These policiesthen manage extension installation on VMs within their respective zones.

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

About rollout plans

Global VM extension policies use rollout plans to manage the deployment ofextensions across different locations. You can use one of the predefined rolloutplans 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 therolloutPlans.insert method.For example, the following JSON defines a rollout plan namedtest-rollout-planthat 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 whencreating a global policy, as shown in Example 2.

Create a global policy

Use thegcloud beta compute global-vm-extension-policies create commandto create a global VM extension policy:

gcloudbetacomputeglobal-vm-extension-policiescreatePOLICY_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:

Create a zonal VM extension policy

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

Console

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

    Go to VM extension policies

  2. ClickCreate extension policy.
  3. In theName field, enter a name for the policy.
  4. Optional: In theDescription field, enter a description for the policy.
  5. In thePriority field, specify a priority number to resolve conflictsbetween policies. Lower numbers indicate higher priority. The default value is 1000.
  6. In theZone list, select the zone where you want to apply this policy.
  7. In theExtensions section, clickAdd extension and do the following for each extension that you want to install on the target VMs:
    1. From theExtension list, select an extension. SeeSupported extensions.
    2. From theVersion list, specify the version number of the extension. Leaveblank to select the latest version.
      • For Ops Agent, you can specify version2.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 theConfig file content field, enter configurationparameters for the extension.
  8. In theTarget VM instances section, select the VMs for the policy. Toselect VMs with specific labels, clickAdd labels and add the key-value pair.
  9. ClickCreate.

gcloud

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

gcloudbetacomputezone-vm-extension-policiescreatePOLICY_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:

Example 1

The following command creates a policy namedtest-extension-policy that installstheops-agent extension in zoneus-central1-f for projecttest-project.The--config-from-file flag specifies the path to a local file containing a YAMLconfiguration for the Ops Agent.

gcloudbetacomputezone-vm-extension-policiescreatetest-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 namedtest-extension-policy-2 thatinstalls theops-agent extension in zoneus-central1-f for projecttest-project on VMs with labelenv=prod. The policy priority is set to500, and the--config-from-file flag specifies the path to a local filecontaining a YAML configuration for the Ops Agent.

gcloudbetacomputezone-vm-extension-policiescreatetest-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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-12 UTC.