Instalar o Agente de Operações usando as políticas do Gerenciador de Extensões de VM

As políticas do Gerenciador de extensões de VM permitem instalar o Agente de Operações em uma frota de VMs do Compute Engine. Uma política de extensão pode instalar o Agente de Operações globalmente no projeto do Google Cloud ou em uma zona específica, manter a versão do agente atualizada e aplicar uma configuração personalizada ao agente.

Antes de começar

Antes de criar políticas de extensão do Gerenciador de Extensões de VM para gerenciar o Agente de Operações, faça o seguinte:

Remover agentes de observabilidade atuais

Antes de criar uma política do Gerenciador de extensões de VM para o Agente de Operações, verifique se não há instâncias do Agente de Operações ou do agente legado do Monitoring e do agente do Logging na VM. A execução do Agente de Operações e dos agentes legados na mesma VM pode causar a ingestão de registros duplicados ou conflitos no processamento de métricas.

Se você usar uma política de extensão para instalar o Agente de Operações em uma VM em que outro agente de observabilidade já esteja instalado, a política vai instalar o agente, mas ele não será executado porque um conflito foi detectado.

A forma de remover os agentes depende de como eles foram instalados.

Ativar as APIs necessárias para usar o Agente de Operações

Para usar o Agente de operações para gravar registros e métricas, ative a API Cloud Logging e a API Cloud Monitoring no projeto do Google Cloud .

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Conceder os papéis necessários para usar o Agente de Operações

Para receber as permissões necessárias para usar o Agente de Operações para gravar registros e métricas, peça ao administrador que conceda a você os seguintes papéis do IAM na sua conta de serviço:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre papéis e o Agente de Operações, consulte Autorizar o Agente de Operações.

Ativar a API usada pelo Gerenciador de extensões de VM

O Gerenciador de Extensões de VM usa a API Compute Engine. Ative essa API no projeto do Google Cloud , caso ainda não esteja ativada.

Ativar a API Compute Engine

Conceder papéis necessários para usar o Gerenciador de Extensões de VM

Para receber as permissões necessárias para criar políticas de extensão de VM, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para criar políticas de extensão de VM. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para criar políticas de extensão de VM:

  • Para criar políticas de extensão: compute.vmExtensionPolicies.create

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para mais informações sobre papéis e permissões do IAM no Compute Engine, consulte Papéis e permissões do Compute Engine.

Instalar a CLI do Google Cloud

É possível criar e gerenciar políticas de extensão de VM usando o console do Google Cloud ou a Google Cloud CLI, gcloud. Para usar a gcloud, primeiro instale a Google Cloud CLI.

Para ver os componentes que você instalou, execute o seguinte comando:

gcloud components list

Para verificar se você tem a versão mais recente, execute o seguinte comando:

gcloud components update

Conflitos e prioridades de políticas

O Gerenciador de extensões de VM associa uma prioridade a cada nova política, com números mais baixos indicando prioridades mais altas. A prioridade padrão é 1000. Uma VM pode ser coberta por várias políticas para uma extensão como o Agente de Operações, mas apenas uma política para a extensão do Agente de Operações é eficaz na VM.

O Gerenciador de Extensões de VM usa prioridades para resolver conflitos entre as políticas aplicadas a uma VM. Para mais informações sobre o processo de resolução, consulte Prioridade de política e resolução de conflitos.

Planos de lançamento para políticas globais

As políticas globais do Gerenciador de Extensões de VM usam um plano de lançamento para determinar como uma política é distribuída para as VMs de destino. Há dois tipos de planos de lançamento:

  • Predefinidos: há dois planos de lançamento predefinidos, escolhidos pelo valor usado com a opção --rollout-predefined-plan para comandos da CLI gcloud.

    • Lançamento lento, que implanta o Agente de Operações gradualmente em diferentes zonas ao longo de um período. Este plano de lançamento é recomendado.

      Especifique esse plano de lançamento usando a opção --rollout-predefined-plan=slow_rollout.

    • Lançamento rápido, que implanta o Agente de Operações em todas as VMs de destino em todas as zonas e regiões imediatamente.

      Especifique esse plano de lançamento usando a opção --rollout-predefined-plan=fast_rollout.

  • Planos de lançamento personalizados, especificados usando a opção --rollout-custom-plan para comandos da CLI gcloud.

    Crie planos de lançamento personalizados adicionando-os ao conjunto de planos de lançamento no projeto do Google Cloud . Para mais informações, consulte o método da API Compute Engine rolloutPlans.insert.

Para mais informações sobre planos de lançamento, consulte Planos de lançamento para políticas globais.

Criar políticas de extensão de VM para instalar o Agente de Operações

Com o Gerenciador de Extensões de VM, você cria políticas que declaram quais extensões quer instalar nas VMs. O Agente de Operações é uma das extensões disponíveis. Ao definir uma política, você garante que as extensões compatíveis, incluindo o Agente de Operações, sejam instaladas e mantidas em todas as VMs que atendem aos critérios especificados, como rótulos de VM.

É possível usar políticas de extensão para o Agente de Operações para realizar tarefas como as seguintes:

  • Instalação em toda a frota: instale o Agente de Operações nos seguintes itens:

    • Todas as VMs em uma ou mais zonas no projeto do Google Cloud .
    • Todas as VMs globalmente (no seu projeto do Google Cloud ).
    • Um subconjunto de VMs em uma zona, identificadas por rótulos.
    • Um subconjunto de VMs em zonas no seu projeto do Google Cloud , identificadas por rótulos.

  • Controle de versão:

    • Mantenha o Agente de Operações atualizado para a versão mais recente.
    • Fixe a versão do Agente de Operações em uma versão específica.

  • Gerenciamento de configuração: aplique uma configuração personalizada ao Agente de Operações em todas as VMs gerenciadas por uma política.

As seções a seguir mostram exemplos de políticas que instalam o Agente de Operações de acordo com critérios específicos.

O Gerenciador de Extensões de VM é compatível com a versão 2.58.0 ou mais recente do Agente de Operações, quando ele é instalado por uma política de extensão. O Gerenciador de extensões de VM não pode gerenciar versões anteriores do Agente de operações, instâncias do Agente de operações instaladas por outros meios ou o agente do Monitoring ou o agente do Logging legados.

Instalar o Agente de Operações mais recente em todas as VMs

Para criar uma política que instale a versão mais recente do Agente de Operações em todas as VMs de uma zona ou globalmente e atualize o agente quando uma nova versão for lançada, faça o seguinte:

Console

Para criar uma política zonal, use o console do Google Cloud .

  1. No console do Google Cloud , acesse a página Políticas de extensão:

    Acesse Políticas de extensão.

    Se você usar a barra de pesquisa para encontrar a página, selecione o resultado com o subtítulo Compute Engine.

  2. Clique em + Criar.
  3. No campo Nome, insira um nome para a política.
  4. Opcional: no campo Descrição, insira uma descrição para a política.
  5. No campo Prioridade, especifique um número de prioridade para resolver conflitos entre políticas. Números menores indicam prioridade mais alta. O valor padrão é 1000.
  6. Na lista Zona, selecione a zona em que você quer aplicar essa política.
  7. Na seção Gerenciar extensões, clique em Adicionar extensão e faça o seguinte:
    1. Na lista Extensão, selecione Google Cloud's Extension for Ops Agent.
    2. Deixe o campo Version em branco.
  8. Clique em Criar.

gcloud

Para criar uma política zonal ou global, use a CLI gcloud.

Zonal

Use o seguinte comando gcloud compute zone-vm-extension-policies create para criar a política:

gcloud compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.
  • ZONE: a zona de destino, por exemplo, us-central1-f.

O comando gcloud compute zone-vm-extension-policies create usa uma opção --version. Se você omitir a opção --version, a política vai instalar a versão mais recente e atualizar o Agente de Operações quando uma nova versão for lançada.

Global

Use o seguinte comando gcloud compute global-vm-extension-policies create para criar a política:

gcloud compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.

O comando gcloud compute global-vm-extension-policies create usa uma opção --version. Se você omitir a opção --version, a política vai instalar a versão mais recente e atualizar o Agente de Operações quando uma nova versão for lançada.

Fixar o Agente de Operações em uma versão específica em todas as VMs

Para criar uma política que instale uma versão específica do Agente de Operações em todas as VMs de uma zona ou globalmente, faça o seguinte:

Console

Para criar uma política zonal, use o console do Google Cloud .

  1. No console do Google Cloud , acesse a página Políticas de extensão:

    Acesse Políticas de extensão.

    Se você usar a barra de pesquisa para encontrar a página, selecione o resultado com o subtítulo Compute Engine.

  2. Clique em + Criar.
  3. No campo Nome, insira um nome para a política.
  4. Opcional: no campo Descrição, insira uma descrição para a política.
  5. No campo Prioridade, especifique um número de prioridade para resolver conflitos entre políticas. Números menores indicam prioridade mais alta. O valor padrão é 1000.
  6. Na lista Zona, selecione a zona em que você quer aplicar essa política.
  7. Na seção Gerenciar extensões, clique em Adicionar extensão e faça o seguinte:
    1. Na lista Extensão, selecione Google Cloud's Extension for Ops Agent.
    2. Na lista Versão, selecione a versão que você quer instalar. Use a versão 2.58.0 ou mais recente.
  8. Clique em Criar.

gcloud

Para criar uma política zonal ou global, use a CLI gcloud.

Zonal

Use o seguinte comando gcloud compute zone-vm-extension-policies create para criar a política:

gcloud compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent  \
  --version=ops-agent=VERSION

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.
  • ZONE: a zona de destino, por exemplo, us-central1-f.
  • VERSION: a versão do Agente de Operações a ser instalada. Use a versão 2.58.0 ou mais recente.

    Se você omitir a opção --version, a política vai instalar a versão mais recente e atualizar o Agente de Operações quando uma nova versão for lançada, conforme mostrado no exemplo que instala a versão mais recente.

Global

Use o seguinte comando gcloud compute global-vm-extension-policies create para criar a política:

gcloud compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout \
  --version=ops-agent=VERSION

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.
  • VERSION: a versão do Agente de Operações a ser instalada. Use a versão 2.58.0 ou mais recente.

    Se você omitir a opção --version, a política vai instalar a versão mais recente e atualizar o Agente de Operações quando uma nova versão for lançada, conforme mostrado no exemplo que instala a versão mais recente.

Para ver uma lista de versões do Agente de Operações, consulte a página de versões no GitHub.

Instalar o Agente de Operações em VMs com um rótulo específico

Para criar uma política que instale a versão mais recente do Agente de Operações nas VMs em uma zona ou globalmente que tenham um rótulo específico, faça o seguinte:

Console

Para criar uma política zonal, use o console do Google Cloud .

  1. No console do Google Cloud , acesse a página Políticas de extensão:

    Acesse Políticas de extensão.

    Se você usar a barra de pesquisa para encontrar a página, selecione o resultado com o subtítulo Compute Engine.

  2. Clique em + Criar.
  3. No campo Nome, insira um nome para a política.
  4. Opcional: no campo Descrição, insira uma descrição para a política.
  5. No campo Prioridade, especifique um número de prioridade para resolver conflitos entre políticas. Números menores indicam prioridade mais alta. O valor padrão é 1000.
  6. Na lista Zona, selecione a zona em que você quer aplicar essa política.
  7. Na seção Gerenciar extensões, clique em Adicionar extensão e faça o seguinte:
    1. Na lista Extensão, selecione Google Cloud's Extension for Ops Agent.
    2. Deixe o campo Version em branco.
  8. Na seção Instâncias de VM de destino, selecione as VMs para a política. Para selecionar VMs com rótulos específicos, clique em Adicionar rótulos e inclua o par de chave-valor.
  9. Clique em Criar.

gcloud

Para criar uma política zonal ou global, use a CLI gcloud.

Zonal

Use a opção --inclusion-labels para o comando gcloud compute zone-vm-extension-policies create para especificar uma lista separada por vírgulas de pares de chave-valor:

gcloud compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent 
  --inclusion-labels=KEY1=VALUE1,KEY2=VALUE2

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.
  • ZONE: a zona de destino, por exemplo, us-central1-f.
  • KEY1=VALUE1,KEY2=VALUE2: uma lista separada por vírgulas de pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor (AND lógico) para serem incluídas. Se você especificar a opção --inclusion_labels várias vezes, a política vai segmentar as VMs que correspondem a todos os rótulos em qualquer um dos seletores (OR lógico). Se você omitir essa opção, a política vai segmentar todas as VMs na zona especificada.

Global

Use a opção --inclusion-labels para o comando gcloud compute global-vm-extension-policies create para especificar uma lista separada por vírgulas de pares de chave-valor:

gcloud compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout \
  --inclusion-labels=KEY1=VALUE1,KEY2=VALUE2

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.
  • KEY1=VALUE1,KEY2=VALUE2: uma lista separada por vírgulas de pares de chave-valor que definem rótulos de inclusão para um seletor. As VMs precisam ter todos os rótulos especificados em um seletor (AND lógico) para serem incluídas. Se você especificar a opção --inclusion_labels várias vezes, a política vai segmentar as VMs que correspondem a todos os rótulos em qualquer um dos seletores (OR lógico). Se você omitir essa opção, a política vai segmentar todas as VMs na zona especificada.

Instalar o Agente de Operações com uma configuração personalizada em todas as VMs

Para criar uma política que instale a versão mais recente do Agente de Operações em todas as VMs de uma zona ou globalmente e forneça uma configuração personalizada para o Agente de Operações, faça o seguinte:

Console

Para criar uma política zonal, use o console do Google Cloud .

  1. No console do Google Cloud , acesse a página Políticas de extensão:

    Acesse Políticas de extensão.

    Se você usar a barra de pesquisa para encontrar a página, selecione o resultado com o subtítulo Compute Engine.

  2. Clique em + Criar.
  3. No campo Nome, insira um nome para a política.
  4. Opcional: no campo Descrição, insira uma descrição para a política.
  5. No campo Prioridade, especifique um número de prioridade para resolver conflitos entre políticas. Números menores indicam prioridade mais alta. O valor padrão é 1000.
  6. Na lista Zona, selecione a zona em que você quer aplicar essa política.
  7. Na seção Gerenciar extensões, clique em Adicionar extensão e faça o seguinte:
    1. Na lista Extensão, selecione Google Cloud's Extension for Ops Agent.
    2. Deixe o campo Version em branco.
    3. No campo Conteúdo do arquivo de configuração, insira a string de configuração YAML do Agente de Operações.
  8. Clique em Criar.

gcloud

Para criar uma política zonal ou global, use a CLI gcloud.

Zonal

Use a opção --config-from-file no comando gcloud compute zone-vm-extension-policies create para especificar um arquivo de configuração:

gcloud compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --extensions=ops-agent 
  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.
  • ZONE: a zona de destino, por exemplo, us-central1-f.
  • OPS_AGENT_CONFIG_PATH: o caminho para um arquivo que contém a string de configuração YAML do Agente de Operações. Esse arquivo precisa existir no ambiente em que você executa o comando gcloud.

    O YAML de configuração do Agente de Operações pode ser longo. Colocar a configuração em um arquivo e transmiti-lo para a CLI gcloud é muito menos propenso a erros do que tentar inserir um YAML formatado corretamente na linha de comando. Alterar esse arquivo depois de criar a política não a atualiza. Para atualizar uma política, use o comando gcloud compute zone-vm-extension-policies update.

Global

Use a opção --config-from-file no comando gcloud compute global-vm-extension-policies create para especificar um arquivo de configuração:

gcloud compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=slow_rollout \
  --config-from-file=ops-agent="OPS_AGENT_CONFIG_PATH"

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.
  • OPS_AGENT_CONFIG_PATH: o caminho para um arquivo que contém a string de configuração YAML do Agente de Operações. Esse arquivo precisa existir no ambiente em que você executa o comando gcloud.

    O YAML de configuração do Agente de Operações pode ser longo. Colocar a configuração em um arquivo e transmiti-lo para a CLI gcloud é muito menos propenso a erros do que tentar inserir um YAML formatado corretamente na linha de comando. Alterar esse arquivo depois de criar a política não atualiza a política. Para atualizar uma política, use o comando gcloud compute global-vm-extension-policies update.

Se você fornecer uma configuração personalizada para o Agente de Operações ao criar ou atualizar uma política de extensão, ela vai implantar o Agente de Operações com a configuração personalizada. Não é necessário reiniciar manualmente o agente.

A configuração é armazenada com a política de extensão. Portanto, não inclua dados sensíveis, como senhas, na configuração. Como a configuração é armazenada com a política de extensão, modificar o arquivo de configuração não altera a configuração do agente. É preciso atualizar a configuração armazenada com a política usando o comando gcloud apropriado:

Quando você fornece uma configuração personalizada para o Agente de Operações, o Gerenciador de Extensões de VM copia a configuração para o local usado pelo Agente de Operações para arquivos de configuração especificados pelo usuário na VM de destino:

  • Linux: /etc/google-cloud-ops-agent/config.yaml
  • Windows: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

Se houver um arquivo config.yaml na VM, a política de extensão o substituirá.

Para informações gerais sobre como usar oGoogle Cloud console e a CLI gcloud para criar políticas de extensão de VM, consulte Instalar extensões de VM usando políticas de extensão .

Instalar o Agente de Operações com um plano de lançamento rápido em prioridade mais alta (somente global)

Para criar uma política global que instale a versão mais recente do Agente de Operações usando uma prioridade maior que a padrão e o plano de lançamento rápido, use o seguinte comando gcloud compute global-vm-extension-policies create:

gcloud compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-predefined-plan=fast_rollout \
  --priority=500

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.

Instalar o Agente de Operações em um subconjunto de zonas em um projeto do Google Cloud (somente global)

Para criar uma política global que se aplique apenas a um subconjunto de zonas em um projeto doGoogle Cloud , use um plano de lançamento personalizado que especifique as zonas em que a política será aplicada. Para informações sobre como criar planos de lançamento personalizados, consulte Sobre planos de lançamento. Para especificar um conjunto de zonas, use o campo locationSelector.includedLocations ao criar o plano de lançamento.

Para criar uma política de extensão que use um plano de lançamento personalizado, use o seguinte comando gcloud compute global-vm-extension-policies create:

gcloud compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --extensions=ops-agent  \
  --rollout-custom-plan=projects/PROJECT_ID/locations/global/rolloutPlans/CUSTOM_PLAN_NAME

Substitua as seguintes variáveis no comando:

  • POLICY_NAME: um nome para a política de extensão de VM.
  • PROJECT_ID: o identificador do projeto.
  • CUSTOM_PLAN_NAME: o nome associado ao seu plano de lançamento personalizado.

Verificar a instalação do Agente de Operações

Esta seção explica como fazer o seguinte:

Verificar o status ou a versão de uma instalação do Agente de Operações

Para determinar o status ou a versão do Agente de Operações, use uma das seguintes páginas do console doGoogle Cloud :

Compute Engine

  1. No Google Cloud console, acesse a página Instâncias de VM:

    Acessar Instâncias de VM

    Se você usar a barra de pesquisa para encontrar a página, selecione o resultado com o subtítulo Compute Engine.

  2. Selecione uma VM na lista.
  3. Clique na guia Observabilidade.

Cloud Monitoring

  1. No console do Google Cloud , acesse a página Instâncias de VM:

    Acesse Instâncias de VM.

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

  2. Selecione a visualização em Lista.

Quando o Agente de Operações é instalado na VM e está coletando registros e métricas, o status do agente é marcado com uma marca de seleção verde ao lado do rótulo Agente de Operações.

Para determinar a versão do agente instalado, passe o cursor sobre o rótulo Agente de operações no painel do Compute Engine ou do Monitoring.

Verificar se o Agente de Operações está coletando telemetria

Se o Agente de Operações tiver sido instalado e estiver em execução corretamente, ele vai enviar métricas para o Cloud Monitoring e registros para o Cloud Logging.

A seguir