Agent policies enable automated installation and maintenance of theOps Agentacross a fleet of Compute Engine VMs that matchuser-specified criteria. You can create a policy for aGoogle Cloud project that governs existing and new VMs associated with thatGoogle Cloud project, ensuring properinstallation and uninstallation of the Ops Agenton those VMs.

Agent policies for the Ops Agent

Support for agent policies for the Ops Agent is availableat two release levels: GA and beta. Both types of policies rely onOS Config features provided byVM Manager, but the implementations aredifferent. We recommend using the GA policies when possible. In most cases,you canconvert beta policies to GA policies.

This section describes the differences between the beta and GA agent policiesFor information about creating and managing agent policies, see the following:

• Use agent policies (GA)
• Use agent policies (beta)

Differences between beta and GA agent policies

The beta and GA agent policies differ in the following ways:

• Creation mechanisms

  • Beta agent policies are created by using the following:
    • Thegcloud beta compute instances ops-agents policies command groupin the Google Cloud SDK.
    • Theagent-policyTerraform module
  • GA agent policies are created by using the following:
    • Thegcloud compute instances ops-agents policies command groupin the Google Cloud SDK.
    • Theops-agent-policyTerraform module

• Support for the legacy Monitoring agent and Logging agent

  • Beta agent policies can manage the legacy Monitoring agent and Logging agentas well as the Ops Agent.
  • GA agent policies manage only the Ops Agent.

• Automatic upgrade of agent version

  • Beta agent policies can keep the agent at the latest version byupgrading the agent.
  • GA agent policies don't support an auto-upgrade operation. Foralternative approaches, seeReplace beta agent-upgrade policies.

• Application of policy to named Compute Engine instances

  • Beta agent policies can be applied to a list of namedinstances.
  • GA agent policies don't provide support for named instances.For information about getting the same behavior with GA policies, seeConvert a beta named-instance policy to a GApolicy.

• Global or zonal application of agent policies within a Google Cloud project

  • Beta agent policies are globally applied to all instances selected by thepolicy criteria within your Google Cloud project.
  • GA agent policies are applied to all instances selected by thepolicy criteria within the zone that the policy specifies. For example,a policy created in theus-central1-a zone has no effect onVMs in other zones.

The beta and GA policies are also structurally different:

• Policies created by usinggcloud beta compute instances ops-agents policiesdescribe agent policies by passing individual options to the commands, forexample:

  gcloudbetacomputeinstancesops-agentspoliciescreateops-agents-test-policy\--agent-rules="type=logging,enable-autoupgrade=false;type=metrics,enable-autoupgrade=false"\--description="A test policy."\--os-types=short-name=centos,version=7\--instances=zones/us-central1-a/instances/test-instance\--projectPROJECT_ID

  The agent-policy Terraform module provides the samecapabilities.

• Pollicies created by using thegcloud compute instances ops-agents policiesdescribe agent policy by using aYAML configurationfile and a zone, for example:

  gcloudcomputeinstancesops-agentspoliciescreatetest-policy\--zoneus-central1-a\--filetest-policy.yaml\--projectPROJECT_ID

  The ops-agent-policy Terraform module provides the samecapabilities.

Use of both beta and GA policies

You can use both beta and GA agent policies with the Ops Agent, as long as youconsider thedifferences between the policy types.

The biggest behavioral difference between beta and GA agent policies is that GApolicies are zonal, and beta agent policies are global within a project.That is, GA agent policies select only VMs in the zone in which thepolicy is created, but beta policies can select any VM in yourGoogle Cloud project.

If the beta policies select one set of VMs and the GA policies select adifferent set of VMs, then the policies can't conflict.

You can have beta and GA agent policies that apply to the same VM, but youneed to ensure that the policies don't have conflicting purposes, for example,a beta policy that installs the Ops Agent and a GA policy that uninstalls theOps Agent.

Convert beta policies to GA policies

You can convert your Ops Agent beta agent policies to GA agent policies, aslong as there are nodifferences between the policy types thatyou can't work around. You can't convert beta agent policies for the legacyMonitoring agent or Logging agent to GA agent policies.

To convert beta agent policies to GA policies by using the Google Cloud SDK,do the following:

1. Generate a list of all beta agent policies in your project by running thefollowing command:

   gcloudbetacomputeinstancesops-agentspolicieslist--projectPROJECT_ID

2. Identify the beta agent policies that you want to convert to GA policies.

3. For each beta policy that you identify for conversion, do the following:

   1. Create a YAML configuration file that is as close to the beta policyas possible, given thedifferences between the beta and GA policies.For information about the YAML configuration format, seeDescribe agent policies.

   2. Create a GA agent policy in each zone where you need the policy.For information about creating GA agent policies, seeCreate an agent policy.

   3. Delete the beta agent policy by running the following command:

      gcloudbetacomputeinstancesops-agentspoliciesdeletePOLICY_ID--projectPROJECT_ID

You might not be able to write a GA agent policy for the Ops Agent that isexactly the same as an existing beta agent policy. However, with the exceptionof the auto-upgrade option of the beta agent policy, you can get equivalentbehavior.

The following sections describe how to handle the following cases:

• Beta agent policies that select named instances
• Beta agent-upgrade policies

Convert a beta named-instance policy to a GA policy

To convert a beta agent policy that is applied to a named set of VMinstances, you can do the following:

1. Apply a label to the instances in the set of VMs you want to select.To apply a label to an existing VM, use thegcloud compute instancesadd-labels command,as shown in the following command:

   gcloudcomputeinstancesadd-labelsINSTANCE_NAME--labels=KEY=VALUE

2. Describe a GA agent policy that selects VMs with the new label by usingtheinstanceFilter structure in theconfiguration. The following example creates a file calledconfig.yamlthat contains a policy that matches the label applied in the previousstep:

   cat >config.yaml <<EOFagentsRule:packageState:installedversion:2.47.0instanceFilter:inclusionLabels:-labels:KEY:VALUEEOF

   For more information about describing GA agent policies, seeConfiguration files for agent policies.

3. Create a GA agent policy in each zone that has VMs with the new label:

   gcloudcomputeinstancesops-agentspoliciescreatePOLICY_ID\--zoneZONE\--fileconfig.yaml--projectPROJECT_ID

   For more information about creating GA agent policies, seeCreate an agent policy.

Replace beta agent-upgrade policies

To replace beta agent policies that upgrade the agent, you have the followingoptions:

• To make sure the Ops Agent is always up to date, useOS Patch to create and run anOS Patch job that keeps the agent at the latestversion.

• To perform a one-time upgrade, do the following:

  1. Determine the latest version of the Ops Agent by consultingthe Ops Agentrelease notes onGitHub.

  2. Create or modify an agent policy that installs the latest agent version.For example, if the latest version is 2.60.0,then you can use an agent-policy YAML that resembles the following:

     agentsRule:packageState:installedversion:2.60.0instanceFilter:[...]

  3. Apply the policy to VMs in each zone.

Supported operating systems

You can apply an agent policy toCompute EngineVM instances running the operating systems shown in the following table:

Operating system	Ops Agent (GA & beta† policies)	Logging agent (beta† policies only)	Monitoring agent (beta† policies only)
CentOS 8
Rocky Linux 8
RHEL 6
RHEL 7: rhel-7, rhel-7-6-sap-ha, rhel-7-7-sap-ha, rhel-7-9-sap-ha			‡
RHEL 8: rhel-8, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha			‡
Debian 9 (Stretch)
Debian 11 (Bullseye)
Deep Learning VM Images based on Debian 11 (Bullseye)
Ubuntu LTS 18.04 (Bionic Beaver): ubuntu-1804-lts, ubuntu-minimal-1804-lts
Ubuntu LTS 20.04 (Focal Fossa): ubuntu-2004-lts, ubuntu-minimal-2004-lts
Ubuntu LTS 22.04 (Jammy Jellyfish): buntu-2204-lts, ubuntu-minimal-2204-lts
SLES 12: sles-12, sles-12-sp5-sap
SLES 15: sles-15, sles-15-sp2-sap, sles-15-sp3-sap, sles-15-sp4-sap, sles-15-sp5-sap, sles-15-sp6-sap
OpenSUSE Leap 15: opensuse-leap (opensuse-leap-15-3-*, opensuse-leap-15-4-*)
Windows Server: 2016, 2019, 2022, Core 2016, Core 2019, Core 2022

^†  In beta agent policies, the agent columns map to anagent type specified to thegcloud beta compute instances ops-agents policiescreate invocation:

• Ops Agent maps to agent typeops-agent.
• Logging agent maps to agent typelogging.
• Monitoring agent maps to agent typemetrics.

^‡ The Monitoring agent is not supported onrhel-7-9-sap-ha,rhel-8-2-sap-ha, orrhel-8-4-sap-ha.

What's next

For information about using agent policies to manage the Ops Agent, see thefollowing:

• Use agent policies (GA)
• Use agent policies (beta)