Cloud Shell용 Cloud Code에서 Kubernetes 애플리케이션 디버그

참고: 디버깅 지원은 Node.js, Python, Go, Java, .NET에서 사용할 수 있습니다.

Cloud Code를 사용하면 skaffold debug를 활용하여 Google Kubernetes Engine(GKE) 클러스터에 배포된 애플리케이션을 디버깅할 수 있습니다.

로컬 클러스터(예: minikube또는 Docker Desktop), GKE 또는 다른 클라우드 제공업체의 애플리케이션을 디버깅할 수 있습니다.

Cloud Code의 디버깅 지원이 제공되므로 포트 전달 설정 또는 언어별 디버그 인수 삽입과 같은 수동 설정을 완료할 필요가 없습니다. 디버깅을 위해서는 skaffold.yaml 구성 파일과 cloudcode.kubernetes 실행 구성이 포함된 Cloud Code에 사용 가능한 GKE 애플리케이션이 필요합니다.

GKE 애플리케이션 디버깅

GKE 애플리케이션 디버깅을 시작하려면 다음 단계를 따르세요.

1. Cloud Code 상태 표시줄에서 활성 프로젝트 이름을 클릭합니다.

   

2. 표시되는 빠른 선택 메뉴에서 Kubernetes에서 디버그를 선택합니다.

3. 애플리케이션에 필요한 Skaffold 구성이나 cloudcode.kubernetes 실행 구성이 없으면 Cloud Code에서 설정을 도와줍니다.

4. 현재의 Kubernetes 컨텍스트를 사용하여 앱을 실행할지 또는 선호하는 컨텍스트로 전환할지 확인합니다.

5. 원격 클러스터를 컨텍스트로 선택한 경우 메시지가 표시되면 이미지를 푸시할 이미지 레지스트리를 선택합니다. Container Registry를 사용하는 경우 기존 레지스트리를 탐색하거나 만들 레지스트리의 이름을 지정할 수 있습니다. 프로젝트에 Artifact Registry API가 사용 설정되어 있고 하나 이상의 Artifact Registry 저장소가 있는 경우 기존 Artifact Registry 저장소를 찾아서 선택할 수 있습니다.

   다음 샘플은 몇 가지 일반적인 레지스트리의 경우 컨테이너 이미지가 저장되는 위치를 지정하는 방법을 보여줍니다.

   Artifact Registry	{region}-docker.pkg.dev/{project_id}/{repo-name}
   Container Registry	gcr.io/{project_id}
   Docker Hub	docker.io/{account} 비공개 Docker Hub 저장소를 사용하는 경우 적절하게 인증되었는지 확인합니다.

   Cloud Code는 최종 이미지 저장소 이름을 생성하기 위해 이 이미지 레지스트리를 Kubernetes 매니페스트에 지정된 이미지 이름과 연결합니다. 이 선택사항은 cloudcode.kubernetes 실행 구성(.vscode/launch.json에 있음)에 저장됩니다.

   자세한 내용은 이미지 레지스트리 처리 가이드를 참조하세요.

   Cloud Code가 컨테이너를 빌드하여 레지스트리로 푸시하고 Kubernetes 구성을 클러스터에 적용하여 출시를 기다립니다.

   출시가 완료되면 Cloud Code는 선언된 모든 컨테이너 포트를 자동으로 머신에 포트 전달하고 출력창에 URL을 표시하여 실시간 애플리케이션을 탐색할 수 있습니다.

6. 애플리케이션의 디버깅 가능한 각 컨테이너에서 디버깅할 프로그램이 있는 원격 컨테이너에서 디렉터리를 확인하거나 입력합니다.

   또는 ESC를 눌러 컨테이너 디버깅을 건너뛸 수 있습니다.

   

   Cloud Code는 애플리케이션에서 디버깅 가능한 각 컨테이너에 대한 디버그 세션을 연결합니다.

   이제 중단점 설정 및 단계별 코드 실행과 같이 실제 Kubernetes 클러스터에 대해 로컬 코드를 디버깅할 때 일반적으로 하는 동일한 작업을 수행할 수 있습니다.

   기본적으로 애플리케이션 변경사항이 자동 저장되면 Cloud Code는 애플리케이션을 다시 배포하고 새 디버그 세션을 설정합니다. 프로젝트 실행 구성에서 watch 플래그를 사용하여 이 기능을 켜고 끌 수 있습니다.

7. 변수 및 스택 정보를 검사하려면 디버그 사이드바를 사용합니다. 디버깅 세션과 상호작용하려면 하단 창 디버거에 있는 디버그 콘솔을 사용합니다.

8. 세션이 완료되면 다음 컨텍스트 메뉴 명령어를 사용할 수 있습니다.

   • 배포 로그 열기: Cloud Code 로그 탐색기를 사용하여 특정 배포의 애플리케이션 로그를 엽니다.
   • 서비스 URL 열기: 웹브라우저에서 특정 서비스의 애플리케이션 서비스 URL을 엽니다.

9. 시작 구성에서 감시 모드를 사용 중지한 상태에서 애플리케이션을 변경하고 애플리케이션을 다시 빌드 및 다시 배포하려면 개발 세션 창에서 실행 작업을 일시중지한 다음 애플리케이션 다시 빌드 및 다시 배포를 클릭합니다.

10. 디버깅 세션을 종료하려면 디버그 툴바에서 중지를 클릭합니다.

    디버깅 세션을 종료한 후에는 배포된 모든 Kubernetes 리소스가 클러스터에서 삭제됩니다.

구성 세부정보

참고: Cloud Code는 로컬 Kubernetes 구성을 수정하지 않습니다. 배포 시에 변환이 발생하며 서버에서만 볼 수 있습니다.

Skaffold에 의해 구동되는 Cloud Code는 지원되는 모든 언어에 대해 다음 구성 세부정보를 자동으로 처리합니다.

• 디버거를 연결할 수 있도록 디버그 포트 전달
• 애플리케이션에서 디버그 가능한 하나 이상의 컨테이너에 디버거 연결. 애플리케이션에 skaffold.yaml에서 구성된 디버그 가능한 컨테이너(Cloud Code 디버그가 언어를 지원하는 컨테이너)가 여러 개 있는 경우 디버거가 디버깅 가능한 각 컨테이너에 연결됩니다.
• 세션 전반에서 소스 매핑 정의를 유지하고 .vscode/launch.json 파일을 직접 수정하여 이러한 정의를 맞춤설정할 수 있습니다.

Cloud Code는 또한 다음과 같은 언어별 구성 세부정보를 처리합니다.

Node.js

호출할 진입점 다시 작성:

node --inspect=localhost:9229

Python

Init 컨테이너를 사용하여 ptvsd 모듈을 설치하고 호출할 진입점 다시 작성:

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

Go

초기화 컨테이너를 사용하여 dlv 디버거를 설치하고, 시작된 디버그 세션이 헤드리스 모드에서 디버그 서버로만 실행되도록 진입점을 다시 작성하면 시작 시 디버깅된 프로세스가 계속되고, 여러 클라이언트 연결을 수락하고, localhost:56268에서 수신 대기합니다.

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

자바

적절한 JDWP(Java Debug Wire Protocol) 구성과 함께 환경 JAVA_TOOLS_OPTIONS를 추가하면 JDWP 디버깅 에이전트가 포트 5005에서 소켓 연결을 수신 대기하고 디버거가 연결되기 전에 VM이 실행되도록 허용합니다.

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

Skaffold로 지원되는 디버깅에 대한 자세한 내용은 skaffold debug 문서를 참조하세요.

컨테이너 설정

디버깅할 컨테이너를 준비하려면 사용 중인 언어의 안내를 따르세요.

Node.js

• --inspect=<debugPort>로 Node.js 애플리케이션을 시작합니다. 여기서 debugPort는 연결 구성에서 가져옵니다. 예시: CMD ["node", "--inspect=9229", "index.js"]

Python

• 머신과 컨테이너에 ptvsd 모듈이 설치되어 있는지 유의하세요.
• ptvsd를 통해 Python 애플리케이션을 시작합니다. 지정된 포트를 연결 구성의 debugPort 필드에 일치시킵니다. 예를 들면 다음과 같습니다.

  CMD ["python", "-m", "ptvsd", "--port", "", "app.py"]
  

Go

• 머신과 Go 컨테이너에 dlv 패키지가 설치되어 있는지 유의하세요.

• dlv debug를 통해 Go 애플리케이션을 시작합니다.

  시작 명령어에 지정된 포트는 연결 구성의 debugPort 속성 값과 동일해야 합니다. 예를 들면 다음과 같습니다.

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

  문제 해결 팁: Go 애플리케이션을 디버깅하면 애플리케이션이 멈추고 디버거가 연결될 때까지 대기합니다. 서비스를 시작하려면 디버거를 연결하세요.

자바

• 머신에 JVM이 설치되어 있는지 유의하세요.

• 다음 옵션으로 자바 애플리케이션을 시작합니다. 여기서 debugPort는 연결 구성에서 가져옵니다.

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

  예를 들어 디버그 모드에서 자바 애플리케이션을 시작하고 포트 debugPort에서 연결을 리슨하려면 다음 안내를 따르세요.

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

.NET Core

• Kubernetes 컨테이너에 Microsoft의 .NET Core 명령줄 디버거인 vsdbg가 설치되어 있는지 유의하세요.

  예를 들면 다음과 같습니다.

  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
  

연결 구성 설정

디버그 가능한 컨테이너에 연결하려면 cloudcode.kubernetes 유형의 연결 구성이 있어야 합니다.

.vscode/launch.json 파일 추가

프로젝트의 launch.json 폴더에 .vscode 파일이 없는 경우 디버그 패널을 사용하여 파일을 추가할 수 있습니다.

1. 디버그 패널로 이동하려면 작업 표시줄에서 디버그를 클릭합니다.

2. 드롭다운 메뉴에서 구성 추가를 선택합니다.

3. Cloud Code: Kubernetes를 환경으로 설정합니다.

   

4. Kubernetes 포드에 연결 옵션을 선택합니다.

   

5. 사용 중인 프로그래밍 언어를 선택합니다.

   그러면 프로젝트의 launch.json 파일이 생성되어 열리고 연결 구성이 생성됩니다.

6. 프로젝트의 구성 속성과 일치하도록 launch.json 파일에서 구성 속성을 업데이트합니다. 구성 속성에 대한 자세한 내용은 구성 속성을 참조하세요.

.vscode/launch.json 파일에 연결 구성 추가

기존 .vscode/launch.json 파일에 새 연결 구성을 추가하려면 다음 안내를 따르세요.

1. launch.json 파일을 엽니다.
2. Intellisense 스니펫을 호출하려면 구성 추가를 클릭합니다.
3. 연결 구성을 추가하려면 사용 중인 언어에 Cloud Code: Kubernetes 포드에 연결 스니펫을 선택합니다.
4. 프로젝트의 속성과 일치하도록 구성의 속성을 업데이트합니다. 구성 속성에 대한 자세한 내용은 구성 속성을 참조하세요.

구성 속성

속성	설명
debugPort	컨테이너에서 사용되는 디버그 포트입니다.
podSelector	디버그 포드를 선택하는 데 사용되는 키-값 쌍 집합입니다. 자세한 내용은 선택기 가이드를 참조하세요. 다음 샘플은 일반적인 podSelector를 보여줍니다. "podSelector": { "app": <deployment-name> }
localRoot	디버깅할 프로그램이 있는 로컬 디렉터리 경로입니다. 기본값은 ${workspaceFolder}입니다.
remoteRoot	디버깅할 프로그램이 있는 (Kubernetes 컨테이너의) 원격 디렉터리의 절대 경로입니다.

Kubernetes 포드에 디버거 연결

Cloud Shell용 Cloud Code는 디버거를 Node.js, Python, Go, 자바, .NET용 Kubernetes 포드에 연결하는 기능을 지원합니다. 이때 디버그 가능 컨테이너와 cloudcode.kubernetes 유형의 연결 구성만 있으면 됩니다.

Kubernetes 포드 연결과 Kubernetes 애플리케이션 디버깅의 차이에 대한 자세한 내용은 포드에 디버거 연결과 Kubernetes 애플리케이션 디버깅의 차이점을 참조하세요.

디버거를 Kubernetes 포드에 연결하려면 다음 태스크를 수행합니다.

1. 디버그 패널로 이동하려면 작업 표시줄에서 디버그를 클릭합니다.

2. F5를 눌러 구성을 선택하고 시작합니다.

   • 디버깅 중에 localhost:${debugPort}가 컨테이너의 debugPort로 포트 전달됩니다.

   이제 디버깅 세션이 성공적으로 설정되었습니다. 중단점 설정 및 단계별 코드 실행과 같이 로컬 코드를 디버깅할 때 일반적으로 하는 작업을 수행할 수 있습니다.

3. 변수 및 스택 정보를 검사하려면 디버그 사이드바를 사용합니다. 디버깅 세션과 상호작용하려면 하단 창 디버거에 있는 디버그 콘솔을 사용합니다.

4. 디버깅 세션을 종료하려면 디버그 툴바에서 중지를 클릭합니다.

포드에 디버거 연결과 Kubernetes 애플리케이션 디버깅의 차이점

Kubernetes 포드에 연결	Kubernetes 애플리케이션 디버깅
단일 Kubernetes 포드 디버깅	애플리케이션에서 디버그 가능한 모든 컨테이너 디버깅
디버깅하기 전에 애플리케이션을 Kubernetes 포드에서 실행해야 합니다.	Kubernetes 클러스터에서 애플리케이션을 실행하고 디버거를 연결합니다.
cloudcode.kubernetes 유형의 구성(.vscode/launch.json)을 사용하고 attach를 요청합니다.	cloudcode.kubernetes 유형의 구성(.vscode/launch.json)을 사용하고 launch를 요청합니다. 자세한 내용은 출시 구성과 연결 구성 비교를 참조하세요.
샘플 구성: { "name": "Attach to Kubernetes Pod (NodeJS)", "type": "cloudcode.kubernetes", "request": "attach", "language": "Node", "debugPort": 9229, "podSelector": { "app": "hello-world" }, "localRoot": "${workspaceFolder}", "remoteRoot": "/app" }	샘플 구성: { "name": "Run/Debug on Kubernetes", "type": "cloudcode.kubernetes", "request": "launch", "skaffoldConfig": "${workspaceFolder}/skaffold.yaml", "watch": true, "cleanUp": true, "portForward": true }
이 구성은 애플리케이션을 실행하는 데 사용할 수 없습니다.	이 구성은 애플리케이션을 실행하거나 디버깅하는 데 사용할 수 있습니다.
이 구성은 언어별로 다릅니다.	이 구성은 언어별로 적용되지 않습니다.
전용 명령어 없음	Kubernetes의 디버그 명령어

다음 단계

• 파일 동기화 및 핫 리로드를 사용하여 개발 속도 높이기
• Cloud Code에서 지속적 개발 환경 설정
• Cloud Code에서 Kubernetes 로그 보기