O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Como solucionar problemas do VM Manager

Neste documento, descrevemos como solucionar problemas com o VM Manager.

Para mais informações sobre o VM Manager, consulte VM Manager.

Antes de começar

Configure a autenticação, caso ainda não tenha feito isso. Com isso, você confirma sua identidade para acesso a serviços e APIs do Google Cloud . Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:
Selecione a guia para como planeja usar as amostras nesta página:
Console

Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud , não é necessário configurar a autenticação.
gcloud
1. Instale a CLI do Google Cloud. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando:
  gcloud init
  Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
  
  Observação: se você já instalou a CLI gcloud, verifique se tem a versão mais recente executando gcloud components update.
Defina uma região e uma zona padrão.

REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Visão geral

Para resolver problemas, primeiro verifique se o VM Manager está configurado corretamente. Se a configuração estiver correta e você ainda tiver problemas, analise os registros. Ao analisar os registros, é possível identificar problemas com a VM ou no fluxo de trabalho do VM Manager, como erros em comandos ou scripts, que você pode isolar e resolver.

É possível coletar as seguintes informações dos registros:

Qualquer mensagem de erro ou aviso registrado pela VM. Esses registros ajudam a identificar erros no nível da VM ou de outros serviços em execução na VM. Para analisar esses registros, consulte Inspecionar o Cloud Logging.
Informações de depuração detalhadas registradas pelo agente de configuração do SO. Esses registros ajudam a identificar problemas com qualquer uma das operações executadas pelo VM Manager. Para inspecionar os registros de depuração do agente de configuração do SO, consulte Inspecionar registros de depuração.

Depois de identificar os problemas ou erros, consulte também a seção de erros comuns para ver possíveis correções ou a solução alternativa para gerenciar implantações de patch em uma organização.

Inspecionar o Cloud Logging

Use os links rápidos do console do Google Cloud de cada recurso para ver os registros.

Patch do SO

No console do Google Cloud , acesse a guia Execução de jobs na página Patch.
Acessar a execução de jobs
Clique no nome do job de patch que você quer depurar.
Acesse a seção Instâncias de VM atualizadas.
Para uma VM específica, em Registros, clique em Exibir.

Políticas do SO

Esse procedimento é compatível com políticas do SO. Para políticas de convidado (Beta), use a opção de registros de depuração, na seção a seguir.

No console do Google Cloud , acesse a guia Instâncias de VM na página Políticas do SO.
Acessar instâncias de VM
Clique no nome da VM que você quer depurar.
Acesse a seção Políticas.
Em Registros, clique em Exibir.

Orquestradores de políticas do SO

No console do Google Cloud , acesse a guia Orquestradores de políticas do SO na página Políticas do SO.
Acessar os orquestradores de políticas do SO
Clique no nome do orquestrador de políticas de SO que você quer depurar.
Acesse a seção Registros e verifique a entrada de registro.

Inspecionar registros de depuração

Para identificar problemas com qualquer recurso do VM Manager, ative a depuração do agente de configuração do SO e visualize o registro de depuração.

Ativar a geração de registros de depuração para o agente de configuração do SO

Para ativar a geração de registros de depuração, defina os metadados de osconfig-log-level=debug na instância ou no projeto da VM.

Para ativar a geração de registros de depuração na sua VM, conclua as seguintes etapas:

Console

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

Acessar instâncias de VM
Clique no nome da VM em que você quer definir o valor dos metadados.
Na página Detalhes da instância, clique em Editar para editar as configurações.
Em Metadados personalizados, adicione as entradas de metadados a seguir:

Chave: osconfig-log-level
Valor: debug
Clique em Salvar para aplicar as mudanças à VM.

gcloud

Use o comando instances add-metadata com a sinalização --metadata=osconfig-log-level=debug.

gcloud compute instances add-metadata VM_NAME \
    --metadata=osconfig-log-level=debug

Substitua VM_NAME pelo nome da VM.

REST

Para saber mais, siga as instruções da API sobre Como configurar metadados da instância.

O seguinte par de chave-valor é exigido como parte da propriedade de metadados:

Chave: osconfig-log-level
Valor: debug

Ver registros de depuração

Quando a geração de registros de depuração está ativada, o agente de configuração do SO grava entradas de registro no Cloud Logging e no console da porta serial.

Depois de ativar a geração de registros de depuração na sua VM, o agente de configuração do SO leva aproximadamente dez minutos para começar a gravar mensagens de depuração no Cloud Logging. Para reduzir esse tempo de espera, reinicie o agente ou sua VM. Para mais informações sobre o Cloud Logging, consulte Como visualizar registros do Cloud Logging.

Para ver os registros de depuração, use as seguintes opções:

Cloud Logging: use o console do Google Cloud ou a Google Cloud CLI
Console de porta serial

Console

Acesse a página Geração de registros > Análise de registros (Análise de registros) no console doGoogle Cloud :

Acessar a Análise de registros
Se necessário, selecione um projeto do Google Cloud na parte de cima da página ou crie um novo.
Na lista suspensa Recurso, selecione Instância da VM. Será exibida uma lista de VMs disponíveis (instance_id).
Clique na VM que você quer visualizar.
Clique em Adicionar.
Na lista suspensa Nome do registro, selecione OSConfigAgent.
Clique em Adicionar.

A consulta será semelhante à seguinte:

resource.type="gce_instance" resource.labels.instance_id="INSTANCE_ID"
logName="projects/PROJECT_ID/logs/OSConfigAgent"

Clique em Run query.

gcloud

Execute o comando gcloud logging read.

 gcloud logging read "resource.type=gce_instance AND logName=projects/PROJECT_ID/logs/OSConfigAgent"

Substitua PROJECT_ID pelo ID do projeto.

Porta serial

Para informações de registro de depuração a partir do console da porta serial, consulte Como visualizar a saída da porta serial.

Erros comuns

Problemas de autenticação

Para que o VM Manager funcione, você precisa ter o seguinte:

Uma conta de serviço anexada. O VM Manager usa essa conta de serviço para assinar solicitações ao serviço da API.
Verifique se a conta de serviço anexada tem o papel roles/logging.logWriter para gravar registros na API Logging.
Agente de serviço de configuração do SO do Google Cloud. O VM Manager cria esse agente de serviço ao iniciar jobs de patch e atribui a ele o papel de agente de serviço de configuração do Cloud OS. Para criar políticas do SO, não é necessário configurar esse agente de serviço.

Se você usar o VM Manager e não tiver uma conta de serviço anexada ou um agente de serviço de configuração do SO do Google Cloud, talvez encontre os seguintes erros ao trabalhar com jobs de patch:

Service account permissions are missing. Verify that the service account has the correct permissions and try again.

OSConfigAgent Error main.go:88: error getting token from metadata: metadata: GCE metadata "instance/service-accounts/default/identity?audience=osconfig.googleapis.com&format=full" not defined

message: "Error running OPERATION_NAME: error calling OPERATION_NAME: code: "PermissionDenied", message: "The caller does not have permission", details: []"

Os problemas de autenticação também podem impedir que as instâncias de VM apareçam no painel de patch.

Para resolver esses problemas, tente uma ou todas as opções a seguir:

Verifique se todas as VMs têm uma conta de serviço anexada.
Verifique se o papel de Agente de serviço de configuração do Cloud OS (roles/osconfig.serviceAgent) está definido no Agente de serviço de configuração do SO do Google Cloud.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-osconfig.iam.gserviceaccount.com' \
  --role='roles/osconfig.serviceAgent'
```
Substitua:
- PROJECT_ID: ID do projeto
- PROJECT_NUMBER: o ID do número do projeto

Erro ao excluir pacotes para atualizações de patch

Se você especificar caracteres curinga ou caracteres especiais para o nome de pacotes ao excluir pacotes em um job de patch, o gerenciamento de correções do SO poderá ignorar a lista e atualizar todos os pacotes.

Para resolver esse problema, atualize o agente de configuração do SO para a versão 20220829.00 e use barras (/) para unir o nome do pacote.

No exemplo a seguir, o Gerenciamento de correções do SO exclui pacotes yum com o prefixo google- no nome do pacote.

      gcloud compute os-config patch-jobs execute --instance-filter-all 

        --yum-excludes=/google-.*/

Solução alternativa para gerenciar implantações de patch em uma organização

As implantações de patch e os jobs de patch têm como escopo projetos individuais do Google Cloud , ao contrário das políticas de SO, que podem ser orquestradas em uma organização ou pasta usando orquestradores de políticas.

Como solução alternativa para gerenciar implantações de patch em grande escala, use o Inventário de recursos do Cloud e a Google Cloud CLI em um script Bash para iterar todos os projetos na sua organização. Com esse script, é possível realizar as seguintes tarefas:

Ativar o VM Manager em vários projetos
Criar uma implantação de patch em vários projetos
Exportar resultados de jobs de patch em projetos para CSV

Permissões necessárias e ID da organização

Antes de executar os scripts nesta seção, verifique se você tem as permissões necessárias do Identity and Access Management (IAM) e o ID da organização:

Nível da organização: para listar todos os projetos na sua organização usando o Inventário de recursos do Cloud, sua conta de usuário ou de serviço precisa ter a permissão cloudasset.assets.searchAllResources (incluída no papel de Leitor de recursos do Cloud, roles/cloudasset.viewer) na organização.
Nível do projeto de destino: dependendo das tarefas executadas na organização, sua conta de usuário ou de serviço precisa ter as seguintes permissões em cada projeto de destino (por exemplo, herdadas de uma vinculação de papel no nível da organização):
- Para ativar a API OS Config e definir os metadados do projeto: serviceusage.services.enable (Administrador do Service Usage, roles/serviceusage.serviceUsageAdmin) e compute.projects.setCommonInstanceMetadata (Administrador da instância do Compute (v1), roles/compute.instanceAdmin.v1).
- Para criar implantações de patch: osconfig.patchDeployments.create (Administrador de implantação de patch do OS Config, roles/osconfig.patchDeploymentAdmin).
- Para listar jobs de patch e ver detalhes da instância de VM: osconfig.patchJobs.list e osconfig.patchJobs.get (Leitor de jobs de patch da configuração do SO, roles/osconfig.patchJobViewer).

Para descobrir o ID da organização, execute o comando gcloud projects get-ancestors em qualquer projeto da organização:

gcloud projects get-ancestors PROJECT_ID

Substitua PROJECT_ID pelo ID de um projeto na sua organização. A saída lista as pastas pai do projeto e o ID de organization.

Ativar o VM Manager em vários projetos

Para ativar o VM Manager em todos os projetos atuais e futuros em uma organização ou pasta, o Google recomenda usar ativação de serviço hierárquica e políticas da organização ou o Terraform.

Como alternativa, para ativar a API OS Config (osconfig.googleapis.com) e definir os metadados do projeto enable-osconfig=TRUE em todos os projetos atuais da sua organização usando um script Bash, execute o seguinte comando:

for project in $(gcloud asset search-all-resources \
    --scope=organizations/ORGANIZATION_ID \
    --asset-types=cloudresourcemanager.googleapis.com/Project \
    --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
  gcloud services enable osconfig.googleapis.com --project="$project"
  gcloud compute project-info add-metadata --project="$project" \
      --metadata=enable-osconfig=TRUE
done

Substitua ORGANIZATION_ID pelo ID da organização.

Criar uma implantação de patch em vários projetos

Para aplicar uma programação de implantação de patch padronizada em todos os projetos da sua organização, crie um arquivo de configuração de implantação de patch e aplique-o a cada projeto:

Crie um arquivo de modelo JSON ou YAML chamado patch_deployment_template.json que defina o filtro da instância de destino, a configuração de patch e a programação. Para mais informações sobre os campos de configuração compatíveis, consulte Como criar uma implantação de patch e a referência de recursos PatchDeployment.

Por exemplo, o arquivo patch_deployment_template.json a seguir programa um job de patch semanal recorrente todas as terças-feiras às 19h30 no fuso horário America/Los_Angeles para todas as instâncias de VM em um projeto:
```
{
  "instanceFilter": {
    "all": true
  },
  "patchConfig": {
    "rebootConfig": "DEFAULT"
  },
  "recurringSchedule": {
    "frequency": "WEEKLY",
    "weekly": {
      "dayOfWeek": "TUESDAY"
    },
    "timeOfDay": {
      "hours": 19,
      "minutes": 30
    },
    "timeZone": {
      "id": "America/Los_Angeles"
    }
  }
}
```

Execute o loop a seguir para criar a implantação de patch em cada projeto da organização usando o comando gcloud compute os-config patch-deployments create:

for project in $(gcloud asset search-all-resources \
    --scope=organizations/ORGANIZATION_ID \
    --asset-types=cloudresourcemanager.googleapis.com/Project \
    --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
  gcloud compute os-config patch-deployments create patch-"$project" \
      --project="$project" \
      --file=patch_deployment_template.json
done

Substitua ORGANIZATION_ID pelo ID da organização.

Exportar resultados de jobs de patch em projetos para CSV

Para auditar os resultados do job de patch, use o comando gcloud compute os-config patch-jobs list-instance-details para exportar detalhes da instância de VM de jobs de patch com falha ou bem-sucedidos para um arquivo CSV.

Job de patch único: para exportar as instâncias de VM que falharam ou foram bem-sucedidas em um job de patch específico, execute os seguintes comandos:

Exporte as instâncias de VM com falha:

gcloud compute os-config patch-jobs list-instance-details PATCH_JOB_ID \
    --project=PROJECT_ID \
    --filter="state:(FAILED OR TIMED_OUT OR NO_AGENT_DETECTED)" \
    --format="csv(name.basename():label=INSTANCE_NAME,zone:label=ZONE,state:label=STATE,failureReason:label=FAILURE_REASON)" > failed_patches.csv

Exportar instâncias de VM bem-sucedidas:

gcloud compute os-config patch-jobs list-instance-details PATCH_JOB_ID \
    --project=PROJECT_ID \
    --filter="state=SUCCEEDED" \
    --format="csv(name.basename():label=INSTANCE_NAME,zone:label=ZONE,state:label=STATE,attemptCount:label=ATTEMPT_COUNT)" > succeeded_patches.csv

Substitua:

PATCH_JOB_ID: o ID do job de patch
PROJECT_ID: o ID do projeto;

Todos os projetos em uma organização: para iterar todos os projetos na sua organização e exportar instâncias de VM com falha e bem-sucedidas em jobs de patch para arquivos CSV, execute o seguinte script:

echo "PROJECT_ID,PATCH_JOB_ID,INSTANCE_NAME,ZONE,STATE,FAILURE_REASON" > failed_patches.csv
echo "PROJECT_ID,PATCH_JOB_ID,INSTANCE_NAME,ZONE,STATE,ATTEMPT_COUNT" > succeeded_patches.csv

for project in $(gcloud asset search-all-resources \
    --scope=organizations/ORGANIZATION_ID \
    --asset-types=cloudresourcemanager.googleapis.com/Project \
    --format="csv(additionalAttributes.projectId)" | sed 1d | sort); do
  for job in $(gcloud compute os-config patch-jobs list \
      --project="$project" \
      --format="value(name.basename())"); do
    gcloud compute os-config patch-jobs list-instance-details "$job" \
        --project="$project" \
        --filter="state:(FAILED OR TIMED_OUT OR NO_AGENT_DETECTED)" \
        --format="csv[no-heading](name.basename(),zone,state,failureReason)" | \
        sed "s/^/${project},${job},/" >> failed_patches.csv
    gcloud compute os-config patch-jobs list-instance-details "$job" \
        --project="$project" \
        --filter="state=SUCCEEDED" \
        --format="csv[no-heading](name.basename(),zone,state,attemptCount)" | \
        sed "s/^/${project},${job},/" >> succeeded_patches.csv
  done
done

Substitua ORGANIZATION_ID pelo ID da organização.

Por padrão, o comando gcloud compute os-config patch-jobs list retorna até 10 jobs de patch por projeto. Para exportar resultados apenas do job de patch mais recente em cada projeto, adicione --sort-by="~update_time" --limit=1 ao comando gcloud compute os-config patch-jobs list.

Para relatórios de conformidade de patch e vulnerabilidade em toda a organização no console doGoogle Cloud ou no BigQuery, consulte Ver resumo do patch para VMs em uma organização ou pasta e Ver relatórios de vulnerabilidade para sua organização.

Como solucionar problemas do VM Manager Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Console

gcloud

REST

Visão geral

Inspecionar o Cloud Logging

Patch do SO

Políticas do SO

Orquestradores de políticas do SO

Inspecionar registros de depuração

Ativar a geração de registros de depuração para o agente de configuração do SO

Console

gcloud

REST

Ver registros de depuração

Console

gcloud

Porta serial

Erros comuns

Problemas de autenticação

Erro ao excluir pacotes para atualizações de patch

Solução alternativa para gerenciar implantações de patch em uma organização

Permissões necessárias e ID da organização

Ativar o VM Manager em vários projetos

Criar uma implantação de patch em vários projetos

Exportar resultados de jobs de patch em projetos para CSV

A seguir

Como solucionar problemas do VM Manager