As políticas de agente permitem a instalação e a manutenção automatizadas dos agentes de observabilidade do Google Cloud em uma frota de VMs que correspondem aos 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 |
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 Google Cloud CLI, siga estas etapas:
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
.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
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?.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 dogcloud 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.
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 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 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:
Verifique se você executou o script
set-permissions.sh
na seção Como criar uma política de agente.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 emgoog-
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"
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 IAMosconfig.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
. OGCLOUD_MEMBER
precisa estar no formatouser:USER_EMAIL
ouserviceaccount: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
oudelete
é 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:
Conecte-se à sua instância usando o RDP ou uma ferramenta semelhante e faça login no Windows.
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 instructions 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:
Conecte-se à sua instância usando o RDP ou uma ferramenta semelhante e faça login no Windows.
Abra o aplicativo
Event Viewer
, emWindows Logs
=>Application
, pesquise registros comSource
igual aOSConfigAgent
.
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
eroles/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 parteroles/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.