Autorizar o agente do Monitoring

Observação: ignore este guia e volte para Instalar o agente do Monitoring a menos que você esteja usando VMs muito antigas do Compute Engine ou precise usar uma conta de serviço personalizada em vez da conta de serviço padrão. As instâncias do Compute Engine são pré-autorizadas para executar o agente.

Neste guia, explicamos como garantir que o agente do Monitoring, que você instala na instância de máquina virtual (VM), tenha autorização para enviar dados de telemetria para o Google Cloud Observability.

Visão geral da autorização

Autorização refere-se ao processo de determinação das permissões que um cliente autenticado tem em um conjunto de recursos. O Google Cloud autoriza o agente do Monitoring em uma instância de VM do Compute Engine usando Application Default Credentials (ADC).

O agente do Monitoring é compatível com o ADC que autentica uma conta de serviço anexada a uma VM ou uma chave de conta de serviço.

• Uma conta de serviço anexadase refere a uma conta de serviço específica para um determinado recurso, como uma VM. A conta de serviço tem as próprias credenciais exclusivas. O ADC usa o servidor de metadados da VM para receber credenciais de um serviço.
• A chave de conta de serviço é uma chave privada usada para autorizar o par de chaves em uma conta de serviço em um projeto, permitindo que você crie um token de acesso. Use o token para fornecer uma identidade e interagir com as APIs do Google Cloud em nome da conta de serviço.

Recomendamos que você configure o ADC para autenticar uma conta de serviço anexada sempre que possível, já que a chave privada requer armazenamento local, e esse armazenamento pode ser comprometido. Para mais informações sobre as chaves da conta de serviço, consulte Práticas recomendadas para gerenciar chaves de conta de serviço.

Para instâncias de VM do AWS EC2, o agente do Monitoring é compatível com autenticação apenas usando o método de chave da conta de serviço.

Antes de começar

Leia este guia se uma destas situações for o caso:

• Se você estiver executando instâncias do Compute Engine muito antigas ou tiver modificado os escopos de acesso ou as configurações da conta de serviço das instâncias do Compute Engine, conclua as etapas deste guia antes de instalar o agente. Essas VMs podem não ter o arquivo de chave da conta de serviço necessário. Para informações sobre como verificar os escopos de acesso e as configurações da conta de serviço das instâncias, consulte Verificar as credenciais do Compute Engine.

  Nas instâncias de VM do Compute Engine recém-criadas, os escopos de acesso e as configurações da conta de serviço são suficientes para executar os agentes.

• Se você estiver executando instâncias de VM do Amazon EC2 (AWS VC2), realize as seguintes ações antes de instalar o agente:

  1. Identifique o projeto de hospedagem da AWS para a conta da AWS com suas instâncias do EC2. O projeto de hospedagem é um projeto do Google Cloud com o único propósito de armazenar as métricas e os registros das instâncias do EC2 em uma conta da AWS.

     Se você não conseguir encontrar um projeto de hospedagem da AWS para a conta, recomendamos criar um projeto do Google Cloud para servir como o projeto de hospedagem. Se você tiver instâncias do EC2 em várias contas da AWS, crie um projeto do Google Cloud para cada conta. Também recomendamos que você use uma convenção de nomenclatura para esses projetos ou que você use rótulos de projeto para identificar seus projetos de hospedagem. Não recomendamos reutilizar um projeto do Google Cloud que já existe, especialmente se ele contiver recursos do Google Cloud.

  2. Conclua as etapas para autorizar o agente usando um arquivo de chave da conta de serviço.

Para verificar os escopos de acesso, faça o seguinte:

1. Consulte os escopos de acesso executando o seguinte comando na instância do Compute Engine:

   curl --silent --connect-timeout 1 -f -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/scopes

2. Na resposta ao comando, se o escopo de acesso https://www.googleapis.com/auth/cloud-platform estiver listado, isso significa que você tem autorização suficiente.

   Se https://www.googleapis.com/auth/cloud-platform não estiver listado, serão necessários dois escopos de acesso, um de cada par de "geração de registros" e "monitoramento" a seguir:

   • https://www.googleapis.com/auth/logging.write ou
     https://www.googleapis.com/auth/logging.admin
   • https://www.googleapis.com/auth/monitoring.write ou
     https://www.googleapis.com/auth/monitoring.admin

Para modificar os escopos de acesso, faça o seguinte:

1. No Console do Google Cloud, 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. Se necessário, clique na lista suspensa de projetos do Google Cloud e selecione o nome do seu projeto.
3. Selecione Instâncias de VM no menu de navegação, a guia Instâncias e o nome da VM.
4. Encerre a VM clicando em  Parar.
5. Depois que a VM for interrompida, clique em Editar.
6. Localize Escopos de acesso na seção Identidade e acesso à API da página e selecione Definir acesso para cada API.
7. Para as entradas da API Stackdriver Logging e da API Stackdriver Monitoring, selecione Somente gravação.
8. Clique em Salvar e reinicie a VM clicando em  Iniciar/Retomar.

Usar uma conta de serviço

A autenticação é o processo de determinação da identidade de um cliente. Para autenticação, recomendamos usar uma conta de serviço, um tipo especial de conta normalmente usada por um aplicativo ou uma carga de trabalho, em vez de uma pessoa. Para mais informações, consulte visão geral de contas de serviço.

É possível usar contas de serviço para autenticação, não importa onde o código é executado: no Compute Engine, no App Engine ou no local. Veja mais informações em Autenticação no Google.

Veja nesta seção como criar uma nova conta de serviço e conceder a ela os papéis necessários, além de como atualizar uma conta de serviço atual se ela não tiver os papéis necessários.

Crie uma conta de serviço

Para criar uma conta de serviço, conclua os procedimentos de Como criar uma conta de serviço com as seguintes informações:

• Selecione o projeto do Google Cloud em que a conta de serviço precisa ser criada:

  • Para instâncias do Compute Engine, escolha o projeto em que você criou a instância.

  • Para instâncias do Amazon EC2, selecione o projeto de hospedagem da AWS.

• No menu suspenso Papéis, selecione os seguintes papéis:

  • Monitoring > Monitoring Metric Writer Com isso, você autoriza agente do Monitoring.

  Se você também instalar o agente do Logging, adicione o seguinte papel a esse agente:

  • Logging > Logs Writer. Com isso, você autoriza o agente do Logging.

• Se você planeja autenticar usando uma chave de conta de serviço, selecione JSON como o Tipo de chave e clique em Criar.

  Quando você clica em Criar, é feito o download de um arquivo que contém uma chave de conta de serviço para seu sistema local. Para mais informações, consulte Criar e excluir chaves de contas de serviço.

  Observação: após o download de uma chave, não será possível fazer o download dela novamente.

Em seguida, defina a conta de serviço e as configurações com base na autorização de contas de serviço anexadas ou de chaves privadas de conta de serviço.

Verificar e modificar papéis de uma conta de serviço atual

Use o console do Google Cloud para determinar quais papéis uma conta de serviço atual tem e adicionar os papéis necessários que estão faltando:

1. No console do Google Cloud, abra a página IAM.

   Acesse o IAM

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

2. Se necessário, clique na lista suspensa de projetos do Google Cloud e selecione o nome do seu projeto.

3. Se você não vir uma lista de principais do IAM (usuários e contas de serviço), selecione a guia Permissões.

4. Na lista Ver pelos participantes, localize a entrada da conta de serviço. A coluna Papel lista os papéis concedidos à conta de serviço.

5. Se a conta de serviço não tiver os papéis necessários para o agente do Monitoring, use as etapas a seguir para adicionar os papéis descritos em Criar uma conta de serviço:

   1. Clique em  Editar na entrada da conta de serviço.
   2. Clique em Adicionar outro papel para adicionar os papéis ausentes.
   3. Clique em Salvar.

Autorizar com uma conta de serviço anexada

Para autorizar o agente do Monitoring instalado em uma instância de VM do Compute Engine que tem uma conta de serviço anexada, faça isto:

1. Verifique se você verificou os escopos de acesso da VM.

2. Conceda a essa conta de serviço os papéis de privilégio mínimo do IAM. Para saber quais são os papéis necessários, consulte a seção Criar uma conta de serviço nesta página.

3. Anexe a conta de serviço à VM em que o agente está sendo executado.

4. Se ainda não tiver instalado o agente, instale-o. Para mais informações sobre como instalar o agente, consulte Como instalar o agente.

Autorizar com uma chave de conta de serviço

Observação: os arquivos de chave da conta de serviço não são compatíveis com o agente do Monitoring para VMs do Compute Engine que executam o Windows. Nessas VMs, o agente usa as credenciais fornecidas pelo servidor de metadados.

Para autorizar o agente do Monitoring instalado em uma instância de VM usando chaves privadas de conta de serviço, faça o seguinte:

1. Transfira o arquivo de chave da conta de serviço do sistema local para a instância de VM:

   1. Crie uma variável de ambiente para apontar para o arquivo de chave da conta de serviço no seu sistema local. O exemplo a seguir cria uma variável chamada CREDS:

      CREDS=~/Downloads/PROJECT-NAME-KEY-ID.json
      

   2. Conclua as etapas exibidas na tabela a seguir:

      Observação: as instruções de cópia de arquivo a seguir presumem que você tem um ambiente Linux no sistema local e na instância. Se você estiver usando um ambiente diferente, veja a documentação do provedor de nuvem sobre como copiar o arquivo de chave de conta de serviço. Verifique se o arquivo de chave da conta de serviço está no mesmo local que a variável CREDS.

      Compute Engine

      1. No Console do Google Cloud, 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.

         Identifique o INSTANCE_NAME e o INSTANCE_ZONE da VM.

      2. No sistema local, execute um comando do Google Cloud CLI para copiar o arquivo de chave do sistema local para a instância de VM:

         REMOTE_USER="$USER"
         INSTANCE="INSTANCE_NAME"
         ZONE="INSTANCE_ZONE"
         gcloud compute scp "$CREDS" "$REMOTE_USER@$INSTANCE:~/temp.json" --zone "$ZONE"
         

      3. Na instância do Compute Engine, mova o arquivo de chave da conta de serviço do local temporário para um permanente. Para Linux, verifique se o arquivo de chave da conta de serviço pode ser lido apenas por root.

         Aviso: se você já tiver um arquivo de chave da conta de serviço, verifique se o novo arquivo de chave não substitui o arquivo de chave dos aplicativos atuais.
         Observação: os arquivos de chave da conta de serviço não são compatíveis com o agente do Monitoring para VMs do Compute Engine que executam o Windows. Nessas VMs, o agente usa as credenciais fornecidas pelo servidor de metadados.

         Estes são os locais em que o agente espera o arquivo de chave:

         • VMs do Linux: /etc/google/auth/application_default_credentials.json
         • VMs do Linux: qualquer local que você armazena na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, que precisa estar visível para o processo do agente. Para informações de configuração, consulte Definir GOOGLE_APPLICATION_CREDENTIALS.

         Por exemplo, no Linux, é possível executar o script a seguir, que move o arquivo de chave da conta de serviço para o local padrão e, em seguida, define as permissões adequadas:

         CREDENTIALS_FILE_LOCATION="/etc/google/auth/application_default_credentials.json"
         sudo mkdir -p /etc/google/auth
         sudo mv "$HOME/temp.json" "$CREDENTIALS_FILE_LOCATION"
         sudo chown root:root "$CREDENTIALS_FILE_LOCATION"
         sudo chmod 0400 "$CREDENTIALS_FILE_LOCATION"
         

      Amazon EC2

      1. Para sua VM, identifique YOUR-INSTANCE'S-ID e YOUR-INSTANCE'S-AWS-REGION.

      2. No sistema local, use scp para copiar o arquivo de chave da conta de serviço do sistema local para a instância de VM:

         KEY="YOUR-SSH-KEY-PAIR-FILE"
         INSTANCE="ec2-YOUR-INSTANCE'S-ID.YOUR-INSTANCE'S-AWS-REGION.compute.amazonaws.com"
         # The remote user depends on the installed OS: ec2-user, ubuntu, root, etc.
         REMOTE_USER="EC2-USER"
         scp -i "$KEY" "$CREDS" "$REMOTE_USER@$INSTANCE:~/temp.json"
         

         O valor da variável de ambiente INSTANCE pressupõe que sua instância do EC2 não está na região us-east-1. Para saber como definir a variável INSTANCE quando a instância estiver na região us-east-1, consulte a convenção de nomenclatura definida pela Amazon.

      3. Na instância do EC2, mova o arquivo de chave da conta de serviço do local temporário para um dos seguintes locais e, para Linux, verifique se o arquivo de chave da conta de serviço pode ser lido apenas por root.

         Aviso: se você já tiver um arquivo de chave da conta de serviço, verifique se o novo arquivo de chave não substitui o arquivo de chave dos aplicativos atuais.

         Estes são os locais em que o agente espera o arquivo de chave:

         • VMs do Linux: /etc/google/auth/application_default_credentials.json

         • VMs do Windows: C:\ProgramData\Google\Auth\application_default_credentials.json

         • VMs do Linux e do Windows: qualquer local que você armazena na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, que precisa estar visível para o processo do agente. Para informações de configuração, consulte Definir GOOGLE_APPLICATION_CREDENTIALS.

         Por exemplo, no Linux, é possível executar o script a seguir, que move o arquivo de chave da conta de serviço para o local padrão e, em seguida, define as permissões adequadas:

         CREDENTIALS_FILE_LOCATION="/etc/google/auth/application_default_credentials.json"
         sudo mkdir -p /etc/google/auth
         sudo mv "$HOME/temp.json" "$CREDENTIALS_FILE_LOCATION"
         sudo chown root:root "$CREDENTIALS_FILE_LOCATION"
         sudo chmod 0400 "$CREDENTIALS_FILE_LOCATION"
         

2. Agora sua instância de VM tem o arquivo de chave da conta de serviço de que o agente precisa. Depois, instale ou reinicie o agente:

   • Para mais informações sobre como instalar o agente, consulte Como instalar o agente.

   • Para informações sobre como reiniciar o agente, consulte este link.

   • Se você quiser verificar novamente o arquivo de chave da conta de serviço, consulte Como verificar credenciais de chave privada.

Definir GOOGLE_APPLICATION_CREDENTIALS

Nesta seção, mostramos como definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para que ela fique visível para o processo do agente.

Observação: o agente do Monitoring não é o único serviço que usa a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Se você alterar o valor dessa variável conforme descrito nesta seção, essa mudança afetará todos os serviços do sistema que dependem dessa variável.

Linux

1. Edite o seguinte arquivo de configuração ou crie o arquivo, se ele ainda não existir:

   /etc/default/stackdriver-agent
   

2. Adicione o código abaixo ao arquivo de configuração:

   GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_CREDENTIAL_FILE
   

3. Reinicie o agente do Logging ao executar o comando a seguir na instância de VM.

   sudo service stackdriver-agent restart
   

Windows

Observação: os arquivos de chave da conta de serviço não são compatíveis com o agente do Monitoring para VMs do Compute Engine que executam o Windows. Nessas VMs, o agente usa as credenciais fornecidas pelo servidor de metadados.

1. No PowerShell, execute os seguintes comandos como administrador para definir a variável de ambiente do sistema GOOGLE_APPLICATION_CREDENTIALS para o Agente de operações usar.

   [Environment]::SetEnvironmentVariable("GOOGLE_APPLICATION_CREDENTIALS", "PATH_TO_CREDENTIAL_FILE", "Machine")
   

2. Reinicie o agente do Logging ao executar o comando a seguir na instância de VM.

   Restart-Service -Name StackdriverMonitoring