Depurar aplicativos do Kubernetes no Cloud Code para Cloud Shell

O Cloud Code permite depurar um aplicativo implantado em um cluster do Google Kubernetes Engine (GKE) usando o skaffold debug.

É possível depurar seu aplicativo em um cluster local, como o minikube ou o Docker Desktop, o GKE ou qualquer outro provedor de nuvem.

Com o suporte à depuração do Cloud Code, você não precisa concluir configuração manual, como configurar o encaminhamento de portas ou injetar uma linguagem específica de depuração. A depuração exige uma biblioteca de cliente Aplicativo do GKE que inclui um skaffold.yaml e uma configuração de inicialização cloudcode.kubernetes.

Depurar um aplicativo do GKE

Para começar a depurar seu aplicativo do GKE, siga estas etapas:

  1. Na barra de status do Cloud Code, clique no nome do projeto ativo.

    Nome do projeto ativo na barra de status

  2. No menu "Escolha rápida" que aparece, selecione Depurar no Kubernetes.

  3. Se o aplicativo não tiver a configuração necessária do Skaffold ou a configuração de inicialização cloudcode.kubernetes, o Cloud Code ajudará você a configurá-las.

  4. Confirme se você quer usar o contexto do Kubernetes atual para executar o aplicativo (ou alternar para um preferido).

  5. Se você escolheu um cluster remoto como contexto, quando solicitado, escolha um registro de imagem para enviar as imagens. Se você estiver usando o Container Registry, poderá navegar até um registro atual ou especificar o nome de um registro a ser criado. Se o projeto tiver a API Artifact Registry ativada e pelo menos um repositório do Artifact Registry, é possível navegar e selecionar um repositório existente do Artifact Registry. de dados.

    Os exemplos a seguir demonstram como especificar onde as imagens de contêiner são armazenadas para alguns registros comuns:

    Artifact Registry {region}-docker.pkg.dev/{project_id}/{repo-name}
    Container Registry gcr.io/{project_id}
    Docker Hub docker.io/{account}
    Verifique se você tem a autenticação correta se estiver usando um repositório particular do Docker Hub.

    Para gerar o nome final do repositório de imagem, o Cloud Code concatena esse registro de imagem com o nome da imagem especificado nos manifestos do Kubernetes. Essa escolha é armazenada na configuração de inicialização do cloudcode.kubernetes (encontrada em .vscode/launch.json).

    Para mais informações, consulte o guia de processamento de registros de imagem.

    O Cloud Code, em seguida, cria os contêineres, os envia para o registro, aplica as configurações do Kubernetes ao cluster e aguarda o lançamento.

    Após a conclusão do lançamento, o Cloud Code encaminha automaticamente todas as portas de contêiner declaradas à sua máquina e exibe os URLs na janela de saída para que seja possível procurar seu aplicativo ativo.

  6. Para cada contêiner depurável no seu aplicativo, confirme ou insira o diretório no contêiner remoto em que o programa que você quer depurar está localizado.

    Se preferir, pressione ESC para pular a depuração do contêiner.

    Solicitação de raiz remota

    O Cloud Code anexa uma sessão de depuração para cada elemento depurável. contêiner no aplicativo.

    Agora é possível realizar as mesmas tarefas realizadas ao depurar código local, como definir pontos de interrupção e avançar o código, em um cluster ativo do Kubernetes.

    Por padrão, quando uma alteração no aplicativo é salva automaticamente, o Cloud Code implanta o aplicativo novamente e configura uma nova sessão de depuração. Alterne esse recurso com a sinalização watch na configuração de inicialização do seu projeto.

  7. Para inspecionar informações de pilha e variáveis, use a barra lateral de depuração (em inglês). Para interagir com a sessão, use o Console de depuração (em inglês) no depurador do painel inferior.

  8. Depois que a sessão for concluída, use os seguintes comandos do menu de contexto:

    • Abrir registros de implantação: abra os registros do aplicativo de uma implantação específica com o explorador de registros do Cloud Code.
    • Open Service URL: abra o URL do serviço do aplicativo de um serviço específico em um navegador da Web.
  9. Se você desativou o modo de exibição na configuração de inicialização e quer fazer alterações no aplicativo e recriá-lo e reimplantá-lo, pause a ação de execução no painel "Sessões de desenvolvimento" e clique em Ícone "Recriar e reimplantar" Recrie e reimplante o aplicativo.

  10. Para encerrar a sessão de depuração, clique em Ícone de parada de depuração Stop na barra de ferramentas de depuração.

    Depois de terminar a sessão de depuração, todos os recursos implantados do Kubernetes são excluídos do cluster.

Detalhes da configuração

O Cloud Code, com a tecnologia do Skaffold, automaticamente processa os seguintes detalhes de configuração para todos os idiomas compatíveis:

  • Encaminhar a porta de depuração para que o depurador seja anexado.
  • Como anexar um depurador a um ou mais contêineres depuráveis no aplicativo. Caso seu aplicativo tenha vários contêineres depuráveis (contêineres com linguagem compatível com a depuração do Cloud Code) configurada skaffold.yaml, um depurador será anexado a cada contêiner depurável.
  • manter definições de mapeamento de origem entre sessões; é possível personalizar essas definições editando o arquivo .vscode/launch.json diretamente.

O Cloud Code também processa os seguintes detalhes de configuração específicos da linguagem:

Node.js

Como reescrever o ponto de entrada para invocar:

node --inspect=localhost:9229

Python

Como instalar o depurador do módulo ptvsd usando um contêiner de inicialização e reescrever o ponto de entrada para invocar:

python -m ptvsd --host localhost --port 5678

Go

Instalar o depurador dlv usando um contêiner de inicialização e reescrever o ponto de entrada para que a sessão de depuração iniciada seja executada somente com um servidor de depuração (no modo headless) o processo depurado no início, aceita várias conexões de clientes e escuta em localhost:56268:

  dlv exec --headless --continue --accept-multiclient --listen=localhost:56268 --api-version=2, <app> --

Java

Adicionar um ambiente JAVA_TOOLS_OPTIONS com a configuração apropriada do Java Debug Wire (JDWP) para que o agente de depuração JDWP detecte uma conexão de soquete na porta 5005 e permita que a VM comece a ser executada antes do depurador anexado:

  jdwp=transport=dt_socket,server=y,suspend=n,address=5005,quiet=y

Para mais detalhes sobre a depuração com tecnologia Skaffold, consulte a documentação do skaffold debug.

Configurar o contêiner

Para preparar o contêiner para depuração, siga as instruções referentes à linguagem que você está usando:

Node.js

  • Iniciar o aplicativo Node.js com --inspect=<debugPort> em que debugPort vem do anexar configuração. Exemplo: CMD ["node", "--inspect=9229", "index.js"]

Python

  • Certifique-se de que você Módulo ptvsd instalado na máquina e no contêiner.
  • Inicie o aplicativo Python por meio do ptvsd. Corresponde à porta especificada ao campo debugPort na configuração de anexação. Exemplo:
    CMD ["python", "-m", "ptvsd", "--port", "", "app.py"]

Go

  • Certifique-se de que você Pacote dlv instalado na máquina e no contêiner do Go.
  • Inicie o aplicativo Go por meio do dlv debug.

    A porta especificada no comando inicial deve ser a mesma que a Valor do atributo debugPort na Anexar configuração. Exemplo:

    CMD ["dlv", "debug", "--headless", "--listen=:<debugPort>", "--log"]

    Dica de solução de problemas: ao depurar um aplicativo em Go, ele travará e aguardará a instalação de um depurador. Anexe um depurador para iniciar o serviço.

Java

  • Verifique se a JVM está instalada na sua máquina.
  • Inicie o aplicativo Java com as opções a seguir, em que debugPort vem da configuração de anexação.

    -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=,quiet=y

    Por exemplo, para iniciar o aplicativo Java no modo de depuração e fazer detecções na porta debugPort para realizar a conexão:

    ENTRYPOINT ["java","-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=<debugPort>,quiet=y", "-jar", "my-app-1.0.jar"]

.NET Core

  • Verifique se você tem o vsdbg, o .NET Core depurador de linha de comando da Microsoft, instalado no seu contêiner do Kubernetes.

    Exemplo:

    RUN apt-get update 
    && apt-get install -y --no-install-recommends unzip
    && apt-get install -y procps
    && rm -rf /var/lib/apt/lists/*
    && curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /dbg/netcore/vsdbg

Definir a configuração de anexação

Para anexar a um contêiner depurável, é necessário ter uma configuração de anexação do tipo cloudcode.kubernetes.

Adicionar um arquivo .vscode/launch.json

Se o projeto não tiver um arquivo launch.json no .vscode você pode adicionar um usando o painel de depuração.

  1. Para navegar até o painel de depuração, clique em Ícone de depuração Depuração na Barra de atividades.

  2. Selecione Adicionar configuração no menu suspenso.

  3. Selecione Cloud Code: Kubernetes como o ambiente.

    Como definir o Cloud Code: Kubernetes como o ambiente

  4. Selecione a opção Anexar ao pod do Kubernetes.

    Selecione a opção de configuração do Kubernetes

  5. Selecione a linguagem de programação que você está usando.

    Isso cria e abre um arquivo launch.json para o projeto, além de criar uma configuração de anexação para você.

  6. Atualize os atributos de configuração no arquivo launch.json para que eles correspondam aos do projeto. Para mais informações sobre atributos de configuração, consulte Atributos de configuração.

Adicione uma configuração de anexação ao seu arquivo .vscode/launch.json

Para adicionar uma nova configuração de anexação a um arquivo .vscode/launch.json:

  1. Abra o arquivo launch.json.
  2. Para invocar o snippet Intellisense, clique em Add Configuration.
  3. Para adicionar uma configuração de anexo, selecione o Cloud Code: anexar ao pod do Kubernetes para a linguagem que você está usando.
  4. Atualize os atributos na configuração para que correspondam aos do seu projeto. Para mais informações sobre os atributos de configuração, consulte Atributos de configuração.

Atributos de configuração

Atributo Descrição
debugPort A porta de depuração usada no contêiner.
podSelector Conjunto de pares de chave-valor usado para selecionar o pod de depuração. Para mais informações, consulte o guia sobre seletores. O exemplo a seguir mostra um podSelector típico:

"podSelector": { "app": <deployment-name> }
localRoot O caminho para o diretório local que contém o programa sendo depurado. O padrão é "${workspaceFolder}".
remoteRoot O caminho absoluto para o diretório remoto que contém o programa sendo depurado no contêiner do Kubernetes.

Anexar um depurador ao pod do Kubernetes

O Cloud Code para Cloud Shell permite anexar um depurador a um pod do Kubernetes para Node.js, Python, Go, Java e .NET. Você só precisa de um contêiner depurável e um anexar configuração do tipo cloudcode.kubernetes.

Para informações sobre as diferenças entre anexar a um pod do Kubernetes e depurar um aplicativo do Kubernetes, consulte As diferenças entre anexar um depurador a um pod e depurar um aplicativo do Kubernetes

Para anexar um depurador ao seu pod do Kubernetes, execute as seguintes tarefas:

  1. Para navegar até o painel de depuração, clique em Ícone de depuração Depuração na Barra de atividades.
  2. Selecione e inicie a configuração pressionando F5.

    • A porta de localhost:${debugPort} é encaminhada para debugPort em contêiner durante a depuração.

    A sessão de depuração foi configurada. É possível realizar as tarefas que você normalmente faz ao depurar código local, como definir pontos de interrupção e que percorrem o código.

  3. Para inspecionar informações de pilha e variáveis, use a barra lateral de depuração (em inglês). Para interagir com a sessão, use o Console de depuração (em inglês) no depurador do painel inferior.

  4. Para encerrar a sessão de depuração, clique em Ícone de parada de depuração Stop na barra de ferramentas de depuração.

Qual é a diferença entre anexar um depurador a um pod e depurar um aplicativo do Kubernetes

Anexar a um pod do Kubernetes Depurar um aplicativo do Kubernetes
Depura um único pod do Kubernetes Depura todos os contêineres depuráveis no aplicativo.
O aplicativo precisa estar em execução no pod do Kubernetes antes da depuração. Executa o aplicativo no cluster do Kubernetes e anexa o depurador.
Usa configuration (.vscode/launch.json) do tipo cloudcode.kubernetes e solicitar attach. Usa configuração (.vscode/launch.json) do tipo cloudcode.kubernetes e solicita launch.
Para mais informações, consulte Configurações de inicialização e anexação.
Exemplo de configuração:
{
  "name": "Attach to Kubernetes Pod (NodeJS)",
  "type": "cloudcode.kubernetes",
  "request": "attach",
  "language": "Node",
  "debugPort": 9229,
  "podSelector": {
     "app": "hello-world"
  },
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/app"
}
Exemplo de configuração:
{
  "name": "Run/Debug on Kubernetes",
  "type": "cloudcode.kubernetes",
  "request": "launch",
  "skaffoldConfig": "${workspaceFolder}/skaffold.yaml",
  "watch": true,
  "cleanUp": true,
  "portForward": true
}
Não é possível usar esta configuração para executar o aplicativo. Essa configuração pode ser usada para executar ou depurar o aplicativo.
Essa configuração é específica de um idioma Essa configuração não é específica de um idioma.
Nenhum comando dedicado Comando "Debug on Kubernetes"

A seguir