Console
Start free

Use agent policies (GA)

You create and manage agent policies by using the gcloud compute instances ops-agents policies command group in the Google Cloud CLI or the ops-agent-policy Terraform module. Agent policies use the VM Manager suite of tools in Compute Engine to manage OS policies, which can automate the deployment and maintenance of software configurations like the Ops Agent. These policies can't be applied to the legacy Monitoring agent or the legacy Logging agent. The GA agent policies use OS policy assignment resources in the OS Config API. Although there is a general gcloud CLI command group for managing OS policy assignments, gcloud compute os-config os-policy-assignments, the gcloud compute instances ops-agents policies command group is designed specifically for the agent policies described in this document.

Before you begin

The ops-agent-policy Terraform module is built on top of the gcloud compute instances ops-agents policies commands from the Google Cloud SDK. For information about how Terraform works, see Using Terraform.

Before using the Google Cloud CLI or the Terraform module to create agent policies, complete the following steps:

  1. If you are going to use the gcloud compute instances ops-agents policies commands and if you haven't done so already, then install the Google Cloud CLI.

  2. If you are going to use the Terraform module, then do the following:

    1. For information about installing Terraform, see Install and configure Terraform. Cloud Shell has Terraform already installed.

    2. Clone the terraform-google-cloud-operations repository, which contains the ops-agent-policy module:

      git clone https://github.com/terraform-google-modules/terraform-google-cloud-operations

  3. Download and run the prepare-for-ops-agents-policies.sh script to enable the required APIs and to set the proper permissions for using the Google Cloud CLI or Terraform.

    For information about the script, see The prepare-for-ops-agents-policies.sh script.

Uninstall the legacy Monitoring agent and Logging agent

If you're creating a policy for the Ops Agent, ensure that your VMs don't have the legacy Logging agent or Monitoring agent installed on them. Running the Ops Agent and the legacy agents on the same VM can cause ingestion of duplicate logs or a conflict in metrics ingestion. If necessary, uninstall the Monitoring agent and uninstall the Logging agent before creating a policy to install the Ops Agent.

Verify that the OS Config agent is installed

You might need to manually install and configure the OS Config agent on VMs that predate OS Config. For information about manually installing and verifying the OS Config agent, see the VM Manager verification checklist.

Find values for operating-system information

If you want to apply agent policies to specific operating systems or versions, you need to know the values that OS Config uses to refer to them.

To find values for the osShortName and osVersion fields for a VM, use the following commands:

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^ShortName: "

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^Version: "

These commands require the OS Config agent to be installed on the VM.

Create an agent policy to manage the Ops Agent

Command-line

To create an agent policy, use the gcloud compute instances ops-agents policies create command. This command has the following structure:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone ZONE \
  --file path/to/policy-description-file.yaml \
  --project PROJECT_ID

When using this command, replace the variables as follows:

For information about the other commands in the command group and the available options, see the gcloud compute instances ops-agents policies documentation.

Describe agent policies

You provide policy information to the gcloud compute instances ops-agents policies create by creating a YAML file that describes the policy and passing that file to the command as the value of the --file option.

This section describes the structure of the policy-description file. For additional information, see Example policy-description files.

Format of the YAML policy-description file

The description file for an agent policy must include two field groups:

Structure of the agentsRule field group

The agentsRule field group has the following structure:

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y

Structure of the instanceFilter field group

The instanceFilter field group indicates the VMs in a zone to which the filter applies. This field group is a YAML representation of the InstanceFilter structure used by the OSPolicyAssignment resource in the OS Config API.

The instanceFilter field group has one of the following structures:

  • To apply the agent policy to all VMs in a zone, use the following: 
        instanceFilter:
      all: True
     If you use the all: True filter, then you can't specify any other criteria.
  • To apply the agent policy to a specific set of VMs in a zone, describe the VMs by using a combination of any of the following: For example, the following filter applies the agent policy to the VMs with the specified operating systems that have the label "env=prod" and don't have the label "app=web": 
        instanceFilter:
      inclusionLabels:
      - labels:
          env: prod
      exclusionLabels:
      - labels:
          app: web
      inventories:
      - osShortName: rhel
        osVersion: '7.*'
      - osShortName: debian
        osVersion: '11'
     For information about finding the operating-system values, see Find operating system information.

    • Enable the Cloud Logging API, the Cloud Monitoring API, and the OS Config API for the project.

    If the OS Config API was not already enabled, it is enabled in limited-feature mode, which is sufficient for managing agent policies. For more information, see Pricing.

  • Grant the Identity and Access Management roles Logs Writer (roles/logging.logWriter) and Monitoring Metric Writer (roles/monitoring.metricWriter) to the Compute Engine default service account so that the agents can write logs and metrics to the Logging and Cloud Monitoring APIs.

  • Enable the OS Config metadata for the project so that the OS Config agent on each VM is active.

    • Grant one of the following IAM roles to the non-owner users user or service account needed to create and manage policies. Project owners have full access to create and manage policies; all other users or service accounts must be granted one of the following roles:

    When running the script, you can specify the OSPolicyAssignment roles as admin, editor, or viewer. The script maps those values to the roles/osconfig.osPolicyAssignment* role names.

    The following examples show some common invocations for the script. For more information, see the comments in the script itself.

    To enable the APIs, grant the necessary roles to the default service account, and enable the OS Config metadata for a project, run the script as follows:

    bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID

    To additionally grant one of the OS Config roles to a user who does not have the Owner (roles/owner) role on the project, run the script as follows:

    bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

    To additionally grant one of the OS Config roles to a non-default service account, run the script as follows:

    bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

    The diagnose_policies.sh script

    Given a project ID, a Compute Engine instance ID, a Compute Engine zone, and the agent policy ID, the diagnose_policies.sh script automatically collects the necessary information to help diagnose issues with the policy:

    To invoke the script, run the following command:

    bash diagnose_policies.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID \
  --zone=ZONE

    Pricing

    The gcloud compute instances ops-agents policies commands are implemented by using OS policy assignment resources from VM Manager. The prepare-for-ops-agents-policies.sh script, described in Before you begin, sets up VM Manager in limited-feature mode (OSCONFIG_B), which is sufficient for creating and managing agent policies. There is no cost to use VM Manager in limited mode.

    If you have configured VM Manager in full-feature mode (OSCONFIG_C), then you might incur costs.