Gerenciar políticas de agentes

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 do Compute Engine que correspondem a critérios especificados pelo usuário. Com um comando, é possível criar uma política para um projeto do Google Cloud que administre VMs novas e existentes associadas a esse projeto do Google Cloud, garantindo a instalação adequada e o upgrade automático opcional de todos os agentes do Google Cloud Observability nessas VMs.

É possível criar e gerenciar políticas de agente usando o grupo de comandos gcloud beta compute instances ops-agents policies na CLI do Google Cloud. Os comandos deste grupo usam o conjunto de ferramentas VM Manager do 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 legado do Monitoring e o agente legado do Logging.

Sistemas operacionais compatíveis

É possível aplicar uma política de agente a instâncias de VM do Compute Engine que executam os sistemas operacionais mostrados na tabela a seguir. Na tabela, as colunas do agente são associadas a um tipo de agente especificado para a invocação gcloud beta compute instances ops-agents policies create:

• O agente do Logging é associado a políticas com o tipo de agente logging.
• O agente de monitoramento é associado a políticas com o tipo de agente metrics.
• O Agente de operações é associado a políticas com o 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-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha		^1
Debian 9 (Stretch)
Debian 10 (Buster)
Debian 11 (Bullseye)
Deep Learning VM Images baseadas no 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.

Criar uma política de agente

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.

   Este documento descreve o grupo de comandos beta para gerenciar políticas de agente.

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

Confira um exemplo de plano de lançamento gradual para VMs do CentOS 7 em um projeto chamado my_project:

Fase 1: crie uma política chamada ops-agents-policy-safe-rollout para instalar o agente legado do Logging e o agente do Monitoring 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=logging,version=current-major,package-state=installed,enable-autoupgrade=true;type=metrics,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 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

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. Identifique as VMs em que você quer instalar o agente de configuração do SO e liste-as em um arquivo CSV. Por exemplo, para acessar uma lista de VMs que não são gerenciadas pelo Google Kubernetes Engine, App Engine ou outros serviços do Google Cloud e salvá-la em um arquivo chamado instances.csv, execute o seguinte comando:

     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 de VM com base em goog- filtra VMs do Compute Engine gerenciadas pelo GKE, App Engine e outros serviços.

   Para filtrar ainda mais as instâncias por zonas ou rótulos, altere o valor da sinalização --filter para um valor parecido com este:

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

3. Para instalar o agente de configuração do SO em VMs do Linux, faça o download e execute o script mass-install-osconfig-agent.sh.

   Observação: o script mass-install-osconfig-agent.sh, que automatiza as instruções para instalar o agente de configuração do SO, pode instalar o agente de configuração do SO somente em VMs do Linux. Se você tiver VMs do Windows, execute as instruções de instalação manualmente.

   O comando a seguir instala o agente de configuração do SO nas VMs especificadas no arquivo instances.csv do projeto especificado:

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

   Para mais informações sobre como usar o script, consulte os comentários no script.

Solução de problemas

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ê poderá ver os seguintes erros:

• Permissão de IAM insuficiente

  Veja abaixo um exemplo de erro:

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

  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 valor 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 resposta esperada é:

  - members:
    - GCLOUD_MEMBER
    role: roles/osconfig.guestPolicyAdmin
  

• A API OS Config não está ativada

  Veja abaixo um exemplo de erro:

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

  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 resposta 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 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

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 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"
logName="projects/PROJECT_ID/logs/OSConfigAgent"

Para visualizar os registros do agente de configuração do SO usando SSH para instâncias individuais do Compute Engine Linux, 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 usando RDP para 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 resposta esperada é:

- 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

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.