Bridge to Kubernetes 사용(VS Code)

  • 아티클

Bridge to Kubernetes를 사용하면 나머지 애플리케이션 또는 서비스가 포함된 Kubernetes 클러스터에 연결된 상태로 개발 컴퓨터에서 코드를 실행하고 디버그할 수 있습니다. 이 가이드에서는 Bridge to Kubernetes를 사용하여 개발 컴퓨터에서 실행되는 코드와 Kubernetes 클러스터 간에 트래픽을 리디렉션하는 방법을 알아봅니다.

시작하기 전에

이 문서에서는 마이크로 서비스 아키텍처를 사용하는 자체 클러스터가 있고 클러스터의 Pod 중 하나를 디버깅한다고 가정합니다. 기존 애플리케이션 예제를 사용하여 Bridge to Kubernetes를 사용하는 방법을 알고 싶다면 예제를 이용해 Bridge to Kubernetes 사용을 참조하세요. Azure Kubernetes 서비스를 사용 중이며 더 복잡한 애플리케이션 예제로 사용하고 싶다면 Bridge to Kubernetes(AKS)를 참조하세요.

필수 조건

  • 디버그할 앱이 있는 Kubernetes 클러스터.
  • macOS, Windows 10 이상 또는 Linux에서 실행되는 Visual Studio Code

클러스터에 연결 및 서비스 디버그

Bridge to Kubernetes를 사용한 디버깅 프로세스는 다양한 방법으로 시작할 수 있습니다. Bridge to Kubernetes를 설치하지 않고 오픈 소스 Kubernetes 확장에서 시작하는 경우에는 로컬 터널 디버깅 설치 및 사용으로 이동하세요. Kubernetes를 설치한 경우에는 다음 단계를 계속 진행하세요.

  1. 개발 컴퓨터에서 현재 컨텍스트가 애플리케이션이 실행되고 있는 클러스터 및 네임스페이스로 설정되었는지 확인합니다.

  2. Visual Studio Code에서 디버깅할 앱의 작업 영역을 엽니다. Clusters의 Kubernetes 확장 보기에서 클러스터와 네임스페이스가 선택되어 있는지 확인합니다. 명령 팔레트를 열고(CTRL+SHIFT+P, Mac에서는 Cmd+Shift+P) Bridge to Kubernetes: Configure 명령을 실행하여 구성 프로세스를 시작합니다.

  3. 로컬 버전으로 리디렉션할 Kubernetes 서비스를 선택합니다.

    연결할 서비스 선택

    서비스에 대한 Kubernetes 클러스터의 모든 트래픽이 개발 컴퓨터에서 실행되는 애플리케이션 버전으로 리디렉션됩니다. 또한 Bridge to Kubernetes는 애플리케이션의 모든 아웃바운드 트래픽을 Kubernetes 클러스터로 다시 라우팅합니다.

    Important

    단일 Pod가 있는 서비스만 리디렉션할 수 있습니다.

  4. 서비스를 선택한 후에는 다음 섹션을 건너뛰고 Kubernetes에 대한 브리지를 사용하여 로컬 터널 디버깅용 디버거 구성의 단계를 수행합니다.

로컬 터널 디버깅 설치 및 사용

오픈 소스 Kubernetes 확장을 설치했고 디버그할 서비스가 있는 Kubernetes 클러스터가 있다면 다음 단계를 수행하여 로컬 터널 디버깅 사용을 시작하세요. 이 섹션에 나오는 단계를 거치면 Bridge to Kubernetes를 설치하고 로컬 터널 디버깅 구성 프로세스를 시작할 수 있습니다.

참고 항목

VS Code용 Kubernetes 확장은 확장 작성자가 VS Code Marketplace에서 기타 로컬 터널 솔루션에 참여할 수 있는 API 진입점을 제공합니다. Bridge to Kubernetes는 Local Tunnel Debug 기능의 대표적인 구현입니다.

VS Code에서는 두 가지 방법으로 로컬 터널 디버깅을 사용할 수 있습니다. 첫 번째 방법은 명령 팔레트를 열고(CTRL+SHIFT+P, Mac에서는 Cmd+Shift+P) Kubernetes: Debug (Local Tunnel)를 입력하는 것입니다.

VS Code에서의 Debug (Local Tunnel) 명령을 보여 주는 스크린샷

두 번째 방법은 Kubernetes 클러스터 탐색기로 이동하는 것입니다. 활성 클러스터의 리소스를 열고 디버그할 서비스 또는 Pod를 찾은 다음 서비스를 마우스 오른쪽 단추로 클릭하고 Debug: Local Tunnel을 선택합니다.

이때 로컬 디버깅 기능을 제공하는 VS Code 확장이 설치되지 않았다면 Marketplace로 리디렉션됩니다. 여기서 로컬 디버깅을 제공하는 확장을 선택해야 합니다. Bridge to Kubernetes 확장을 선택합니다.

VS Code에서의 Debug Local Tunnel 상황에 맞는 메뉴를 보여 주는 스크린샷

Bridge to Kubernetes 확장이 설치된 후 Debug: Local Tunnel을 설치하면 설치 단계를 건너뛰고 다음 단계인 Bridge to Kubernetes를 사용한 로컬 터널 디버깅용 디버거 구성을 바로 진행합니다.

Bridge to Kubernetes를 사용한 로컬 터널 디버깅용 디버거 구성

로컬 터널 디버깅용 디버거를 구성하는 첫 번째 단계는 애플리케이션에서 로컬로 실행하는 데 사용하는 TCP 포트를 입력하는 것입니다.

포트 번호 입력

애플리케이션을 로컬로 실행할 때 일반적으로 사용하는 디버그 시작 구성을 선택합니다. 시작 구성이 없다면 Bridge to Kubernetes에서 만들게 하거나 시작 구성을 만들지 않을 수 있습니다. 어떤 경우든 애플리케이션이나 서비스를 수동으로 시작해야 합니다. 시작 구성에 대해 자세히 알아보세요.

디버거 시작 구성 선택

격리 실행 또는 비격리 실행 옵션을 선택할 수 있습니다. 격리 실행의 경우 사용자의 요청만 로컬 프로세스로 라우팅됩니다. 다른 개발자는 영향받지 않고 클러스터를 사용할 수 있습니다. 격리를 실행하지 않으면 모든 트래픽이 로컬 프로세스로 리디렉션됩니다. 이 옵션에 대한 자세한 내용은 격리 상태로 개발하기 위한 라우팅 기능 사용을 참조하세요.

격리 선택

왼쪽의 디버그 아이콘을 선택하고 새로 추가된 Kubernetes 시작 구성을 선택합니다(예: 상단의 Kubernetes를 사용하여 NPM을 통해 실행). 이 시작 구성은 옵션을 선택한 경우 Bridge to Kubernetes에서 생성합니다.

디버그 시작 프로필 선택

참고 항목

EndpointManager가 관리자 권한으로 실행되고 hosts 파일을 수정할 수 있게 허용하라는 메시지가 표시됩니다.

VS Code 상태 표시줄이 주황색으로 바뀌고 Kubernetes 확장에서 연결되었다고 표시되면 개발 컴퓨터가 연결된 것입니다.

Bridge to Kubernetes를 사용한 디버깅

개발 컴퓨터가 연결되면 바꾸려는 서비스에 대한 트래픽이 개발 컴퓨터로 리디렉션되기 시작합니다.

참고 항목

이후에 시작할 때는 서비스 이름, 포트, 시작 작업이나 격리 실행 여부를 묻는 메시지가 표시되지 않습니다. 이러한 값은 .vscode/tasks.json에 저장됩니다. 나중에 이 설정을 변경하려면 명령 팔레트를 열고(CTRL+SHIFT+P, Mac에서는 Cmd+Shift+P) Bridge to Kubernetes: Configure 명령을 실행합니다. .vscode/launch.json과 .vscode/tasks.json을 열면 Bridge to Kubernetes가 시작 프로필에 추가하는 구체적인 구성 설정을 확인할 수 있습니다.

c-ares를 사용하는 gRPC의 구현인 gRPC C 코어를 클러스터에서 사용하는 경우, 환경 변수가 시작 프로필인 GRPC_DNS_RESOLVER에 값 native와 함께 추가됩니다 . 이 변수는 연결 시 2분 지연 시간을 방지하는 해결 방법을 사용하도록 지정합니다. 자세한 내용은 이 gRPC 문제를 참조하세요.

중단점 설정

F9로 중단점을 설정하거나 실행을 선택한 후 중단점 설정/해제를 선택합니다.

공용 URL을 열어 애플리케이션 예제로 이동합니다. 코드가 중단점에 도달하면 디버거에서 코드가 열립니다. 서비스를 다시 시작하려면 Ctrl+F5를 누르거나 실행을 선택한 후 계속을 선택합니다. 브라우저로 돌아가서 자전거에 대한 자리 표시자 이미지가 표시되는지 확인합니다.

애플리케이션 업데이트

코드를 로컬에서 변경하는 경우, 클러스터를 사용하는 다른 사용자에 대한 코드 표시 여부는 격리 실행 여부를 기준으로 결정됩니다. 격리 실행의 경우 다른 사용자에게 영향을 주지 않고 변경을 적용할 수 있습니다.

코드를 편집하고, 변경 사항을 저장하고, Ctrl+Shift+F5(Mac에서는 ⇧⌘F5)를 누르거나 실행을 선택한 다음 디버깅 다시 시작을 선택합니다. 다시 연결되면 브라우저를 새로 고치고 변경 사항의 유효성을 검사합니다.

실행을 선택하고 디버깅 중지를 선택하거나 Shift+F5를 눌러 디버거를 중지합니다.

참고 항목

기본적으로 디버깅 작업을 중지하면 Kubernetes 클러스터에서 개발 컴퓨터의 연결이 끊어집니다. Visual Studio Code 설정에서 Bridge to Kubernetes: 디버깅 후 연결 끊기를 검색한 후 디버깅이 중단되면 자동으로 연결 끊기 옆에 있는 선택 표시를 제거하면 이 동작을 변경할 수 있습니다. 이 설정을 업데이트하면 디버깅을 중지하고 시작할 때 개발 컴퓨터가 연결된 상태를 유지합니다. 클러스터와 개발 컴퓨터의 연결을 끊으려면 상태 표시줄에서 Bridge to Kubernetes 확장을 클릭하고 현재 세션 연결 끊기를 선택합니다.

추가 구성

Bridge to Kubernetes는 추가 구성 없이 트래픽 라우팅 및 환경 변수 복제를 처리할 수 있습니다. Kubernetes 클러스터의 컨테이너에 탑재된 파일(예: ConfigMap 파일)을 다운로드해야 하는 경우 KubernetesLocalProcessConfig.yaml을 만들어 해당 파일을 개발용 컴퓨터에 다운로드할 수 있습니다. 자세한 내용은 Bridge to Kubernetes 구성을 참조하세요.

Microsoft Entra ID에서 제공하는 보안 기능인 관리 ID를 사용하는 AKS 클러스터를 사용하는 경우에는 Bridge to Kubernetes로 관리 ID 사용을 참조하여 이 시나리오에서 Bridge to Kubernetes를 구성하는 방법을 확인하세요.

로깅 및 진단 사용

로깅 출력은 개발 컴퓨터가 Kubernetes 클러스터에 연결된 후 Bridge to Kubernetes 창에 작성됩니다.

Kubernetes 상태 표시줄을 클릭하고 연결 진단 정보 표시를 선택합니다. 이 명령은 로깅 출력에 현재 환경 변수 및 DNS를 인쇄합니다.

개발 컴퓨터의 TEMP 디렉터리에 있는 Bridge to Kubernetes 디렉터리에서 진단 로그를 찾을 수도 있습니다. Windows 10에서는 %TEMP%\Bridge to Kubernetes에 있습니다. Mac에서는 터미널 창에서 실행 echo $TMPDIR 하여 TEMP 디렉터리를 찾을 수 있습니다. Linux에서는 /tmp/Bridge to Kubernetes입니다.

격리 모드에서 실행

Bridge to Kubernetes를 사용하면 작업 중인 서비스의 격리 버전을 설정하여 클러스터를 사용하는 다른 사용자가 변경의 영향을 받지 않게 할 수 있습니다. 해당 격리 모드는 영향을 받는 각 서비스의 복사본으로 요청을 라우팅하고 다른 모든 트래픽을 정상적으로 라우팅하는 방식으로 수행됩니다. 격리된 앱의 로컬 엔드포인트 URL에 액세스하려면 디버거를 격리 모드에서 시작하고 상태 표시줄에서 Kubernetes 메뉴를 연 다음 엔드포인트 항목을 선택합니다. Bridge to Kubernetes 작동 방식에서 격리 모드에서의 라우팅 작동 방식에 대해 자세히 알 수 있습니다.

헤더 전파

Bridge to Kubernetes를 원래 방식대로 사용하려면 들어오는 요청의 Bridge to Kubernetes 헤더를 사용자의 서비스가 클러스터의 다른 서비스로 보내는 요청으로 전파해야 합니다. 언어에 관계 없이 모든 HTTP 요청 API는 이 작업을 수행하는 프레임워크별 방법을 제공합니다. 예를 들어 C#의 .NET 코드에서는 다음과 비슷한 코드를 사용할 수 있습니다.

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);

참고 항목

요청을 할 때마다 코드가 영향받지 않게 하려면 System.Net.Http.DelegatingHandler에서 상속되는 클래스를 만들고 이전 예시에서 나오는 것과 비슷한 SendAsync 메서드를 사용해 재정의하면 됩니다. 웹에서 이 기법을 사용하여 코드를 찾을 수 있습니다. 대표적인 예는 Bridge to Kubernetes에서 ‘kubernetes-route-as’를 적절하게 전파입니다.

Node.js 서비스의 경우 Bridge to Kubernetes 리포지토리에 있는 todo-app 예제에서 가져오는, 다음과 비슷한 코드를 사용할 수 있습니다.

    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();
    });

다른 서비스와의 통신

HTTP 요청 등이 있는 동일한 Kubernetes 클러스터에 있는 다른 서비스와 통신할 때는 일반적으로 요청에 대한 URL에 있는 하드 코딩된 서비스 이름을 사용하지만, Remote SSH, WSL, Codespaces를 사용하는 일부 시나리오에서는 이를 사용할 수 없습니다. 이 문서에서는 Kubernetes 서비스 환경 변수를 사용하여 이러한 시나리오를 위한 연결 URL을 지정하는 방법을 설명합니다.

문제 해결

Bridge to Kubernetes 확장을 활성화할 때

‘종속성 업데이트 실패: 재시도 최대 횟수 초과’ 오류가 발생하는 경우

먼저 단추를 사용하여 활성화를 다시 시도합니다. 계속 실패한다면 https://github.com/microsoft/mindaro/issues/32를 참조하세요.

원격 SSH 세션에서 Bridge to Kubernetes를 사용할 때 EndpointManager에서 장애가 발생하는 경우, 성능 문제 때문에 Bridge to Kubernetes에서 호스트 파일을 수정할 수 없음이 원인일 수 있습니다. 원격 SSH나 미승격 사용자로 실행하는 기능을 사용하도록 설정하려면, 서비스 환경 변수 항목의 설명에 따라 Kubernetes 서비스 환경 변수를 사용하도록 코드를 업데이트하고 VS Code에서 이를 사용하도록 구성해야 합니다.

다음 단계

Bridge to Kubernetes 작동 방식에서 Bridge to Kubernetes에 대해 자세히 알아보세요.

여러 서비스를 동시에 디버깅해야 하는 경우에는 여러 서비스를 동시에 디버그를 참조하세요.

현재 지원되는 기능과 Bridge to Kubernetes의 향후 로드맵에 대한 정보는 Bridge to Kubernetes 로드맵에서 확인할 수 있습니다.