Usar Bridge para Kubernetes (VS Code)

Observação

Bridge to Kubernetes será aposentado em 30 de abril de 2025. Para obter detalhes sobre a descontinuação e alternativas de código aberto, consulte o problema no GitHub, referência.

O Bridge to Kubernetes permite que você execute e depure código em seu computador de desenvolvimento, enquanto ainda está conectado ao cluster do Kubernetes com o resto do seu aplicativo ou serviços. Neste guia, você aprenderá a usar o Bridge to Kubernetes para redirecionar o tráfego entre o cluster do Kubernetes e o código em execução no computador de desenvolvimento.

Antes de começar

Este artigo pressupõe que você já tenha seu próprio cluster com uma arquitetura de microsserviços e queira depurar um dos pods em seu cluster. Se você quiser aprender a usar o Bridge to Kubernetes com um aplicativo de exemplo existente, consulte Usar o Bridge to Kubernetes com um exemplo. Se você estiver usando o serviço Kubernetes do Azure e quiser usar um aplicativo de exemplo mais complexo, consulte Bridge to Kubernetes (AKS).

Pré-requisitos

• Um cluster Kubernetes com um aplicativo que você deseja depurar.
• Visual Studio Code em execução no macOS, Windows 10 ou posterior, ou Linux.

Ligar-se ao cluster e resolver problemas de um serviço

Existem algumas maneiras diferentes de iniciar o processo de depuração com o Bridge to Kubernetes. Se você estiver começando a partir da extensão Kubernetes de código aberto, sem o Bridge to Kubernetes instalado, vá para Instalar e use a depuração de túnel local. Se você já tiver o Bridge to Kubernetes instalado, continue com as seguintes etapas:

1. No computador de desenvolvimento, verifique se o contexto atual está definido para o cluster e o namespace em que o aplicativo está sendo executado.

2. Abra o espaço de trabalho do aplicativo que você deseja depurar no Visual Studio Code. Na vista de extensão do Kubernetes em Clusters, certifique-se de que o seu cluster e o namespace estão selecionados. Abra a Paleta de comandos (CTRL+SHIFT+P ou Cmd+Shift+P em um Mac) e execute o comando Bridge to Kubernetes: Configure para iniciar o processo de configuração.

3. Escolha o serviço Kubernetes que você deseja redirecionar para sua versão local.

   

   Todo o tráfego no cluster Kubernetes é redirecionado para o seu serviço na versão da sua aplicação que está a correr no seu computador de desenvolvimento local. O Bridge to Kubernetes também roteia todo o tráfego de saída do aplicativo de volta para o cluster do Kubernetes.

   Importante

   Você só pode redirecionar serviços que tenham um único pod.

4. Depois de selecionar o seu serviço, ignore a próxima seção e continue seguindo as etapas em Configurar o depurador para depuração de túnel local com o Bridge to Kubernetes.

Instalar e utilizar a depuração de tunelagem local

Siga estes passos para começar a usar o debug de túnel local quando tiver a extensão Kubernetes de código aberto instalada e tiver um cluster Kubernetes com serviços que deseja depurar. As etapas nesta seção irão guiá-lo através da instalação do Bridge to Kubernetes e iniciarão o processo de configuração para depuração de túnel local.

Observação

A extensão Kubernetes para VS Code fornece um ponto de entrada de API que permite que os autores de extensões contribuam com outras soluções de túnel local do VS Code Marketplace. Bridge to Kubernetes é uma implementação possível do recurso de depuração de túnel local.

Há duas maneiras de iniciar a utilização da depuração de túnel local no VS Code. A primeira maneira é abrir a Paleta de Comandos (CTRL+SHIFT+P ou Cmd+Shift+P em um Mac) e digitar Kubernetes: Debug (Local Tunnel).

Como alternativa, navegue até o explorador de clusters do Kubernetes. Abra os recursos do cluster ativo e localize um serviço ou pod que deseja depurar, clique com o botão direito do mouse no serviço e selecione Depurar: Túnel Local.

Neste ponto, se você não tiver nenhuma extensão VS Code instalada que ofereça recursos de depuração local, será redirecionado para o Marketplace para selecionar uma extensão que forneça depuração local. Selecione a extensão Bridge to Kubernetes.

Depois de a extensão Bridge to Kubernetes ser instalada, na próxima vez que escolher Depurar: Túnel Local, irá ignorar o passo de instalação e irá prosseguir diretamente para o próximo passo, Configurar o depurador para depuração de túnel local com o Bridge to Kubernetes.

Configurar o depurador para a depuração de túneis locais com o Bridge to Kubernetes

A primeira etapa na configuração do depurador para depuração de túnel local é que você será solicitado a inserir a porta TCP que seu aplicativo usa para ser executado localmente:

Escolha uma configuração de inicialização de depuração que você normalmente usa ao executar seu aplicativo localmente. Se você não tiver uma configuração de inicialização, poderá permitir que o Bridge to Kubernetes crie uma ou opte por não criar uma, caso em que você terá que iniciar seu aplicativo ou serviço manualmente. Saiba mais em Configurações de inicialização.

Você tem a opção de executar de forma isolada ou não. Se você executar isolado, somente suas solicitações serão encaminhadas para o processo local; outros desenvolvedores podem usar o cluster sem serem afetados. Se você não executar isolado, todo o tráfego será redirecionado para o processo local. Para obter mais informações sobre essa opção, consulte Usando recursos de roteamento para desenvolvimento isolado.

Selecione o ícone Debug à esquerda e selecione a configuração de inicialização do Kubernetes recém-adicionada, como Launch via NPM com Kubernetes, na parte superior. Essa configuração de inicialização é criada pelo Bridge to Kubernetes, se você escolher essa opção.

Observação

Você será solicitado a permitir que o EndpointManager execute com privilégios elevados e modifique seu ficheiro hosts.

Seu computador de desenvolvimento é conectado quando a barra de status do VS Code fica laranja e a extensão Kubernetes mostra que você está conectado.

Assim que o computador de desenvolvimento estiver conectado, o tráfego começará a ser redirecionado para o computador de desenvolvimento do serviço que você está substituindo.

Observação

Em iniciações subsequentes, você não será solicitado a fornecer o nome do serviço, a porta, a tarefa de inicialização ou se deseja ser executado isoladamente. Esses valores são salvos em .vscode/tasks.json. Para alterar essas configurações posteriormente, abra a Paleta de comandos (CTRL+SHIFT+P ou Cmd+Shift+P em um Mac) e execute o comando Bridge to Kubernetes: Configure. Você pode abrir launch.json .vscode/ e tasks.json .vscode/ para ver as definições de configuração específicas que o Bridge to Kubernetes adiciona ao seu perfil de inicialização.

Se o cluster utiliza gRPC C core, uma implementação do gRPC que usa c-ares, uma variável de ambiente é adicionada ao seu perfil de inicialização, GRPC_DNS_RESOLVER, com o valor native. Esta variável especifica o uso de uma solução alternativa para evitar um atraso de 2 minutos ao se conectar. Para obter mais informações, consulte este problema do gRPC.

Definir um ponto de interrupção

Defina um ponto de interrupção com F9 ou selecionando Executar e, em seguida, Alternar ponto de interrupção.

Navegue até o aplicativo de exemplo abrindo a URL pública. Quando o código atingir o ponto de interrupção, ele deverá ser aberto no depurador. Para retomar o serviço, pressione Ctrl+F5 ou selecione Executar e, em seguida, Continuar. Volte ao seu navegador e verifique se aparece uma imagem de espaço reservado para a bicicleta.

Atualize a sua candidatura

Quando você faz alterações de código localmente, se elas são visíveis ou não para outras pessoas que estão usando o cluster depende se você está executando isolado ou não. Se você estiver executando isolado, poderá fazer alterações que não afetem outros usuários.

Edite seu código, salve suas alterações e pressione Ctrl+Shift+F5 (⇧⌘F5 em um Mac) ou selecione ExecutarReiniciar a depuração. Depois de se reconectar, atualize o navegador e valide as alterações.

Selecione Executar e, em seguida, Parar depuração ou pressione Shift+F5 para parar o depurador.

Observação

Por padrão, parar a tarefa de depuração também desconecta o seu computador de desenvolvimento do cluster do Kubernetes. Você pode alterar esse comportamento procurando por Bridge to Kubernetes: Disconnect After Debugging nas configurações do Visual Studio Code e removendo a verificação ao lado de Desconectar automaticamente quando a depuração parar. Depois de atualizar essa configuração, o computador de desenvolvimento permanecerá conectado quando você parar e iniciar a depuração. Para desconectar o computador de desenvolvimento do cluster, clique na extensão Bridge to Kubernetes na barra de status e escolha Desconectar sessão atual.

Configuração adicional

O Bridge to Kubernetes pode lidar com o tráfego de roteamento e replicar variáveis de ambiente sem qualquer configuração adicional. Se você precisar baixar todos os arquivos montados no contêiner do cluster do Kubernetes, como um arquivo ConfigMap, poderá criar um KubernetesLocalProcessConfig.yaml para baixar esses arquivos para o computador de desenvolvimento. Para obter mais informações, consulte Configurar Bridge to Kubernetes.

Se você estiver usando um cluster AKS que usa identidade gerenciada, um recurso de segurança fornecido pelo ID do Microsoft Entra, consulte Usar identidade gerenciada com o Bridge to Kubernetes para obter informações sobre como configurar o Bridge to Kubernetes para este cenário.

Usando registo e diagnóstico

A saída de log é gravada na janela Bridge to Kubernetes após o computador de desenvolvimento ser conectado ao seu cluster do Kubernetes.

Clique na barra de status do Kubernetes e escolha a opção Mostrar informações de diagnóstico de conexão . Este comando imprime as variáveis de ambiente atuais e as entradas DNS na saída de log.

Além disso, você pode encontrar os logs de diagnóstico no diretório Bridge to Kubernetes no diretório TEMP do computador de desenvolvimento. No Windows 10, isso está em %TEMP%\Bridge to Kubernetes. Em um Mac, o diretório TEMP pode ser encontrado executando echo $TMPDIR a partir de uma janela do terminal. No Linux, é /tmp/Bridge to Kubernetes.

Executando no modo de isolamento

Com o Bridge to Kubernetes, você também pode configurar uma versão isolada dos serviços em que está trabalhando, o que significa que outras pessoas que estão usando o cluster não serão afetadas por suas alterações. Esse modo de isolamento é realizado roteando suas solicitações para sua cópia de cada serviço afetado, mas roteando todo o outro tráfego normalmente. Para aceder à URL do ponto de extremidade local para a aplicação isolada, inicie o depurador no modo de isolamento, abra o menu do Kubernetes na barra de estado e escolha a entrada do ponto de extremidade. Você pode encontrar mais sobre como o roteamento funciona no modo de isolamento em How Bridge to Kubernetes Works.

Propagação de cabeçalho

Para usar o Bridge to Kubernetes da maneira como ele foi projetado, você precisa se certificar de propagar o cabeçalho Bridge to Kubernetes de solicitações de entrada para quaisquer solicitações que seus serviços façam a outros serviços no cluster. Todas as APIs de solicitação HTTP, independentemente da linguagem, fornecem algum método específico da framework para fazer isso. Por exemplo, para código .NET em C#, você pode usar código semelhante ao seguinte:

var request = new HttpRequestMessage();
request.RequestUri = new Uri("http://mywebapi/api/values/1");
if (this.Request.Headers.ContainsKey("kubernetes-route-as"))
{
    // Propagate the dev space routing header
    request.Headers.Add("kubernetes-route-as", this.Request.Headers["kubernetes-route-as"] as IEnumerable<string>);
}
var response = await client.SendAsync(request);

Observação

Para evitar afetar o código em cada solicitação, você pode criar uma classe que herda de System.Net.Http.DelegatingHandler e substituir o método SendAsync com código semelhante ao exemplo anterior. Você pode encontrar código usando esta técnica na web; um exemplo é propagando corretamente "kubernetes-route-as" no Bridge to Kubernetes.

Para serviços Node.js, pode usar um código semelhante ao seguinte, retirado do exemplo de aplicação todo no repositório doBridge to Kubernetes:

    server.get("/api/stats", function (req, res) {
        var options = {
            host: process.env.STATS_API_HOST,
            path: '/stats',
            method: 'GET'
        };
        const val = req.get('kubernetes-route-as');
        if (val) {
            console.log('Forwarding kubernetes-route-as header value - %s', val);
            options.headers = {
                'kubernetes-route-as': val
            }
        }
        var req = http.request(options, function(statResponse) {
            res.setHeader('Content-Type', 'application/json');
            var responseString = '';
            //another chunk of data has been received, so append it to `responseString`
            statResponse.on('data', function (chunk) {
                responseString += chunk;
            });
            statResponse.on('end', function () {
                res.send(responseString);
            });
        });

        req.on('error', function(e) {
            console.log('problem with request: ' + e.message);
          });

          req.end();
    });

Comunicação com outros serviços

Quando você se comunica com outro serviço no mesmo cluster do Kubernetes, por exemplo, com uma solicitação HTTP, normalmente usa o nome de serviço codificado na URL da solicitação, mas isso não funciona em alguns cenários, como ao usar SSH remoto, WSL e Codespaces. Este artigo descreve como usar as variáveis de ambiente de serviço do Kubernetes para especificar a URL de conexão para esses cenários.

Solução de problemas

Se você receber esse erro ao ativar a extensão Bridge to Kubernetes:

"Falha ao atualizar dependências: número máximo de tentativas excedido"

Primeiro, tente novamente a ativação usando o botão. Caso não tenha sucesso repetidamente, consulte https://github.com/microsoft/mindaro/issues/32.

Quando você estiver usando o Bridge to Kubernetes em uma sessão SSH remota, se o EndpointManager falhar, o problema pode ser que o Bridge to Kubernetes não pode modificar o arquivo hosts devido a um problema de permissões. Para habilitar o SSH remoto ou a execução como usuário não elevado, você deve atualizar seu código para usar variáveis de ambiente de serviço do Kubernetes e configurar o VS Code para usá-las, conforme descrito no tópico Variáveis de ambiente do Serviço.

Próximos passos

Saiba mais sobre o Bridge to Kubernetes em Como funciona o Bridge to Kubernetes.

Se você precisar depurar vários serviços ao mesmo tempo em paralelo, consulte Depurar vários serviços ao mesmo tempo.