Como gerenciar políticas de agente

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.

As políticas de agente possibilitam a instalação e manutenção automatizadas dos agentes do Google Cloud Observability em uma frota de VMs que correspondem a critérios especificados pelo usuário. Com um comando, é possível criar uma política para o projeto do Google Cloud que rege VMs atuais e novas associadas a esse projeto, garantindo a instalação adequada e o upgrade automático opcional de todos os agentes.

Sistemas operacionais compatíveis

É possível aplicar uma política de agente às instâncias do Compute Engine com os sistemas operacionais a seguir.

Logging agent mapeia para políticas com tipo de agente logging. Monitoring agent mapeia para políticas com tipo de agente metrics. Ops Agent mapeia para políticas com tipo de agente ops-agent.

Sistema operacional	Agente do Logging	Agente do Monitoring	Agente de operações
CentOS 7
CentOS 8
Rocky Linux 8
RHEL 6
RHEL 7: rhel-7, rhel-7-6-sap-ha, rhel-7-7-sap-ha, rhel-7-9-sap-ha		^1
RHEL 8: rhel-8, rhel-8-2-sap-ha, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha		^1
Debian 9 (Stretch)
Debian 10 (Buster)
Debian 11 (Bullseye)
Ubuntu LTS 18.04 (Bionic Beaver): ubuntu-1804-lts, ubuntu-minimal-1804-lts
Ubuntu LTS 20.04 (Focal Fossa): ubuntu-2004-lts, ubuntu-minimal-2004-lts
Ubuntu LTS 22.04 (Jammy Jellyfish): ubuntu-2204-lts, ubuntu-minimal-2204-lts
SLES 12: sles-12, sles-12-sp5-sap
SLES 15: sles-15, sles-15-sp2-sap, sles-15-sp3-sap, sles-15-sp4-sap, sles-15-sp5-sap
OpenSUSE Leap 15: opensuse-leap (opensuse-leap-15-3-*, opensuse-leap-15-4-*)
Windows Server: 2016, 2019, 2022, Core 2016, Core 2019, Core 2022

¹ O agente do Monitoring não é compatível com rhel-7-9-sap-ha, rhel-8-2-sap-ha nem rhel-8-4-sap-ha.

Como criar uma política de agente

Para criar uma política de agente usando a Google Cloud CLI, siga estas etapas:

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

   Na CLI gcloud, o grupo de comandos para gerenciar as políticas de agente está na versão 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
   

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

      gcloud components update
      

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

   Para informações sobre o script, consulte O que o script set-permissions.sh está fazendo?.

   Observação: set-permissions.sh foi projetado para ser executado no Linux. Se você estiver usando 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.

   Veja exemplos de como formatar o comando na seção Exemplos da documentação da Google Cloud CLI.

   Saiba mais sobre os comandos da CLI gcloud e as opções disponíveis na documentação de 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.

Veja um exemplo de um plano de lançamento gradual para as VMs do CentOS 7:

Fase 1: crie uma política 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=centos,version=7 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

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

Fase 2: atualize essa política para segmentar env=prod e app=myproduct e apenas uma zona.

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

Limitações

Para que uma política entre em vigor nas VMs que antecedem a configuração do SO, é necessária uma configuração extra para garantir que o agente de configuração do SO em que a política foi implementada esteja instalado nas VMs. Para instalar o agente de configuração do SO em uma frota de VMs, conclua as etapas a seguir:

1. Verifique se você executou o script set-permissions.sh na seção Como criar uma política de agente.

2. Decida quais VMs quer instalar o agente de configuração do SO e liste-as em um arquivo CSV.

   Para ver uma lista de todas as instâncias não gerenciadas pelo Google (por exemplo, pelo Google Kubernetes Engine ou o Google App Engine) em um csv, execute:

     gcloud compute instances list \
         --filter="-labels.list(show="keys"):goog-" \
         --format="csv(name,zone)" \
         | grep -v -x -F -f  <(gcloud compute instances os-inventory list-instances \
             --format="csv(name,zone)") \
         | sed 's/$/,update/' > instances.csv
   

   A seção grep filtra as VMs que já têm o agente de configuração do SO instalado e ativado. A exclusão do rótulo da VM com base em goog- filtra as VMs do Compute Engine gerenciadas pelo GKE, o App Engine etc.

   Para filtrar ainda mais as instâncias por zonas ou rótulos, altere --filter para algo semelhante a este:

     "-labels.list(show="keys"):goog- AND zone:(ZONE_1,ZONE_2) AND labels.KEY_1:VALUE_1 AND labels.KEY_2=VALUE_2"
   

Observação: mass-install-osconfig-agent.sh foi projetado para ser executado no Linux. Se você estiver usando um sistema operacional diferente, execute o script no Cloud Shell.

1. Faça o download e execute o script mass-install-osconfig-agent.sh seguindo as instruções no script para executar um comando como:

      bash mass-install-osconfig-agent.sh --project project-id --input-file instances.csv
   

   Esse script automatiza as instruções de instalação do agente de configuração do SO.

Solução de problemas

Falha nos comandos da política de agentes de operações

Se os comandos da política de agentes de operações falharem, eles mostrarão um erro de validação correspondente. Corrija os erros corrigindo os argumentos e as sinalizações de comando, conforme sugerido pela mensagem de erro.

Além dos erros de validação, você poderá ver os seguintes erros:

• Permissão de IAM insuficiente

  Veja abaixo um exemplo de erro:

  ERROR: (gcloud.beta.compute.instances.ops-agents.policies.XXX) PERMISSION_DENIED: Caller does not have required permission to XXX
  

  Certifique-se de executar o script set-permissions.sh na seção Como criar uma política de agente para configurar o papel do IAM osconfig.guestPolicy específico.

  Para verificar se você tem o papel de política de convidado da configuração do SO suficiente ativado para o projeto, execute o comando a seguir. Neste exemplo, o comando verifica se o usuário tem o papel roles/osconfig.guestPolicyAdmin. O GCLOUD_MEMBER precisa estar no formato user:USER_EMAIL ou serviceaccount:SERVICE_ACCOUNT_EMAIL.

  gcloud projects get-iam-policy project-id \
      --filter=--member=gcloud-member \
      | grep "roles/osconfig.guestPolicyAdmin" -B 2
  

  A saída esperada é:

  - members:
    - gcloud-member
    role: roles/osconfig.guestPolicyAdmin
  

• A API Osconfig não está ativada

  Veja abaixo um exemplo de erro:

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

  Execute o script set-permissions.sh na seção Como criar uma política de agente para conceder todas as permissões necessárias.

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

  gcloud services list --project project-id \
      | grep osconfig.googleapis.com
  

  A saída esperada é:

  osconfig.googleapis.com    Cloud OS Config API
  

• A política não existe.

  Veja abaixo um exemplo de erro:

  NOT_FOUND: Requested entity was not found
  

  Isso sugere que a política já foi excluída. Verifique se o ID da política no comando describe, update ou delete é mapeado para uma política existente.

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 não ter efeito se o agente de configuração do SO 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

As instâncias do SUSE e do Ubuntu do Compute Engine não têm o agente de configuração do SO pré-instalado. Por isso, siga as instruções de instalação do agente de configuração do SO para instalar o agente nessas instâncias do Compute Engine.

O agente de configuração do SO está instalado, mas não instala os agentes 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 o Explorer de registros ou o SSH/RDP em instâncias individuais do Compute Engine.

Para visualizar os registros do agente de configuração do SO no Explorer de registros, use o seguinte filtro:

resource.type="gce_instance"
logName="projects/project-id/logs/OSConfigAgent"

Para ver os registros do agente de configuração do SO por SSH em instâncias individuais do Linux do Compute Engine, execute o seguinte comando:

• CentOS / RHEL / SLES / SUSE

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

• Debian / Ubuntu

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

Para visualizar os registros do agente de configuração do SO por RDP em instâncias individuais do Windows do Compute Engine, execute as seguintes etapas:

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

2. Abra o aplicativo Event Viewer, em Windows Logs => Application, pesquise registros com Source igual a OSConfigAgent.

Se houver um erro de conexão com o Serviço de configuração do SO, execute o script set-permissions.sh na seção Como criar uma política de agente para configurar os metadados.

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 é:

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

Os agentes de operações estão instalados, mas não estão funcionando corretamente

Consulte as páginas de solução de problemas do agente do Logging e do agente do Monitoring para depurar problemas específicos.

Como ativar registros de nível de depuração

É muito útil ativar o registro de nível de depuração do agente de configuração do SO 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

Mais informações

O que o script set-permissions.sh está fazendo?

Com um ID do projeto, um papel do Identity and Access Management (IAM, na sigla em inglês) e um e-mail ou conta de serviço, o script set-permissions.sh executa as seguintes ações:

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

• Concede os papéis roles/logging.logWriter e roles/monitoring.metricWriter à conta de serviço padrão do Compute Engine para que os agentes possam gravar registros e métricas no APIs Logging e Cloud Monitoring.

• Ativa os metadados de configuração do SO do projeto para que os agentes de configuração do SO sejam ativados nas VMs.

• Concede o papel do IAM especificado ao usuário gcloud ou à conta de serviço. Os proprietários do projeto têm acesso total para criar e gerenciar uma política. Para todos os outros usuários ou contas de serviço, os proprietários do projeto precisam conceder um dos seguintes papéis:

  • roles/osconfig.guestPolicyAdmin: fornece acesso total a uma política.

  • roles/osconfig.guestPolicyEditor: permite que os usuários recebam, atualizem e listem uma política.

  • roles/osconfig.guestPolicyViewer: fornece acesso somente leitura para consultar e listar uma política.

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

A invocação do script a seguir ativa as APIs, concede os papéis necessários à conta de serviço padrão e ativa os metadados de configuração do SO:

bash set-permissions.sh --project=PROJECT_ID

Para usar o script para também conceder um dos papéis de configuração do SO a um usuário que não tem o papel roles/owner (Proprietário) no projeto, execute o script da seguinte maneira:

bash set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

Para usar o script que também concede 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]

Para saber mais, consulte o conteúdo do script.

O que o script diagnose.sh está fazendo?

Ao fornecer um projeto, um ID de instância do Compute Engine e um ID de política do agente de operações, 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 uma instância do Compute Engine

Integração com o Terraform

O suporte do Terraform é baseado nos comandos da Google Cloud CLI. Para criar uma política de agente usando o Terraform, siga as instruções do módulo do Terraform.