Recurso REST: projects.guestPolicies

Recurso: GuestPolicy

Recurso da configuração do SO que representa uma política de configuração de convidado. Essas políticas representam o estado pretendido para ambientes de convidado de instância da VM, incluindo pacotes para instalar ou remover, configurações do repositório do pacote e software para instalação.

Representação JSON

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

string

Obrigatório. Nome exclusivo do recurso neste projeto usando um dos seguintes formatos: projects/{project_number}/guestPolicies/{guestPolicyId}.

description

string

Descrição da política do convidado. O tamanho da descrição limita-se a 1.024 caracteres.

createTime

string (Timestamp format)

Apenas saída. Horário da criação da política de convidado.

Um carimbo de data/hora no formato UTC “Zulu” RFC3339, medido com precisão de nanossegundos. Exemplo: "2014-10-02T15:01:23.045123456Z".

updateTime

string (Timestamp format)

Apenas saída. A última atualização da política de convidado.

Um carimbo de data/hora no formato UTC “Zulu” RFC3339, medido com precisão de nanossegundos. Exemplo: "2014-10-02T15:01:23.045123456Z".

assignment

object (Assignment)

Obrigatório. Especifica as instâncias de VM que são atribuídas a esta política. Isso permite segmentar conjuntos ou grupos de instâncias de VMs por parâmetros diferentes, como rótulos, nomes, SOs ou zonas.

Se ficar vazio, todas as instâncias de VM dessa política serão segmentadas.

No mesmo nível na hierarquia de recursos (que está dentro de um projeto), o serviço impede a criação de várias políticas que entram em conflito umas com as outras. Para mais informações, veja como o serviço administra conflitos de atribuição.

packages[]

object (Package)

Os pacotes de software a serem gerenciados por essa política.

packageRepositories[]

object (PackageRepository)

Uma lista de repositórios de pacotes a serem configurados na instância da VM. Para poder usar esses repositórios, isso precisa ser feito antes que qualquer outra configuração seja aplicada. Os repositórios de pacotes serão configurados somente se os gerenciadores de pacotes correspondentes estiverem disponíveis.

recipes[]

object (SoftwareRecipe)

Uma lista de roteiros para instalar na instância da VM.

etag

string

A etag dessa política de convidado. Se esses dados forem fornecidos durante a atualização, eles precisarão corresponder ao etag do servidor.

Atribuição

Uma atribuição representa o grupo ou os grupos de instâncias de VM aos quais a política se aplica.

Se uma atribuição estiver vazia, ela será aplicada a todas as instâncias de VM. Caso contrário, as instâncias de VM segmentadas precisam atender a todos os critérios especificados. Portanto, se os rótulos e as zonas forem especificados, a política será aplicada às instâncias de VM com esses rótulos e nessas zonas.

Representação JSON

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

object (GroupLabel)

Segmenta instâncias correspondentes em pelo menos um desses conjuntos de rótulos. Isso permite que uma atribuição segmente grupos distintos, por exemplo, "env=prod ou env=staging".

zones[]

string

Segmenta instâncias em qualquer uma dessas zonas. Deixe em branco para segmentar instâncias em qualquer zona.

A segmentação por zona é incomum e é compatível para facilitar o gerenciamento de alterações por zona.

instances[]

string

Segmenta qualquer uma das instâncias especificadas. As instâncias são especificadas pelo URI no formato zones/[ZONE]/instances/[INSTANCE_NAME].

A segmentação por instância é incomum e é compatível para facilitar o gerenciamento de alterações pela instância ou para segmentar instâncias de VM específicas para desenvolvimento e teste.

Compatível somente com políticas no nível do projeto e precisa referir-se a instâncias neste projeto.

instanceNamePrefixes[]

string

Segmenta instâncias de VM que tem nomes que comecem com um desses prefixos.

Assim como os rótulos, essa é outra forma de agrupar instâncias de VM ao segmentar configurações, por exemplo, prefix="prod-".

Compatível somente com políticas no nível do projeto.

osTypes[]

object (OsType)

Segmenta instâncias de VM que correspondam a pelo menos um dos seguintes tipos de SO.

As instâncias de VM precisam corresponder a todos os critérios fornecidos para que um determinado OsType seja incluído.

GroupLabel

Representa um grupo de instâncias de VM que pode ser identificada como tendo todos esses rótulos, por exemplo, "env=prod e app=web".

Representação JSON

{
  "labels": {
    string: string,
    ...
  }
}
Campos
labels

map (key: string, value: string)

Os rótulos de instância do Google Compute Engine que precisam estar presentes para que uma instância seja incluída nesse grupo de atribuição.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

OsType

Define os critérios para selecionar instâncias de VM por tipo de sistema operacional.

Representação JSON

{
  "osShortName": string,
  "osVersion": string,
  "osArchitecture": string
}
Campos
osShortName

string

Segmenta instâncias de VM com o inventário do SO ativado e com o seguinte nome curto do sistema operacional, por exemplo, "debian" ou "windows".

osVersion

string

Segmenta instâncias de VM com o inventário do SO ativado e com a seguinte versão do sistema operacional.

osArchitecture

string

Segmenta instâncias de VM com o inventário do SO ativado e com a seguinte arquitetura do sistema operacional.

Pacote

O pacote é uma referência ao pacote de software a ser instalado ou removido. O agente na instância da VM usa o gerenciador de pacotes do sistema para aplicar a configuração.

Estes são os comandos que o agente usa para instalar ou remover pacotes.

Instalação do Apt: apt-get update && apt-get -y install package1 package2 package3 remove: apt-get -y remove package1 package2 package3

Instalação do Yum: yum -y install package1 package2 package3 remove: yum -y remove package1 package2 package3

Instalação do Zypper: zypper install package1 package2 package3 remove: zypper rm package1 package2

Instalação do Googet: googet -noconfirm install package1 package2 package3 remover googet -noconfirm remove package1 package2 package3

Representação JSON

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

string

Obrigatório. O nome do pacote. Os pacotes são identificados exclusivamente para validação de conflitos verificando o nome do pacote e o gerenciador que o pacote segmenta.

desiredState

enum (DesiredState)

O desiredState que o agente precisa manter para este pacote. O padrão é garantir que o pacote esteja instalado.

manager

enum (Manager)

Tipo de gerenciador de pacotes que pode ser usado para instalar este pacote. Se algum sistema não tiver o gerenciador de pacotes, o pacote não será instalado ou removido e nenhuma mensagem de erro será apresentada. Por padrão, ou se você especificar ANY, o agente tenta instalar e remover esse pacote usando o gerenciador de pacotes padrão. Isso é útil ao criar uma política que se aplica a diferentes tipos de sistemas.

O comportamento padrão é ANY.

DesiredState

O estado desejado que o agente de configuração do SO mantém na instância da VM.

Enums
DESIRED_STATE_UNSPECIFIED O padrão é garantir que o pacote esteja instalado.
INSTALLED O agente garante que o pacote esteja instalado.
UPDATED O agente garante que o pacote esteja instalado e verifica e instala atualizações periodicamente.
REMOVED O agente garante que o pacote não está instalado e o desinstala se for detectado.

Gerenciador

Tipos de gerenciadores de pacotes que podem ser usados para gerenciar este pacote.

Enums
MANAGER_UNSPECIFIED O comportamento padrão é ANY.
ANY Aplique esta configuração de pacote usando o gerenciador de pacotes padrão do sistema.
APT Aplique esta configuração de pacote somente se Apt estiver disponível no sistema.
YUM Aplique esta configuração de pacote somente se Yum estiver disponível no sistema.
ZYPPER Aplique esta configuração de pacote somente se Zypper estiver disponível no sistema.
GOO Aplique esta configuração de pacote somente se GooGet estiver disponível no sistema.

PackageRepository

Um repositório de pacotes.

Representação 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.
}
Campos
Campo de união repository. Um tipo específico de repositório. repository pode ser apenas de um dos tipos a seguir:
apt

object (AptRepository)

Repositório do Apt.

yum

object (YumRepository)

Repositório do Yum.

zypper

object (ZypperRepository)

Repositório do Zypper.

goo

object (GooRepository)

Repositório do Goo.

AptRepository

Representa um único repositório de pacotes do Apt. Este repositório é adicionado a um arquivo do repositório armazenado em /etc/apt/sources.list.d/google_osconfig.list.

Representação JSON

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

enum (ArchiveType)

Tipo de arquivo neste repositório. O comportamento padrão é DEB.

uri

string

Obrigatório. O URI para este repositório.

distribution

string

Obrigatório. Distribuição deste repositório.

components[]

string

Obrigatório. Lista de componentes para este repositório. Precisa conter pelo menos um item.

gpgKey

string

O URI do arquivo de chave para este repositório. O agente mantém um keyring em /etc/apt/trusted.gpg.d/osconfig_agent_managed.gpg contendo todas as chaves em qualquer política de convidado aplicada.

ArchiveType

O tipo de arquivo.

Enums
ARCHIVE_TYPE_UNSPECIFIED Não especificado.
DEB DEB indica que o arquivo contém arquivos binários.
DEB_SRC DEB_SRC indica que o arquivo contém arquivos de origem.

YumRepository

Representa um único repositório de pacotes do Yum. Este repositório é adicionado a um arquivo do repositório armazenado em /etc/yum.repos.d/google_osconfig.repo.

Representação JSON

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

string

Obrigatório. Um nome exclusivo com uma única palavra para este repositório. Este é o repo id no arquivo de configuração do Yum e também o displayName se displayName for omitido. Esse ID também é usado como identificador exclusivo na verificação de conflitos de política de convidado.

displayName

string

O nome de exibição do repositório.

baseUrl

string

Obrigatório. O local do diretório do repositório.

gpgKeys[]

string

URIs de chaves GPG.

ZypperRepository

Representa um único repositório de pacotes do Zypper. Este repositório é adicionado a um arquivo do repositório armazenado em /etc/zypp/repos.d/google_osconfig.repo.

Representação JSON

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

string

Obrigatório. Um nome exclusivo com uma única palavra para este repositório. Este é o repo id no arquivo de configuração do Zypper e também o displayName se displayName for omitido. Esse ID também é usado como identificador exclusivo na verificação de conflitos de política de convidado.

displayName

string

O nome de exibição do repositório.

baseUrl

string

Obrigatório. O local do diretório do repositório.

gpgKeys[]

string

URIs de chaves GPG.

GooRepository

Representa um repositório de pacotes do Goo. Ele é adicionado a um arquivo de repositório armazenado em C:/ProgramData/GooGet/repos/google_osconfig.repo.

Representação JSON

{
  "name": string,
  "url": string
}
Campos
name

string

Obrigatório. O nome do repositório.

url

string

Obrigatório. O URL do repositório.

SoftwareRecipe

O roteiro de software é um conjunto de instruções para instalar e configurar um software. Trata-se de um conjunto de artefatos baixados e um conjunto de etapas que instalam, configuram e/ou atualizam o software.

Os roteiros são compatíveis com a instalação e atualização de software por artefatos nos seguintes formatos: arquivo zip, arquivo tar, Windows MSI, pacote Debian e pacote RPM.

Além disso, esses roteiros são compatíveis com a execução de um script (definido em um arquivo ou diretamente nesta API) em bash, sh, cmd e powershell.

Como atualizar roteiros de software

Se um roteiro for atribuído a uma instância e houver algum com o mesmo nome, mas uma versão inferior já estiver instalada e o estado atribuído do roteiro for INSTALLED_KEEP_UPDATED, ele será atualizada com a nova versão.

Diretórios de trabalho de script

Cada script ou etapa de execução é executado em seu próprio diretório temporário, que é excluído após a conclusão da etapa.

Representação JSON

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

string

Obrigatório. Identificador exclusivo do roteiro. Somente um roteiro com um determinado nome é instalado em uma instância.

Os nomes também são usados para identificar recursos que ajudam a determinar se as políticas de convidados têm conflitos. Isso significa que as solicitações para criar vários roteiros com o mesmo nome e versão são rejeitadas, já que podem ter atribuições conflitantes.

version

string

A versão deste roteiro de software. A versão pode ter até quatro números separados por pontos (por exemplo, 12.34.56.78).

artifacts[]

object (Artifact)

Recursos disponíveis para uso nas etapas do roteiro.

installSteps[]

object (Step)

Ações a serem realizadas para instalar este roteiro. Em caso de falha, ele interrompe as etapas e não tenta outra instalação. As etapas realizadas (incluindo as parcialmente concluídas) não são revertidas.

updateSteps[]

object (Step)

Ações a serem realizadas para atualizar este roteiro. Em caso de falha, ele interrompe as etapas e não tenta outra atualização para este roteiro. As etapas realizadas (incluindo as parcialmente concluídas) não são revertidas.

desiredState

enum (DesiredState)

O padrão é INSTALLED. O estado pretendido que o agente precisa manter para este roteiro.

INSTALLED: o roteiro do software é instalado na instância, mas não será atualizado para novas versões. INSTALLED_KEEP_UPDATED: o roteiro do software está instalado na instância. O roteiro será atualizado com uma versão superior se alguma versão superior dele for atribuída a essa instância. REMOVE: a remoção de roteiros de software não é compatível e as tentativas de criar ou atualizar um roteiro para o estado REMOVE foram rejeitadas.

Artefato

Especifica um recurso a ser usado no roteiro.

Representação 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.
}
Campos
id

string

Obrigatório. ID do artefato ao qual as etapas de instalação e atualização desse roteiro podem fazer referência. Os artefatos em um roteiro não podem ter o mesmo ID.

allowInsecure

boolean

O padrão é "false". Quando falso, os roteiros estão sujeitos a validações com base no tipo de artefato:

Remota: uma soma de verificação precisa ser especificada e somente protocolos com Transport Layer Security são permitidos. GCS: um número de geração de objeto precisa ser especificado.

Campo de união artifact. Um tipo específico de artefato. artifact pode ser apenas de um dos tipos a seguir:
remote

object (Remote)

Um artefato remoto genérico.

gcs

object (Gcs)

Um artefato do Google Cloud Storage.

Remoto

Especifica um artefato disponível por meio de algum URI.

Representação JSON

{
  "uri": string,
  "checksum": string
}
Campos
uri

string

URI a partir do qual buscar o objeto. Ele precisa conter o protocolo e o caminho seguindo o formato {protocol}://{location}.

checksum

string

Precisa ser fornecido se allowInsecure for false. A soma de verificação SHA256 está no formato hexadecimal, para comparação com a soma de verificação do artefato. Se a soma de verificação não estiver vazia e não corresponder ao artefato, a instalação do roteiro falhará antes de executar qualquer uma das etapas.

Gcs

Especifica um artefato disponível como um objeto do Google Cloud Storage.

Representação JSON

{
  "bucket": string,
  "object": string,
  "generation": string
}
Campos
bucket

string

Intervalo do objeto do Google Cloud Storage. URL de exemplo: https://storage.googleapis.com/my-bucket/foo/bar#1234567, esse valor seria my-bucket.

object

string

Nome do objeto do Google Cloud Storage. Conforme especificado aqui. URL de exemplo: https://storage.googleapis.com/my-bucket/foo/bar#1234567 esse valor seria foo/bar.

generation

string (int64 format)

É preciso fornecer se allowInsecure for falso. Número de geração do objeto do Google Cloud Storage. https://storage.googleapis.com/my-bucket/foo/bar#1234567 esse valor seria 1234567.

Etapa

Uma ação que pode ser tomada como parte da instalação ou atualização de um roteiro.

Representação 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.
}
Campos
Campo de união step. Um tipo específico de etapa. step pode ser apenas de um dos tipos a seguir:
fileCopy

object (CopyFile)

Copia um arquivo na instância.

archiveExtraction

object (ExtractArchive)

Extrai um arquivo no diretório especificado.

msiInstallation

object (InstallMsi)

Instala um arquivo MSI.

dpkgInstallation

object (InstallDpkg)

Instala um arquivo deb por meio de dpkg.

rpmInstallation

object (InstallRpm)

Instala um arquivo rpm por meio do utilitário rpm.

fileExec

object (ExecFile)

Executa um artefato ou arquivo local.

scriptRun

object (RunScript)

Executa comandos em um shell.

CopyFile

Copia o artefato ao caminho especificado na instância.

Representação JSON

{
  "artifactId": string,
  "destination": string,
  "overwrite": boolean,
  "permissions": string
}
Campos
artifactId

string

Obrigatório. O ID do artefato relevante no roteiro.

destination

string

Obrigatório. O caminho absoluto na instância para colocar o arquivo.

overwrite

boolean

Define a permissão para esta etapa para substituir os arquivos atuais. Se for falso e o arquivo já existir, esse arquivo não será substituído e a etapa será considerada bem-sucedida. O padrão é "false".

permissions

string

Consiste em três dígitos octais que representam, na ordem, as permissões do proprietário, do grupo e de outros usuários para o arquivo (de forma semelhante ao modo numérico usado no utilitário chmod linux). Cada dígito representa um número de três bits com os quatro bits correspondentes às permissões de leitura, os dois bits correspondem ao bit de gravação e um bit corresponde à permissão de execução. O comportamento padrão é 755.

Veja abaixo alguns exemplos de permissões e seus valores associados: ler, gravar e executar: 7; leitura e execução: 5; leitura e gravação: 6; somente leitura: 4.

ExtractArchive

Extrai um arquivo do tipo especificado no diretório especificado.

Representação JSON

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

string

Obrigatório. O ID do artefato relevante no roteiro.

destination

string

Diretório onde será extraído o arquivo. O padrão é / no Linux ou C:\ no Windows.

type

enum (ArchiveType)

Obrigatório. O tipo do arquivo a ser extraído.

ArchiveType

Especifica o tipo de arquivo.

Enums
ARCHIVE_TYPE_UNSPECIFIED Indica que o tipo de arquivo não foi especificado.
TAR Indica que o arquivo é um arquivo tar sem criptografia.
TAR_GZIP Indica que o arquivo é um arquivo tar com criptografia gzip.
TAR_BZIP Indica que o arquivo é um arquivo tar com criptografia bzip.
TAR_LZMA Indica que o arquivo é um arquivo tar com criptografia lzma.
TAR_XZ Indica que o arquivo é um arquivo tar com criptografia xz.
ZIP Indica que o arquivo é um arquivo zip.

InstallMsi

Instala um arquivo MSI.

Representação JSON

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

string

Obrigatório. O ID do artefato relevante no roteiro.

flags[]

string

As sinalizações a serem usadas ao instalar o MSI assumem o padrão de ["/i"] (ou seja, a sinalização de instalação).

allowedExitCodes[]

integer

Códigos de retorno que indicam que o software foi instalado ou atualizado. O padrão de comportamento é [0].

InstallDpkg

Instala um deb por meio de dpkg.

Representação JSON

{
  "artifactId": string
}
Campos
artifactId

string

Obrigatório. O ID do artefato relevante no roteiro.

InstallRpm

Instala um arquivo rpm por meio do utilitário rpm.

Representação JSON

{
  "artifactId": string
}
Campos
artifactId

string

Obrigatório. O ID do artefato relevante no roteiro.

ExecFile

Executa um artefato ou arquivo local.

Representação 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.
}
Campos
args[]

string

Argumentos a serem passados para o executável fornecido.

allowedExitCodes[]

integer

O padrão é [0]. Uma lista de possíveis valores que o programa pode retornar para indicar sucesso.

Campo de união location_type. Localização do arquivo a ser executado. location_type pode ser apenas de um dos tipos a seguir:
artifactId

string

O ID do artefato relevante no roteiro.

localPath

string

O caminho absoluto do arquivo no sistema de arquivos local.

RunScript

Executa um script por meio de um intérprete.

Representação JSON

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

string

Obrigatório. O script de shell a ser executado.

allowedExitCodes[]

integer

Códigos de retorno que indicam que o software foi instalado ou atualizado. O padrão de comportamento é [0].

interpreter

enum (Interpreter)

O intérprete de script a ser usado para executar o script. Se nenhum intérprete for especificado, o script será executado diretamente, o que provavelmente será bem-sucedido apenas para scripts com linhas shebang.

Intérprete

O intérprete usado para executar um script.

Enums
INTERPRETER_UNSPECIFIED Valor padrão para ScriptType.
SHELL Indica que o script é executado com /bin/sh no Linux e cmd no Windows.
POWERSHELL Indica que o script é executado com o PowerShell.

Métodos

create

Cria uma política de convidado para Configuração do SO.

delete

Exclui uma política de convidado da Configuração do SO.

get

Recebe uma política de convidado da Configuração do SO.

list

Recebe uma página das políticas de convidado da Configuração do SO.

patch

Atualiza uma política de visitante da Configuração do sistema operacional.