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 Google Cloud project if it's not already enabled.
- Ensure that your VM runs the guest agent version
20241209.01or 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 Google Cloud 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 Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
gcloud init
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .
- 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 .
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
- In the Google Cloud console, go to the VM extension policiespage.
- Click Create extension policy.
- In the Namefield, enter a name for the policy.
- Optional: In the Descriptionfield, enter a description for the policy.
- In the Priorityfield, specify a priority number to resolve conflicts between policies. Lower numbers indicate higher priority. The default value is 1000.
- In the Zonelist, select the zone where you want to apply this policy.
- In the Extensionssection, click Add extensionand do the following for each extension that you want to install on the target VMs:
- From the Extensionlist, select an extension. See Supported extensions .
- From the Versionlist, specify the version number of the extension. Leave
blank to select the latest version.
- For Ops Agent, you can specify version
2.58.0or later. - For Extension for SAP and Extension for Compute workloads, leave the field blank to select the latest version.
- For Ops Agent, you can specify version
- Optional: In the Config file contentfield, enter configuration parameters for the extension.
- In the Target VM instancessection, select the VMs for the policy. To select VMs with specific labels, click Add labelsand add the key-value pair.
- 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 thegcloudcommand, not on the VM where you install the extension.Alternatively, to provide configuration as inline string, use the
--configflag instead of--config-from-file—for example,EXTENSION_NAME_1 =" CONFIG_1 ". You can use either--config-from-fileor--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-labelsmultiple 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
- Learn how to manage VM extensions .
