Use políticas de agentes

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

As políticas de agente permitem a instalação e a manutenção automatizadas dos agentes do Google Cloud Observability numa frota de VMs do Compute Engine que correspondem aos critérios especificados pelo utilizador. Pode criar uma política para um Google Cloud projeto que rege as VMs existentes e novas associadas a esse Google Cloud projeto, garantindo a instalação, a desinstalação e a atualização automática opcional de todos os agentes do Google Cloud Observability nessas VMs.

Cria e gere políticas de agentes através do grupo de comandos gcloud beta compute instances ops-agents policies na CLI Google Cloud ou do agent-policy módulo Terraform. As políticas de agentes 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 os agentes do Google Cloud Observability: o agente de operações, o agente de monitorização antigo e o agente de registo antigo.

Sistemas operativos compatíveis

Pode aplicar uma política de agente a instâncias de VM do Compute Engine que executam os sistemas operativos apresentados na tabela seguinte:

Sistema operativo	Ops Agent (Políticas de GA e beta^†)	Agente de registos (apenas para políticas ^† beta)	Agente de monitorização (apenas políticas beta^†)
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			^‡
RHEL 8: rhel-8, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha			^‡
Debian 9 (Stretch)
Debian 11 (Bullseye)
Imagens de VMs de aprendizagem avançada 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): buntu-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, sles-15-sp6-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

^†  Nas políticas de agentes beta, as colunas de agentes são mapeadas para um tipo de agente especificado para a gcloud beta compute instances ops-agents policies invocação create:

• O Ops Agent é mapeado para o tipo de agente ops-agent.
• O agente de registos é mapeado para o tipo de agente logging.
• O agente de monitorização é mapeado para o tipo de agente metrics.

^‡ O agente de monitorização não é suportado no rhel-7-9-sap-ha, rhel-8-2-sap-ha nem no rhel-8-4-sap-ha.

Crie uma política de agente

Esta secção descreve a utilização do Google Cloud SDK para gerir políticas de agentes. Para informações sobre a utilização do Terraform, consulte o artigo Integração do Terraform.

Para criar uma política do agente através da CLI do Google Cloud, conclua os seguintes passos:

1. Se ainda não o fez, instale a CLI Google Cloud.

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

2. Se ainda não o fez, instale o componente beta da CLI gcloud:

   gcloud components install beta
   

   Para verificar se tem o componente beta instalado, execute o seguinte comando:

   gcloud components list
   

   Se instalou anteriormente o componente beta, certifique-se de que tem a versão mais recente:

   gcloud components update
   

3. Transfira e use o seguinte script para ativar as APIs e definir as autorizações adequadas para usar a CLI do Google Cloud: set-permissions.sh.

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

   Nota: o script set-permissions.sh foi concebido para ser executado no Linux. Se estiver a usar um computador com um sistema operativo diferente, execute o script a partir do Cloud Shell.

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

   Para ver exemplos que mostram como formatar o comando, consulte a secção Exemplos na documentação da CLI gcloud.

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

Práticas recomendadas para usar políticas de agentes

Para controlar o impacto nos sistemas de produção durante a implementação, recomendamos que use etiquetas de instâncias e zonas para filtrar as instâncias às quais a política se aplica.

Segue-se um exemplo de um plano de implementação faseada para VMs do Debian 11 num projeto denominado my_project:

Fase 1: crie uma política denominada ops-agents-policy-safe-rollout para instalar o agente de registo e o agente de monitorização antigos em todas as VMs com as etiquetas 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=debian,version=11 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

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

Fase 2: atualize essa política para segmentar VMs numa única zona que tenham as etiquetas 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, de modo que seja implementado 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

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.

Resolva problemas com políticas de agentes beta

Esta secção fornece informações para ajudar a resolver problemas com as políticas do agente beta para o agente Ops, o agente Monitoring antigo e o agente Logging antigo.

Os comandos ops-agents policy falham

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

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

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

Autorização de IAM insuficiente

Se um comando gcloud beta compute instances ops-agents policies falhar com um erro de autorização, certifique-se de que executou o script set-permissions.sh conforme descrito no artigo Crie uma política de agente para configurar as funções da política de configuração do SO:

• Administrador da GuestPolicy (roles/osconfig.guestPolicyAdmin): Fornece acesso total às políticas de hóspedes.
• Editor de GuestPolicy (roles/osconfig.guestPolicyEditor): permite aos utilizadores obter, atualizar e listar políticas de convidados.
• GuestPolicy Viewer (roles/osconfig.guestPolicyViewer): Fornece acesso só de leitura para obter e listar políticas de convidados.

Para mais informações sobre o guião set-permissions.sh, consulte O guião set-permissions.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 script descrito em Crie uma política de agente para conceder todas as autorizações necessárias.set-permissions.sh Se introduzir y no comando na mensagem de erro, continua a ter de executar o script set-permissions.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 beta 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 beta 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 beta 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 monitorização

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 set-permissions.sh, conforme descrito no artigo Crie uma política de agente 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'

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

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

• Resolva problemas do Ops Agent
• Resolva problemas do agente de registos antigo
• Resolva problemas do agente de monitorização antigo

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

O script set-permissions.sh

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

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

• Conceda as funções de Identity and Access Management Logs Writer (roles/logging.logWriter) e Monitoring Metric Writer (roles/monitoring.metricWriter) à conta de serviço predefinida do Compute Engine para que os agentes possam escrever registos e métricas nas APIs Logging e Cloud Monitoring.

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

• Conceda uma das seguintes funções de IAM ao utilizador ou à conta de serviço que não seja proprietário e que seja necessária para criar e gerir políticas. Os proprietários do projeto têm acesso total para criar e gerir políticas. Todos os outros utilizadores ou contas de serviço têm de receber uma das seguintes funções:

  • Administrador da GuestPolicy (roles/osconfig.guestPolicyAdmin): Fornece acesso total às políticas de hóspedes.
  • Editor de GuestPolicy (roles/osconfig.guestPolicyEditor): permite aos utilizadores obter, atualizar e listar políticas de convidados.
  • GuestPolicy Viewer (roles/osconfig.guestPolicyViewer): Fornece acesso só de leitura para obter e listar políticas de convidados.

  Quando executa o script, só tem de especificar a parte guestPolicy* do nome da função. O script fornece a parte roles/osconfig. do nome.

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

O script diagnose.sh

Dado um ID do projeto, um ID da instância do Compute Engine e o ID da política do agente, o script diagnose.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 política de convidado de configuração do SO subjacente
• As políticas aplicáveis a esta instância do Compute Engine
• Os repositórios de pacotes de agentes que são transferidos para esta 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 do Terraform

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.

O suporte do Terraform para políticas de agentes baseia-se nos comandos da CLI do Google Cloud. Para criar uma política de agente através do Terraform, siga as agent-policyinstruções do módulo Terraform. Também pode encontrar exemplos de políticas no examples diretório.