Como gerenciar políticas de agente

As políticas de agente possibilitam a instalação e manutenção automatizadas dos agentes do pacote de operações do Google Cloud 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 novas VMs atuais e 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 Versão do agente do Monitoring anterior à versão 6.0.0 Agente do Monitoring versão 6.0.0 e superior Agente de operações
CentOS 7
CentOS 8
RHEL 6
RHEL 7:
rhel-7, rhel-7-6-sap-ha, rhel-7-7-sap-ha, rhel-7-9-sap-ha
1 1
RHEL 8:
rhel-8, rhel-8-1-sap-ha, rhel-8-2-sap-ha, rhel-8-4-sap-ha
1 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 21.04 (Hirsute Hippo):
ubuntu-2104, ubuntu-minimal-2104
SLES 12:
sles-12, sles-12-sp3-sap, sles-12-sp4-sap, sles-12-sp5-sap
SLES 15:
sles-15, sles-15-sap, sles-15-sp1-sap, sles-15-sp2-sap
OpenSUSE Leap 15:
opensuse-leap (opensuse-leap-15-2-*, opensuse-leap-15-3-*)
Windows Server 2012 R2
Windows Server 2016
Windows Server 2019
Windows Server Core 2012 R2
Windows Server Core 2016
Windows Server Core 2019

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.

Como criar uma política de agente

Para criar uma política de agente usando a ferramenta de linha de comando gcloud, siga estas etapas:

  1. Instale o SDK do Cloud, se ainda não tiver feito isso.

    No SDK do Cloud, o grupo de comandos para gerenciar políticas de agente está na versão beta.

  2. Se você ainda não tiver feito isso, instale o componente beta da ferramenta 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 seguinte script para ativar as APIs e definir as permissões apropriadas para o uso da ferramenta de linha de comando gcloud: 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 de como formatar o comando, consulte a seção Exemplos na documentação do SDK do Cloud.

    Para mais informações sobre os comandos da ferramenta gcloud 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, é recomendável usar os rótulos e as zonas da instância para filtrar as instâncias às quais a política se aplica.

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

Fase 1: crie uma política para segmentar todas as VMs com o rótulo 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

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 tenha efeito no Ubuntu e nas VMs do Ubuntu e do SLES OS que precedem a configuração do SO, é necessária uma configuração adicional para garantir que o agente de configuração do SO em que a política se baseia 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"
    
  3. 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 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
    

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 Visualizador 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 Visualizador 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 de gerenciamento de identidade e acesso (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.

Veja um exemplo de uso nos comentários 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 ferramenta de linha de comando gcloud. Para criar uma política de agente usando o Terraform, siga as instruções do módulo do Terraform.