Use políticas de agentes (GA)

Cria e gere políticas de agentes através do grupo de comandos gcloud compute instances ops-agents policies na CLI Google Cloud ou do ops-agent-policy módulo Terraform. As políticas de agente usam o conjunto de ferramentas do VM Manager no Compute Engine para gerir políticas de SO, que podem automatizar a implementação e a manutenção de configurações de software, como o agente de operações. Estas políticas não podem ser aplicadas ao agente de monitorização antigo nem ao agente de registo antigo.

As políticas do agente do GA usam recursos de atribuição de políticas do SO na API OS Config. Embora exista um grupo de comandos gcloud CLI geral para gerir atribuições de políticas do SO, , o grupo de comandos foi concebido especificamente para as políticas do agente descritas neste documento.gcloud compute os-config os-policy-assignmentsgcloud compute instances ops-agents policies

Antes de começar

O módulo do ops-agent-policy Terraform é criado com base nos comandos gcloud compute instances ops-agents policies do SDK Cloud da Google. Para ver informações sobre como o Terraform funciona, consulte o artigo Usar o Terraform.

Antes de usar a CLI Google Cloud ou o módulo Terraform para criar políticas de agentes, conclua os seguintes passos:

  1. Se vai usar os comandos gcloud compute instances ops-agents policies e ainda não o fez, instale a CLI do Google Cloud.

  2. Se for usar o módulo do Terraform, faça o seguinte:

    1. Para ver informações sobre a instalação do Terraform, consulte o artigo Instale e configure o Terraform. O Cloud Shell tem o Terraform já instalado.

    2. Clone o repositório terraform-google-cloud-operations, que contém o módulo ops-agent-policy:

      git clone https://github.com/terraform-google-modules/terraform-google-cloud-operations

  3. Transfira e execute o script prepare-for-ops-agents-policies.sh para ativar as APIs necessárias e definir as autorizações adequadas para usar a CLI Google Cloud ou o Terraform.

    Para obter informações sobre o script, consulte o artigo O prepare-for-ops-agents-policies.sh script.

Desinstale o agente de monitorização e o agente de registo antigos

Se estiver a criar uma política para o agente de operações, certifique-se de que as suas VMs não têm o agente de registo ou o agente de monitorização antigo instalados. A execução do agente de operações e dos agentes antigos na mesma VM pode causar o carregamento de registos duplicados ou um conflito no carregamento de métricas. Se necessário, desinstale o agente de monitorização e desinstale o agente de registo antes de criar uma política para instalar o agente de operações.

Confirme se o agente de configuração do SO está instalado

Pode ter de instalar e configurar manualmente o agente de configuração do SO em VMs anteriores à configuração do SO. Para ver informações sobre a instalação manual e a validação do agente de configuração do SO, consulte a lista de verificação da validação do VM Manager.

Encontre valores para informações do sistema operativo

Se quiser aplicar políticas de agente a sistemas operativos ou versões específicos, tem de saber os valores que a configuração do SO usa para se referir a eles.

Para encontrar valores para os campos osShortName e osVersion de uma VM, use os seguintes comandos:

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^ShortName: "

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^Version: "

Estes comandos requerem que o agente de configuração do SO esteja instalado na VM.

Crie uma política de agente para gerir o agente de operações

Linha de comandos

Para criar uma política de agente, use o comando gcloud compute instances ops-agents policies create. Este comando tem a seguinte estrutura:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone ZONE \
  --file path/to/policy-description-file.yaml \
  --project PROJECT_ID

Quando usar este comando, substitua as variáveis da seguinte forma:

  • POLICY_ID é um nome para a sua política.
  • ZONE é uma zona do Compute Engine. As políticas de agentes são aplicadas apenas a VMs na zona especificada. Para aplicar uma política em várias zonas, tem de criar várias políticas.
  • path/to/policy-description-file.yaml é o caminho para um ficheiro YAML que descreve a política. Para informações sobre a estrutura deste ficheiro, consulte o artigo Descreva as políticas de agentes.
  • PROJECT_ID é o ID do seu Google Cloud projeto.

Para ver informações sobre os outros comandos no grupo de comandos e as opções disponíveis, consulte a documentação gcloud compute instances ops-agents policies.

Descreva as políticas de agentes

Fornece informações de políticas ao gcloud compute instances ops-agents policies create através da criação de um ficheiro YAML que descreve a política e da transmissão desse ficheiro para o comando como o valor da opção --file.

Esta secção descreve a estrutura do ficheiro policy-description. Para mais informações, consulte os ficheiros de descrição de políticas de exemplo.

Formato do ficheiro YAML de descrição das políticas

O ficheiro de descrição de uma política de agente tem de incluir dois grupos de campos:

  • agentsRule, que indica à política do agente se deve instalar ou remover o Ops Agent e especifica a versão do Ops Agent a usar.

  • instanceFilter, que descreve as VMs às quais a política se aplica.

Estrutura do grupo de campos agentsRule

O grupo de campos agentsRule tem a seguinte estrutura:

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y
  • O campo packageState indica à política o estado pretendido do agente do Google Operations. Os valores válidos são installed e removed.

  • O campo version indica a versão do agente de operações a instalar ou remover. Pode especificar os seguintes valores:

    • latest é a versão mais recente do agente de operações.
    • 2.*.* é o lançamento mais recente da versão principal 2 do agente Ops.
    • 2.x.y indica um lançamento específico da versão principal 2.

    Para obter informações sobre as versões disponíveis do agente de operações, consulte o repositório GitHub do agente.

Estrutura do grupo de campos instanceFilter

O grupo de campos instanceFilter indica as VMs numa zona à qual o filtro se aplica. Este grupo de campos é uma representação YAML da estrutura InstanceFilter usada pelo recurso OSPolicyAssignment na API OS Config.

O grupo de campos instanceFilter tem uma das seguintes estruturas:

  • Para aplicar a política do agente a todas as VMs numa zona, use o seguinte:

    instanceFilter:
  all: True

    Se usar o filtro all: True, não pode especificar outros critérios.

  • Para aplicar a política do agente a um conjunto específico de VMs numa zona, descreva as VMs através de uma combinação de qualquer um dos seguintes elementos:

    • Etiquetas na VM, para inclusão ou exclusão:
      • inclusionLabels:
      • exclusionLabels:
    • Sistema operativo: inventories:

    Por exemplo, o seguinte filtro aplica a política do agente às VMs com os sistemas operativos especificados que têm a etiqueta "env=prod" e não têm a etiqueta "app=web":

    instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  exclusionLabels:
  - labels:
      app: web
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

    Para obter informações sobre como encontrar os valores do sistema operativo, consulte o artigo Encontre informações do sistema operativo.

Terraform

Para criar uma política do agente totalmente personalizada, use o módulo ops-agent-policy no diretório do repositório modulesterraform-google-cloud-operations. Este módulo requer as mesmas informações que o comando gcloud compute instances ops-agents policies create. Para uma descrição de todos os campos usados para descrever uma política de agente, selecione o separador Linha de comandos.

O diretório examples no repositório terraform-google-cloud-operations contém ficheiros que lhe fornecem muitas das variáveis necessárias para o módulo ops-agent-policy. Para mais informações, consulte as Configurações de políticas de exemplo.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform. Para ver informações sobre como o Terraform funciona, consulte o artigo Usar o Terraform.

Valide o estado das políticas de agentes

Esta secção descreve como verificar o estado das políticas criadas e a instalação do agente de operações. Estas informações também podem ajudar a resolver problemas das políticas do seu agente.

Página Políticas de SO do Compute Engine

A página Políticas de SO do Compute Engine fornece informações sobre as políticas de agente que gerem o agente de operações e sobre as VMs no separador Instâncias de VM. Por exemplo:

  • A coluna Estado indica se uma política foi instalada com êxito ("Em conformidade"), está em curso ("Pendente"), pode ter falhado ("Desconhecido") ou está em falta ("Sem políticas").
  • A coluna VM monitorizada indica se o agente de operações está a ser gerido pela configuração do SO ("Monitorizada") ou não ("Não monitorizada").

    Se uma política estiver em "Conformidade", mas a VM mostrar "Não monitorizada", pode haver um problema na instalação do agente de operações. Por exemplo, pode ter um agente antigo já instalado.

Na Google Cloud consola, aceda à página Políticas de SO:

Aceda às políticas de SO

Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Compute Engine.

O separador Instâncias de VM nas políticas de SO do Compute Engine mostra informações sobre os agentes geridos por todas as políticas de SO no seuGoogle Cloud projeto. Estas políticas estão etiquetadas como goog-ops-agent-policy.

  • O indicador goog-ops-agent-policy inclui vários tipos de políticas:

    Para distinguir entre políticas, use o separador Atribuições de políticas do SO na página para ver os IDs das políticas de todas as atribuições de políticas no seu Google Cloud projeto.

  • Esta coluna VM monitored não reflete a instalação do agente Ops por outros meios, como a instalação manual ou através de políticas de agentes beta.

Página Instâncias de VM do Cloud Monitoring

A página Instâncias de VM no Cloud Monitoring inclui uma coluna Agente que apresenta o agente instalado em cada VM e, para o agente de operações, inclui um indicador para os agentes instalados que são mais antigos do que a versão mais recente.

Na Google Cloud consola, aceda à página Painel de controlo de instâncias de VM:

Aceda ao painel de controlo de instâncias de VM

Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

Exemplos de configurações de políticas

Esta secção descreve exemplos de configuração de políticas de agentes quando usa o Google Cloud SDK ou o Terraform.

Linha de comandos

Exemplos de ficheiros de descrição de políticas

Esta secção apresenta alguns exemplos de ficheiros YAML de descrição de políticas para uma variedade de cenários. Os exemplos partem do princípio de que colocou o YAML num ficheiro denominado agent-policy-description.yaml e que criou a política na zona us-central1-a através de um comando como o seguinte:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone us-central1-a \
  --file agent-policy-description.yaml \
  --project PROJECT_ID

Instale em todas as VMs

Para instalar a versão mais recente do agente de operações em todas as VMs na zona us-central1-a, use a seguinte descrição da política:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  all: True

Remova de todas as VMs

Para remover a versão mais recente do agente de operações em todas as VMs na zona us-central1-a, use a seguinte descrição da política:

agentsRule:
  packageState: removed
  version: latest
instanceFilter:
  all: True

Instale em VMs com base em etiquetas

Para instalar a versão mais recente do agente de operações em todas as VMs na zona us-central1-a com a etiqueta "env=prod" ou "app=web", use a seguinte descrição da política:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  - labels:
      app: web

Quando especifica várias entradas labels: para inclusão ou exclusão, uma VM corresponde se estiver presente qualquer uma das etiquetas. Ou seja, os conjuntos de etiquetas para inclusão ou exclusão são correspondidos como uma operação lógica OR e não uma operação lógica AND.

Instale em VMs com base noutras etiquetas

Para instalar a versão mais recente do agente de operações em todas as VMs na zona us-central1-a que executam o Debian 11, exceto as que têm as etiquetas "env=prod" e "app=web6", use a seguinte descrição da política:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  exclusionLabels:
  - labels:
      env: prod
      app: web6
  inventories:
  - osShortName: debian
    osVersion: '11'

Quando especifica vários pares de chave-valor numa única entrada labels: para inclusão ou exclusão, uma VM tem correspondência se todas as etiquetas estiverem presentes; ou seja, as etiquetas têm correspondência como uma operação lógica AND e não como uma operação lógica OR.

Instale em VMs com base no sistema operativo

Para instalar a versão 2 mais recente do agente de operações em todas as VMs que executam o Debian 11 ou o RHEL 7.* na zona us-central1-a, use a seguinte descrição da política:

agentsRule:
  packageState: installed
  version: 2.*.*
instanceFilter:
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

Terraform

Esta secção descreve os exemplos no diretório examples do repositório terraform-google-cloud-operations. Estes exemplos contêm ficheiros que configuram muitas das variáveis necessárias para si pelo módulo ops-agent-policy. Também pode copiar e modificar os exemplos. Por exemplo, todos estes exemplos instalam o agente de operações; pode modificá-los para eliminar o agente.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

Exemplo: ops_agent_policy_install_all

Este exemplo instala a versão mais recente do agente de operações em todas as VMs elegíveis no seu projeto Google Cloud .

Quando executa o comando terraform plan ou terraform apply, são-lhe pedidos os seguintes valores:

  • PROJECT_ID: o ID do seu Google Cloud projeto

Exemplo: ops_agent_policy_install_all_in_region

Este exemplo instala a versão mais recente do agente de operações em todas as VMs elegíveis numa determinada região, como us-west1. Uma região contém várias zonas, neste caso, us-west-1a, us-west-1b e us-west-1c.

Quando executa o comando terraform plan ou terraform apply, são-lhe pedidos os seguintes valores:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • REGION: a região na qual instalar o agente nas VMs

Exemplo: ops_agent_policy_install_all_in_zone

Este exemplo instala a versão mais recente do agente de operações em todas as VMs elegíveis numa determinada zona, como us-central1-a.

Quando executa o comando terraform plan ou terraform apply, são-lhe pedidos os seguintes valores:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • ZONE: a zona na qual instalar o agente nas VMs

Resolva problemas com políticas de agentes do GA

Esta secção fornece informações para ajudar a resolver problemas com as políticas de agentes do GA para o agente de operações. As informações descritas no artigo Verifique o estado das políticas de agentes também podem ser úteis.

Os comandos ops-agents policy falham

Quando um comando gcloud compute instances ops-agents policies falha, a resposta mostra um erro de validação. Corrija os erros corrigindo os argumentos dos comandos e os indicadores, conforme sugerido na mensagem de erro.

Além dos erros de validação, pode ver erros que indicam as seguintes condições:

As secções seguintes descrevem estas condições mais detalhadamente.

Autorização de IAM insuficiente

Se um comando gcloud compute instances ops-agents policies falhar com um erro de autorização, certifique-se de que executou o script prepare-for-ops-agents-policies.sh conforme descrito em Antes de começar para configurar as funções da política de configuração do SO:

Para mais informações sobre o guião prepare-for-ops-agents-policies.sh, consulte O guião prepare-for-ops-agents-policies.sh.

A API OS Config não está ativada

Um erro de exemplo tem o seguinte aspeto:

API [osconfig.googleapis.com] not enabled on project PROJECT_ID.
Would you like to enable and retry (this will take a few minutes)?
(y/N)?

Pode introduzir y para ativar a API ou executar o prepare-for-ops-agents-policies.shscript, descrito em Antes de começar, para conceder todas as autorizações necessárias. Se introduzir y no comando na mensagem de erro, continua a ter de executar o script prepare-for-ops-agents-policies.sh para definir as autorizações necessárias.

Para verificar se a API OS Config está ativada para o projeto, execute os seguintes comandos:

gcloud services list --project PROJECT_ID | grep osconfig.googleapis.com

Segue-se o resultado esperado:

osconfig.googleapis.com    Cloud OS Config API

A política já existe

Um erro de exemplo tem o seguinte aspeto:

ALREADY_EXISTS: Requested entity already exists

Este erro significa que esta política já existe com o mesmo nome, ID do projeto e região. Pode usar o comando gcloud compute instances ops-agents policies describe para confirmar esta ação.

A política não existe

Um erro de exemplo tem o seguinte aspeto:

NOT_FOUND: Requested entity was not found

Este erro pode significar que a política nunca foi criada, que a política foi eliminada ou que o ID da política especificado está incorreto. Certifique-se de que o POLICY_ID usado num comando gcloud compute instances ops-agents policies describe, update ou delete corresponde a uma política existente. Para obter uma lista de políticas do agente, use o comando gcloud compute instances ops-agents policies list.

A política é criada, mas parece não ter efeito

Os agentes de configuração do SO são implementados em cada instância do Compute Engine para gerir os pacotes dos agentes de registo e monitorização. A política pode parecer não ter efeito se o agente de configuração do SO subjacente não estiver instalado.

Linux

Para verificar se o agente OS Config está instalado, execute o seguinte comando:

gcloud compute ssh instance-id \
    --project project-id \
    -- sudo systemctl status google-osconfig-agent

Um exemplo de saída é:

    google-osconfig-agent.service - Google OSConfig Agent
    Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset:
    Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago
    Main PID: 369 (google_osconfig)
     Tasks: 8 (limit: 4374)
    Memory: 102.7M
    CGroup: /system.slice/google-osconfig-agent.service
            └─369 /usr/bin/google_osconfig_agent

Windows

Para verificar se o agente de configuração do SO está instalado, execute os seguintes passos:

  1. Estabeleça ligação à sua instância através do RDP ou de uma ferramenta semelhante e inicie sessão no Windows.

  2. Abra um terminal do PowerShell e, de seguida, execute o seguinte comando do PowerShell. Não precisa de privilégios de administrador.

    Get-Service google_osconfig_agent

Um exemplo de saída é:

    Status   Name               DisplayName
    ------   ----               -----------
    Running  google_osconfig_a… Google OSConfig Agent

Se o agente de configuração do SO não estiver instalado, pode estar a usar um sistema operativo que não suporta o VM Manager. O documento Detalhes do sistema operativo do Compute Engine indica que funcionalidades do VM Manager são suportadas para cada sistema operativo do Compute Engine.

Se o sistema operativo suportar o VM Manager, pode instalar o agente de configuração do SO manualmente.

O agente de configuração do SO está instalado, mas não instala o agente de operações

Para verificar se existem erros quando o agente de configuração do SO aplica políticas, pode verificar o registo do agente de configuração do SO. Isto pode ser feito através do Explorador de registos ou da utilização de SSH ou RDP para verificar instâncias individuais do Compute Engine.

Para ver os registos do agente OS Config no Explorador de registos, use o seguinte filtro:

resource.type="gce_instance"
logId(OSConfigAgent)

Para ver os registos do agente de configuração do SO, faça o seguinte:

CentOS, RHEL,
SLES, SUSE

Execute o seguinte comando: 

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/messages \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Debian, Ubuntu

Execute o seguinte comando: 

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/syslog \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Windows

  1. Estabeleça ligação à sua instância através do RDP ou de uma ferramenta semelhante e inicie sessão no Windows.

  2. Abra a app Event Viewer e, de seguida, selecione Windows Logs > Application e pesquise registos com Source igual a OSConfigAgent.

Se ocorrer um erro ao estabelecer ligação ao serviço OS Config, certifique-se de que executa o script prepare-for-ops-agents-policies.sh conforme descrito em Antes de começar para configurar os metadados do OS Config.

Para verificar se os metadados de configuração do SO estão ativados, pode executar o seguinte comando:

gcloud compute project-info describe \
    --project PROJECT_ID \
    | grep "enable-osconfig\|enable-guest-attributes" -A 1

Segue-se o resultado esperado:

- key: enable-guest-attributes
  value: 'TRUE'
- key: enable-osconfig
  value: 'TRUE'

O agente de operações está instalado, mas não está a funcionar corretamente

Para mais informações sobre a depuração de problemas do agente de operações, consulte o artigo Resolva problemas do agente de operações.

Ative os registos ao nível de depuração para o agente de configuração do SO

Pode ser útil ativar o registo ao nível de depuração no agente de configuração do SO quando comunicar um problema.

Pode definir os metadados osconfig-log-level: debug para ativar o registo ao nível de depuração do agente de configuração do SO. Os registos recolhidos têm mais informações para ajudar na investigação.

Para ativar o registo ao nível de depuração para todo o projeto, execute o seguinte comando:

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Para ativar o registo ao nível de depuração para uma VM, execute o seguinte comando:

gcloud compute instances add-metadata INSTANCE_ID \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Scripts auxiliares

Esta secção fornece informações adicionais sobre os scripts auxiliares descritos neste documento:

O script prepare-for-ops-agents-policies.sh

Depois de transferir o script prepare-for-ops-agents-policies.sh, pode usá-lo para realizar as seguintes ações, com base nos argumentos que fornecer:

Os exemplos seguintes mostram algumas invocações comuns para o script. Para mais informações, consulte os comentários no próprio script.

Para ativar as APIs, conceder as funções necessárias à conta de serviço predefinida e ativar os metadados de configuração do SO para um projeto, execute o script da seguinte forma:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID

Para conceder adicionalmente uma das funções de configuração do SO a um utilizador que não tenha a função Proprietário (roles/owner) no projeto, execute o script da seguinte forma:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

Para conceder adicionalmente uma das funções de configuração do SO a uma conta de serviço não predefinida, execute o script da seguinte forma:

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

O script diagnose_policies.sh

Dado um ID do projeto, um ID da instância do Compute Engine, uma zona do Compute Engine e o ID da política do agente, o script diagnose_policies.sh recolhe automaticamente as informações necessárias para ajudar a diagnosticar problemas com a política:

  • A versão do agente de configuração do SO
  • A atribuição da política do SO subjacente
  • As atribuições de políticas de SO aplicáveis a esta instância do Compute Engine
  • Uma descrição desta instância do Compute Engine

Para invocar o script, execute o seguinte comando:

bash diagnose_policies.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID \
  --zone=ZONE

Preços

Os comandos gcloud compute instances ops-agents policies são implementados através de recursos de atribuição de políticas do SO do VM Manager. O script prepare-for-ops-agents-policies.sh, descrito em Antes de começar, configura o VM Manager no modo de funcionalidades limitadas (OSCONFIG_B), que é suficiente para criar e gerir políticas de agentes. A utilização do VM Manager no modo limitado não tem qualquer custo.

Se configurou o VM Manager no modo de funcionalidades completas (OSCONFIG_C), pode incorrer em custos.