kubectl을 사용하여 EKS 클러스터에 연결할 수 없는 이유는 무엇입니까?

5분 분량

kubectl 명령줄 도구를 사용하여 Amazon Elastic Kubernetes Service(Amazon EKS) 클러스터에 연결하려고 하면 오류 메시지가 표시됩니다.

해결 방법

kubectl을 사용할 때 Amazon EKS 클러스터에 연결할 수 없다면 서비스, 권한 또는 설정을 잘못 구성한 것일 수 있습니다. 로컬 환경이 EKS 클러스터의 API 서버와 통신할 수 없는 경우에도 오류가 발생할 수 있습니다. 수신한 오류 메시지를 기반으로 문제를 해결하십시오.

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하면 AWS CLI의 오류 해결을 참조하십시오. 또한 최신 AWS CLI 버전을 사용하고 있는지 확인하십시오.

사전 요구 사항:

다음 명령을 실행하여 시스템이 올바른 클러스터와 연결을 수립할 수 있는지 확인합니다.
```
kubectl config current-context
```
다음 get-caller-identity AWS CLI 명령을 실행하여 현재 인증된 AWS Identity and Access Management(IAM) 사용자 또는 역할이 올바른지 확인합니다.
```
aws sts get-caller-identity
```
참고: IAM 위탁자가 클러스터 인증 모드를 기반으로 클러스터의 Kubernetes 객체에 액세스할 수 있도록 허용하십시오.

‘exec plugin invalid’ 오류 메시지

kubeconfig 파일의 인증 API 버전이 Kubernetes API 컨트롤 플레인 버전과 호환되지 않는 경우 다음과 같은 오류 메시지가 표시됩니다.

"exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha""

다음 update-kubeconfig 명령을 실행하여 클러스터의 kubeconfig 파일을 업데이트합니다.

aws eks update-kubeconfig --region region-code --name my-cluster

참고: region-code를 클러스터가 위치한 AWS 리전으로, my-cluster를 클러스터 이름으로 바꾸십시오.

kubectl 버전은 Amazon EKS 클러스터 컨트롤 플레인 버전보다 1 마이너 버전 이전 또는 이후 버전이어야 합니다. 예를 들어 kubectl 버전 1.29 클라이언트는 Kubernetes 1.28, 1.29 및 1.30 클러스터와 함께 작동합니다.

‘couldn't get current server API group list’ 오류 메시지

kubeconfig 파일이 존재하지 않거나 인증 기관(CA)을 포함하지 않는 경우 다음과 같은 오류 메시지가 표시됩니다.

"couldn't get current server API group list: Get "https://xxxxxxxxxxxxxxxxxxxx..eks.amazonaws.com/api?timeout=32s": tls: failed to verify certificate: x509: certificate signed by unknown authority"

다음 명령을 실행하여 kubeconfig 파일이 홈 디렉터리의 기본 위치(.kube)에 있는지 확인합니다.
```
cat ~/.kube/config
```
파일이 존재한다면 base64로 인코딩된 클러스터 CA가 kubeconfig 파일에 있는지 확인합니다. 또한 certificate-authority-data 파일이 존재하고 올바르게 구성했는지 확인합니다.

kubeconfig 파일이 존재하지 않는 경우 다음 명령을 실행하여 다시 만듭니다.

kubectl get svc --insecure-skip-tls-verify

TLS를 차단할 수 있는 프록시나 VPN을 사용하는지 확인합니다.

‘could not get current server API group list’ 시간 초과 오류 메시지

소스 호스트가 포트 443에서 API 서버와 통신할 수 없는 경우 요청 제한 시간이 초과되고 다음과 같은 오류 메시지를 받습니다.

"could not get current server API group list: Get "https://xxxxxxxxxxxxxxxxxxxx.gr7.<region-code>.eks.amazonaws.com/api?timeout=32s": dial tcp xx.yy.zz.vvv:443: i/o timeout"

다음 명령을 실행하여 포트 443의 텔넷을 사용해 디바이스에서 API 서버 엔드포인트 연결을 확인합니다.

$ echo exit | telnet

출력 예시:

xxxxxxxxxxxxxxxxxxxx.gr7.us-east-2.eks.amazonaws.com 443Trying 18.224.160.210...
Connected to xxxxxxxxxxxxxxxxxxxx.gr7.us-east-2.eks.amazonaws.com.
Escape character is '^]'.
Connection closed by foreign host.

텔넷 명령으로 문제가 해결되지 않으면 다음 작업을 수행하십시오.

API 서버 엔드포인트에서 퍼블릭 액세스를 활성화한 경우 API 서버 엔드포인트에 대한 액세스를 특정 CIDR 범위로 제한했는지 확인합니다. 디바이스의 IP 주소가 CIDR 블록에 속하는지 확인합니다. 또한 API 서버 엔드포인트 액세스 동작을 확인합니다.
API 서버 엔드포인트에서 프라이빗 액세스만 활성화한 경우 모든 클러스터 API 서버 트래픽은 가상 프라이빗 클라우드(VPC) 또는 연결된 네트워크에서 수신되어야 합니다. 또한 kubectl 명령은 VPC 또는 연결된 네트워크 내에서 수신되어야 합니다. 자세한 내용은 프라이빗 전용 API 서버에 액세스를 참조하십시오.
보안 그룹 또는 네트워크 액세스 제어 목록(네트워크 ACL)이 Kubernetes API 서버에 대한 요청을 차단하는지 확인합니다. 클러스터 보안 그룹이 소스 CIDR의 포트 443에서 트래픽을 허용하는지 확인합니다.

‘couldn't get current API server group list’ 오류 메시지

Amazon EKS 클러스터에서 Kubernetes API 액세스 권한 없이 작업을 수행하려고 하면 다음과 같은 오류 메시지가 표시됩니다.

"couldn't get current server API group list: the server has asked for the client to provide credentials"

이 문제를 해결하려면 다음 단계를 완료하십시오.

get-caller-identity 명령을 실행하여 EKS 클러스터에 액세스 요청을 보낸 사용자를 확인합니다.

aws sts get-caller-identity

출력 예시:

{
 "UserId": "user-ID",
 "Account": "account-ID",
 "Arn": "arn:aws:iam::account-ID:user/kube-user"
}

참고: 위 예제 출력에는 요청을 보낸 IAM 엔터티의 사용자 ID, AWS 계정 및 ARN이 포함되어 있습니다.

API_AND_CONFIG_MAP 또는 API로 인증 모드를 변경한 다음, EKS 액세스 항목을 사용하여 IAM 사용자에게 Kubernetes 액세스 권한을 부여합니다.

적절한 권한을 부여하려면 API 또는 API_AND_CONFIG_MAP 인증 모드를 사용하여 IAM 엔터티 항목을 추가합니다.
API 인증 모드
다음 create-access-entry를 실행하여 IAM 위탁자가 Amazon EKS 클러스터를 인증할 수 있도록 허용하는 액세스 항목을 만듭니다.

aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:user/my-user --type STANDARD --username my-user

참고: 위 명령에서 위탁자 ARN을 IAM 엔터티의 ARN으로 바꾸십시오.
다음 associate-access-policy 명령을 실행하여 액세스 항목을 액세스 정책과 연결합니다.

aws eks associate-access-policy --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/my-role \
    --access-scope type=cluster --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy

API_AND_CONFIG_MAP 인증 모드
API_AND_CONFIG_MAP 인증 모드의 경우 위 API 인증 모드를 사용하거나 configmap을 편집할 수 있습니다.
aws-auth configmap을 편집하려면 다음 명령을 실행합니다.

kubectl edit configmap aws-auth -n kube-system

mapRoles 또는 mapUsers 섹션에 IAM 역할 또는 사용자를 추가합니다.
다음은 IAM 역할 항목이 있는 mapRoles 섹션의 예입니다.

mapRoles: |
    - groups:
      - system:masters
      rolearn: arn:aws:iam::111122223333:role/MyEKSrole
      username: eks-user

참고: 예제 ARN을 IAM 역할의 ARN으로 바꾸십시오. IAM 사용자를 사용하는 경우 MapRoles를 MapUsers로, ARN을 IAM 사용자의 ARN으로 바꾸십시오.

위 예제에서는 클러스터에 대한 전체 관리 액세스 권한을 부여하는 system:masters 그룹에 IAM 위탁자를 매핑합니다. 액세스를 더 제한하려면 IAM 위탁자를 사용자 지정 Kubernetes 사용자 또는 그룹에 매핑하고 Kubernetes 역할 기반 액세스 제어(RBAC) 객체를 사용하여 필요한 권한을 정의하십시오. 자세한 내용은 Kubernetes 웹 사이트에서 RBAC 권한 부여 사용을 참조하십시오.

‘Did you specify the right host or port?’ 오류 메시지

kubeconfig 파일을 올바르게 구성하지 않은 경우 kubectl이 EKS 클러스터에 연결할 수 없으며 다음과 같은 오류 메시지가 표시됩니다.

"The connection to the server localhost:8080 was refused - did you specify the right host or port?"

이 문제를 해결하려면 다음 작업을 수행하십시오.

다음 명령을 실행하여 kubeconfig 파일을 업데이트합니다.

aws eks update-kubeconfig --region region-code --name my-cluster

다음 명령을 실행하여 kubeconfig 파일의 현재 컨텍스트를 확인합니다.

kubectl config current-context

current-context 명령의 출력이 예상 EKS 클러스터를 가리키지 않는 경우 다음 명령을 실행합니다.
```
kubectl config use-context ;
```