Amazon EKS에서 kubectl 명령을 실행할 수 없는 이유는 무엇입니까?

간략한 설명

kubectl 명령을 실행하려고 하면 다음과 같은 문제가 발생할 수 있습니다.

• kubectl exec, kubectl logs, kubectl attach 또는 kubectl port-forward를 실행할 수 없습니다.
• kubectl이 컨트롤 플레인에 연결할 수 없습니다.
• kubectl을 설치할 수 없습니다.
• 인증 오류가 발생합니다.

해결 방법

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

kubectl exec, kubectl logs, kubectl attach 또는 kubectl port-forward를 실행할 수 없음

kubectl exec, kubectl logs, kubectl attach 또는 kubectl port-forward 명령을 실행하려면 Amazon EKS API가 kubelet과 신뢰할 수 있는 연결을 설정해야 합니다. 인증에 실패하면 다음 예와 유사한 오류가 표시됩니다.

"Error from server: error dialing backend: remote error: tls: internal error"

네트워크 연결 문제 확인

API 서버가 포트 1025의 작업 노드와 통신할 수 있는지 확인하십시오. 워커 노드 보안 그룹은 포트 10250의 클러스터 보안 그룹으로부터의 인바운드 트래픽을 허용해야 합니다. 클러스터 보안 그룹은 포트 443의 워커 노드 보안 그룹으로부터의 인바운드 트래픽을 허용해야 합니다. 보안 그룹이 Amazon EKS 요구 사항을 준수하는지 확인하십시오.

CSR 문제 확인

제어판에서 kubelet이 제출한 인증서 서명 요청(CSR)을 승인하지 않으면 kubelet을 실행할 수 없습니다.

문제가 있는 CSR을 확인하려면 다음 명령을 실행합니다.

kubectl get certificatesigningrequest

CSR 요청의 상태를 확인하려면 다음 명령을 실행합니다.

kubectl describe certificatesigningrequest csr-name -n namespace

참고: csr-name을 CSR 이름으로 바꾸고 namespace를 네임스페이스 이름으로 바꾸십시오.

출력에서 CSR이 승인됨, 발급됨 상태 대신 보류 중 또는 승인됨 상태인지 확인하십시오.

kubelet에서 RotateKubeletServerCertificate 및 ServerTLSBootstrap 플래그를 활성화해야 kubelet이 제공되는 인증서를 자체적으로 제출하고 교체할 수 있습니다. kubelet-config JSON 파일의 플래그가 true로 설정되어 있는지 확인하려면 워커 노드 내에서 다음 명령을 실행합니다.

cat /etc/kubernetes/kubelet/kubelet-config.json

출력 예시:

"serverTLSBootstrap": true
"featureGates": {
    "RotateKubeletServerCertificate": true
    }

kubelet이 CSR을 생성하고 제출하려면 eks:node-bootstrapper 역할을 system:bootstrappers 및 system:nodes 그룹에 연결해야 합니다. ClusterRole 및 ClusterRoleBinding에 eks:node:boostrapper 역할이 있는지 확인하려면 다음 명령을 실행합니다.

kubectl describe clusterrole eks:node-bootstrapper
kubectl describe clusterrolebinding eks:node-bootstrapper

출력 예시:

kubectl describe clusterrole eks:node-bootstrapper
 Name: eks:node-bootstrapper
 Labels: eks.amazonaws.com/component=node
 Annotations: <none>
 PolicyRule:
 Resources Non-Resource URLs Resource Names Verbs
 --------- ----------------- -------------- -----
 certificatesigningrequests.certificates.k8s.io/selfnodeserver [] [] [create]

$ kubectl describe clusterrolebinding eks:node-bootstrapper
 Name: eks:node-bootstrapper
 Labels: eks.amazonaws.com/component=node
 Annotations: <none>
 Role:
 Kind: ClusterRole
 Name: eks:node-bootstrapper
 Subjects:
 Kind Name Namespace
 ---- ---- ---------
 Group system:bootstrappers
 Group system:nodes

eks:node-bootstrapper 역할이 없는 경우 다음 구성으로 YAML 파일을 생성합니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eks:node-bootstrapper
  labels:
    eks.amazonaws.com/component: node
rules:
  - apiGroups: ["certificates.k8s.io"]
    resources: ["certificatesigningrequests/selfnodeserver"]
    verbs: ["create"]

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: eks:node-bootstrapper
  labels:
    eks.amazonaws.com/component: node
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: eks:node-bootstrapper
subjects:
  - kind: Group
    name: system:bootstrappers
  - kind: Group
    name: system:nodes

그런 다음, 아래 명령을 실행하여 Amazon EKS 클러스터를 업데이트합니다.

 kubectl apply -f file-name command

참고: file-name을 YAML 파일 이름으로 바꾸십시오.

ConfigMap 인증 방법을 사용하는 경우 aws-auth 파일에서 구성한 instance-role을 system:bootstrappers 및 system:nodes 그룹에도 연결해야 합니다. instance-role을 다음과 같은 형식으로 aws-auth에 추가하십시오.

kubectl get cm aws-auth -n kube-system -o yaml
apiVersion: v1
data:
  mapRoles: |
    - groups:
      - system:bootstrappers
      - system:nodes
      rolearn: arn:aws:iam::12345678912:role/kubectl-cluster-nodegroup-custo-NodeInstanceRole-1KFZHWE6FCBDS
      username: system:node:{{EC2PrivateDNSName}}

참고: Amazon EKS API를 클러스터 인증 모드로 구성한 경우 구성을 확인하십시오. 워커 노드의 AWS Identity and Access Management(IAM) 역할이 system:node:{{EC2PrivateDNSName}} 사용자 이름에 매핑되어야 합니다. 이 구성을 통해 Amazon EKS는 CSR 요청자를 인식하고 CSR을 자동으로 승인합니다. Amazon EKS는 **system:node:{{EC2PrivateDNSName}}**의 CSR만 자동으로 승인합니다.

요청자 세부 정보를 확인하려면 다음 명령을 실행합니다.

kubectl describe csr csr-name

참고: csr-name을 CSR 이름으로 바꾸십시오.

출력 예시:

Name:               csr-tpb4m
Labels:             <none>
Annotations:        <none>
CreationTimestamp:  Tue, 12 Dec 2023 11:18:30 +0530
Requesting User:    system:node:ip-000-00-00-000.ec2.internal
Signer:             kubernetes.io/kubelet-serving
Status:             Approved,Issued
Subject:
  Common Name:    system:node:ip-172-31-73-240.ec2.internal
  Serial Number:  
  Organization:   system:nodes
Subject Alternative Names:
         DNS Names:     ip-172-31-73-240.ec2.internal
         IP Addresses:  172.31.73.240
Events:  <none>

CSR 요청자가 system:node:ip-abc-xx-x-xabc.ec2.internal 형식인지 확인하십시오. 워커 노드용 클러스터를 생성한 것과 동일한 IAM 역할을 사용하는 경우 요청자는 system:node:EC2PrivateDNSName 대신 kubernetes-admin가 될 수 있습니다. Amazon EKS는 system:node:EC2PrivateDNSName에서 오지 않은 요청을 거부합니다. 워커 노드 역할을 aws-auth의 사용자 지정 사용자 이름에 매핑한 경우 워커 노드 역할을 system:node:EC2PrivateDNSName에 올바르게 매핑했는지 확인하십시오.

kubelet 로그 확인

kubelet의 상태를 확인하려면 다음 명령을 실행합니다.

systemctl status kubelet

출력에서 kubelet 상태가 중지됨으로 표시되면 다음 명령을 실행하여 kubelet을 다시 시작합니다.

sudo systemctl restart kubelet

kubelet 로그에서 cert 키워드를 확인하려면 다음 명령을 실행합니다.

 journalctl -u kubelet | grep cert

오류 예시:

kubelet[8070]: I1021 18:49:21.594143 8070 log.go:184] http: TLS handshake error from 192.168.130.116:38710: no serving certificate available for the kubelet

명령 출력에 cert 오류가 표시되지 않으면 새 CSR을 제출할 수 있습니다. 자세한 로그를 보려면 --v=4 플래그를 사용하십시오. 자세한 분석을 위해 워커 노드 로그를 수집하려면 GitHub 웹 사이트의 log-collector-script를 사용하십시오.

컨트롤 플레인 로그 확인

전제 조건: Amazon EKS 클러스터가 컨트롤 플레인 로그를 Amazon CloudWatch Logs Insights에 전송하도록 허용합니다.

CSR 문제에 대한 추가적인 인사이트를 보려면 다음 명령을 실행하여 CloudWatch Logs Insights를 사용해 컨트롤 플레인 로그를 확인하십시오.

fields @timestamp, @message, @logStream, @log
| filter message like 'csr-name'
| sort @timestamp desc
| limit 10000

참고: csr-name을 문제가 있는 CSR의 이름으로 바꾸십시오.

Kubectl이 컨트롤 플레인에 연결할 수 없음

Amazon EKS 엔드포인트에 대한 액세스 확인

클러스터의 Kubernetes API 서버 엔드포인트에 대한 프라이빗 액세스를 활성화한 경우 다음 소스에서만 API 서버에 액세스할 수 있습니다.

• 가상 프라이빗 네트워크(VPC)
• 연결된 네트워크

VPC에 속하지 않거나 연결된 네트워크에 있지 않은 클라이언트에서 kubectl을 실행하는 경우 클러스터의 API 서버에 연결할 수 없습니다. 다음 예와 유사한 오류가 표시됩니다.

"E1009 12:33:44.852680 106 memcache.go:265] couldn't get current server API group list: Get "APISERVERENDPOINT": dial tcp 11.11.111.111:443: i/o timeout"

이 문제를 해결하려면 클러스터 엔드포인트 액세스를 퍼블릭 액세스로 변경하십시오. 프라이빗 클러스터가 필요한 경우 클러스터의 VPC에 Amazon Elastic Compute Cloud(Amazon EC2) 배스천 호스트를 생성하십시오. 그런 다음, 배스천 호스트를 사용하여 클러스터에 액세스하십시오. 배스천 호스트의 보안 그룹을 클러스터의 보안 그룹에 추가해야 합니다.

호스트 및 포트 구성 확인

The connection to the server localhost:8080 was refused 오류 메시지가 표시되는 경우 호스트 및 포트 구성을 확인하십시오. 이 오류는 일반적으로 kubectl이 kubeconfig 파일에서 Amazon EKS API 서버 엔드포인트의 올바른 포트 및 호스트 정보를 찾을 수 없을 때 발생합니다.

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

1. kubeconfig 파일을 업데이트하려면 다음 update-kubeconfig AWS CLI 명령을 실행합니다.

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

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

2. 현재 컨텍스트를 보려면 다음 명령을 실행합니다.

   kubectl config current-context

3. 환경에 구성한 IAM 사용자 또는 역할을 확인하려면 다음 get-caller-identity 명령을 실행합니다.

   aws sts get-caller-identity

IAM 문제를 해결하려면 Amazon EKS에서 클러스터를 생성한 후 다른 IAM 사용자 및 역할에 클러스터 액세스 권한을 제공하려면 어떻게 해야 합니까?를 참조하십시오.

컨트롤 플레인 및 워커 노드 보안 그룹 규칙 확인

컨트롤 플레인 및 노드 보안 그룹 규칙이 API 서버에 대한 액세스를 차단하는 경우 다음과 같은 오류가 발생합니다.

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

이 문제를 해결하려면 컨트롤 플레인 및 노드 보안 그룹에 필요한 인바운드 및 아웃바운드 규칙이 있는지 확인하십시오. API 서버 보안 그룹은 포트 443에서 API 서버 클라이언트의 인바운드 액세스를 허용해야 합니다.

kubectl을 설치할 수 없음

클러스터와 마이너 버전 간의 차이가 1 이내인 kubectl 버전을 사용해야 합니다. 예를 들어 v1.31 클라이언트는 컨트롤 플레인 버전 v1.30, v1.31 및 v1.32와 통신할 수 있습니다. 문제를 피하려면 ](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html#kubectl-install-update)kubectl의 호환 가능한 최신 버전을 설치하십시오[.

kubectl을 설치할 때 다음 오류 중 하나가 표시될 수 있습니다.

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

-또는-

"Unable to connect to the server: getting credentials: decoding stdout: no kind "ExecCredential" is registered for version "client.authentication.k8s.io/v1alpha1" in scheme "pkg/client/auth/exec/exec.go:62""

위 오류는 일반적으로 이전 버전의 AWS CLI를 사용하여 update-kubeconfig 명령을 실행할 때 발생합니다. 이 문제를 해결하려면 AWS CLI 업데이트를 수행하십시오. 자세한 내용은 GitHub 웹 사이트에서 Kubernetes 클라이언트 API 버전 v1alpha1 사용 중지를 참조하십시오.

kubectl 명령을 실행할 때 인증 오류 발생

kubectl 명령을 실행할 때 다음과 같은 오류가 발생할 수 있습니다.

"error: You must be logged in to the server (Unauthorized)"

이 문제를 해결하려면 Amazon EKS API 서버에 연결할 때 발생하는 "You must be logged in to the server (Unauthorized)" 오류를 해결하려면 어떻게 해야 합니까?를 참조하십시오.