Usar o Bridge to Kubernetes (VS Code)

Observação

A Microsoft planeja não manter mais ativamente o projeto Bridge to Kubernetes. Nos próximos meses, faremos a transição do projeto para um estado de arquivamento. Enquanto isso, o projeto ainda está disponível para uso e download. Durante esse período, esperamos explorar e recomendar projetos da comunidade que forneçam benefícios semelhantes ao Bridge to Kubernetes para seu uso futuro. Se você tiver dúvidas, entre em contato conosco em nosso quadro de problemas no GitHub.

O Bridge to Kubernetes permite que você execute e depure o código em seu computador de desenvolvimento, enquanto ainda está conectado ao cluster do Kubernetes com o restante do aplicativo ou dos 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 deseja depurar um dos pods em seu cluster. Se você quiser saber como usar o Bridge to Kubernetes com um aplicativo de exemplo existente, confira Usar Bridge to Kubernetes com um exemplo. Se você estiver usando o serviço de Kubernetes do Azure e quiser usar um aplicativo de exemplo mais complexo, confira Bridge to Kubernetes (AKS).

Pré-requisitos

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

Conectar-se ao cluster e depurar um serviço

Há 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 de código aberto Kubernetes, sem o Bridge to Kubernetes instalado, acesse Instalar e usar 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 no qual o aplicativo está em execução.

2. Abra o workspace do aplicativo que você deseja depurar no Visual Studio Code. Na exibição da extensão do Kubernetes em Clusters, verifique se o 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: configurar para iniciar o processo de configuração.

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

   

   Todo o tráfego no cluster do Kubernetes é redirecionado para o serviço para a versão do aplicativo em execução no computador de desenvolvimento. Bridge to Kubernetes também encaminha todo o tráfego de saída do aplicativo de volta para o cluster do Kubernetes.

   Importante

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

4. Depois de selecionar 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 usar a depuração de túnel local

Execute estas etapas para começar a usar a depuração de túnel local quando você tiver a extensão do Kubernetes de software livre instalada e tiver um cluster do Kubernetes com os serviços que deseja depurar. As etapas nesta seção levarão você pela 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 do Kubernetes para VS Code fornece um ponto de entrada de API que permite que os autores de extensão contribuam com outras soluções de túnel local do VS Code Marketplace. Bridge to Kubernetes é uma implementação possível da funcionalidade de Depuração do Túnel Local.

Há duas maneiras de começar a usar a 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: Depurar (Túnel Local).

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

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

Depois que a extensão Bridge to Kubernetes for instalada, na próxima vez que você escolher Depurar: Túnel Local, ignorará a etapa de instalação e prosseguirá diretamente para a próxima etapa, Configure o depurador para depuração de túnel local com o Bridge to Kubernetes.

Configurar o depurador para depuração de túnel local com o Bridge to Kubernetes

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

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, nesse caso, você precisa iniciar seu aplicativo ou serviço manualmente. Saiba mais em Configurações de inicialização.

Você tem a opção de executar isolado ou não isolado. Se você executar isolado, somente suas solicitações serão roteadas 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 saber mais sobre essa opção, confira Usar recursos de roteamento para desenvolver isoladamente.

Selecione o ícone Depurar à esquerda e selecione a configuração de inicialização do Kubernetes recém-adicionada, como Iniciar 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ê receberá uma solicitação para permitir que o EndpointManager execute com privilégios elevados e modifique o arquivo de hosts.

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

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

Observação

Nas inicializações subsequentes, você não receberá a solicitação para fornecer o nome do serviço, a porta, a tarefa de inicialização ou a execução isolada. 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 .vscode/launch.json e .vscode/tasks.json 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 usar o gRPC C core, uma implementação de gRPC que usa c-ares, uma variável de ambiente será adicionada ao seu perfil de inicialização, GRPC_DNS_RESOLVER, com o valor native. Essa variável especifica usar uma solução alternativa para evitar um atraso de dois minutos ao se conectar. Para saber mais, confira este problema de gRPC.

Definir um ponto de interrupção

Defina um ponto de interrupção com F9 ou selecione 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 Continuar. Retorne ao navegador e verifique se você vê uma imagem de espaço reservado para a bicicleta.

Atualizar o aplicativo

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

Edite seu código, salve as alterações e pressione Ctrl+Shift+F5 (⇧⌘F5 em um Mac) ou selecione Executar e, em seguida, Reiniciar 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 interromper o depurador.

Observação

Por padrão, parar a tarefa de depuração também desconecta o computador de desenvolvimento do cluster do Kubernetes. Você pode alterar esse comportamento pesquisando Bridge to Kubernetes: Desconectar após depuração nas configurações do Visual Studio Code e removendo a verificação ao lado de Desconectar automaticamente quando a depuração for interrompida. 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

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

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

Usando log e diagnóstico

A saída de registro em log é gravada na janela Bridge to Kubernetes depois que o computador de desenvolvimento está conectado ao cluster do Kubernetes.

Clique na barra Status do Kubernetes e escolha Mostrar informações de diagnóstico de conexão. Esse comando imprime as variáveis de ambiente atuais e inteiros 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. Em Windows 10, isso está em %TEMP%\Bridge to Kubernetes. Em um Mac, o diretório TEMP pode ser encontrado executando echo $TMPDIR em uma janela de terminal. No Linux, é /tmp/Bridge to Kubernetes.

Em execução no modo de isolamento

Com o Bridge to Kubernetes, você também pode configurar uma versão isolada nos 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 tráfego normalmente. Para acessar a URL do ponto de extremidade local para o aplicativo isolado, inicie o depurador no modo de isolamento, abra o menu Kubernetes na barra de status e escolha a entrada do ponto de extremidade. Você pode encontrar mais sobre como o roteamento funciona no modo de isolamento em Como funciona o Bridge to Kubernetes.

Propagação de cabeçalho

Para usar o Bridge to Kubernetes da maneira como ele foi projetado, você precisa propagar o cabeçalho Bridge to Kubernetes de solicitações de entrada para quaisquer solicitações feitas por seus serviços para outros serviços no cluster. Todas as APIs de solicitação HTTP, independentemente da linguagem, fornecem alguma maneira específica de estrutura para fazer isso. Por exemplo, para o código .NET em C#, você pode usar um 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 por um código semelhante ao exemplo anterior. Você pode encontrar código usando essa técnica na Web; um exemplo é Propagar corretamente "kubernetes-route-as" em Bridge to Kubernetes.

Para serviços Node.js, você pode usar um código semelhante ao seguinte, obtido do exemplo todo-app no repositório Bridge 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();
    });

Comunicando-se 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 do serviço codificado na URL para a solicitação, mas isso não funcionará em alguns cenários, como ao usar SSH Remoto, WSL e Codespaces. Este artigo descreve como usar as variáveis de ambiente do serviço Kubernetes para especificar a URL de conexão desses 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 excedidas"

Primeiro, repita a ativação usando o botão. Se isso não tiver êxito repetidamente, confira 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 poderá ser que o Bridge to Kubernetes não possa modificar o arquivo de hosts devido a um problema de permissões. Para habilitar o SSH remoto ou em execução como um 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 de serviço.

Próximas etapas

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, confira Depurar vários serviços ao mesmo tempo.