Manage VMs covered by the Ops Agent OS policy

If you created Compute Engine VMs with the Ops Agent installed duringcreation or, in some cases, if youinstalled the agent on existingVMs by using the Google Cloud console,then Google Cloud also createdVM Manager OS policies that install and monitor the Ops Agent. Thisdocument describes how to query those Ops Agent OS policies and manage theOps Agent on VMs covered by the policies. For information about creating VMswith the Ops Agent automatically installed,seeInstall the Ops Agent during VM creation.

After an Ops Agent OS policy has been created, you can do the following:

  • Determine which VMs are covered by the policy.
  • Determine which zones are covered by the policy.
  • Extend policy coverage to existing VMs.
  • Uninstall the agent from a VM covered by the policy.

Find VMs covered by Ops Agent OS policies

You can use the Google Cloud console or the Google Cloud CLI to seewhich VMs in your Google Cloud project are covered by Ops Agent OS policiesthrough an OS policy assignment. If you believe a VM is missing coverage, youcan troubleshoot by doing the following:

Verify that an Ops Agent OS policy is assigned to VMs in a zone

To verify that the VMs in a zone are covered by the Ops Agent OS policy,use either the Google Cloud console or the gcloud CLI to seewhether the VM is related to an Ops Agent OS policy assignment.

Console

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

    Go toOS policies

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

  2. On theVM instances tab, select the VM that you want to check.

  3. If the VM is covered by an Ops Agent OSpolicy, then theOS policy id column includesgoog-ops-agent-policy andthe state is "Compliant".

gcloud

To display a list of Ops Agent OS policy assignments in a zone,run the following command:

gcloud compute os-config os-policy-assignment-reports list --location=ZONE --filter="ASSIGNMENT_ID ~ goog-ops-agent"

The output shows a list of VMs with an Ops Agent OSpolicy assignment. If the Ops Agent is installed on the VM, the Summary columnhas a value of "1/1 policies compliant".

INSTANCE    ASSIGNMENT_ID                                    LOCATION    UPDATE_TIME                  SUMMARYinstance-1  goog-ops-agent-v2-x86-template-1-0-0-us-east4-c  us-east4-c  2023-04-28T02:11:15.118088Z  1/1 policies compliantinstance-3  goog-ops-agent-v2-x86-template-1-0-0-us-east4-c  us-east4-c  2023-04-28T02:11:15.118088Z  1/1 policies compliant

Verify that a VM has an Ops Agent OS policy label

To see which VMs in your Google Cloud project have theOps Agent OS policy label,goog-ops-agent-policy, useeither the Google Cloud console or the gcloud CLI.

Console

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

    Go toVM instances

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

  2. Select the name of your VM.

  3. In theBasic information panel, locate theLabels entry.

    If the VM is covered by the Ops Agent OS policy, then it has alabel likegoog-ops-agent-policy:v2-x86-template-1-0-0.

gcloud

To see all the VMs that have the Ops Agent OS policy labelgoog-ops-agent-policy, run the following command:

gcloud compute instances list --format="table(name,zone,labels)" --filter="labels=goog-ops-agent-policy"

The output shows the name, zone, and labels of the VMs.For example:

NAME                  ZONE           LABELStest-vm1              us-central1-a  {'goog-ops-agent-policy': 'v2-x86-template-1-0-0'}test-vm1              us-east4-c     {'goog-ops-agent-policy': 'v2-x86-template-1-0-0'}

To see whether a specific VM has the Ops Agent OS policy label,run the following command:

gcloud compute instances describe --format "yaml(labels)" --zone=ZONEVM_NAME

The output shows a list of labels for your VM. If your VM hasthe Ops Agent OS policy label, thengoog-ops-agent-policyappears in thelabels list. For example:

labels:  goog-ops-agent-policy: v2-x86-template-1-0-0

Verify that an Ops Agent OS policy assignment was successfully rolled out

View your Google Cloud project OS policy assignments to verify thatan Ops Agent OS policy assignment was correctly deployed to a specific zone.

Console

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

    Go toOS policies

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

  2. To see the state of OS policy rollouts, click theOS policy assignmentstab.

    Ops Agent OS policy assignments have IDs that start with the string"goog-ops-agent".If the assignment was rolled out successfully, then it has a rollout state of"Succeeded".

gcloud

To view all Ops Agent OS policy assignments in a zone,run the following command:

gcloud compute os-config os-policy-assignments list --location=ZONE --filter="ASSIGNMENT_ID ~ goog-ops-agent"

The output shows a list of Ops Agent OS policy assignments in a zone.If the assignment was rolled out successfully,then it has a rollout state of "SUCCEEDED". For example:

ASSIGNMENT_ID                                       ROLLOUT_STATE    REVISION_CREATE_TIME       REVISION_ID    goog-ops-agent-v2-x86-template-1-4-0-us-central1-b  SUCCEEDED        2023-01-28T05:23:41Z.      940df3e9-77fd-470b-84df-53fb24825c4agoog-ops-agent-v2-x86-template-1-0-0-us-central1-b  SUCCEEDED        2022-01-28T05:23:41Z.      qwareaff-efte-erew-aeet-faer234t4gga

To view details about a specific Ops Agent OS policy assignment,run the following command:

gcloud compute os-config os-policy-assignments describePOLICY_ASSIGNMENT_ID --location=ZONE

Uninstall the Ops Agent on VMs covered by the Ops Agent OS policy

If you manuallyuninstall the Ops Agent on a VM covered by the Ops AgentOS policy,then the policy re-installs it. To uninstall the Ops Agent, you must firstremove thegoog-ops-agent-policy label from the VM. After you have removed theOps Agent OS policy label from a VM, you can uninstall the Ops Agentpermanently.

Uninstall the Ops Agent on a specific VM

To remove the policy and uninstall the Ops Agent from a specific VM, you canuse the Google Cloud console or the gcloud CLI.

Console

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

    Go toVM instances

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

  2. Select the name of the VM that you want to edit.

  3. ClickEdit.

  4. Go to theLabels section and then click+ Add Labels.

  5. Locate the label with the keygoog-ops-agent-policy and clickDelete item.

  6. Uninstall the agent.

gcloud

  1. To remove thegoog-ops-agent-policy label from a VM,run the following command:

    gcloud compute instances updateVM_NAME \  --remove-labels=goog-ops-agent-policy

  2. Uninstall the agent.

Uninstall the Ops Agent on all VMs

To uninstall the Ops Agent from VMs in zone that has an Ops Agent OS policyassignment, use the script provided by Cloud Monitoring. You can't uninstallthe agent from a group of VMs by using the Google Cloud console.

To run the script, you must have theGuestPolicy Editor role (roles/osconfig.guestPolicyEditor).

Run the following script in Cloud Shell. You can provide any numberof zones:

curl -sSO https://dl.google.com/cloudagents/undo-ops-agent-policies.shbash undo-ops-agent-policies.shZONE1ZONE2

The script performs the following tasks in each zone:

  1. Finds all Ops Agent OS policies.
  2. Edits each policy so that it uninstalls the Ops Agent on itscovered VMs.
  3. Deletes the Ops Agent OS policy.
  4. Removes thegoog-ops-agent-policy label from eachcovered VM.

Add Ops Agent OS policy coverage to an existing VM

The Ops Agent OS policy covers only VMsthat have thegoog-ops-agent-policy label and are in the same zone as an existingOps Agent OS policy assignment. However, you can extend coverage to other VMsthat were created without the Ops Agent OS policyassigned to them.

To extend policy coverage to a VM, you need to know the template version ofthe Ops Agent OS policy assignment in your zone. If your zone has multipleOps Agent OS policy assignments, then findthe assignment with the latest template version.To show a list of Ops Agent OS policy assignments in azone, run the following command:

gcloud compute os-config os-policy-assignments list --location=ZONE  --filter="ASSIGNMENT_ID ~ goog-ops-agent"

To extend policy coverage to other VMs, use either the Google Cloud consoleor the gcloud CLI:

Console

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

    Go toVM instances

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

  2. In theVM instances list, select the checkboxes next to the VMs that youwant to label and then clickLabels.

  3. To add labels, click+Add label and add the key-value pair.The key must begoog-ops-agent-policy and the value is the desired templateversion, such as1-0-0.

  4. Save your changes.

gcloud

To extend policy coverage to a VM without coverage, run the following commands:

gcloud compute instances updateVM_NAME --zone=ZONE  --update-labels=goog-ops-agent-policy:v2-x86-template-1-0-0
gcloud compute instances add-metadataVM_NAME --zone=ZONE  --metadata=enable-osconfig=TRUE

Permission

Ops Agent installation uses VM Manager and requires permissions toactivate the VM Manager API and create a policy. The requiredpermissions are all available using theEditor role (roles/Editor). Or you canask a project administrator to grant the minimal permissions using theGoogle Cloud CLI.

Required permissions for installing the Ops Agent during VM creation:

  • serviceusage.services.get
  • serviceusage.services.enable
  • osconfig.osPolicyAssignments.get
  • osconfig.osPolicyAssignments.create
  • osconfig.projectFeatureSettings.update
  • compute.instances.create

Required permissions for installing Ops Agent on existing VMs:

  • serviceusage.services.get
  • serviceusage.services.enable
  • osconfig.osPolicyAssignments.get
  • osconfig.osPolicyAssignments.create
  • osconfig.projectFeatureSettings.update
  • compute.instances.setMetadata
  • compute.instances.setLabels

You can find corresponding roles that provide those permissions in theIAM basic and predefined roles reference.

Sample commands to grant roles for permissions:

gcloudprojectsadd-iam-policy-bindingproject-id--member='user:user-email'--role='roles/osconfig.projectFeatureSettingsEditor'

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-19 UTC.