Gerenciar extensões de VM usando políticas de extensão

O VM Extension Manager usa políticas de extensão para gerenciar suas extensões de VM em grande escala. Para mais informações, consulte Sobre o gerenciador de extensões de VM. Este documento descreve como visualizar, atualizar e excluir políticas de extensão de VM.

Permissões e papéis do IAM

Para ter as permissões necessárias para ver, modificar e excluir 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 visualizar, modificar e excluir 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 seguintes permissões são necessárias para visualizar, modificar e excluir políticas de extensão de VM:

  • Para conferir as políticas de extensão: compute.vmExtensionPolicies.list
  • Para conferir detalhes de uma política de extensão: compute.vmExtensionPolicies.get
  • Para modificar as políticas de extensão: compute.vmExtensionPolicies.update
  • Para excluir políticas de extensão: compute.vmExtensionPolicies.delete

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.

Conferir políticas de extensão

É possível conferir uma lista das políticas de extensão de VM no projeto ou os detalhes de uma política específica usando o console Google Cloud ou a Google Cloud CLI.

Console

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

    Acessar políticas de extensão de VM

    Nesta página, listamos todas as políticas de extensão de VM no seu projeto.
  2. Para ver detalhes de uma política de extensão específica, clique no nome dela.

gcloud

Para conferir todas as políticas de extensão em um projeto, use o comando gcloud beta compute zone-vm-extension-policies list:

gcloud beta compute zone-vm-extension-policies list \
  --project=PROJECT_ID \
  --zone=ZONE \
  --page-size=PAGE_SIZE

Substitua:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • ZONE: o nome da zona em que você quer listar as políticas de extensão de VM.
  • PAGE_SIZE: o número máximo de resultados a serem retornados por página.

Para conferir os detalhes de uma política de extensão específica, use o comando gcloud beta compute zone-vm-extension-policies describe:

gcloud beta compute zone-vm-extension-policies describe POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer descrever.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • ZONE: a Google Cloud zona em que a política de extensão de VM está localizada.

Modificar extensões atualizando uma política de extensão de VM

Quando você atualiza uma política, o Gerenciador de extensões de VM implementa as mudanças em todas as VMs aplicáveis, geralmente em um minuto. Se você modificar os rótulos de inclusão, as extensões poderão ser instaladas em novas VMs ou desinstaladas de VMs atuais, dependendo se elas corresponderem aos rótulos atualizados.

Console

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

    Acessar políticas de extensão de VM

  2. Selecione a política que você quer atualizar.
  3. Clique em Editar.
  4. Modifique a Descrição, a Prioridade, as Extensões ou as Instâncias de VM de destino.
  5. Clique em Salvar.

gcloud

Use o comando gcloud beta compute zone-vm-extension-policies update para modificar uma política de extensão de VM atual. Quando você atualiza uma política usando a gcloud, a solicitação funciona como uma substituição completa. Os campos opcionais omitidos voltam aos valores padrão em vez de manter os valores da política modificada.

Para atualizar uma política de extensão de VM, execute o seguinte comando:

  gcloud beta compute zone-vm-extension-policies update POLICY_NAME \
      --zone=ZONE \
      --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
      --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
      --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
      --inclusion-labels=KEY_1=VALUE_1 \
      --priority=PRIORITY_NUMBER \
      --description="DESCRIPTION"

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM a ser atualizada.
  • ZONE: a Google Cloud zona em que a política se aplica.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: os nomes das extensões a serem atualizadas. É preciso especificar pelo menos uma extensão.
  • VERSION_1: a versão da primeira extensão de VM.
  • VERSION_2: a versão da segunda extensão de VM.

  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: uma lista separada por vírgulas de pares de chave-valor em que a chave é o nome da extensão e o valor é o caminho para o arquivo de configuração dessa extensão. Esse caminho está na VM em que você executa o comando gcloud, não na VM em que você instala a extensão.

    Como alternativa, para fornecer a configuração como uma string inline, use a flag --config em vez de --config-from-file. Por exemplo, EXTENSION_NAME_1="CONFIG_1". É possível usar --config-from-file ou --config, mas não ambos no mesmo comando.

  • KEY_1=VALUE_1: 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 para serem segmentadas. Se você especificar --inclusion-labels várias vezes, a política vai segmentar VMs que correspondem a qualquer um dos seletores fornecidos (OR lógico). Se você omitir essa flag, a política vai segmentar todas as VMs na zona especificada.

  • PRIORITY_NUMBER: o número de prioridade da política de extensão de VM.

  • DESCRIPTION: uma descrição da política de extensão de VM.

Desinstalar extensões excluindo uma política de extensão de VM

Quando você exclui uma política, o VM Extension Manager desinstala as extensões de todas as VMs gerenciadas por essa política. No entanto, se outra política ativa de menor prioridade for aplicada a uma VM e declarar a mesma extensão, ela vai permanecer instalada nessa VM com base na política de menor prioridade.

O VM Extension Manager remove as extensões de todas as VMs acessíveis em até um minuto após a exclusão da política. Se uma VM estiver inacessível porque o agente convidado foi removido ou a VM foi excluída, o Gerenciador de extensões de VM vai pular a exclusão da extensão. Se uma VM assim ficar disponível novamente, o VM Extension Manager vai remover as extensões nesse momento.

Console

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

    Acessar políticas de extensão de VM

  2. Selecione a política que você quer excluir.
  3. Clique em Excluir.
  4. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Use o comando gcloud beta compute zone-vm-extension-policies delete para excluir uma política de extensão de VM.

gcloud beta compute zone-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

Substitua:

  • POLICY_NAME: o nome da política de extensão de VM que você quer excluir.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • ZONE: a Google Cloud zona em que a política está localizada.

Resolver problemas de extensões de VM

Nesta seção, descrevemos como solucionar problemas com extensões de VM.

Verificar se uma extensão está instalada

Para verificar se uma extensão está instalada, confira o seguinte na VM:

  • Conecte-se à VM e verifique os processos em execução.

    A tabela a seguir lista os nomes dos processos para cada extensão:

    Nome da extensão Nome do processo da extensão
    google-cloud-sap-extension google_cloud_sap_agent
    google-cloud-workload-extension google_cloud_workload_agent
    ops-agent ops-agent

    Linux 

    ps aux | grep 'EXTENSION_PROCESS_NAME'
     Substitua EXTENSION_PROCESS_NAME pelo nome do processo da extensão. Por exemplo, para verificar o processo do Agente de operações, execute o seguinte comando: 
    ps aux | grep 'ops-agent'

    Windows 

    tasklist | findstr "EXTENSION_PROCESS_NAME"
     Substitua EXTENSION_PROCESS_NAME pelo nome do processo da extensão. Por exemplo, para verificar o processo do Agente de operações, execute o seguinte comando: 
    tasklist | findstr "ops-agent"

    A saída do comando ps em uma VM do Linux para o Agente de operações pode mostrar uma entrada semelhante a esta:

    ....
/var/lib/google-guest-agent/931374772276853249/plugins/ops-agent_baddabb3dac3
....

  • Ative e revise os registros do agente convidado. Os registros do agente convidado mostram quando uma extensão é instalada e iniciada.

    Confira a seguir um exemplo da saída que pode aparecer nos registros do agente convidado quando uma extensão do Agente de operações é instalada:

    my-instance google_guest_agent [14972]: Installing plugin "ops-agent", revision "2dfa648c1892da87"
my-instance google_guest_agent [14972]: (client.go:181) Sent message [[type.googleapis.com/agent_controlplane.PluginEventMessage: (revision_id:"2dfa648c1892da87)]]
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "DownloadPluginStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (pluginengine.go:316) Successfully downloaded "https://storage.googleapis.com/acp-gcs-bucket-us-centrall-a/ops-agent
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "UnpackPluginArchiveStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (pluginengine.go:361) Successfully unpacked "/var/lib/google-guest-agent/ops-agent.tar.gz" to "/google-guest-agent/ops-agent_2dfa648c1892da87
my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "LaunchPluginStep" on plugin "ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (run_linux.go:32) Attempting process start: (OutputType:0 Name:/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87)
my-instance google_guest_agent [14972]: (pluginlauncher.go:132) Launched a plugin process from "/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87"
my-instance google_guest_agent [14972]: (plugin.go:136) Dialing in on plugin "ops-agent 2dfa648c1892da87"
my-instance google_guest_agent [14972]: (plugin.go:51) Executing start request on plugin "ops-agent_2dfa648c1892da87"

Resolver problemas na instalação

Se uma extensão não for instalada em uma VM depois que você criar uma política, siga estas etapas para resolver o problema:

  1. Aguarde a aplicação da política. Pode levar até uma hora para uma política ser aplicada, incluindo novas tentativas.
  2. Verifique se os rótulos de inclusão especificados na política correspondem aos rótulos da VM.
  3. Para identificar possíveis erros de instalação, ative o registro de depuração para o agente convidado.

  4. Depois de corrigir o problema, tente instalar novamente usando um dos métodos a seguir:

    • Recrie a política: exclua a política e crie uma nova.

    • Use uma política temporária de alta prioridade: se você quiser evitar recriar uma política que afeta muitas VMs, use uma política temporária de maior prioridade para tentar novamente a instalação em VMs específicas:

      1. Adicione um novo rótulo às VMs em que a instalação falhou. Por exemplo, adicione um rótulo status=failed.
      2. Crie uma política com uma prioridade maior que tenha como destino o novo rótulo. Por exemplo, se a política original que falhou tinha a prioridade padrão de 1000, crie uma política com uma prioridade maior, como 500. 
        gcloud beta compute zone-vm-extension-policies create temp-policy  
        
--project=test-project 
        
--zone=us-central1-f 
        
--extensions=ops-agent 
        
--config-from-file=ops-agent="/usr/ops-agent-config.yaml" 
        
--priority=500 
        
--inclusion-labels=status=failed
      3. Depois que a extensão for instalada, exclua a política temporária e remova o rótulo das VMs. A extensão permanece instalada porque a política original ainda está ativa.

Ver registros de depuração do agente convidado

Para ativar a geração de registros de depuração, adicione as configurações de nível de registro e verbosidade à seção Core do arquivo de configuração do agente convidado da seguinte maneira:

Linux

  1. Abra o arquivo de configuração do agente convidado localizado em /etc/default/instance_configs.cfg.

  2. Adicione as seguintes linhas ao arquivo. Se a seção [Core] já existir, adicione as configurações log_level e log_verbosity a ela.

    [Core]
log_level = 4
log_verbosity = 4

  3. Reinicie o gerenciador de agentes convidados executando o seguinte comando:

     sudo systemctl restart google-guest-agent-manager

  4. Para ver os registros da atividade do agente convidado durante a instalação da extensão, execute o seguinte comando:

    journalctl -u google-guest-agent-manager

Windows

  1. Abra o arquivo de configuração do agente convidado localizado em C:\Program Files\Google\Compute Engine\instance_configs.cfg.

  2. Adicione as seguintes linhas ao arquivo. Se a seção [Core] já existir, adicione as configurações log_level e log_verbosity a ela.

    [Core]
log_level = 4
log_verbosity = 4

  3. Reinicie o gerenciador de agentes convidados executando o seguinte comando como administrador do Windows:

     net stop GCEAgentManager
 net start GCEAgentManager

  4. Para ver os registros da atividade do agente convidado durante a instalação da extensão, execute o seguinte comando no PowerShell:

    Get-Eventlog -Source google_guest_agent_manager -LogName Application

Depois de ativar os registros de depuração, verifique os seguintes erros comuns:

  • Espaço em disco insuficiente: se os registros informarem que não há espaço suficiente, libere espaço no disco ou redimensione-o para adicionar mais espaço.
  • Uso excessivo de recursos: se os registros indicarem que o agente convidado interrompeu a extensão devido ao uso excessivo de memória ou CPU, mude o tipo de máquina da VM para um com mais recursos.

A seguir