kubectl 문제 해결
kubectl 문제 해결 (Troubleshoot kubectl)
이 문서는 kubectl 관련 문제를 조사하고 진단하는 방법에 관한 것이에요. kubectl에 접근하거나 클러스터에 연결할 때 문제가 발생하면, 이 문서는 가능한 일반적인 시나리오와 잠재적 해결책을 설명해 가능성이 높은 원인을 식별하고 해결하도록 도와줍니다.
출처: 문서
본문
시작하기 전에
- 쿠버네티스 클러스터가 있어야 합니다.
kubectl도 설치되어 있어야 합니다 - 도구 설치 참조
kubectl 설정 검증
로컬 머신에 kubectl을 올바르게 설치하고 구성했는지 확인하세요. kubectl 버전을 확인해 최신 상태이고 클러스터와 호환되는지 확인하세요.
kubectl 버전 확인:
kubectl version
비슷한 출력이 보일 것입니다:
Client Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.4",GitCommit:"fa3d7990104d7c1f16943a67f11b154b71f6a132", GitTreeState:"clean",BuildDate:"2023-07-19T12:20:54Z", GoVersion:"go1.20.6", Compiler:"gc", Platform:"linux/amd64"}
Kustomize Version: v5.0.1
Server Version: version.Info{Major:"1", Minor:"27", GitVersion:"v1.27.3",GitCommit:"25b4e43193bcda6c7328a6d147b1fb73a33f1598", GitTreeState:"clean",BuildDate:"2023-06-14T09:47:40Z", GoVersion:"go1.20.5", Compiler:"gc", Platform:"linux/amd64"}
Server Version 대신 Unable to connect to the server: dial tcp <server-ip>:8443: i/o timeout이 보이면, 클러스터와의 kubectl 연결을 문제 해결해야 합니다.
kubectl 설치 공식 문서에 따라 kubectl을 설치했고, $PATH 환경 변수를 올바르게 구성했는지 확인하세요.
kubeconfig 확인
kubectl은 쿠버네티스 클러스터에 연결하려면 kubeconfig 파일이 필요합니다. kubeconfig 파일은 보통 ~/.kube/config 디렉터리에 있습니다. 유효한 kubeconfig 파일이 있는지 확인하세요. kubeconfig 파일이 없다면 쿠버네티스 관리자에게 얻거나, 쿠버네티스 컨트롤 플레인의 /etc/kubernetes/admin.conf 디렉터리에서 복사할 수 있어요. 쿠버네티스 클러스터를 클라우드 플랫폼에 배포했고 kubeconfig 파일을 잃어버렸다면, 클라우드 제공자의 도구를 사용해 다시 생성할 수 있습니다. kubeconfig 파일 재생성은 클라우드 제공자 문서를 참조하세요.
$KUBECONFIG 환경 변수가 올바르게 구성되었는지 확인하세요. $KUBECONFIG 환경 변수를 설정하거나 kubectl과 함께 --kubeconfig 파라미터를 사용해 kubeconfig 파일의 디렉터리를 지정할 수 있습니다.
VPN 연결 확인
가상 사설망(VPN)을 사용해 쿠버네티스 클러스터에 접근한다면, VPN 연결이 활성화되고 안정적인지 확인하세요. 때로 VPN 연결 끊김이 클러스터와의 연결 문제로 이어질 수 있습니다. VPN에 다시 연결하고 클러스터에 다시 접근해 보세요.
인증과 권한 부여
토큰 기반 인증을 사용하고 kubectl이 인증 토큰이나 인증 서버 주소에 대한 오류를 반환한다면, 쿠버네티스 인증 토큰과 인증 서버 주소가 올바르게 구성되었는지 검증하세요.
kubectl이 권한 부여에 대한 오류를 반환한다면, 유효한 사용자 자격 증명을 사용하고 있는지 확인하세요. 그리고 요청한 리소스에 접근할 권한이 있는지 확인하세요.
컨텍스트 검증
쿠버네티스는 여러 클러스터와 컨텍스트를 지원합니다. 클러스터와 상호작용하는 데 올바른 컨텍스트를 사용하고 있는지 확인하세요.
사용 가능한 컨텍스트 나열:
kubectl config get-contexts
적절한 컨텍스트로 전환:
kubectl config use-context <context-name>
API 서버와 로드 밸런서
API 서버는 쿠버네티스 클러스터의 핵심 구성 요소입니다. API 서버 또는 API 서버 앞에서 실행되는 로드 밸런서에 도달할 수 없거나 응답하지 않으면 클러스터와 상호작용할 수 없습니다.
ping 명령으로 API 서버 호스트에 도달할 수 있는지 확인하세요. 클러스터의 네트워크 연결과 방화벽을 확인하세요. 클러스터 배포에 클라우드 제공자를 사용한다면 클러스터의 API 서버에 대한 클라우드 제공자 상태 확인을 확인하세요.
로드 밸런서가(사용하는 경우) 정상이고 API 서버로 트래픽을 전달하는지 상태를 확인하세요.
TLS 문제
- 추가로 필요한 도구 -
base64와 버전 3.0 이상의openssl.
쿠버네티스 API 서버는 기본적으로 HTTPS 요청만 제공합니다. 이 경우 인증서 만료나 신뢰 체인 유효성 같은 다양한 이유로 TLS 문제가 발생할 수 있습니다.
TLS 인증서는 ~/.kube/config 디렉터리에 있는 kubeconfig 파일에서 찾을 수 있습니다. certificate-authority 속성은 CA 인증서를, client-certificate 속성은 클라이언트 인증서를 포함합니다.
이 인증서들의 만료를 확인합니다:
kubectl config view --flatten --output 'jsonpath={.clusters[0].cluster.certificate-authority-data}' | base64 -d | openssl x509 -noout -dates
출력:
notBefore=Feb 13 05:57:47 2024 GMT
notAfter=Feb 10 06:02:47 2034 GMT
kubectl config view --flatten --output 'jsonpath={.users[0].user.client-certificate-data}'| base64 -d | openssl x509 -noout -dates
출력:
notBefore=Feb 13 05:57:47 2024 GMT
notAfter=Feb 12 06:02:50 2025 GMT
kubectl 헬퍼 검증
일부 kubectl 인증 헬퍼는 쿠버네티스 클러스터에 쉽게 접근할 수 있게 해줍니다. 그러한 헬퍼를 사용했고 연결 문제를 겪고 있다면, 필요한 구성이 여전히 있는지 확인하세요.
인증 세부 정보에 대한 kubectl 구성 확인:
kubectl config view
이전에 헬퍼 도구(예: kubectl-oidc-login)를 사용했다면, 그것이 여전히 설치되고 올바르게 구성되었는지 확인하세요.