VM Extension Manager policies for the Ops Agent overview

VM Extension Manager policies let you automate the deployment, configuration, and version management of the Ops Agent across your Compute Engine fleet. You can apply policies globally or target specific zones and labeled subsets of VMs, roll out custom configurations, and keep agents updated or pinned to a specific release. You can also define VM extension policies across different levels of the Google Cloud resource hierarchy: project and, in Preview, folder or organization.

About extension policies for the Ops Agent

With VM Extension Manager, you create policies that declare which extensions you want to install on VMs. The Ops Agent is one of the supported extensions. When you create an extension policy, you describe how you want the Ops Agent or other supported extension to be installed and maintained on any VMs that match the policy's criteria.

You can use extension policies for the Ops Agent to perform tasks like the following:

  • Fleetwide installation: Install the Ops Agent at the project, folder, and organization levels:

    • All VMs in one or more zones.
    • All VMs globally.
    • A labeled subset of VMs in a zone.
    • A labeled subset of VMs across zones.

  • Version control:

    • Keep the Ops Agent updated to the latest version.
    • Pin the Ops Agent version to a specific release.

  • Configuration management: Apply and update a custom configuration to the Ops Agent on all VMs managed by a policy.

VM Extension Manager supports Ops Agent version 2.58.0 or newer, when the Ops Agent has been installed by an extension policy. VM Extension Manager can't manage earlier versions of the Ops Agent, Ops Agent instances installed by using other means, or the legacy Monitoring agent or Logging agent.

Resource hierarchy scopes

In addition to creating project-level policies, you can create policies at the organization and folder levels (available in Preview) to manage extensions across multiple projects. The following table compares the available resource hierarchy scopes:

Scope Definition level Policy evaluation
Project-level policies You define the policy at the Google Cloud project level. VM Extension Manager evaluates the policy against VMs within a single project.
Folder-level policies (Preview) You define the policy at the Google Cloud folder level. VM Extension Manager evaluates the policy against all descendant projects and VMs within that folder.
Organization-level policies (Preview) You define the policy at the Google Cloud organization level. VM Extension Manager evaluates the policy against all descendant projects and VMs across the organization.

Defining extension policies at the organization or folder level centralizes fleet-wide governance and lets you enforce software configurations at scale without intervening in individual projects. Organization and folder-level policies support the following primary use cases:

  • Fleet-wide policy enforcement: Establish mandatory baseline configurations, such as deploying the Ops Agent, across an entire organization or specific folders.
  • Organizational security baselines: Enforce security extensions and monitoring tools across all projects within a hierarchy to maintain compliance.
  • Standardized environments: Maintain consistent software environments for production or business-unit workloads without manual intervention in individual projects.

Zonal and global scopes

Within an organization, folder, or project, you can configure VM extension policies as either zonal or global:

  • Zonal policies: You define and manage the policy in a specific zone. Zonal policies affect VMs only in the designated zone. For general information about zonal extension policies, see Zonal VM extension policies.
  • Global policies: You define the policy once at the organization, folder, or project level, and VM Extension Manager automatically replicates it into corresponding zonal policies across all target zones according to your rollout plan (FAST or SLOW). Depending on the rollout plan that you select, a slow rollout can take several days to complete across all zones. For general information about global extension policies, see Global VM extension policies.

Interface support

You can interact with project-scoped policies, both zonal and global, by using the gcloud CLI, the Compute Engine API, or the Google Cloud console. Only the gcloud CLI and the Compute Engine API are supported for folder- and organization-level policies (in Preview).

The following table summarizes the supported interfaces:

  Project
 		 Folder
(Preview)		 Organization
(Preview)
 
Zonal
  		gcloud
Compute Engine API
Google Cloud console 		gcloud
Compute Engine API
  		gcloud
Compute Engine API
 
 
Global
  		gcloud
Compute Engine API
Google Cloud console 		gcloud
Compute Engine API
  		gcloud
Compute Engine API
 

The documentation for Ops Agent extension policies doesn't cover using the Compute Engine API. For information about using the Compute Engine API to create and manage extension policies, see the VM Extension Manager documentation.

Visibility and auditing with read-only APIs

VM Extension Manager provides global and zonal read-only APIs so you can inspect registered extensions and their runtime states on VM instances.

You can use the read-only Compute Engine APIs and corresponding Google Cloud CLI commands to perform the following auditing and troubleshooting tasks:

  • Verify effective extension states on VMs. Retrieve the runtime enforcement state (enforcementState) and health status (healthStatus) of each extension on a VM instance. When multiple zonal or global extension policies target the same instance, you can inspect the policyId and version fields to audit the final effective configuration after priority resolution.
  • Troubleshoot unexpected or failing extensions. List all active extensions on a specific instance to investigate unauthorized extensions or to inspect diagnostic error messages (enforcementMsg and healthMsg) when an extension fails to install or crashes.
  • Audit extension support levels before deployment. Discover all available global and zonal VM extensions in your project and verify their stability compliance (PREVIEW or GA) before you roll out extension policies across your fleet.

For more information, see View the states of extensions on a VM.

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 you can use extension policies to manage 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