Console
Start free

Install and manage the Ops Agent by using VM Extension Manager policies

You can install and manage the Ops Agent on a fleet of Compute Engine VMs globally or within a specific zone by using VM Extension Manager policies. For example, you can use these policies to perform tasks like the following:

With VM Extension Manager, you create policies that declare which extensions you want to install on VMs. The Ops Agent is one of the available extensions. VM Extension Manager policies can manage the Ops Agent version 2.58.0 or newer, when the Ops Agent has been installed by using VM Extension Manager. These policies can't manage versions of the Ops Agent earlier than version 2.58.0, Ops Agent instances installed by using other means, or any version of the legacy Monitoring agent or Logging agent.

You can create and manage zonal VM extension policies by using the Google Cloud console or the Google Cloud CLI, gcloud. You can create and manage global VM extension policies by using gcloud.

Before you begin

Before starting to using VM Extension Manager extension policies, do the following:

Review supported operating systems

Before attempting to use VM Extension Manager policies to manage the Ops Agent, verify that your target operating system is compatible with both the Ops Agent and VM Extension Manager.

VM Extension Manager supports all operating systems supported by the Ops Agent, except for SUSE Linux Enterprise Server (SLES) and Ubuntu. For more information about the operating systems supported by the Ops Agent, see Operating systems.

If your operating system is supported by both the Ops Agent and VM Extension Manager, then follow the rest of this document.

Enable the APIs required to use the Ops Agent

To use the Ops Agent to write logs and metrics, you must enable the Cloud Logging API and Cloud Monitoring API on your Google Cloud project.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Grant roles required to use the Ops Agent

To get the permissions that you need to use the Ops Agent to write logs and metrics, ask your administrator to grant you the following IAM roles on your service account:

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

You might also be able to get the required permissions through custom roles or other predefined roles.

For more information about roles and the Ops Agent, see Authorize the Ops Agent.

Grant roles required to use VM Extension Manager

To get the permissions that you need to create, 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, see Manage access to projects, folders, and organizations.

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

Required permissions

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

You might also be able to get these permissions with custom roles or other predefined roles.

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

Install the Google Cloud CLI

You can create and manage VM extension policies by using the Google Cloud console or the Google Cloud CLI, gcloud. To use gcloud, you must first install it by performing the following steps:

  1. If you haven't done so already, install the Google Cloud CLI.

    The extension policies described in this document use the beta command group.

  1. If you haven't done so already, install the beta component of the gcloud CLI by running the following command:

    gcloud components install beta

    To check if you have the beta component installed, run the following command:

    gcloud components list

    If you previously installed the beta component, verify that have the latest version:

    gcloud components update

Uninstall any observability agents

Before creating a VM Extension Manager policy to manage the Ops Agent on a VM, ensure that there are no instances of the Ops Agent or the legacy Monitoring agent and Logging agent already on the VM. Running the Ops Agent and the legacy agents on the same VM can cause ingestion of duplicate logs or conflicts in metrics ingestion.

If you use an extension policy to install the Ops Agent on a VM where another observability agent is already installed, then the policy installs the agent, but the agent fails to run because a conflict is detected.

How you remove existing agents depends on how those agents were installed.

Install the Ops Agent by creating VM extension policies

Create VM extension policies to automatically install and manage the Ops Agent on a fleet of Compute Engine virtual machines (VMs). By defining a policy, you can ensure that specific extensions, like the Ops Agent, are installed and maintained on any VMs that match criteria you specify, such as VM labels.

Policy conflicts and priorities

VM Extension Manager associates a priorty with each new policy, with lower numbers indicating higher priorities; the default priority is 1000. A VM can be covered by multiple policies for an extension like the Ops Agent, but only one policy for the Ops Agent extension is effective on the VM.

VM Extension Manager uses priorities to resolve conflicts among policies applied to a VM. For more information about the resolution process, see Policy priority and conflict resolution.

Policy rollout plans for global policies

VM Extension Manager global policies use a rollout plan to determine how a policy is distributed to target VMs. There are two types of rollout plans:

For more information about rollout plans, see Rollout plans for global policies.

Install the latest Ops Agent on all VMs

To create a policy that installs the latest version of the Ops Agent on all VMs in a zone or globally, and updates the Ops Agent when a new version is released, do the following:

Console

To create a zonal policy, you can use the Google Cloud console.

  1. In the Google Cloud console, go to the Extension policies page:

    Go to Extension policies

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

  2. Click + Create.
  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 Manage extensions section, click Add extension and do the following:

    1. From the Extension list, select Google Cloud's Extension for Ops Agent.
    2. Leave the Version field blank.

  8. Click Create.

gcloud

To create a zonal or global policy, you can use the gcloud CLI.

Zonal

Use the following gcloud beta compute zone-vm-extension-policies create command to create the policy:

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.

The gcloud beta compute zone-vm-extension-policies create takes an option --version option. If you omit the --version option, then the policy installs the latest version and updates the Ops Agent when a new version is released.

Global

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

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.

The gcloud beta compute global-vm-extension-policies create takes an option --version option. If you omit the --version option, then the policy installs the latest version and updates the Ops Agent when a new version is released.

Pin the Ops Agent to a specific version on all VMs

To create a policy that installs a specific version of the Ops Agent on all VMs in a zone or globally, do the following:

Console

To create a zonal policy, you can use the Google Cloud console.

  1. In the Google Cloud console, go to the Extension policies page:

    Go to Extension policies

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

  2. Click + Create.
  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 Manage extensions section, click Add extension and do the following:

    1. From the Extension list, select Google Cloud's Extension for Ops Agent.
    2. From the Version list, select the version to install. Use version 2.58.0 or newer.

  8. Click Create.

gcloud

To create a zonal or global policy, you can use the gcloud CLI.

Zonal

Use the following gcloud beta compute zone-vm-extension-policies create command to create the policy:

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent  \
  --version=ops-agent=VERSION

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.

  • VERSION: The version of the Ops Agent to install. Use version 2.58.0 or newer.

    If you omit the --version option, then the policy installs the latest version and updates the Ops Agent when a new version is released, as shown in the example that installs the latest version.

Global

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

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout \
  --version=ops-agent=VERSION

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.

  • VERSION: The version of the Ops Agent to install. Use version 2.58.0 or newer.

    If you omit the --version option, then the policy installs the latest version and updates the Ops Agent when a new version is released, as shown in the example that installs the latest version.

For a list of Ops Agent versions, see the Ops Agent releases page on GitHub.

Install the Ops Agent on VMs that have a specific label

To create a policy that installs the latest version of Ops Agent on the VMs in a zone or globally that have a specific label, do the following:

Console

To create a zonal policy, you can use the Google Cloud console.

  1. In the Google Cloud console, go to the Extension policies page:

    Go to Extension policies

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

  2. Click + Create.
  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:

    1. From the Extension list, select Google Cloud's Extension for Ops Agent.
    2. Leave the Version field blank.

  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 zonal or global policy, you can use the gcloud CLI.

Zonal

Use the --inclusion-labels option to the gcloud beta compute zone-vm-extension-policies create command to specify a comma-separated list of key-value pairs:

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent 
  --inclusion-labels=KEY1=VALUE1,KEY2=VALUE2

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.
  • KEY1=VALUE1,KEY2=VALUE2: A comma-separated list of key-value pairs that define inclusion labels for a selector. VMs must have all the labels specified in a selector (logical AND) to be included. If you specify the --inclusion_labels option multiple times, then the policy targets the VMs that match all the labels in any of the selectors (logical OR). If you omit this option, the policy targets all VMs in the specified zone.

Global

Use the --inclusion-labels option to the gcloud beta compute global-vm-extension-policies create command to specify a comma-separated list of key-value pairs:

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout \
  --inclusion-labels=KEY1=VALUE1,KEY2=VALUE2

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • KEY1=VALUE1,KEY2=VALUE2: A comma-separated list of key-value pairs that define inclusion labels for a selector. VMs must have all the labels specified in a selector (logical AND) to be included. If you specify the --inclusion_labels option multiple times, then the policy targets the VMs that match all the labels in any of the selectors (logical OR). If you omit this option, the policy targets all VMs in the specified zone.

Install the Ops Agent with a custom configuration on all VMs

To create a policy that installs the latest version of the Ops Agent on all VMs in a zone or globally, and provides custom configuration for the Ops Agent, do the following:

Console

To create a zonal policy, you can use the Google Cloud console.

  1. In the Google Cloud console, go to the Extension policies page:

    Go to Extension policies

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

  2. Click + Create.
  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:

    1. From the Extension list, select Google Cloud's Extension for Ops Agent.
    2. Leave the Version field blank.
    3. In the Config file content field, enter the YAML configuration string for the Ops Agent.

  8. Click Create.

gcloud

To create a zonal or global policy, you can use the gcloud CLI.

Zonal

Use the --config-from-file option to the gcloud beta compute zone-vm-extension-policies create command to specify a configuration file:

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent 
  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.

  • OPS_AGENT_CONFIG_PATH: The path to a file containing the YAML configuration string for the Ops Agent. This file must exist in the environment where you run the gcloud command.

    Configuration YAML for the Ops Agent can be lengthy. Putting the configuration into a file and passing the file to the gcloud CLI is much less error-prone than attempting to enter properly formatted YAML on the command line. Changing this file after creating the policy doesn't update the policy; to update a policy, use the gcloud beta compute zone-vm-extension-policies update command.

Global

Use the --config-from-file option to the gcloud beta compute global-vm-extension-policies create command to specify a configuration file:

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout \
  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.

  • OPS_AGENT_CONFIG_PATH: The path to a file containing the YAML configuration string for the Ops Agent. This file must exist in the environment where you run the gcloud command.

    Configuration YAML for the Ops Agent can be lengthy. Putting the configuration into a file and passing the file to the gcloud CLI is much less error-prone than attempting to enter properly formatted YAML on the command line. Changing this file after creating the policy doesn't update the policy; to update a policy, use the gcloud beta compute global-vm-extension-policies update command.

If you provide a custom configuration for the Ops Agent when creating or updating an extension policy, then the policy deploys the Ops Agent with the custom configuration. You don't need to manually restart the agent.

The configuration is stored with the extension policy, so don't include sensitive data like passwords in the configuration. Because the configuration is stored with the extension policy, modifying the configuration file does not change the configuration of the agent. You must update the configuration stored with the policy by using the appropriate gcloud command:

When you provide a custom configuration for the Ops Agent, VM Extension Manager copies the configuration to the location used by the Ops Agent for user-specified configuration files on the target VM:

If there is a config.yaml file present on the VM, the extension policy overwrites it.

For general information about using the Google Cloud console and the gcloud CLI to create VM extension policies, see Install VM extensions by creating extension policies .

Install the Ops Agent with a fast rollout plan at higher priority (global only)

To create a global policy that installs the latest version of the Ops Agent on by using a higher-than-default priority and the fast-rollout plan, use the following gcloud beta compute global-vm-extension-policies create command:

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=fast_rollout \
  --priority=500

Replace the following variables in the command:

Install the Ops Agent on a subset of zones in a Google Cloud project (global only)

To create a global policy that applies to only a subset of zones in a Google Cloud project, you must use a custom rollout plan that specifies the zones in which to apply the policy. For information about creating custom rollout plans, see About rollout plans. To specify a set of zones, use the locationSelector.includedLocations field when creating the rollout plan.

To create an extension policy that uses a custom rollout plan, use the following gcloud beta compute global-vm-extension-policies create command:

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-custom-plan=projects/PROJECT_ID/locations/global/rolloutPlans/CUSTOM_PLAN_NAME

Replace the following variables in the command:

Manage the Ops Agent by updating VM extension policies

To change how a policy manages the Ops Agent, update the policy. When you update a policy, VM Extension Manager rolls out the changes to all applicable VMs, typically within one minute. If you modify inclusion labels, then the Ops Agent might be installed on new VMs or uninstalled from existing VMs based on whether the VMs match the updated labels.

The following sections show how to manage the Ops Agent to do the following:

Update the pinned version of the Ops Agent on all VMs in a zone

To change the pinned version of the Ops Agent on all VMs in a zone, do the following:

Console

To create a zonal policy, you can use the Google Cloud console.

  1. In the Google Cloud console, go to the Extension policies page:

    Go to Extension policies

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

  2. Select the policy that you want to update.
  3. Click Edit.
  4. In the Manage extensions section, do the following:
    1. Select Google Cloud's Extension for Ops Agent.
    2. Modify the Version field. Use version 2.58.0 or newer.
    3. Click Done.
  5. Click Save.

gcloud

To create a zonal or global policy, you can use the gcloud CLI.

Zonal

Use the gcloud beta compute zone-vm-extension-policies update with the --version option command to modify the pinned agent version.

When you update a policy by using gcloud, the request acts as a complete replacement. Any optional fields you omit revert to their default values instead of retaining existing values from the modified policy.

To change the version of the Ops Agent installed on all VMs in a zone by a policy, use the following command:

gcloud beta compute zone-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent 
  --version=ops-agent=VERSION

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.

  • VERSION: The version of the Ops Agent to install. Use version 2.58.0 or newer. For a list of versions, see the Ops Agent releases page on GitHub.

    If you omit the --version option, then the policy installs the latest version and updates the Ops Agent when a new version is released, as shown in the example that installs the latest version.

Global

Use the gcloud beta compute global-vm-extension-policies update with the --version option command to modify the pinned agent version.

When you update a policy by using gcloud, the request acts as a complete replacement. Any optional fields you omit revert to their default values instead of retaining existing values from the modified policy.

To change the version of the Ops Agent installed on all VMs by a global policy, use the following command:

gcloud beta compute global-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout \
  --version=ops-agent=VERSION

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.

  • VERSION: The version of the Ops Agent to install. Use version 2.58.0 or newer. For a list of versions, see the Ops Agent releases page on GitHub.

    If you omit the --version option, then the policy installs the latest version and updates the Ops Agent when a new version is released, as shown in the example that installs the latest version.

Modify the configuration of the Ops Agent on all VMs

To modify the configuration of the Ops Agent, do the following:

Console

To create a zonal policy, you can use the Google Cloud console.

  1. In the Google Cloud console, go to the Extension policies page:

    Go to Extension policies

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

  2. Select the policy that you want to update.
  3. Click Edit.
  4. In the Manage extensions section, do the following:
    1. Select Google Cloud's Extension for Ops Agent.
    2. Modify the Config file content field.
    3. Click Done.
  5. Click Save.

gcloud

To create a zonal or global policy, you can use the gcloud CLI.

Zonal

Use the gcloud beta compute zone-vm-extension-policies update with the --config-from-file option or the --config option to specify a new configuration.

When you update a policy by using gcloud, the request acts as a complete replacement. Any optional fields you omit revert to their default values instead of retaining existing values from the modified policy.

To change the configuration of the Ops Agent installed on all VMs in a zone by a policy, use the following command:

gcloud beta compute zone-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent 
  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.

  • OPS_AGENT_CONFIG_PATH: The path to a file containing the YAML configuration string for the Ops Agent. This file must exist in the environment where you run the gcloud command.

    Configuration YAML for the Ops Agent can be lengthy. Putting the configuration into a file and passing the file to the gcloud CLI is much less error-prone than attempting to enter properly formatted YAML on the command line.

Global

Use the gcloud beta compute global-vm-extension-policies update with the --config-from-file option or the --config option to specify a new configuration.

When you update a policy by using gcloud, the request acts as a complete replacement. Any optional fields you omit revert to their default values instead of retaining existing values from the modified policy.

To change the configuration of the Ops Agent installed on all VMs by a policy, use the following command:

gcloud beta compute global-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout \
  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.

  • OPS_AGENT_CONFIG_PATH: The path to a file containing the YAML configuration string for the Ops Agent. This file must exist in the environment where you run the gcloud command.

    Configuration YAML for the Ops Agent can be lengthy. Putting the configuration into a file and passing the file to the gcloud CLI is much less error-prone than attempting to enter properly formatted YAML on the command line.

If you provide a custom configuration for the Ops Agent when creating or updating an extension policy, then the policy deploys the Ops Agent with the custom configuration. You don't need to manually restart the agent.

The configuration is stored with the extension policy, so don't include sensitive data like passwords in the configuration. Because the configuration is stored with the extension policy, modifying the configuration file does not change the configuration of the agent. You must update the configuration stored with the policy by using the appropriate gcloud command:

When you provide a custom configuration for the Ops Agent, VM Extension Manager copies the configuration to the location used by the Ops Agent for user-specified configuration files on the target VM:

If there is a config.yaml file present on the VM, the extension policy overwrites it.

For general information about using the Google Cloud console and the gcloud CLI to manage VM extension policies, see Modify extensions by updating a VM extension policy.

Extend an existing global policy to include new zones (global only)

When VMs are created in new zones after a global policy has been created and rolled out, VM Extension Manager does not automatically apply the policy to the VMs in the new zones. To include the VMs in new zones, you must restart the global policy rollout.

To restart a global policy rollout, use the gcloud beta compute global-vm-extension-policies update command and supply the --rollout-retry-uuid=UUID option.

For example, suppose you created and rolled out a global policy by using the following command:

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

To extend the policy to VMs created in previously unused zones, restart the rollout by using the following command:

gcloud beta compute global-vm-extension-policies update test-policy POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --version=ops-agent=2.61.0 \
  --rollout-predefined-plan=slow_rollout \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --rollout-retry-uuid=UUID

Replace the following variables in the command:

Update a global policy to exclude a set of zones (global only)

To update the zones to which a global policy that excludes some zones in a Google Cloud project, you must use a new custom rollout plan that specifies the zones in which to apply the policy. For information about creating custom rollout plans, see About rollout plans. To specify a set of zones, use the locationSelector.includedLocations field when creating the rollout plan.

To update an extension policy that uses a custom rollout plan, use the following gcloud beta compute global-vm-extension-policies update command:

gcloud beta compute global-vm-extension-policies update POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-custom-plan=projects/PROJECT_ID/locations/global/rolloutPlans/NEW_CUSTOM_PLAN_NAME \
  --rollout-retry-uuid=UUID

Replace the following variables in the command:

Uninstall the Ops Agent by deleting VM extension policies

To uninstall the Ops Agent, delete the VM extension policy that manages the agent. If another active, lower-priority policy applies to a VM and also manages the Ops Agent, then the agent remains installed on that VM based on the lower-priority policy.

VM Extension Manager removes the Ops Agent from all accessible VMs within one minute of policy deletion. If a VM is inaccessible, then VM Extension Manager skips deletion of the agent. If the VM becomes available again, then VM Extension Manager removes the agent at that time.

Console

  1. In the Google Cloud console, go to the Extension policies page:

    Go to Extension policies

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

  2. Select the policy that you want to delete.
  3. Click Delete.
  4. In the confirmation dialog, click Delete.

gcloud

Zonal

To delete the VM extension policy that manages the Ops Agent, use the gcloud beta compute zone-vm-extension-policies delete command:

gcloud beta compute zone-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.

Global

To delete the global VM extension policy that manages the Ops Agent, use the gcloud beta compute global-vm-extension-policies delete command:

gcloud beta compute global-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --rollout-predefined-plan=slow_rollout

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.

To accelerate an already started deletion rollout, issue a new deletion command that uses the fast_rollout plan. You must also specify the --rollout-retry-uuid=UUID option:

gcloud beta compute global-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --rollout-predefined-plan=fast_rollout \
  --rollout-retry-uuid=UUID

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • UUID: A universally unique identifier (UUID) that identifies the retry request. You can use any UUID generator to create one. For more information, see Retry a rollout .

Retrieve information about VM extension policies

You can retrieve the following information about existing VM extension policies:

Console

  1. In the Google Cloud console, go to the Extension policies page:

    Go to Extension policies

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

    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

Zonal

List VM extension policies

To list information about all VM extension policies in a zone, use the gcloud beta compute zone-vm-extension-policies list:

gcloud beta compute zone-vm-extension-policies list \
  --project=PROJECT_ID \
  --zone=ZONE \
  --page-size=PAGE_SIZE_INTEGER

Replace the following variables in the command:

  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.
  • PAGE_SIZE_INTEGER: The number of policies to list per page; for example, 2. For more information about sorting and filtering options, see gcloud beta compute zone-vm-extension-policies list.

Describe a named VM extension policy

To retrieve the configuration of a named policy in a zone, use the gcloud beta compute zone-vm-extension-policies describe:

gcloud beta compute zone-vm-extension-policies describe POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.
  • ZONE: The target zone; for example, us-central1-f.

Global

List global VM extension policies

To list information about global VM extension policies, use the gcloud beta compute global-vm-extension-policies list:

gcloud beta compute global-vm-extension-policies list \
  --project=PROJECT_ID \
  --page-size=PAGE_SIZE_INTEGER

Replace the following variables in the command:

Describe a named global VM extension policy

To retrieve the configuration of a named policy in a zone, use the gcloud beta compute global-vm-extension-policies describe:

gcloud beta compute global-vm-extension-policies describe POLICY_NAME \
  --project=PROJECT_ID

Replace the following variables in the command:

  • POLICY_NAME: A name for the VM extension policy.
  • PROJECT_ID: The identifier of the project.

For general information about using the Google Cloud console and the gcloud CLI to retrieve information about VM extension policies, see View extension policies.

Verify the installation of the Ops Agent

This section describes how to do the following:

Verify the status or version of an Ops Agent installation

To determine the status or version of the Ops Agent, use one of the following Google Cloud console pages:

Compute Engine

  1. In the Google Cloud console, go to the VM instances page:

    Go to VM instances

    If you use the search bar to find this page, then select the result whose subheading is Compute Engine.

  2. Select a VM from the list.
  3. Click the Observability tab.

Cloud Monitoring

  1. In the Google Cloud console, go to the VM Instances page:

    Go to VM Instances

    If you use the search bar to find this page, then select the result whose subheading is Monitoring.

  2. Select the List view.

When the Ops Agent has been installed on the VM and is collecting logs and metrics, the agent's status is marked with a green checkmark next to the Ops Agent label.

To determine the version of the installed agent, hover over the Ops Agent label on the Compute Engine or Monitoring dashboard.

Verify that the Ops Agent is collecting telemetry

If the Ops Agent has been successfully installed and is running correctly, then it sends metrics to Cloud Monitoring and logs to Cloud Logging.

Restart an Ops Agent installed by an extension policy

When the Ops Agent is installed and managed by VM Extension Manager, the Ops Agent isn't managed by the system-management service of the operating system, that is, systemd on Linux or the Windows Service Manager on Windows. Therefore, Linux systemctl commands and Windows *-Service commands don't work with an Ops Agent installed by an extension policy.

To restart an Ops Agent that was installed by an extension policy, do one of the following:

Enable guest agent debug log on the VM

VM Extension Manager policies use the Compute Engine guest agent to manage the Ops Agent as a VM extension. For information about enabling debug logging for the guest agent, see View debug logs for the guest agent.

Troubleshoot extension policies

This section provides information about troubleshooting the use of extension policies to manage the Ops Agent:

For information about troubleshooting the Ops Agent, see Troubleshoot the Ops Agent.

gcloud beta compute zone-vm-extension-policies commands fail

When a gcloud beta compute zone-vm-extension-policies command fails, the response includes troubleshooting suggestions. Correct any errors in the command flags or arguments suggested by the error message.

If the output of the command mentions insufficient IAM permissions, then review the necessary roles and permissions described in Grant the roles required to use VM Extension Manager.

The extension policy is created, but the Ops Agent status is "not detected"

You successfully created an extension policy, but the Ops Agent shows a "not detected" status on the VM.

The Ops Agent might show as "not detected" if either of the following occurs:

The following sections describe how to diagnose these cases.

Verify that the Ops Agent was installed by the policy

VM Extension Manager policies use the Compute Engine guest agent to manage the Ops Agent as a VM extension.

To determine if the Ops Agent was installed by the extension policy, use one of the following to look for log entries from the guest agent:

Logs Explorer

  1. In the Google Cloud console, go to the Logs Explorer page:

    Go to Logs Explorer

    If you use the search bar to find this page, then select the result whose subheading is Logging.

  2. Enter the following query and click Run query:

    log_id("GCEGuestAgentManager")

Linux

Run the following command on the Compute Engine VM:

journalctl -u google-guest-agent-manager

Windows

Run the following command on the Compute Engine VM:

Get-Eventlog -Source google_guest_agent_manager -LogName Application

If you see logs containing a string like Failed to install plugin "ops-agent-plugin" ..., or the query returns no logs, then the extension policy failed to install the Ops Agent. For next steps, see Extension policy fails to install the Ops Agent.

If you see logs containing a string like Successfully installed plugin "ops-agent_nnnnnnnn", then the extension policy successfully installed the Ops Agent. For next steps, see Installed Ops Agent is "not detected".

Extension policy fails to install the Ops Agent

An extension policy might be ineffective if one of the following is true:

Installed Ops Agent has status "not detected"

The Ops Agent can have a status of "not detected" if one of the following is true:

Verify that the Ops Agent configuration is valid

You provided a custom configuration to the Ops Agent by creating or updating an extension policy, but the agent status is "not detected". The problem might be an error in your custom configuration. Use the guest agent debug logs to look for configuration errors.

Enable guest agent debug logging

For information about enabling debug logging for the guest agent, see View debug logs for the guest agent.

Examine debug logs

Logs Explorer

  1. In the Google Cloud console, go to the Logs Explorer page:

    Go to Logs Explorer

    If you use the search bar to find this page, then select the result whose subheading is Logging.

  2. Enter the following query and click Run query:

    severity>=DEBUG log_id("GCEGuestAgentManager") "The agent config file is not valid"

Linux

Run the following command on the Linux Compute Engine VM:

journalctl -u google-guest-agent-manager | grep "The agent config file is not valid"

Windows

Run the following command on the Windows Compute Engine VM:

Get-Eventlog -Source google_guest_agent_manager -LogName Application | Where-Object {$_.Message -like "*The agent config file is not valid*"}

If you see logs containing the string The agent config file is not valid, then the custom configuration for the Ops Agent you provided when creating or updating the extension policy is invalid.

To fix this problem, do the following:

Linux systemctl status and Windows Get-Service commands don't work with the Ops Agent

You run a command like sudo systemctl status google-cloud-ops-agent"*" but it returns no information.

When the Ops Agent is installed and managed by VM Extension Manager, the Ops Agent isn't managed by the system-management service of the operating system, that is, systemd on Linux or the Windows Service Manager on Windows.

To find the status information for an Ops Agent managed by VM Extension Manager, see the following:

Linux systemctl restart and Windows Restart-Service commands don't work with the Ops Agent

You run a command like sudo systemctl restart google-cloud-ops-agent but the Ops Agent isn't restarted.

When the Ops Agent is installed and managed by VM Extension Manager, the Ops Agent isn't managed by the system-management service of the operating system, that is, systemd on Linux or the Windows Service Manager on Windows. Therefore, you can't stop or start the Ops Agent manually, and commands like the following don't work with the Ops Agent:

To stop or restart an Ops Agent managed by VM Extension Manager, you must uninstall the agent by deleting the extension policy. For more information about stopping or restarting the Ops Agent, see Restart an Ops Agent installed by an extension policy.

Additional troubleshooting information

For more information about troubleshooting the creation and use of VM Extension Manager policies, see Troubleshoot VM extensions.

For more information about troubleshooting the Ops Agent, see Troubleshoot the Ops Agent.

Quota

For information about the number of extension policies you can create in a Google Cloud project, see Quota.

Pricing

For information about costs associated with using VM Extension Manager, see Pricing.

If you install the Ops Agent, then you might be charged for the metrics, logs, or traces that the agent sends to your Google Cloud project. For pricing information, see Google Cloud Observability pricing.

What's next