Creating a guest policy

Use guest policies to maintain consistent software configurations across VM instances.

To set up a guest policy on a set of VMs, complete the following steps:

  1. Assign the required permissions to users.
  2. Set up your VM.
  3. Configure the guest policy JSON or YAML file.
  4. Create the guest policy.

Before you begin

Supported operating systems

  • Debian 9 and 10
  • Ubuntu 16.04 and 18.04+
  • Centos 6 and 7
  • Red Hat Enterprise Linux (RHEL) 6, 7, and 8
  • Windows Server 2012R2, 2016, 2019, and semi-annual releases 1803, 1809, and 1903
  • SUSE Enterprise Linux Server (SLES) 12 and 15

Limitations

  • All instances targeted by a guest policy are updated each time the agent checks in with the service. This check happens every 10 to 15 minutes.
  • There are no compliance dashboards, notifications, or alerting services available with this beta. VMs that are not running the OS Config agent do not report failure. For best results, use this feature with the OS inventory management service or any other compliance monitoring tool.

Permissions

Because you can use guest policies to install and manage software packages on a VM, the creation and management of guest policies is equivalent to granting remote code execution access on a VM.

When you use guest policies, access is controlled using IAM permissions and is audit logged. However, the ability to execute code on the VM is still an option and can pose a potential security risk. To mitigate this, we recommend that you provide only the required access to each user.

Owners of a project have full access to create and manage policies. For all other users, you need to grant permissions. You can also set granular permissions and roles for a project.

The following roles are available:

  • GuestPolicy Admin (roles/osconfig.guestPolicyAdmin)
  • GuestPolicy Editor (roles/osconfig.guestPolicyEditor)
  • GuestPolicy Viewer (roles/osconfig.guestPolicyViewer)

For example, to grant a user admin access to guest policies, run the following command:

gcloud projects add-iam-policy-binding project-id \
    --member user:user-id@gmail.com \
    --role roles/osconfig.guestPolicyAdmin

Replace the following:

  • project-id: Your project ID.
  • user-id: Your G Suite username.

Setting up your VM

To use the OS patch management service, you need to set up the OS Config service API and install the OS Config agent. For detailed instructions, see Managing your operating systems.

Configuring a guest policy yaml or JSON file

You must provide guest policy specifications by using either a JSON or YAML file. To view sample configurations, see example guest policy YAML files.

The YAML or JSON file contains the following two main sections:

Assignments

You can assign guest policies to all the VM instances in your project or you can use the assignment key in your JSON or YAML file to target a specific group of VMs.

For example, you can target a group of VMs by using any of the following characteristics:

To assign a guest policy using operating system information, the OS Configuration agent must send operating system information to the guest attributes endpoint for the VM. To ensure privacy, by default, operating system information for VMs is unavailable. To group by operating system information, you must ensure that guest attributes and OS Inventory Management is enabled. See enabling the Systems Management service.

Guest policy configurations are automatically applied to all new VMs that match the assignment.

Required configuration

The required configuration can be accomplished by using any or a combination of the following tasks:

Example guest policy YAML files

Example 1

Install a package my-package that must be kept up to date on the following VM instances: my-instance-1 and my-instance-2.

assignment:
  instances:
  - zones/us-east1-c/instances/my-instance-1
  - zones/us-east1-c/instances/my-instance-2
packages:
- name: "my-package"
  desiredState: UPDATED

For more information about assigning guest policies for packages, see the Package JSON representation refrence document.

Example 2

Install the Stackdriver Monitoring agent, using the yum package manager, on all VM instances that have either of the following instance name prefix: test-instance- or dev-instance-.

assignment:
  instanceNamePrefixes:
  - "test-instance-"
  - "dev-instance-"
packages:
- name: "stackdriver-agent"
  desiredState: INSTALLED
  manager: YUM
packageRepositories:
- yum:
    id: google-cloud-monitoring
    displayName: "Google Cloud Monitoring Agent Repository"
    baseUrl: https://packages.cloud.google.com/yum/repos/google-cloud-monitoring-el7-x86_64
    gpgKeys:
    - https://packages.cloud.google.com/yum/doc/yum-key.gpg
    - https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg

For more information about assigning guest policies for pacakage repositories, see the PackageRepository JSON representation refrence document.

Example 3

Install my-package and remove bad-package-1 and bad-package-2 from instances with a specific set of labels. Also add repositories for the apt and yum package managers.

assignment:
  # Assign to VM instances where `(label.color=red AND label.env=test) OR (label.color=blue AND label.env=test)`
  groupLabels:
  - labels:
      color: red
      env: test
  - labels:
      color: blue
      env: test
packages:
- name: "my-package"
  desiredState: INSTALLED
- name: "bad-package-1"
  desiredState: REMOVED
- name: "bad-package-2"
  desiredState: REMOVED
  manager: APT  # Only apply this to systems with APT.
packageRepositories:
- apt:  # Only apply this to systems with APT.
    uri: "https://packages.cloud.google.com/apt"
    archiveType: DEB
    distribution: cloud-sdk-stretch
    components:
    - main
- yum:  # Only apply this to systems with YUM.
    id: google-cloud-sdk
    displayName: "Google Cloud SDK"
    baseUrl: https://packages.cloud.google.com/yum/repos/cloud-sdk-el7-x86_64
    gpgKeys:
    - https://packages.cloud.google.com/yum/doc/yum-key.gpg
    - https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg

Example 4

Installs software from an MSI hosted on Cloud Storage to all instances in us-east1-b and us-east1-d.

assignment:
  zones:
  - us-east1-b
  - us-east1-d
recipes:
- name: "swr-msi-gcs"
  desiredState: INSTALLED
  artifacts:
  - id: "the-msi"
    gcs:
      bucket: "my-bucket"
      object: "executable.msi"  # full URI gs://my-bucket/executable.msi#nnnnn
      generation: 1546030865175603
  installSteps:
  - msiInstallation:

For more information about configuring recipe policies, see the SoftwareRecipe JSON representation refrence document.

Example 5

Install software by running an inline script on all VM instances that meet the following requirements:

  • Operating system: Red Hat Enterprise Linux 7
  • Label: color=red
assignment:
  osTypes:
  - osShortName: rhel
    osVersion: "7"
  groupLabels:
  - labels:
      color: red
recipes:
- name: recipe-runscript
  desiredState: INSTALLED
  installSteps:
  - scriptRun:
      script: |-
        #!/bin/bash
        touch /TOUCH_FILE

For more information about configuring recipe policies, see the SoftwareRecipe JSON representation refrence document.

Creating a guest policy

You can create a guest policy by using either the gcloud command-line tool, or the Cloud OS Config API.

When you create a guest policy, the name of the guest policy must meet the following naming requirements:

  • Contain only lowercase letters, numbers, and hyphens
  • Start with a letter
  • End with a number or a letter
  • Be between 1 and 63 characters
  • Each policy ID must be unique within a project

In the gcloud command-line tool and the Cloud OS Config API, the name of the guest policy name is referred to as the policy-id.

gcloud

Use the os-config guest-policies create command to create a guest policy.

gcloud beta compute os-config guest-policies create policy-id \
    --file=file

Replace the following:

  • policy-id: The name for the guest policy that you want to create.
  • file: The JSON or YAML file that contains the guest policy specifications. To view sample configurations, see Example guest policy YAML files.

API

In the API, create a POST request to the projects.guestPolicies.create method.

POST https://osconfig.googleapis.com/v1beta/projects/project-id/guestPolicies?guestPolicyId=policy-id

{
 For more information, see Guest policy JSON
}

Replace the following:

  • project-id: Your project ID.
  • policy-id: The name for your guest policy.

To view sample configurations, see example guest policy YAML files.

What's next?