Gerenciar políticas de agentes

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
1 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?.

  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.

    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:

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.