Kubernetes 연결 문제 해결: exec 및 port-forward를 효과적으로 사용하는 방법

Kubernetes 연결 문제 해결: exec 및 port-forward 효과적으로 사용하기

선도적인 컨테이너 오케스트레이션 플랫폼인 Kubernetes는 컨테이너화된 애플리케이션의 배포, 확장 및 관리를 자동화할 수 있도록 지원합니다. 선언적(declarative) 특성 덕분에 많은 운영 작업이 단순화되지만, 연결 문제 및 내부 애플리케이션 문제를 해결하는 것은 여전히 어려울 수 있습니다. 애플리케이션이나 내부 상태에 직접적인 접근이 필요할 때, kubectl exec 및 kubectl port-forward는 디버깅 도구 키트에서 없어서는 안 될 도구입니다.

이 문서는 컨테이너 내에서 명령을 실행하기 위한 kubectl exec와 서비스에 안전한 로컬 액세스를 설정하기 위한 kubectl port-forward의 실용적인 응용 방법을 안내합니다. 이러한 명령을 숙달함으로써 애플리케이션 동작에 대한 더 깊은 통찰력을 얻고, 네트워크 문제를 진단하며, 연결 문제를 보다 효율적으로 해결하여 궁극적으로 Kubernetes 배포의 안정성과 성능을 향상시킬 수 있습니다.

kubectl exec 이해하기

kubectl exec 명령을 사용하면 파드(Pod) 내에서 실행 중인 컨테이너 내부에서 명령을 실행할 수 있습니다. 이는 애플리케이션이 실행되는 환경에서 직접 로그를 검사하고, 구성을 확인하고, 진단 도구를 실행하는 데 매우 유용합니다.

기본 구문

kubectl exec의 기본 구문은 다음과 같습니다:

kubectl exec <pod-name> -- <command> [args...]

• <pod-name>: 명령을 실행하려는 파드의 이름입니다.
• --: 이 구분 기호는 매우 중요합니다. 이는 kubectl 플래그와 컨테이너 내부에서 실행하려는 명령을 구분합니다.
• <command>: 컨테이너 내에서 실행할 명령(예: ls, cat, ping)입니다.
• [args...]: 명령에 대한 모든 인수입니다.

대화형 셸 액세스

kubectl exec의 가장 일반적인 용도 중 하나는 컨테이너 내부에 대화형 셸(예: bash 또는 sh)을 얻는 것입니다. 이를 통해 컨테이너의 파일 시스템을 탐색하고 여러 명령을 실행할 수 있습니다.

대화형 셸을 얻는 방법:

kubectl exec -it <pod-name> -- /bin/bash

• -i (또는 --stdin): 연결되지 않은 경우에도 stdin을 열린 상태로 유지합니다.
• -t (또는 --tty): 의사 TTY를 할당하며, 이는 대화형 셸 세션에 필수적입니다.

예시: my-app-pod라는 이름의 파드에서 bash 셸에 액세스하기:

kubectl exec -it my-app-pod -- /bin/bash

내부에 들어가면 표준 Linux 명령을 사용할 수 있습니다. 셸을 종료하려면 exit를 입력하거나 Ctrl+D를 누르십시오.

단일 명령 실행

대화형 셸 없이 단일 명령을 실행할 수도 있습니다. 이는 빠른 확인이나 스크립팅에 유용합니다.

예시: my-app-pod의 /app 디렉터리 파일 확인:

kubectl exec my-app-pod -- ls /app

예시: 구성 파일 config.yaml의 내용 보기:

kubectl exec my-app-pod -- cat /etc/my-app/config.yaml

파드 내에서 컨테이너 지정하기

파드에 여러 개의 컨테이너가 있는 경우, -c 플래그를 사용하여 명령을 실행할 컨테이너를 지정해야 합니다.

kubectl exec <pod-name> -c <container-name> -- <command>

예시: multi-container-pod의 sidecar-container에서 env 실행:

kubectl exec multi-container-pod -c sidecar-container -- env

kubectl port-forward 이해하기

kubectl port-forward 명령을 사용하면 로컬 시스템에서 Kubernetes 클러스터의 특정 파드 또는 서비스로 보안 터널을 설정할 수 있습니다. 이는 외부로 노출되지 않은 애플리케이션을 디버깅하거나, 데이터베이스에 액세스하거나, 내부 API를 테스트하는 데 매우 유용합니다.

기본 구문

일반적인 구문은 다음과 같습니다:

kubectl port-forward <pod-name> <local-port>:<remote-port>

• <pod-name>: 연결하려는 파드의 이름입니다.
• <local-port>: 연결을 수신할 로컬 시스템의 포트입니다.
• <remote-port>: 전달된 트래픽을 수신할 파드의 포트입니다.

예시: 로컬 포트 8080을 my-app-pod의 포트 80으로 포트 포워딩:

kubectl port-forward my-app-pod 8080:80

이 명령이 실행되면 웹 브라우저에서 http://localhost:8080으로 이동하거나 로컬 시스템에서 curl과 같은 도구를 사용하여 애플리케이션에 액세스할 수 있습니다.

서비스로 포트 포워딩

특정 파드 대신 Kubernetes 서비스로 트래픽을 포워딩할 수도 있습니다. kubectl은 해당 서비스를 지원하는 파드를 자동으로 선택합니다.

kubectl port-forward service/<service-name> <local-port>:<service-port>

예시: 로컬 포트 3000을 my-service 서비스의 포트 80으로 포트 포워딩:

kubectl port-forward service/my-service 3000:80

Deployment 또는 StatefulSet으로 포트 포워딩

마찬가지로 Deployment 또는 StatefulSet으로 포워딩할 수 있습니다. kubectl은 지정된 리소스에 의해 관리되는 파드 중 하나를 선택합니다.

kubectl port-forward deployment/<deployment-name> <local-port>:<container-port>

kubectl port-forward statefulset/<statefulset-name> <local-port>:<container-port>

특정 주소에 바인딩

기본적으로 port-forward는 localhost에 바인딩됩니다. --address 플래그를 사용하여 다른 로컬 주소를 지정할 수 있습니다.

kubectl port-forward --address 127.0.0.1 <pod-name> <local-port>:<remote-port>

다중 포트 포워딩

kubectl port-forward는 여러 포트를 동시에 포워딩할 수 있습니다.

kubectl port-forward my-app-pod 8080:80 9090:90

이 명령은 로컬 포트 8080을 파드 포트 80으로, 로컬 포트 9090을 파드 포트 90으로 포워딩합니다.

일반적인 문제 해결 시나리오 및 솔루션

시나리오 1: 애플리케이션이 응답하지 않지만 파드는 정상으로 보일 때.

• 문제: 파드는 실행 중이지만, 서비스로의 요청이 실패하거나 시간 초과됩니다. 애플리케이션에 내부 구성 문제가 있거나 멈췄을 수 있습니다.
• kubectl exec를 사용한 해결책:
  1. 파드 내부에 대화형 셸을 얻습니다: kubectl exec -it <pod-name> -- /bin/bash
  2. 셸 내부에서 애플리케이션 로그를 확인합니다 (예: tail -f /var/log/myapp.log).
  3. 애플리케이션의 내부 구성 파일을 확인합니다.
  4. ping 또는 curl (설치된 경우)을 사용하여 파드 내부에서 다른 서비스로의 네트워크 연결을 확인합니다.
• kubectl port-forward를 사용한 해결책:
  1. 애플리케이션의 수신 포트로 포트를 포워딩합니다: kubectl port-forward <pod-name> 8080:<app-port>
  2. http://localhost:8080을 통해 로컬로 애플리케이션에 액세스를 시도합니다. 이는 문제가 Kubernetes 서비스 디스커버리 또는 인그레스에 있는지, 아니면 애플리케이션 자체가 응답하지 않는지 판단하는 데 도움이 됩니다.

시나리오 2: 파드에서 실행 중인 데이터베이스 디버깅이 필요할 때.

• 문제: 데이터 검사 또는 쿼리 실행을 위해 로컬 데이터베이스 클라이언트를 Kubernetes 파드 내부에서 실행 중인 데이터베이스에 연결해야 합니다.
• kubectl port-forward를 사용한 해결책:
  1. 데이터베이스가 실행 중인 파드와 해당 포트를 식별합니다 (예: mysql-pod, 포트 3306).
  2. 로컬 포트를 데이터베이스 포트로 포워딩합니다: kubectl port-forward mysql-pod 3306:3306
  3. 적절한 데이터베이스 자격 증명을 사용하여 로컬 데이터베이스 클라이언트가 localhost:3306에 연결하도록 구성합니다.

시나리오 3: 파드 내 DNS 확인 문제 진단.

• 문제: 파드 내부의 애플리케이션이 서비스 이름을 통해 다른 서비스에 도달할 수 없으며, 이는 DNS 문제를 시사합니다.
• kubectl exec를 사용한 해결책:
  1. 파드 내부에 대화형 셸을 얻습니다: kubectl exec -it <pod-name> -- /bin/bash
  2. 셸 내부에서 알려진 서비스 이름을 확인하려고 시도합니다: nslookup <service-name>.<namespace>.svc.cluster.local 또는 dig <service-name>.<namespace>.svc.cluster.local.
  3. 파드 내에서 클러스터의 DNS 구성이 올바른지 확인하기 위해 /etc/resolv.conf의 내용을 확인합니다.

모범 사례 및 팁

• port-forward를 계속 실행 유지: kubectl port-forward는 포그라운드에서 실행됩니다. 터미널 창을 열어 두어야 합니다. 백그라운드에서 실행하려면 nohup 또는 screen/tmux와 같은 도구를 사용할 수 있습니다.
• 디버깅 시 특정 파드 사용: 서비스로 포워딩하는 것이 편리하지만, 특정 인스턴스의 문제를 정확히 파악하려면 이름으로 특정 파드에 포워딩하는 것이 더 효과적인 경우가 많습니다.
• 보안: 노출하는 포트에 유의하십시오. 꼭 필요한 경우가 아니면 민감한 포트 포워딩을 피하고 로컬 시스템이 안전한지 확인하십시오.
• 리소스 사용량: kubectl exec는 리소스를 소비할 수 있습니다. 특히 프로덕션 클러스터에서는 신중하게 사용하십시오.
• 권한: kubectl 컨텍스트에 파드에서 명령을 실행하거나 포트를 포워딩하는 데 필요한 권한이 있는지 확인하십시오.

결론

kubectl exec 및 kubectl port-forward는 Kubernetes 애플리케이션 및 네트워크 환경에 대한 가시성을 확보하는 강력한 도구입니다. exec는 실행 중인 컨테이너와 직접 상호 작용하여 심층 검사 및 명령 실행을 가능하게 하며, port-forward는 로컬 시스템과 클러스터 내 서비스 사이의 격차를 해소하여 원활한 디버깅 및 테스트를 용이하게 합니다. 이러한 명령을 정기적인 문제 해결 워크플로우에 통합함으로써 복잡한 연결 및 애플리케이션 문제를 해결하는 데 필요한 시간과 노력을 크게 줄여 더욱 견고하고 안정적인 Kubernetes 배포를 이끌 수 있습니다.