Usar políticas de agente (Beta)

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É possível criar e gerenciar políticas de agente usando o grupo de comandos gcloud beta compute instances ops-agents policies na Google Cloud CLI ou o módulo Terraform agent-policy. As políticas de agente usam o conjunto de ferramentas do VM Manager no Compute Engine para gerenciar políticas do SO, que podem automatizar a implantação e a manutenção de configurações de software, como os agentes do Google Cloud Observability: o Agente de operações, o Agente de monitoramento legado e o agente do Logging legado.

Observação:este documento descreve as políticas de agente Beta. As políticas de agente também estão disponíveis em uma versão de disponibilidade geral. Para informações sobre as políticas de agente GA, consulte Usar políticas de agente (GA). Para mais informações sobre as diferenças entre as duas versões e sobre a conversão de políticas de agente Beta em políticas de agente GA, consulte a Visão geral das políticas de agente do Agente de operações.

Criar uma política de agente

Esta seção descreve como usar o SDK Google Cloud para gerenciar políticas de agentes. Para informações sobre como usar o Terraform, consulte Integração do Terraform.

Para criar uma política de agente usando a CLI do Google Cloud, conclua as seguintes etapas:

1. Instale a Google Cloud CLI, caso ainda não tenha feito isso.

   As políticas de agente descritas neste documento usam o grupo de comandos beta.

2. Se ainda não tiver feito isso, instale o componente beta da CLI gcloud:

   gcloud components install beta
   

   Para verificar se você tem o componente beta para a instalação, execute:

   gcloud components list
   

   Se você instalou o componente beta anteriormente, verifique se tem a versão mais recente:

   gcloud components update
   

3. Faça o download do script a seguir para ativar as APIs e definir as permissões adequadas para usar a CLI do Google Cloud: set-permissions.sh.

   Para mais informações sobre o script, consulte o script set-permissions.sh .

   Observação: o script set-permissions.sh foi desenvolvido para execução no Linux. Se você estiver usando uma máquina em um sistema operacional diferente, execute o script no Cloud Shell.

4. Use o comando gcloud beta compute instances ops-agents policies create para criar uma política. Para a sintaxe do comando, consulte a documentação do gcloud beta compute instances ops-agents policies create.

   Para exemplos que mostram como formatar o comando, consulte a seção Exemplos na documentação da CLI do Google Cloud.

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

Práticas recomendadas para usar políticas de agente

Para controlar o impacto nos sistemas de produção durante o lançamento, recomendamos que você use rótulos e zonas para filtrar as instâncias a que a política se aplica.

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.

Este é um exemplo de plano de lançamento gradual para VMs do Debian 11 em um projeto chamado my_project:

Fase 1: crie uma política chamada ops-agents-policy-safe-rollout para instalar o Agente de operações em todas as VMs com os rótulos env=test e app=myproduct.

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=ops-agent,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=debian,version=11 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

Para mais informações sobre como especificar o sistema operacional, consulte gcloud beta compute instances ops-agents policiescreate.

Fase 2: atualize essa política para segmentar VMs em uma única zona que tenha os rótulos env=prod e app=myproduct.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c \

Fase 3: atualize essa política para limpar o filtro de zonas para que ela seja lançada globalmente

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --clear-zones

Políticas em VMs anteriores à configuração do SO

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.

Resolver problemas com políticas de agentes na versão Beta

Nesta seção, você encontra informações para resolver problemas com as políticas de agente Beta do Agente de operações, o agente legado do Monitoring e o agente do Logging legado.

Falha nos comandos ops-agents policy

Quando um comando gcloud beta 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:

• Permissão de IAM insuficiente
• A API OS Config não está ativada
• A política especificada não existe

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

Permissão de IAM insuficiente

Se um comando gcloud beta compute instances ops-agents policies falhar com um erro de permissão, verifique se você executou o script set-permissions.sh conforme descrito em Criar uma política de agente para definir os papéis da política de configuração do SO:

• Administrador do GuestPolicy (roles/osconfig.guestPolicyAdmin): Dá acesso total às políticas de convidado.
• Editor do GuestPolicy (roles/osconfig.guestPolicyEditor): Permite que os usuários recebam, atualizem e listem políticas de convidado.
• Leitor do GuestPolicy (roles/osconfig.guestPolicyViewer): Dá acesso somente leitura para receber e listar políticas de convidado.

Para mais informações sobre o script set-permissions.sh, consulte Script set-permissions.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)?

Insira y para ativar a API ou execute set-permissions.sh, descrito em Criar uma política de agente, 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 set-permissions.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 já existe

Um exemplo de erro é semelhante ao seguinte:

ALREADY_EXISTS: Requested entity already exists

Esse erro significa que a política já existe com o mesmo nome, ID do projeto e região. Use o comando describe gcloud beta compute instances ops-agents policies para confirmar isso.

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 beta 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 beta 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 na conexão com o serviço de configuração do SO, execute o script set-permissions.sh conforme descrito em Criar uma política de agente 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'

Os agentes de observabilidade estão instalados, mas não estão funcionando corretamente

Para informações sobre a depuração de agentes específicos, consulte os seguintes documentos:

• Resolver problemas do agente de operações
• Solucionar problemas do agente legado do Logging
• Solucionar problemas do agente legado do Monitoring

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 set-permissions.sh
• O script diagnose.sh

O script set-permissions.sh

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

• Ative a API Cloud Logging, a API Cloud Monitoring e a API OS Config do projeto.

• Conceda os papéis do Identity and Access Management Gravador de registros (roles/logging.logWriter) e Gravador de métricas do Monitoring (roles/monitoring.metricWriter) à conta de serviço padrão do Compute Engine para que os agentes possam gravar registros e métricas nas APIs Cloud Monitoring e Logging.

• Ative os metadados de configuração do SO no projeto para que o agente de configuração do SO em cada VM esteja ativo.

• Atribua um dos seguintes papéis do IAM aos usuários ou conta de serviço que não são proprietários necessários para criar e gerenciar políticas. Proprietários do projeto têm total acesso para criar e gerenciar políticas. Todos os outros usuários ou as contas de serviço precisam receber um dos seguintes papéis:

  • Administrador do GuestPolicy (roles/osconfig.guestPolicyAdmin): Dá acesso total às políticas de convidado.
  • Editor do GuestPolicy (roles/osconfig.guestPolicyEditor): Permite que os usuários recebam, atualizem e listem políticas de convidado.
  • Leitor do GuestPolicy (roles/osconfig.guestPolicyViewer): Dá acesso somente leitura para receber e listar políticas de convidado.

  Ao executar o script, basta especificar a parte guestPolicy* do nome do papel. O script fornece a parte roles/osconfig. do nome.

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 set-permissions.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 set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[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 set-permissions.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

O script diagnose.sh

Ao fornecer um ID do projeto, um ID de instância do Compute Engine e um ID de política do agente de políticas, o script diagnose.sh coleta automaticamente as informações necessárias para ajudar a diagnosticar problemas da política:

• A versão do agente de configuração do SO
• Política de convidado da Configuração do SO subjacente
• As políticas aplicáveis a essa instância do Compute Engine
• Os repositórios de pacotes de agente que são extraídos para a instância do Compute Engine

Para invocar o script, execute o seguinte comando:

bash diagnose.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID 

Integração com o Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para saber como o Terraform funciona, consulte Como usar o Terraform.

O suporte do Terraform para políticas de agentes é baseado nos comandos da Google Cloud CLI. Para criar uma política de agente usando o Terraform, siga as instruções do módulo agent-policy do Terraform. Você também pode encontrar exemplos de políticas no diretório examples.