REST Resource: projects.locations.osPolicyAssignments

Resource: OSPolicyAssignment

OS policy assignment is an API resource that is used to apply a set of OS policies to a dynamically targeted group of Compute Engine VM instances.

An OS policy is used to define the desired state configuration for a Compute Engine VM instance through a set of configuration resources that provide capabilities such as installing or removing software packages, or executing a script.

For more information, see OS policy and OS policy assignment.

JSON representation
{
  "name": string,
  "description": string,
  "osPolicies": [
    {
      object (OSPolicy)
    }
  ],
  "instanceFilter": {
    object (InstanceFilter)
  },
  "rollout": {
    object (Rollout)
  },
  "revisionId": string,
  "revisionCreateTime": string,
  "rolloutState": enum (RolloutState),
  "baseline": boolean,
  "deleted": boolean,
  "reconciling": boolean,
  "uid": string
}
Fields
name

string

Resource name.

Format: projects/{project_number}/locations/{location}/osPolicyAssignments/{osPolicyAssignmentId}

This field is ignored when you create an OS policy assignment.

description

string

OS policy assignment description. Length of the description is limited to 1024 characters.

osPolicies[]

object (OSPolicy)

Required. List of OS policies to be applied to the VMs.

instanceFilter

object (InstanceFilter)

Required. Filter to select VMs.

rollout

object (Rollout)

Required. Rollout to deploy the OS policy assignment. A rollout is triggered in the following situations: 1) OSPolicyAssignment is created. 2) OSPolicyAssignment is updated and the update contains changes to one of the following fields: - instanceFilter - osPolicies 3) OSPolicyAssignment is deleted.

revisionId

string

Output only. The assignment revision ID A new revision is committed whenever a rollout is triggered for a OS policy assignment

revisionCreateTime

string (Timestamp format)

Output only. The timestamp that the revision was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

rolloutState

enum (RolloutState)

Output only. OS policy assignment rollout state

baseline

boolean

Output only. Indicates that this revision has been successfully rolled out in this zone and new VMs will be assigned OS policies from this revision.

For a given OS policy assignment, there is only one revision with a value of true for this field.

deleted

boolean

Output only. Indicates that this revision deletes the OS policy assignment.

reconciling

boolean

Output only. Indicates that reconciliation is in progress for the revision. This value is true when the rolloutState is one of: * IN_PROGRESS * CANCELLING

uid

string

Output only. Server generated unique id for the OS policy assignment resource.

OSPolicy

An OS policy defines the desired state configuration for a VM.

JSON representation
{
  "id": string,
  "description": string,
  "mode": enum (Mode),
  "resourceGroups": [
    {
      object (ResourceGroup)
    }
  ],
  "allowNoResourceGroupMatch": boolean
}
Fields
id

string

Required. The id of the OS policy with the following restrictions:

  • Must contain only lowercase letters, numbers, and hyphens.
  • Must start with a letter.
  • Must be between 1-63 characters.
  • Must end with a number or a letter.
  • Must be unique within the assignment.
description

string

Policy description. Length of the description is limited to 1024 characters.

mode

enum (Mode)

Required. Policy mode

resourceGroups[]

object (ResourceGroup)

Required. List of resource groups for the policy. For a particular VM, resource groups are evaluated in the order specified and the first resource group that is applicable is selected and the rest are ignored.

If none of the resource groups are applicable for a VM, the VM is considered to be non-compliant w.r.t this policy. This behavior can be toggled by the flag allowNoResourceGroupMatch

allowNoResourceGroupMatch

boolean

This flag determines the OS policy compliance status when none of the resource groups within the policy are applicable for a VM. Set this value to true if the policy needs to be reported as compliant even if the policy has nothing to validate or enforce.

Mode

Policy mode

Enums
MODE_UNSPECIFIED Invalid mode
VALIDATION This mode checks if the configuration resources in the policy are in their desired state. No actions are performed if they are not in the desired state. This mode is used for reporting purposes.
ENFORCEMENT This mode checks if the configuration resources in the policy are in their desired state, and if not, enforces the desired state.

ResourceGroup

Resource groups provide a mechanism to group OS policy resources.

Resource groups enable OS policy authors to create a single OS policy to be applied to VMs running different operating Systems.

When the OS policy is applied to a target VM, the appropriate resource group within the OS policy is selected based on the OSFilter specified within the resource group.

JSON representation
{
  "osFilter": {
    object (OSFilter)
  },
  "resources": [
    {
      object (Resource)
    }
  ]
}
Fields
osFilter

object (OSFilter)

Used to specify the OS filter for a resource group

resources[]

object (Resource)

Required. List of resources configured for this resource group. The resources are executed in the exact order specified here.

OSFilter

The OSFilter is used to specify the OS filtering criteria for the resource group.

JSON representation
{
  "osShortName": string,
  "osVersion": string
}
Fields
osShortName

string

This should match OS short name emitted by the OS inventory agent. An empty value matches any OS.

osVersion

string

This value should match the version emitted by the OS inventory agent. Prefix matches are supported if asterisk(*) is provided as the last character. For example, to match all versions with a major version of 7, specify the following value for this field 7.*

Resource

An OS policy resource is used to define the desired state configuration and provides a specific functionality like installing/removing packages, executing a script etc.

The system ensures that resources are always in their desired state by taking necessary actions if they have drifted from their desired state.

JSON representation
{
  "id": string,

  // Union field resource_type can be only one of the following:
  "pkg": {
    object (PackageResource)
  },
  "repository": {
    object (RepositoryResource)
  },
  "exec": {
    object (ExecResource)
  },
  "file": {
    object (FileResource)
  }
  // End of list of possible types for union field resource_type.
}
Fields
id

string

Required. The id of the resource with the following restrictions:

  • Must contain only lowercase letters, numbers, and hyphens.
  • Must start with a letter.
  • Must be between 1-63 characters.
  • Must end with a number or a letter.
  • Must be unique within the OS policy.
Union field resource_type. Resource type. resource_type can be only one of the following:
pkg

object (PackageResource)

Package resource

repository

object (RepositoryResource)

Package repository resource

exec

object (ExecResource)

Exec resource

file

object (FileResource)

File resource

PackageResource

A resource that manages a system package.

JSON representation
{
  "desiredState": enum (DesiredState),

  // Union field system_package can be only one of the following:
  "apt": {
    object (APT)
  },
  "deb": {
    object (Deb)
  },
  "yum": {
    object (YUM)
  },
  "zypper": {
    object (Zypper)
  },
  "rpm": {
    object (RPM)
  },
  "googet": {
    object (GooGet)
  },
  "msi": {
    object (MSI)
  }
  // End of list of possible types for union field system_package.
}
Fields
desiredState

enum (DesiredState)

Required. The desired state the agent should maintain for this package.

Union field system_package. A system package. system_package can be only one of the following:
apt

object (APT)

A package managed by Apt.

deb

object (Deb)

A deb package file.

yum

object (YUM)

A package managed by YUM.

zypper

object (Zypper)

A package managed by Zypper.

rpm

object (RPM)

An rpm package file.

googet

object (GooGet)

A package managed by GooGet.

msi

object (MSI)

An MSI package.

DesiredState

The desired state that the OS Config agent maintains on the VM.

Enums
DESIRED_STATE_UNSPECIFIED Unspecified is invalid.
INSTALLED Ensure that the package is installed.
REMOVED The agent ensures that the package is not installed and uninstalls it if detected.

APT

A package managed by APT. - install: apt-get update && apt-get -y install [name] - remove: apt-get -y remove [name]

JSON representation
{
  "name": string
}
Fields
name

string

Required. Package name.

Deb

A deb package file. dpkg packages only support INSTALLED state.

JSON representation
{
  "source": {
    object (File)
  },
  "pullDeps": boolean
}
Fields
source

object (File)

Required. A deb package.

pullDeps

boolean

Whether dependencies should also be installed. - install when false: dpkg -i package - install when true: apt-get update && apt-get -y install package.deb

File

A remote or local file.

JSON representation
{
  "allowInsecure": boolean,

  // Union field type can be only one of the following:
  "remote": {
    object (Remote)
  },
  "gcs": {
    object (Gcs)
  },
  "localPath": string
  // End of list of possible types for union field type.
}
Fields
allowInsecure

boolean

Defaults to false. When false, files are subject to validations based on the file type:

Remote: A checksum must be specified. Cloud Storage: An object generation number must be specified.

Union field type. A specific type of file. type can be only one of the following:
remote

object (Remote)

A generic remote file.

gcs

object (Gcs)

A Cloud Storage object.

localPath

string

A local path within the VM to use.

Remote

Specifies a file available via some URI.

JSON representation
{
  "uri": string,
  "sha256Checksum": string
}
Fields
uri

string

Required. URI from which to fetch the object. It should contain both the protocol and path following the format {protocol}://{location}.

sha256Checksum

string

SHA256 checksum of the remote file.

Gcs

Specifies a file available as a Cloud Storage Object.

JSON representation
{
  "bucket": string,
  "object": string,
  "generation": string
}
Fields
bucket

string

Required. Bucket of the Cloud Storage object.

object

string

Required. Name of the Cloud Storage object.

generation

string (int64 format)

Generation number of the Cloud Storage object.

YUM

A package managed by YUM. - install: yum -y install package - remove: yum -y remove package

JSON representation
{
  "name": string
}
Fields
name

string

Required. Package name.

Zypper

A package managed by Zypper. - install: zypper -y install package - remove: zypper -y rm package

JSON representation
{
  "name": string
}
Fields
name

string

Required. Package name.

RPM

An RPM package file. RPM packages only support INSTALLED state.

JSON representation
{
  "source": {
    object (File)
  },
  "pullDeps": boolean
}
Fields
source

object (File)

Required. An rpm package.

pullDeps

boolean

Whether dependencies should also be installed. - install when false: rpm --upgrade --replacepkgs package.rpm - install when true: yum -y install package.rpm or zypper -y install package.rpm

GooGet

A package managed by GooGet. - install: googet -noconfirm install package - remove: googet -noconfirm remove package

JSON representation
{
  "name": string
}
Fields
name

string

Required. Package name.

MSI

An MSI package. MSI packages only support INSTALLED state.

JSON representation
{
  "source": {
    object (File)
  },
  "properties": [
    string
  ]
}
Fields
source

object (File)

Required. The MSI package.

properties[]

string

Additional properties to use during installation. This should be in the format of Property=Setting. Appended to the defaults of ACTION=INSTALL REBOOT=ReallySuppress.

RepositoryResource

A resource that manages a package repository.

JSON representation
{

  // Union field repository can be only one of the following:
  "apt": {
    object (AptRepository)
  },
  "yum": {
    object (YumRepository)
  },
  "zypper": {
    object (ZypperRepository)
  },
  "goo": {
    object (GooRepository)
  }
  // End of list of possible types for union field repository.
}
Fields
Union field repository. A specific type of repository. repository can be only one of the following:
apt

object (AptRepository)

An Apt Repository.

yum

object (YumRepository)

A Yum Repository.

zypper

object (ZypperRepository)

A Zypper Repository.

goo

object (GooRepository)

A Goo Repository.

AptRepository

Represents a single apt package repository. These will be added to a repo file that will be managed at /etc/apt/sources.list.d/google_osconfig.list.

JSON representation
{
  "archiveType": enum (ArchiveType),
  "uri": string,
  "distribution": string,
  "components": [
    string
  ],
  "gpgKey": string
}
Fields
archiveType

enum (ArchiveType)

Required. Type of archive files in this repository.

uri

string

Required. URI for this repository.

distribution

string

Required. Distribution of this repository.

components[]

string

Required. List of components for this repository. Must contain at least one item.

gpgKey

string

URI of the key file for this repository. The agent maintains a keyring at /etc/apt/trusted.gpg.d/osconfig_agent_managed.gpg.

ArchiveType

Type of archive.

Enums
ARCHIVE_TYPE_UNSPECIFIED Unspecified is invalid.
DEB Deb indicates that the archive contains binary files.
DEB_SRC Deb-src indicates that the archive contains source files.

YumRepository

Represents a single yum package repository. These are added to a repo file that is managed at /etc/yum.repos.d/google_osconfig.repo.

JSON representation
{
  "id": string,
  "displayName": string,
  "baseUrl": string,
  "gpgKeys": [
    string
  ]
}
Fields
id

string

Required. A one word, unique name for this repository. This is the repo id in the yum config file and also the displayName if displayName is omitted. This id is also used as the unique identifier when checking for resource conflicts.

displayName

string

The display name of the repository.

baseUrl

string

Required. The location of the repository directory.

gpgKeys[]

string

URIs of GPG keys.

ZypperRepository

Represents a single zypper package repository. These are added to a repo file that is managed at /etc/zypp/repos.d/google_osconfig.repo.

JSON representation
{
  "id": string,
  "displayName": string,
  "baseUrl": string,
  "gpgKeys": [
    string
  ]
}
Fields
id

string

Required. A one word, unique name for this repository. This is the repo id in the zypper config file and also the displayName if displayName is omitted. This id is also used as the unique identifier when checking for GuestPolicy conflicts.

displayName

string

The display name of the repository.

baseUrl

string

Required. The location of the repository directory.

gpgKeys[]

string

URIs of GPG keys.

GooRepository

Represents a Goo package repository. These are added to a repo file that is managed at C:/ProgramData/GooGet/repos/google_osconfig.repo.

JSON representation
{
  "name": string,
  "url": string
}
Fields
name

string

Required. The name of the repository.

url

string

Required. The url of the repository.

ExecResource

A resource that allows executing scripts on the VM.

The ExecResource has 2 stages: validate and enforce and both stages accept a script as an argument to execute.

When the ExecResource is applied by the agent, it first executes the script in the validate stage. The validate stage can signal that the ExecResource is already in the desired state by returning an exit code of 100. If the ExecResource is not in the desired state, it should return an exit code of 101. Any other exit code returned by this stage is considered an error.

If the ExecResource is not in the desired state based on the exit code from the validate stage, the agent proceeds to execute the script from the enforce stage. If the ExecResource is already in the desired state, the enforce stage will not be run. Similar to validate stage, the enforce stage should return an exit code of 100 to indicate that the resource in now in its desired state. Any other exit code is considered an error.

NOTE: An exit code of 100 was chosen over 0 (and 101 vs 1) to have an explicit indicator of in desired state, not in desired state and errors. Because, for example, Powershell will always return an exit code of 0 unless an exit statement is provided in the script. So, for reasons of consistency and being explicit, exit codes 100 and 101 were chosen.

JSON representation
{
  "validate": {
    object (Exec)
  },
  "enforce": {
    object (Exec)
  }
}
Fields
validate

object (Exec)

Required. What to run to validate this resource is in the desired state. An exit code of 100 indicates "in desired state", and exit code of 101 indicates "not in desired state". Any other exit code indicates a failure running validate.

enforce

object (Exec)

What to run to bring this resource into the desired state. An exit code of 100 indicates "success", any other exit code indicates a failure running enforce.

Exec

A file or script to execute.

JSON representation
{
  "args": [
    string
  ],
  "interpreter": enum (Interpreter),
  "outputFilePath": string,

  // Union field source can be only one of the following:
  "file": {
    object (File)
  },
  "script": string
  // End of list of possible types for union field source.
}
Fields
args[]

string

Optional arguments to pass to the source during execution.

interpreter

enum (Interpreter)

Required. The script interpreter to use.

outputFilePath

string

Only recorded for enforce Exec. Path to an output file (that is created by this Exec) whose content will be recorded in OSPolicyResourceCompliance after a successful run. Absence or failure to read this file will result in this ExecResource being non-compliant. Output file size is limited to 100K bytes.

Union field source. What to execute. source can be only one of the following:
file

object (File)

A remote or local file.

script

string

An inline script. The size of the script is limited to 1024 characters.

Interpreter

The interpreter to use.

Enums
INTERPRETER_UNSPECIFIED Defaults to NONE.
NONE

If an interpreter is not specified, the source is executed directly. This execution, without an interpreter, only succeeds for executables and scripts that have shebang lines.

SHELL Indicates that the script runs with /bin/sh on Linux and cmd.exe on Windows.
POWERSHELL Indicates that the script runs with PowerShell.

FileResource

A resource that manages the state of a file.

JSON representation
{
  "path": string,
  "state": enum (DesiredState),
  "permissions": string,

  // Union field source can be only one of the following:
  "file": {
    object (File)
  },
  "content": string
  // End of list of possible types for union field source.
}
Fields
path

string

Required. The absolute path of the file within the VM.

state

enum (DesiredState)

Required. Desired state of the file.

permissions