REST 资源:projects.guestPolicies

资源:GuestPolicy

一种表示客机配置政策的 OS Config 资源。这些政策表示虚拟机实例客机环境所需的状态,包括要安装或移除的软件包、软件包代码库配置以及要安装的软件。

JSON 表示法

{
      "name": string,
      "description": string,
      "createTime": string,
      "updateTime": string,
      "assignment": {
        object (Assignment)
      },
      "packages": [
        {
          object (Package)
        }
      ],
      "packageRepositories": [
        {
          object (PackageRepository)
        }
      ],
      "recipes": [
        {
          object (SoftwareRecipe)
        }
      ],
      "etag": string
    }
字段
name

string

必填。此项目中资源的唯一名称,采用以下格式之一:projects/{project_number}/guestPolicies/{guestPolicyId}

description

string

对客机政策的说明。说明的长度不得超过 1024 个字符。

createTime

string (Timestamp format)

仅限输出。此客机政策的创建时间。

此时间戳采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,精确到纳秒。示例:"2014-10-02T15:01:23.045123456Z"

updateTime

string (Timestamp format)

仅限输出。此客机政策上次更新的时间。

此时间戳采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,精确到纳秒。示例:"2014-10-02T15:01:23.045123456Z"

assignment

object (Assignment)

必填。指定分配给此政策的虚拟机实例。此字段允许您按标签、名称、操作系统或地区等不同参数定位一组虚拟机实例。

如果留空,则定位该政策下的所有虚拟机实例。

在资源层次结构中的同一级层(即在项目中),服务会阻止创建彼此冲突的多个政策。如需了解详情,请参阅服务如何处理分配冲突

packages[]

object (Package)

由此政策管理的软件包。

packageRepositories[]

object (PackageRepository)

需要在虚拟机实例上配置的软件包代码库的列表。此列表在应用任何其他配置之前填充,以使这些配置能够使用这些代码库。软件包代码库仅在对应的软件包管理器可用时才会配置。

recipes[]

object (SoftwareRecipe)

需要在虚拟机实例上安装的配方列表。

etag

string

此客机政策的 ETag。如果在更新时提供,则必须与服务器的 ETag 相匹配。

Assignment

Assignment 表示政策应用的一组或多组虚拟机实例。

如果 Assignment 为空,则应用于所有虚拟机实例。否则,目标虚拟机实例必须满足指定的所有条件。因此,如果同时指定了标签和地区,则此政策将应用于具有这些标签且位于这些地区的虚拟机实例。

JSON 表示法

{
      "groupLabels": [
        {
          object (GroupLabel)
        }
      ],
      "zones": [
        string
      ],
      "instances": [
        string
      ],
      "instanceNamePrefixes": [
        string
      ],
      "osTypes": [
        {
          object (OsType)
        }
      ]
    }
字段
groupLabels[]

object (GroupLabel)

定位至少匹配这些标签集之一的实例。这样,Assignment 就可以定位不同的组,例如“env=prod or env=staging”。

zones[]

string

定位上述任一地区中的实例。若留空,则定位任意地区中的实例。

按地区定位并不常见,这一支持是为了协调按地区的管理更改。

instances[]

string

定位指定的任何实例。实例按其 URI 指定,格式如下:zones/[ZONE]/instances/[INSTANCE_NAME]

实例定位并不常见,这一支持是为了协调按实例管理更改,或定位特定虚拟机实例以进行开发和测试。

仅支持项目级层政策,且必须引用此项目中的实例。

instanceNamePrefixes[]

string

定位名称以其中一个前缀开头的虚拟机实例。

与标签一样,这是在定位配置时对虚拟机实例进行分组的另一种方式,例如 prefix="prod-"。

仅支持项目级层政策。

osTypes[]

object (OsType)

定位至少与以下某种操作系统类型匹配的虚拟机实例。

虚拟机实例必须匹配要添加的给定 OsType 的所有提供条件。

GroupLabel

表示可被标识为包含所有这些标签的一组虚拟机实例,例如“env=prod and app=web”。

JSON 表示法

{
      "labels": {
        string: string,
        ...
      }
    }
字段
labels

map (key: string, value: string)

要添加到此 Assignment 组中的实例必须具有的 Google Compute Engine 实例标签。

包含一系列 "key": value 对的对象。示例:{ "name": "wrench", "mass": "1.3kg", "count": "3" }

OsType

定义按操作系统类型选择虚拟机实例的条件。

JSON 表示法

{
      "osShortName": string,
      "osVersion": string,
      "osArchitecture": string
    }
字段
osShortName

string

定位启用了 OS Inventory 且具有以下操作系统简称的虚拟机实例,例如“debian”或“windows”。

osVersion

string

定位启用了 OS Inventory 且具有以下操作系统版本的虚拟机实例。

osArchitecture

string

定位启用了 OS Inventory 且采用以下操作系统架构的虚拟机实例。

Package

Package 是对要安装或移除的软件包的引用。虚拟机实例上的代理使用系统软件包管理器来应用配置。

以下是代理用于安装或移除软件包的命令。

Apt 安装:apt-get update && apt-get -y install package1 package2 package3 移除:apt-get -y remove package1 package2 package3

Yum 安装:yum -y install package1 package2 package3 移除:yum -y remove package1 package2 package3

Zypper 安装:zypper install package1 package2 package3 移除:zypper rm package1 package2

Googet 安装:googet -noconfirm install package1 package2 package3 移除:googet -noconfirm remove package1 package2 package3

JSON 表示法

{
      "name": string,
      "desiredState": enum (DesiredState),
      "manager": enum (Manager)
    }
字段
name

string

必填。软件包的名称。通过检查软件包名称和软件包所定位的管理器可唯一标识软件包以进行冲突验证。

desiredState

enum (DesiredState)

代理应为此软件包维护的 desiredState。默认设置为确保软件包已安装。

manager

enum (Manager)

可用于安装此软件包的软件包管理器的类型。如果系统没有软件包管理器,则系统不会安装或移除软件包,也不会返回任何错误消息。默认情况下,或如果您指定 ANY,代理会尝试使用默认软件包管理器来安装和移除此软件包。在创建应用于不同类型系统的政策时,此字段非常有用。

默认值为 ANY。

DesiredState

OS Config 代理在虚拟机实例上维护的期望状态。

枚举
DESIRED_STATE_UNSPECIFIED 默认设置为确保软件包已安装。
INSTALLED 代理确保软件包已安装。
UPDATED 代理确保软件包已安装并定期检查并安装所有更新。
REMOVED 代理确保未安装此软件包,并在检测到时将其卸载。

Manager

可用于管理此软件包的软件包管理器的类型。

枚举
MANAGER_UNSPECIFIED 默认值为 ANY。
ANY 使用默认的系统软件包管理器应用此软件包配置。
APT 仅当系统中有可用的 Apt 时,才应用此软件包配置。
YUM 仅当系统中有可用的 Yum 时,才应用此软件包配置。
ZYPPER 仅当系统中有可用的 Zypper 时,才应用此软件包配置。
GOO 仅当系统中有可用的 GooGet 时,才应用此软件包配置。

PackageRepository

软件包代码库。

JSON 表示法

{

      // 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.
    }
字段
联合字段 repository。特定的代码库类型。repository 只能是下列其中一项:
apt

object (AptRepository)

Apt 代码库。

yum

object (YumRepository)

Yum 代码库。

zypper

object (ZypperRepository)

Zypper 代码库。

goo

object (GooRepository)

Goo 代码库。

AptRepository

表示单个 Apt 软件包代码库。此代码库会添加到存储在 /etc/apt/sources.list.d/google_osconfig.list 的代码库文件中。

JSON 表示法

{
      "archiveType": enum (ArchiveType),
      "uri": string,
      "distribution": string,
      "components": [
        string
      ],
      "gpgKey": string
    }
字段
archiveType

enum (ArchiveType)

此代码库中的归档文件的类型。默认值为 DEB。

uri

string

必填。此代码库的 URI。

distribution

string

必填。此代码库的分发。

components[]

string

必填。此代码库的组件列表。必须包含至少一项。

gpgKey

string

此代码库的密钥文件的 URI。代理在 /etc/apt/trusted.gpg.d/osconfig_agent_managed.gpg 维护一个密钥环,其中包含任何应用的客机政策中的所有密钥。

ArchiveType

归档类型。

枚举
ARCHIVE_TYPE_UNSPECIFIED 未指定。
DEB DEB 表示归档包含二进制文件。
DEB_SRC DEB_SRC 表示归档包含源文件。

YumRepository

表示单个 Yum 软件包代码库。此代码库会添加到存储在 /etc/yum.repos.d/google_osconfig.repo 的代码库文件中。

JSON 表示法

{
      "id": string,
      "displayName": string,
      "baseUrl": string,
      "gpgKeys": [
        string
      ]
    }
字段
id

string

必填。此代码库的唯一单字名称。这是 Yum 配置文件中的 repo id;如果 displayName 被省略,则为 displayName。在检查客机政策冲突时,此 ID 还用作唯一标识符。

displayName

string

代码库的显示名。

baseUrl

string

必填。代码库目录的位置。

gpgKeys[]

string

GPG 键的 URI。

ZypperRepository

表示单个 Zypper 软件包代码库。此代码库会添加到存储在 /etc/zypp/repos.d/google_osconfig.repo 的代码库文件中。

JSON 表示法

{
      "id": string,
      "displayName": string,
      "baseUrl": string,
      "gpgKeys": [
        string
      ]
    }
字段
id

string

必填。此代码库的唯一单字名称。这是 Zypper 配置文件中的 repo id;如果 displayName 被省略,则也是 displayName。在检查客机政策冲突时,此 ID 还用作唯一标识符。

displayName

string

代码库的显示名。

baseUrl

string

必填。代码库目录的位置。

gpgKeys[]

string

GPG 键的 URI。

GooRepository

表示一个 Goo 软件包代码库。此代码库会添加到存储在 C:/ProgramData/GooGet/repos/google_osconfig.repo 的代码库文件中。

JSON 表示法

{
      "name": string,
      "url": string
    }
字段
name

string

必填。代码库的名称。

url

string

必填。代码库的网址。

SoftwareRecipe

软件配方是一组用于安装和配置软件的说明。它包含一组已下载的工件,以及一组安装、配置和/或更新软件的步骤。

配方支持从下列格式的工件安装和更新软件:Zip 归档、Tar 归档、Windows MSI,Debian 软件包和 RPM 软件包。

此外,配方支持在 bash、sh、cmd 和 powershell 中执行脚本(在文件中定义或直接位于此 API 中)。

更新软件配方

如果将一个配方分配给某个实例,但其中已安装名称相同但版本较低的配方,且其分配状态为 INSTALLED_KEEP_UPDATED,则此配方将更新为新版本。

脚本工作目录

每个脚本或执行步骤都在其自己的临时目录中运行,该目录在完成步骤后会被删除。

JSON 表示法

{
      "name": string,
      "version": string,
      "artifacts": [
        {
          object (Artifact)
        }
      ],
      "installSteps": [
        {
          object (Step)
        }
      ],
      "updateSteps": [
        {
          object (Step)
        }
      ],
      "desiredState": enum (DesiredState)
    }
字段
name

string

必填。配方的唯一标识符。一个实例上只能安装一个具有给定名称的配方。

名称还用于识别有助于确定客机政策是否存在冲突的资源。也就是说,创建具有相同名称和版本的多个配方的请求会被拒绝,因为它们可能具有相互冲突的 Assignment。

version

string

此软件配方的版本。版本号最多可包含 4 个用英文句号分隔的数字(例如 12.34.56.78)。

artifacts[]

object (Artifact)

可用于配方中的步骤的资源。

installSteps[]

object (Step)

安装此配方需要执行的操作。如果失败,它将停止执行步骤,并且不会尝试另一次安装。所有已执行的步骤(包括部分完成的步骤)均不会回滚。

updateSteps[]

object (Step)

更新此配方需要执行的操作。如果失败,它将停止执行步骤,并且不会尝试再次更新此配方。所有已执行的步骤(包括部分完成的步骤)均不会回滚。

desiredState

enum (DesiredState)

默认值为 INSTALLED。代理应为此配方保持的期望状态。

INSTALLED:软件配方已安装在实例上,但不会更新到新版本。INSTALLED_KEEP_UPDATED:软件配方已安装在实例上。如果向此实例分配更高版本的配方,则配方会更新为更高版本。REMOVE:不支持移除软件配方,尝试创建 REMOVE 状态的配方或将配方更新为 REMOVE 状态会被拒绝。

Artifact

指定要在配方中使用的资源。

JSON 表示法

{
      "id": string,
      "allowInsecure": boolean,

      // Union field artifact can be only one of the following:
      "remote": {
        object (Remote)
      },
      "gcs": {
        object (Gcs)
      }
      // End of list of possible types for union field artifact.
    }
字段
id

string

必填。工件的 ID,可由配方的安装和更新步骤引用。一个配方中的工件不能具有相同的 ID。

allowInsecure

boolean

默认值为 false。如果为 false,则根据工件类型对配方进行验证:

Remote:必须指定校验和,且仅允许采用传输层安全协议。GCS:必须指定对象世代编号。

联合字段 artifact。特定的工件类型。artifact 只能是下列其中一项:
remote

object (Remote)

一般的远程工件。

gcs

object (Gcs)

Google Cloud Storage 工件。

Remote

通过某个 URI 指定可用工件。

JSON 表示法

{
      "uri": string,
      "checksum": string
    }
字段
uri

string

需要从中提取对象的 URI。它应包含协议和路径,格式如下:{protocol}://{location}。

checksum

string

如果 allowInsecurefalse,则必须提供。以十六进制格式表示的 SHA256 校验和,以与工件的校验和进行比较。如果校验和不为空且与工件不匹配,则在执行任何步骤之前无法安装配方。

Gcs

指定作为 Google Cloud Storage 对象的可用工件。

JSON 表示法

{
      "bucket": string,
      "object": string,
      "generation": string
    }
字段
bucket

string

Google Cloud Storage 对象的存储分区。对于给定的示例网址:https://storage.googleapis.com/my-bucket/foo/bar#1234567,此值为 my-bucket

object

string

Google Cloud Storage 对象的名称。指定名称请参考此处。对于给定的示例网址:https://storage.googleapis.com/my-bucket/foo/bar#1234567,此值为 foo/bar

generation

string (int64 format)

如果 allowInsecure 为 false,则必须提供。Google Cloud Storage 对象的世代编号。对于 https://storage.googleapis.com/my-bucket/foo/bar#1234567,此值为 1234567

Step

安装或更新配方时执行的一个操作。

JSON 表示法

{

      // Union field step can be only one of the following:
      "fileCopy": {
        object (CopyFile)
      },
      "archiveExtraction": {
        object (ExtractArchive)
      },
      "msiInstallation": {
        object (InstallMsi)
      },
      "dpkgInstallation": {
        object (InstallDpkg)
      },
      "rpmInstallation": {
        object (InstallRpm)
      },
      "fileExec": {
        object (ExecFile)
      },
      "scriptRun": {
        object (RunScript)
      }
      // End of list of possible types for union field step.
    }
字段
联合字段 step。特定的步骤类型。step 只能是下列其中一项:
fileCopy

object (CopyFile)

将文件复制到实例。

archiveExtraction

object (ExtractArchive)

将归档提取到指定目录中。

msiInstallation

object (InstallMsi)

安装 MSI 文件。

dpkgInstallation

object (InstallDpkg)

通过 dpkg 安装 deb 文件。

rpmInstallation

object (InstallRpm)

使用 rpm 实用程序安装 rpm 文件。

fileExec

object (ExecFile)

执行工件或本地文件。

scriptRun

object (RunScript)

在 shell 中运行命令。

CopyFile

将工件复制到实例上的指定路径。

JSON 表示法

{
      "artifactId": string,
      "destination": string,
      "overwrite": boolean,
      "permissions": string
    }
字段
artifactId

string

必填。配方中相关工件的 ID。

destination

string

必填。实例上放置文件的绝对路径。

overwrite

boolean

是否允许此步骤覆盖现有文件。如果此字段为 false 并且该文件已存在,则系统不会覆盖该文件,且此步骤被视为成功。默认值为 false。

permissions

string

由三个八进制数字组成,依次代表文件所有者、群组和其他用户的权限(类似于 linux chmod 实用程序中使用的数字模式)。每个数字代表 3 位数的总和,4 对应于读取权限,2 对应于写入权限,1 对应于执行权限。默认值为 755。

以下是权限及其相关值的示例:读取、写入和执行:7;读取和执行:5;读取和写入:6;只读:4

ExtractArchive

提取指定目录中指定类型的归档。

JSON 表示法

{
      "artifactId": string,
      "destination": string,
      "type": enum (ArchiveType)
    }
字段
artifactId

string

必填。配方中相关工件的 ID。

destination

string

提取归档的目标目录。Linux 上默认为 /,Windows 上为 C:\

type

enum (ArchiveType)

必填。需要提取的归档文件类型。

ArchiveType

指定归档类型。

枚举
ARCHIVE_TYPE_UNSPECIFIED 表示未指定归档类型。
TAR 表示归档是不加密的 tar 归档。
TAR_GZIP 表示归档是采用 gzip 加密的 tar 归档。
TAR_BZIP 表示归档是采用 bzip 加密的 tar 归档。
TAR_LZMA 表示归档是采用 lzma 加密的 tar 归档。
TAR_XZ 表示归档是采用 xz 加密的 tar 归档。
ZIP 表示归档为 zip 归档。

InstallMsi

安装 MSI 文件。

JSON 表示法

{
      "artifactId": string,
      "flags": [
        string
      ],
      "allowedExitCodes": [
        integer
      ]
    }
字段
artifactId

string

必填。配方中相关工件的 ID。

flags[]

string

安装 MSI 时要使用的标志默认为 ["/i"](即安装标志)。

allowedExitCodes[]

integer

返回代码,用于指明软件已成功安装或更新。默认值为 [0]

InstallDpkg

使用 dpkg 安装 deb。

JSON 表示法

{
      "artifactId": string
    }
字段
artifactId

string

必填。配方中相关工件的 ID。

InstallRpm

使用 rpm 实用程序安装 rpm 文件。

JSON 表示法

{
      "artifactId": string
    }
字段
artifactId

string

必填。配方中相关工件的 ID。

ExecFile

执行工件或本地文件。

JSON 表示法

{
      "args": [
        string
      ],
      "allowedExitCodes": [
        integer
      ],

      // Union field location_type can be only one of the following:
      "artifactId": string,
      "localPath": string
      // End of list of possible types for union field location_type.
    }
字段
args[]

string

需要传递给所提供的可执行文件的参数。

allowedExitCodes[]

integer

默认值为 [0]。程序可返回以指示成功的一系列可能的返回值。

联合字段 location_type。需要执行的文件的位置。location_type 只能是下列其中一项:
artifactId

string

配方中相关工件的 ID。

localPath

string

本地文件系统上文件的绝对路径。

RunScript

通过解释器运行脚本。

JSON 表示法

{
      "script": string,
      "allowedExitCodes": [
        integer
      ],
      "interpreter": enum (Interpreter)
    }
字段
script

string

必填。需要执行的 Shell 脚本。

allowedExitCodes[]

integer

返回代码,用于指明软件已成功安装或更新。默认值为 [0]

interpreter

enum (Interpreter)

要用于运行脚本的脚本解释器。如果未指定解释器,脚本会直接执行,可能仅有包含 shebang 行的脚本会成功。

Interpreter

用于执行脚本的解释器。

枚举
INTERPRETER_UNSPECIFIED ScriptType 的默认值。
SHELL 表示此脚本在 Linux 上用 /bin/sh 运行,在 Windows 上用 cmd 运行。
POWERSHELL 表示此脚本使用 PowerShell 运行。

方法

create

创建 OS Config 客机政策。

delete

删除 OS Config 客机政策。

get

获取 OS Config 客机政策。

list

获取 OS Config 客机政策列表。

patch

更新 OS Config 客机政策。