OS policy and OS policy assignment

An OS policy is a file that contains the declarative configuration for OS resources such as packages, repositories, files, or custom resources defined by scripts.

An OS policy assignment is an API resource that is used by VM Manager to apply OS policies to VMs.

OS policy

An OS policy is a JSON or YAML file that has three sections:

Mode. The policy behavior. The following two modes are available:
- Validation: for this mode, the policy checks to see if the resources are in the desired state but doesn't take any action.
- Enforcement: for this mode, the policy checks to see if the resources are in the desired state and, if not, performs the necessary actions to bring them to that desired state.
For both modes, VM Manager reports compliance for the OS policy and the associated resources.
Resource groups. The operating system name and version that the associated resource specifications apply to. For example, you can define a single policy to install or deploy an agent across different operating system distributions and versions.
Resources. The specifications needed for the VM to attain the desired configuration. The following resource types are supported for this preview release:
- pkg: used for installing or removing Linux and Windows packages
- repository: used for specifying which repository software packages can be installed from
- exec: used to enable the running of an ad hoc bash or PowerShell script
- file: used to manage files on the system

Example OS policies

The following examples show how to create OS policies. You can upload these OS policies to the Google Cloud Console when creating an OS policy assignment.

Example 1: installs a package
Example 2: runs a script
Example 3: specifies a download repository and installs packages from that repository.

For a full list of sample OS policies that you can apply in your environment, see the GoogleCloudPlatform/osconfig GitHub repository.

Example 1

Create an OS policy that installs a Windows MSI downloaded from a Cloud Storage bucket.

examples/OSPolicyAssignments/console/install_msi_windows_all.yaml

View on GitHub

# An OS policy to install a Windows MSI downloaded from a Google Cloud Storage bucket.
id: install-msi-policy
mode: ENFORCEMENT
resourceGroups:
  - resources:
      - id: install-msi
        pkg:
          desiredState: INSTALLED
          msi:
            source:
              gcs:
                bucket: my-bucket
                object: my-app.msi
                generation: 1619136883923956

Example 2

Create an OS policy that verifies if the Apache web server is running on your Linux VMs.

examples/OSPolicyAssignments/console/exec_script_linux_all.yaml

View on GitHub

# An OS policy that ensures Apache web server is running on Linux OSes.
id: apache-always-up-policy
mode: ENFORCEMENT
resourceGroups:
  - resources:
      id: ensure-apache-is-up
      exec:
        validate:
          interpreter: SHELL
          # If Apache web server is already running, return an exit code 100 to indicate
          # that exec resource is already in desired state. In this scenario,
          # the `enforce` step will not be run.
          # Otherwise return an exit code of 101 to indicate that exec resource is not in
          # desired state. In this scenario, the `enforce` step will be run.
          script: if systemctl is-active --quiet httpd; then exit 100; else exit 101; fi
        enforce:
          interpreter: SHELL
          # Start Apache web server and return an exit code of 100 to indicate that the
          # resource is now in its desired state.
          script: systemctl start httpd && exit 100

Example 3

Create an OS policy for Google Cloud's operations suite that installs monitoring and logging agents on Red Hat Enterprise Linux (RHEL) and CentOS VMs.

examples/OSPolicyAssignments/console/setup_repo_and_install_package_linux_yum.yaml

View on GitHub

# An OS policy to set up the Google Cloud Monitoring repository and
# install the Stackdriver agent for VMs running either Red Hat Enterprise Linux and CentOS OSes.
id: setup-repo-and-install-package-policy
mode: ENFORCEMENT
resourceGroups:
  - resources:
      - id: setup-repo
        repository:
          yum:
            id: google-cloud-monitoring
            displayName: Google Cloud Monitoring Agent Repository
            baseUrl: https://packages.cloud.google.com/yum/repos/google-cloud-monitoring-el8-x86_64-all
            gpgKeys:
              - https://packages.cloud.google.com/yum/doc/yum-key.gpg
              - https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
      - id: install-pkg
        pkg:
          desiredState: INSTALLED
          yum:
            name: stackdriver-agent

OS policy assignment

An OS policy assignment has the following sections:

OS Policies. One or more OS policies that you want to apply to your VM. To download or create a policy, see OS policies.
Target VMs. A set of VMs within a single zone that you want to apply the policy to. Within a zone you can limit or restrict VMs by using OS families and include or exclude labels. You can select a combination of the following options:
- OS families: specifies the target operating systems that the OS policy applies to. For a full list of operating systems and versions that support OS configuration management (OS policies), see Operating system details.
- Include set: specifies the VMs that the OS policy applies to based on VM or system labels.
- Exclude set: specifies the VMs that the OS policy should ignore based on VM or system labels.
For both include and exclude label sets, a single string label is accepted if it matches the naming convention used by the system. However, most labels are specified in key:value pairs. For more information about labels, see Labeling resources.

For example, you can select all the Ubuntu VMs in your test environment, and exclude those that are running Google Kubernetes Engine, by specifying the following:
- OS family: ubuntu
- Include: env:test, env:staging
- Exclude: goog-gke-node
A rollout rate. Specifies the pace at which to apply the OS policies to the VMs. The OS policies are rolled out gradually to let you track system health and make modifications if the updates cause regressions in your environment. A rollout plan has the following components:
- Disruption budget: the fixed number or percentage of VMs that can experience a rollout at one time. This means that at any moment of the rollout only a specified number of VMs are targeted.
- Wait time: the time between when the service applies policies to the VM and when a VM is removed from the disruption threshold. For example, a wait time of 15 minutes means that the rollout process must wait 15 minutes after applying the policies to a VM before it can remove the VM from the disruption threshold and the rollout can proceed. The wait time helps control the speed of a rollout and also lets you catch and resolve potential rollout issues early. Select a time that is long enough for you to monitor the status of your rollouts.
For example, if you set a target of 10 VMs, set the disruption threshold at 20%, and set a bake time of 15 minutes, then at any given time, only 2 VMs are scheduled to be updated. After each VM is updated, 15 minutes must pass before the VM is removed from the disruption threshold and another VM is added to the rollout.

For more information about rollouts, see Rollouts.

Example OS policy assignment

The following examples show how to create OS policy assignments. You can use these examples to create OS policy assignments from the gcloud command-line tool or the OS Config API.

Example 1: installs a package
Example 2: runs a script
Example 3: specifies a download repository and installs packages from that repository.

For a list of sample OS policy assignments that you can apply in your environment, see the GoogleCloudPlatform/osconfig GitHub repository.

Example 1

Create an OS policy assignment that installs a Windows MSI downloaded from a Cloud Storage bucket.

examples/OSPolicyAssignments/gcloud/install_msi_windows_all.yaml

View on GitHub

# An OS policy assignment to install a Windows MSI downloaded from a Google Cloud Storage bucket on all VMs running Windows Server OS.
osPolicies:
  - id: install-msi-policy
    mode: ENFORCEMENT
    resourceGroups:
      - resources:
          - id: install-msi
            pkg:
              desiredState: INSTALLED
              msi:
                source:
                  gcs:
                    bucket: my-bucket
                    object: my-app.msi
                    generation: 1619136883923956
instanceFilter:
  osShortNames:
    - windows
rollout:
  disruptionBudget:
    fixed: 10
  minWaitDuration: 300s

Example 2

Create an OS policy assignment that verifies if the Apache web server is running on all your Linux VMs.

examples/OSPolicyAssignments/gcloud/exec_script_linux_all.yaml

View on GitHub

# An OS policy assignment that ensures Apache web server is running on Linux OSes.
# The assignment is applied only to those VMs that have the label `type:webserver` assigned to them.
osPolicies:
  - id: apache-always-up-policy
    mode: ENFORCEMENT
    resourceGroups:
      - resources:
          id: ensure-apache-is-up
          exec:
            validate:
              interpreter: SHELL
              # If Apache web server is already running, return an exit code 100 to indicate
              # that exec resource is already in desired state. In this scenario,
              # the `enforce` step will not be run.
              # Otherwise return an exit code of 101 to indicate that exec resource is not in
              # desired state. In this scenario, the `enforce` step will be run.
              script: if systemctl is-active --quiet httpd; then exit 100; else exit 101; fi
            enforce:
              interpreter: SHELL
              # Start Apache web server and return an exit code of 100 to indicate that the
              # resource is now in its desired state.
              script: systemctl start httpd && exit 100
instanceFilter:
  inclusionLabels:
    - labels:
        type: webserver
rollout:
  disruptionBudget:
    fixed: 10
  minWaitDuration: 300s

Example 3

Create an OS policy assignment for Google Cloud's operations suite that installs monitoring and logging agents on Red Hat Enterprise Linux (RHEL) and CentOS VMs.

examples/OSPolicyAssignments/gcloud/setup_repo_and_install_package_linux_yum.yaml

View on GitHub

# An OS policy assignment to set up the Google Cloud Monitoring repository and
# install the Stackdriver agent for VMs running either Red Hat Enterprise Linux and CentOS OSes.
osPolicies:
  - id: setup-repo-and-install-package-policy
    mode: ENFORCEMENT
    resourceGroups:
      - resources:
          - id: setup-repo
            repository:
              yum:
                id: google-cloud-monitoring
                displayName: Google Cloud Monitoring Agent Repository
                baseUrl: https://packages.cloud.google.com/yum/repos/google-cloud-monitoring-el8-x86_64-all
                gpgKeys:
                  - https://packages.cloud.google.com/yum/doc/yum-key.gpg
                  - https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
          - id: install-pkg
            pkg:
              desiredState: INSTALLED
              yum:
                name: stackdriver-agent
instanceFilter:
  osShortNames:
    - rhel
    - centos
rollout:
  disruptionBudget:
    fixed: 10
  minWaitDuration: 300s

What's next?

Learn more about OS configuration management (preview).
Create an OS policy assignment.
Manage OS policies.