Manage VM extensions by using 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.

VM Extension Manager uses extension policies to manage your VM extensions at scale.For more information, seeAbout VM Extension Manager.This document describes how to view, update, and delete VM extension policies.

IAM roles and permissions

To get the permissions that you need to view, modify, and delete VM extension policies, ask your administrator to grant you the following IAM roles on the project:

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to view, modify, and delete VM extension policies. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to view, modify, and delete VM extension policies:

  • To view extension policies: compute.vmExtensionPolicies.list
  • To view details of an extension policy: compute.vmExtensionPolicies.get
  • To modify extension policies: compute.vmExtensionPolicies.update
  • To delete extension policies: compute.vmExtensionPolicies.delete

You might also be able to get these permissions withcustom roles or otherpredefined roles.

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

View extension policies

You can view a list of VM extension policies in your project, or view thedetails of a specific policy by using the Google Cloud console or theGoogle Cloud CLI.

Console

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

    Go to VM extension policies

    This page lists all the VM extension policies in your project.
  2. To view details of a specific extension policy, click the name of the policy.

gcloud

To view all extension policies in a project, use thegcloud beta compute zone-vm-extension-policies list command:

gcloudbetacomputezone-vm-extension-policieslist\--project=PROJECT_ID\--zone=ZONE\--page-size=PAGE_SIZE

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • ZONE: the name of the zone where you want to list VM extension policies.
  • PAGE_SIZE: the maximum number of results to return per page.

To view details of a specific extension policy, use thegcloud beta compute zone-vm-extension-policies describe command:

gcloudbetacomputezone-vm-extension-policiesdescribePOLICY_NAME\--project=PROJECT_ID\--zone=ZONE

Replace the following:

  • POLICY_NAME: the name of the VM extension policy you want to describe.
  • PROJECT_ID: your Google Cloud project ID.
  • ZONE: the Google Cloud zone where the VM extension policy is located.

Modify extensions by updating a VM extension policy

When you update a policy, VM Extension Manager rolls out the changes toall applicable VMs, typically within one minute. If you modify inclusion labels,extensions might be installed on new VMs or uninstalled from existing VMsbased on whether they match the updated labels.

Console

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

    Go to VM extension policies

  2. Select the policy that you want to update.
  3. ClickEdit.
  4. Modify theDescription,Priority,Extensions, orTarget VM instances.
  5. ClickSave.

gcloud

Use thegcloud beta compute zone-vm-extension-policies update command to modify anexisting VM extension policy. When you update a policy by using gcloud, the request acts as acomplete replacement. Any optional fields you omit revert to their defaultvalues instead of retaining existing values from the modified policy.

To update a VM extension policy, run the following command:

gcloudbetacomputezone-vm-extension-policiesupdatePOLICY_NAME\--zone=ZONE\--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_NUMBER\--description="DESCRIPTION"

Replace the following:

  • POLICY_NAME: a name of the VM extension policy to update.
  • ZONE: the Google Cloud zone where the policy applies.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: the names of the extensions to update. You must specify at least one extension.
  • VERSION_1: the version of the first VM extension.
  • VERSION_2: the version of the second VM extension.

  • 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 isthe extension name and value is the path to the configuration file forthat 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--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 inthe same command.

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

  • PRIORITY_NUMBER: the priority number for the VM extension policy.

  • DESCRIPTION: a description of the VM extension policy.

Uninstall extensions by deleting a VM extension policy

When you delete a policy, VM Extension Manager uninstalls the extensionsfrom any VMs managed by that policy. However, if another active, lower-priority policyapplies to a VM and declares the same extension, the extension remains installedon that VM based on the lower-priority policy.

VM Extension Manager removes extensions from all accessible VMs withinone minute of policy deletion. If a VM is inaccessible because the guest agent isremoved or the VM is deleted, VM Extension Manager skips deletion of the extension.If such a VM becomes available again, VM Extension Manager removes the extensions at that time.

Console

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

    Go to VM extension policies

  2. Select the policy that you want to delete.
  3. ClickDelete.
  4. In the confirmation dialog, clickDelete.

gcloud

Use thegcloud beta compute zone-vm-extension-policies delete command to delete an existing VM extension policy.

gcloudbetacomputezone-vm-extension-policiesdeletePOLICY_NAME\--project=PROJECT_ID\--zone=ZONE

Replace the following:

  • POLICY_NAME: the name of the VM extension policy you want to delete.
  • PROJECT_ID: the ID of your Google Cloud project.
  • ZONE: the Google Cloud zone where the policy is located.

Troubleshoot VM extensions

This section describes how to troubleshoot issues with VM extensions.

Verify that an extension is installed

You can verify that an extension is installed by checking the following on theVM:

  • Connect to the VM and check for runningprocesses.

    The following table lists the process names for each extension:

    Extension nameExtension process name
    google-cloud-sap-extensiongoogle_cloud_sap_agent
    google-cloud-workload-extensiongoogle_cloud_workload_agent
    ops-agentops-agent

    Linux

    psaux|grep'EXTENSION_PROCESS_NAME'
    ReplaceEXTENSION_PROCESS_NAME with the process name of the extension.For example, to check the Ops Agent process, run the following command:
    psaux|grep'ops-agent'

    Windows

    tasklist|findstr"EXTENSION_PROCESS_NAME"
    ReplaceEXTENSION_PROCESS_NAME with the process name of the extension.For example, to check the Ops Agent process, run the following command:
    tasklist|findstr"ops-agent"

    The output of theps command on a Linux VM for the Ops Agent might show anentry similar to the following:

    ..../var/lib/google-guest-agent/931374772276853249/plugins/ops-agent_baddabb3dac3....

  • Enable and review guest agent logs. The guest agentlogs show when an extension is installed and started.

    The following is an example of the output you might see in the guest agent logswhen an Ops Agent extension is installed:

    my-instancegoogle_guest_agent[14972]:Installingplugin"ops-agent",revision"2dfa648c1892da87"my-instancegoogle_guest_agent[14972]:(client.go:181)Sentmessage[[type.googleapis.com/agent_controlplane.PluginEventMessage:(revision_id:"2dfa648c1892da87)]]my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "DownloadPluginStep" on plugin "ops-agent_2dfa648c1892da87"my-instance google_guest_agent [14972]: (pluginengine.go:316) Successfully downloaded "https://storage.googleapis.com/acp-gcs-bucket-us-centrall-a/ops-agentmy-instancegoogle_guest_agent[14972]:(pluginengine.go:202)Running"UnpackPluginArchiveStep"onplugin"ops-agent_2dfa648c1892da87"my-instancegoogle_guest_agent[14972]:(pluginengine.go:361)Successfullyunpacked"/var/lib/google-guest-agent/ops-agent.tar.gz"to"/google-guest-agent/ops-agent_2dfa648c1892da87my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "LaunchPluginStep" on plugin "ops-agent_2dfa648c1892da87"my-instance google_guest_agent [14972]: (run_linux.go:32) Attempting process start: (OutputType:0 Name:/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87)my-instance google_guest_agent [14972]: (pluginlauncher.go:132) Launched a plugin process from "/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87"my-instance google_guest_agent [14972]: (plugin.go:136) Dialing in on plugin "ops-agent2dfa648c1892da87"my-instance google_guest_agent [14972]: (plugin.go:51) Executing start request on plugin "ops-agent_2dfa648c1892da87"

Troubleshoot installation issues

If an extension isn't installed on a VM after you create a policy, use thefollowing steps to troubleshoot the issue:

  1. Wait for policy enforcement. It can take up to an hour for a policy to beapplied, including any retries.
  2. Check that the inclusion labels specified in the policy match the labels onthe VM.
  3. To identify potential installation errors,enable debug logging for theguest agent.

  4. After you fix the underlying issue, retry the installation by using one ofthe following methods:

    • Recreate the policy:Delete the policy and thencreate a new policy.

    • Use a temporary high-priority policy: If you want to avoid recreating apolicy that affects many VMs, use a temporary, higher-priority policy toretry the installation on specific VMs:

      1. Add a new label to the VMs for which the installation failed. For example, add a labelstatus=failed.
      2. Create a policy with a higher priority that targets the new label.For example, if the original policy that failed had the default priority of1000,create a policy with a higher priority, such as500.
        gcloudbetacomputezone-vm-extension-policiescreatetemp-policy
        --project=test-project
        --zone=us-central1-f
        --extensions=ops-agent
        --config-from-file=ops-agent="/usr/ops-agent-config.yaml"
        --priority=500
        --inclusion-labels=status=failed
      3. After the extension is installed successfully, delete the temporarypolicy andremove the label from the VMs.The extension remains installed because the original policy is still active.

View debug logs for the guest agent

To enable debug logging, add log level and verbosity settings to theCore section of the guestagent configuration file as follows:

Linux

  1. Open the guest agent configuration file located at/etc/default/instance_configs.cfg.

  2. Add the following lines to the file. If the[Core] section alreadyexists, add thelog_level andlog_verbosity settings to it.

    [Core]log_level = 4log_verbosity = 4

  3. Restart the guest agent manager by running the following command:

    sudosystemctlrestartgoogle-guest-agent-manager

  4. To view logs for guest agent activity during extension installation, runthe following command:

    journalctl-ugoogle-guest-agent-manager

Windows

  1. Open the guest agent configuration file located atC:\ProgramFiles\Google\Compute Engine\instance_configs.cfg.

  2. Add the following lines to the file. If the[Core] section alreadyexists, add thelog_level andlog_verbosity settings to it.

    [Core]log_level = 4log_verbosity = 4

  3. Restart the guest agent manager by running the following command as Windows administrator:

     net stop GCEAgentManager net start GCEAgentManager

  4. To view logs for guest agent activity during extension installation, runthe following command in PowerShell:

    Get-Eventlog-Sourcegoogle_guest_agent_manager-LogNameApplication

After enabling debug logs, check for the following common errors:

  • Not enough disk space: If the logs report insufficient disk space, freeup space on the disk or resize the disk to add more space.
  • Excessive resource usage: If the logs indicate the guest agent stopped the extension due to excessive memory or CPU usage, change the VM's machine type to one with more resources.

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 2025-12-15 UTC.