Resolver problemas de falhas de pipeline

Linux

Observação:o Image Builder está disponível para todos, mas seu projeto precisa ser adicionado a uma lista de permissões antes de poder ser usado. Para solicitar acesso, envie o formulário de solicitação de acesso ou entre em contato com a equipe da sua conta do Google Cloud. A lista de permissões abrange apenas as contas de serviço no seu projeto e não as contas de serviço do Google. Para mais informações, consulte Contas de serviço cobertas pela lista de permissões.

Se o pipeline do Image Builder falhar durante a fase de personalização, revise os arquivos de registro, configure a flag de depuração interativa na VM de worker ou analise as imagens de depuração intermediárias para identificar erros de script ou de tempo de compilação.

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ódigo ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:

  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.
  2. Defina uma região e uma zona padrão.

Revisar canais de geração de registros

O Image Builder grava registros em vários locais para ajudar você a diagnosticar falhas em diferentes níveis da pilha:

• Registros do orquestrador do Cloud Build: mostram as etapas de builder de alto nível no console do Cloud Build. Se uma etapa falhar, um link para o diretório workdir correspondente do Cloud Storage será impresso.
• Registros do agente da VM de personalização: o agente de personalização captura a saída padrão (stdout) e o erro padrão (stderr) das etapas de personalização. O orquestrador pesquisa esses registros e os transmite diretamente para os registros de rastreamento do Cloud Build. Se os registros forem truncados ou você precisar inspecioná-los por completo, acesse a pasta correspondente ao ID de build no bucket _GCS_WORKDIR.
• Registros do console serial: se o SO convidado não for inicializado, o agente de personalização não poderá ser iniciado. Nesses casos, consulte os registros do console serial. O orquestrador transmite a saída da porta serial da VM de worker diretamente para o bucket workdir do Cloud Storage. Um link para o arquivo de registro serial é impresso no final do rastreamento com falha do Cloud Build.
• Registros do diário do SO convidado: para uma solução de problemas detalhada no nível do sistema no Linux, o agente de personalização faz upload de uma cópia completa do registro journal para o bucket workdir do Cloud Storage no final da execução.

Resolver falhas de script usando a flag de depuração

Por padrão, se uma etapa de personalização falhar, o Image Builder vai encerrar a execução e excluir a VM de worker imediatamente para controlar os custos.

Para depurar scripts de forma interativa, ative a flag debug. Isso mantém a VM ativa, permitindo que você se conecte diretamente ao sistema operacional convidado ativo usando SSH.

Ativar a flag de depuração

No arquivo imagebuilder.yaml, defina debug: true no bloco infrastructureConfig:

infrastructureConfig:
  machineType: e2-standard-4
  zone: us-central1-a
  # Enable interactive debugging
  debug: true
  instanceDurationHours: 1.5

Acionar o build e aguardar a falha

Envie seu build usando métodos padrão. Se o pipeline encontrar um erro de script, o seguinte vai acontecer:

1. O orquestrador pausa a execução do build.
2. O Image Builder não exclui a VM de worker. Ele continua em execução no seu projeto.
3. A VM permanece ativa pelo tempo especificado na propriedade instanceDurationHours antes do encerramento automático.

Conectar-se à VM de worker para depurar

Confira a saída do console do Cloud Build para recuperar o nome da instância de VM de worker ativa. Abra um terminal e conecte-se à VM de worker usando gcloud compute ssh:

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID

Se o arquivo imagebuilder.yaml configurar externalIP: none, o que resulta em nenhum endereço IP externo, inclua a flag --tunnel-through-iap para se conectar usando o encaminhamento de TCP do Identity-Aware Proxy (IAP):

gcloud compute ssh WORKER_VM_NAME \
    --zone=BUILD_ZONE \
    --project=PROJECT_ID \
    --tunnel-through-iap

Depois de conectado, você pode executar comandos em tempo real, inspecionar arquivos de destino, analisar processos em execução, revisar registros do histórico do instalador e testar modificações de script diretamente no disco.

Analisar imagens de depuração intermediárias

Como alternativa a manter a VM de worker ativa com a flag debug, analise o estado do disco usando a imagem de depuração gerada automaticamente:

1. Sempre que um build falha com debug: false (o padrão), o orquestrador exporta o disco de inicialização parcialmente personalizado como uma imagem do Compute Engine.
2. A imagem de depuração é nomeada usando o padrão image-builder-debug-image-BUILD_ID e atribuída à família de imagens image-builder-debug-images.

3. Para inspecionar o sistema de arquivos, crie uma instância de VM temporária usando esta imagem de depuração como o disco de inicialização:

   gcloud compute instances create temp-debug-vm \
       --image-family=image-builder-debug-images \
       --zone=ZONE \
       --project=PROJECT_ID
   

4. Conecte-se à instância temp-debug-vm para inspecionar o disco e isolar o motivo da falha na personalização.

Resolver tempos limite do Cloud Build

Se uma execução de pipeline do Image Builder levar mais tempo do que o esperado, o job do Cloud Build será interrompido e vai falhar com um status TIMEOUT.

Os tempos de build podem variar e geralmente são mais longos para tipos de máquinas maiores. Portanto, defina o tempo limite para permitir mais tempo para a conclusão do build. Se não for definido, o tempo limite padrão do Cloud Build será de 1 hora (3600s).

Para configurar um tempo limite maior, defina o campo timeout no nível raiz do arquivo cloudbuild.yaml:

options:
  automapSubstitutions: true
  requestedVerifyOption: VERIFIED
  substitutionOption: ALLOW_LOOSE
  dynamicSubstitutions: true
  logging: CLOUD_LOGGING_ONLY

# Increase the overall build timeout (for example, 2 hours)
timeout: '7200s'

Depois de atualizar o valor de tempo limite, execute o build novamente e verifique se o pipeline do Image Builder consegue ser executado até a conclusão.

Para mais informações sobre o parâmetro timeout, consulte timeout na documentação do Cloud Build.