Usar políticas de agente (GA)

Você cria e gerencia as políticas do agente usando o Comando gcloud compute instances ops-agents policies na Google Cloud CLI ou no ops-agent-policy Módulo do Terraform. As políticas de agente usam o do pacote de ferramentas VM Manager no Compute Engine para gerenciar políticas de SO, que automatiza a implantação e a manutenção das configurações de software como o Agente de operações. Não é possível aplicar essas políticas Agente do Monitoring ou agente do Logging legado.

As políticas do agente do GA usam Atribuição de políticas de SO recursos na API OS Config. Há uma CLI gcloud geral grupo de comandos para gerenciar atribuições de políticas do SO, gcloud compute os-config os-policy-assignments, o O grupo de comandos gcloud compute instances ops-agents policies foi projetado especificamente para o agente políticas descritas neste documento.

Antes de começar

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

Antes de usar a Google Cloud CLI ou o módulo do Terraform para criar um agente , siga estas etapas:

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

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

    1. Para informações sobre como instalar o Terraform, consulte Instalar e configurar o Terraform. O Cloud Shell já tem o Terraform 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. Faça o download e execute o script prepare-for-ops-agents-policies.sh para ativar as APIs necessárias e definir as permissões adequadas para usar a CLI do Google Cloud ou o Terraform.

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

Desinstalar o agente do Monitoring legado e o agente do Logging

Se você estiver criando uma política para o agente de operações, verifique se as VMs não têm o agente do Logging ou do Monitoring legado instalado. A execução do agente de operações e dos agentes legados na mesma VM pode causar a ingestão de registros duplicados ou um conflito no processamento de métricas. Se necessário, desinstale o agente do Monitoring e desinstale o agente do Logging antes de criar uma política para instalar o Agente de operações.

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

Talvez seja necessário instalar e configurar manualmente o agente de configuração do SO em VMs anteriores à configuração do SO. Para informações sobre a instalação manual e a verificação do agente de configuração do SO, consulte Lista de verificação do VM Manager.

Encontrar valores para informações do sistema operacional

Se você quiser aplicar políticas de agentes a sistemas operacionais ou versões específicos, é necessário 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: "

Esses comandos exigem que o agente de configuração do SO esteja instalado na VM.

Criar uma política de agente para gerenciar o Agente de operações

Linha de comando

Para criar uma política de agente, use o Comando gcloud compute instances ops-agents policies create. Esse 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

Ao usar esse comando, substitua as variáveis da seguinte maneira:

  • POLICY_ID é o nome da política.
  • ZONE é uma zona do Compute Engine. As políticas do agente são aplicadas apenas a VMs na zona especificada. Para aplicar uma política em várias zonas, você precisa criar várias políticas.
  • path/to/policy-description-file.yaml é o caminho para um arquivo YAML que descreve a política. Para informações sobre a estrutura desse arquivo, consulte Descrever as políticas do agente.
  • PROJECT_ID é o ID do seu projeto do Google Cloud.

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

Descrever políticas de agentes

Você fornece informações da política para o gcloud compute instances ops-agents policies create ao crie um arquivo YAML que descreva a política e passando esse arquivo para o como o valor do elemento --file é a melhor opção.

Esta seção descreve a estrutura do arquivo de descrição da política. Para mais informações, consulte Exemplos de arquivos de descrição de política.

Formato do arquivo de descrição da política YAML

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

  • agentsRule, que informa à política do agente se quer instalar ou remover do Agente de operações e especifica a versão em que operar.

  • instanceFilter, que descreve as VMs em que a política é aplicada.

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 informa à política o estado pretendido do agente de operações. Os valores válidos são installed e removed.

  • O campo version indica a versão do Agente de operações a ser instalada ou removida. É possível especificar os seguintes valores:

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

    Para informações sobre as versões disponíveis do Agente de operações, consulte repositório do GitHub (em inglês) do agente.

Estrutura do grupo de campos instanceFilter

O grupo de campos instanceFilter indica as VMs em uma zona a que o filtro se aplica. Esse grupo de campos é uma representação YAML do InstanceFilter estrutura 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 em uma zona, use o seguinte:

    instanceFilter:
  all: True

    Se você usar o filtro all: True, não será possível especificar qualquer outro critério.

  • Para aplicar a política do agente a um conjunto específico de VMs em uma zona, descreva as VMs usando uma combinação das seguintes opções:

    • Rótulos na VM, para inclusão ou exclusão:
      • inclusionLabels:
      • exclusionLabels:
    • Sistema operacional: inventories:

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

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

    Para informações sobre como encontrar os valores do sistema operacional, consulte Encontre informações do sistema operacional.

Terraform

Para criar uma política de agente totalmente personalizada, use o módulo ops-agent-policy no diretório modules do repositório terraform-google-cloud-operations. Esse módulo exige as mesmas informações que o comando gcloud compute instances ops-agents policies create. Para conferir uma descrição de todos os campos usados para descrever uma política de agente, Selecione a guia Linha de comando.

O diretório examples no repositório terraform-google-cloud-operations contém arquivos que fornecem muitas das variáveis necessárias pelo módulo ops-agent-policy para você. Para mais informações, consulte Exemplos de configurações de política.

Para saber como aplicar ou remover um arquivo do Terraform, consulte a documentação básica do comandos. Para informações sobre como o Terraform funciona, consulte Como usar o Terraform.

Verificar o status das políticas de agentes

Esta seção descreve como verificar o status das políticas criadas e a instalação do agente de operações. Essas informações também podem ajudar a resolver problemas com as políticas de agentes.

Página Políticas do SO do Compute Engine

A página Políticas de SO do Compute Engine fornece informações sobre as políticas do agente que gerenciam o Agente de operações e as VMs Guia Instâncias de VM. Exemplo:

  • A coluna Estado indica se uma política foi instalada ("Em conformidade"), está em andamento ("Pendente"), possivelmente falhou ("Desconhecido") ou está ausente ("Nenhuma política").
  • A coluna VM monitorada indica se o Agente de operações está sendo gerenciada pela Configuração do SO ("Monitorado") ou não ("Não monitorado").

    Se uma política estiver "Em conformidade", mas a VM mostrar "Não monitorada", talvez haja um problema na instalação do agente de operações. Por exemplo, talvez você já tenha um agente legado instalado.

No console do Google Cloud, acesse a página Políticas do SO:

Acessar as políticas do SO

Se você usar a barra de pesquisa para encontrar a página, selecione o resultado com o subtítulo Compute Engine.

As instâncias de VM na guia Políticas do SO do Compute Engine mostram informações sobre agentes gerenciados por todas as políticas do SO no seu projeto do Google Cloud. Essas políticas são marcadas como goog-ops-agent-policy.

  • O indicador goog-ops-agent-policy inclui vários tipos de políticas:
    • Políticas criadas usando os comandos gcloud compute instances ops-agents policies.
    • Políticas criadas para você se você solicitou a instalação do agente de operações ao criar a VM.
    • Políticas criadas usando o Terraform para gerenciar o agente de operações.

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

  • A coluna VM monitorada não reflete a instalação do o Agente de operações por outros meios, como a instalação manual políticas do agente Beta.

Página Instâncias de VM do Cloud Monitoring

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

No Console do Google Cloud, acesse a página painel de Instâncias de VM.

Acessar o painel de instâncias de VM

Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoramento.

Exemplos de configurações de políticas

Esta seção descreve exemplos de configuração de políticas de agentes ao usar o SDK do Google Cloud ou o Terraform.

Linha de comando

Exemplos de arquivos de descrição da política

Esta seção fornece alguns exemplos de arquivos de descrição de políticas YAML para uma variedade de cenários. Os exemplos pressupõem que você colocou o YAML em um arquivo chamado agent-policy-description.yaml e que crie a política na zona us-central1-a usando 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

Instalar 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 de política:

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

Remover 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 de política:

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

Instalar em VMs com base em rótulos

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

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

Quando você especifica várias entradas labels: para inclusão ou exclusão, uma VM corresponde se algum dos rótulos estiver presente; ou seja, os conjuntos de rótulos para inclusão ou exclusão são correspondidas como uma operação OR lógica, não é uma operação AND lógica.

Instalar em VMs com base em outros rótulos

Para instalar a versão mais recente do agente de operações em todas as VMs na zona us-central1-a com o Debian 11, exceto aquelas com os rótulos "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 você especifica vários pares de chave-valor em uma única entrada labels:. para inclusão ou exclusão, uma VM fará a correspondência se todos os rótulos estiverem presentes; ou seja, a correspondência dos rótulos é feita como uma operação AND lógica, e não como uma operação OR lógica.

Instalar em VMs com base no sistema operacional

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

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

Terraform

Esta seção descreve os exemplos no diretório examples do repositório terraform-google-cloud-operations. Esses exemplos contêm arquivos que configuram muitas das variáveis exigidas pelo ops-agent-policy para você. Você também pode copiar e modificar os exemplos. Por exemplo, todos estes exemplos instalam o Agente de operações. modifique-os para excluir o agente.

Para saber como aplicar ou remover um arquivo do Terraform, consulte a documentação básica do comandos.

Exemplo: ops_agent_policy_install_all

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

Ao executar o comando terraform plan ou terraform apply, você vai receber os seguintes valores:

  • PROJECT_ID: o ID do seu projeto do Google Cloud

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 qualificadas em uma 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.

Ao executar o comando terraform plan ou terraform apply, você vai receber os seguintes valores:

  • PROJECT_ID: o ID do seu projeto do Google Cloud
  • REGION: a região em que o agente será instalado nas VMs.

Exemplo: ops_agent_policy_install_all_in_zone

Este exemplo instala a versão mais recente do Agente de operações VMs qualificadas em uma determinada zona, como us-central1-a.

Ao executar o comando terraform plan ou terraform apply, você vai receber os seguintes valores:

  • PROJECT_ID: o ID do seu projeto do Google Cloud
  • ZONE: a zona em que o agente será instalado nas VMs.

Resolver problemas com políticas de agentes do GA

Esta seção fornece informações para ajudar a resolver problemas com as políticas do agente do GA para o Agente de operações. As informações descritas nos Verifique o status das políticas do agente também pode estar prestativos.

Falha nos comandos ops-agents policy

Quando um comando gcloud compute instances ops-agents policies apresenta falha, é exibido um erro de validação. Corrija os erros ao ajustar os argumentos e as sinalizações de comando, conforme sugerido pela mensagem de erro.

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

As seções a seguir descrevem essas condições em mais detalhes.

Permissão de IAM insuficiente

Se um comando gcloud compute instances ops-agents policies falhar com um erro de permissão, Verifique se você executou o script prepare-for-ops-agents-policies.sh conforme descrito em Antes de começar para definir os papéis da política de configuração do SO:

Para mais informações sobre o script prepare-for-ops-agents-policies.sh, consulte Script prepare-for-ops-agents-policies.sh.

A API OS Config não está ativada

Um exemplo de erro é semelhante ao seguinte:

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)?

Você pode inserir y para ativar a API ou executar prepare-for-ops-agents-policies.sh descrito em Antes de começar, para conceder todas as permissões necessárias. Se você inserir y no comando na na mensagem de erro, ainda será necessário executar o script prepare-for-ops-agents-policies.sh para definir as permissões necessárias.

Para verificar se a API OS Config está ativada no projeto, execute os comandos a seguir:

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

A saída esperada é esta:

osconfig.googleapis.com    Cloud OS Config API

A política não existe.

Um exemplo de erro é semelhante ao seguinte:

NOT_FOUND: Requested entity was not found

Esse erro pode significar que a política nunca foi criada, que a política foi excluída ou que o ID da política especificado está incorreto. Certifique-se de que o POLICY_ID usado em um comando gcloud compute instances ops-agents policies describe, update ou delete corresponde a uma política atual. Para ver uma lista de políticas de agentes, use o comando gcloud compute instances ops-agents policies list.

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

Os agentes de configuração do SO são implantados em cada instância do Compute Engine para gerenciar os pacotes dos agentes do Logging e Monitoring. A política pode parecer não ter efeito se o agente de configuração do sistema operacional subjacente não estiver instalado.

Linux

Para verificar se o agente de configuração do SO está instalado, execute o comando a seguir:

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 as etapas a seguir:

  1. Conecte-se à sua instância usando o RDP ou uma ferramenta semelhante e faça login no Windows.

  2. Abra um terminal do PowerShell e execute os comandos a seguir: Não é necessário ter 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, talvez você esteja usando um sistema operacional não é compatível com o VM Manager. O documento Detalhes do sistema operacional do Compute Engine indica quais recursos do VM Manager têm suporte em cada sistema operacional do Compute Engine.

Se o sistema operacional for compatível com o VM Manager, você 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 há algum erro quando o agente de configuração do SO aplica políticas, verifique o registro do agente. Isso pode ser feito usando a Análise de registros ou SSH ou RDP para verificar instâncias individuais do Compute Engine.

Para visualizar os registros do agente de configuração do SO na Análise de registros, use o seguinte filtro:

resource.type="gce_instance"
logId(OSConfigAgent)

Para acessar os registros do agente de configuração do SO, faça o seguinte:

CentOS, RHEL,
SLES, SUSE

Execute este comando: 

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

Debian, Ubuntu

Execute este comando: 

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

Windows

  1. Conecte-se à sua instância usando o RDP ou uma ferramenta semelhante e faça login no Windows.

  2. Abra o app Visualizador de eventos e selecione Registros do Windows > Aplicativo e pesquise registros com Source igual a OSConfigAgent.

Se houver um erro ao se conectar ao serviço de Configuração do SO, execute o prepare-for-ops-agents-policies.sh conforme descrito nas Antes de começar para definir os metadados de configuração do SO.

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

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

A saída esperada é esta:

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

O Agente de operações está instalado, mas não está funcionando corretamente

Para mais informações sobre como depurar problemas do Agente de operações, consulte Resolver problemas do Agente de operações.

Habilitar registros em nível de depuração para o agente de configuração do SO

Pode ser útil ativar o registro em nível de depuração no agente de configuração do sistema operacional ao relatar um problema.

Defina os metadados osconfig-log-level: debug para ativar a geração de registros de nível de depuração para o agente de configuração do SO. Os registros coletados têm mais informações para ajudar na investigação.

Para ativar a geração de registros no 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 a geração de registros de 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

Nesta seção, você encontra mais informações sobre os scripts auxiliares descritos neste documento:

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

Depois de fazer o download do script prepare-for-ops-agents-policies.sh, é possível usar o script para realizar as seguintes ações, com base nos argumentos fornecidos:

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

Para ativar as APIs, conceder os papéis necessários à conta de serviço padrão e ativar os metadados de configuração do SO para um projeto, execute o script da seguinte maneira:

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

Para conceder um dos papéis de configuração do SO a um usuário que não tem o papel de proprietário (roles/owner) no projeto, execute o script como mostrado a seguir:

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

Para conceder um dos papéis da configuração do SO a uma conta de serviço não padrão, execute o script da seguinte maneira:

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

Com um ID do projeto, um ID de instância do Compute Engine, uma zona do Compute Engine, e o ID da política do agente, O script do diagnose_policies.sh coleta 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 de política do SO subjacente
  • As atribuições de política do SO aplicáveis a essa 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 usando Atribuição de política de SO recursos do VM Manager. O script prepare-for-ops-agents-policies.sh, descrito em Antes de começar, define o VM Manager modo de recursos limitados (OSCONFIG_B), o que é suficiente para criar e gerenciar políticas de agente. Não há custo para usar o VM Manager no modo limitado.

Se você configurou o VM Manager no modo completo (OSCONFIG_C), você poderá receber cobranças.