Amazon EKS Connector 문제 해결

이 주제에서는 Amazon EKS Connector를 사용할 때 발생할 수 있는 몇 가지 일반적인 오류와 이를 해결하는 방법 및 임시 방편에 대해 설명합니다.

출처: 문서

본문

기본 문제 해결

이 섹션에서는 Amazon EKS Connector 문제를 진단하는 단계를 설명합니다.

Amazon EKS Connector 상태 확인

Amazon EKS Connector 상태를 확인하려면 다음을 입력합니다.

kubectl get pods -n eks-connector

Amazon EKS Connector 로그 검사

Amazon EKS Connector Pod는 세 개의 컨테이너로 구성됩니다. 이 모든 컨테이너의 전체 로그를 검사하기 위해 검색하려면 다음 명령을 실행합니다.

connector-init

kubectl logs eks-connector-0 --container connector-init -n eks-connector
kubectl logs eks-connector-1 --container connector-init -n eks-connector

connector-proxy

kubectl logs eks-connector-0 --container connector-proxy -n eks-connector
kubectl logs eks-connector-1 --container connector-proxy -n eks-connector

connector-agent

kubectl exec eks-connector-0 --container connector-agent -n eks-connector -- cat /var/log/amazon/ssm/amazon-ssm-agent.log
kubectl exec eks-connector-1 --container connector-agent -n eks-connector -- cat /var/log/amazon/ssm/amazon-ssm-agent.log

유효한 클러스터 이름 가져오기

Amazon EKS 클러스터는 단일 AWS 계정과 AWS 리전 내에서 clusterName으로 고유하게 식별됩니다. Amazon EKS에 연결된 클러스터가 여러 개 있다면 현재 Kubernetes 클러스터가 등록된 Amazon EKS 클러스터를 확인할 수 있어요. 이렇게 하려면 다음을 입력해 현재 클러스터의 clusterName을 알아내세요.

kubectl exec eks-connector-0 --container connector-agent -n eks-connector \
  -- cat /var/log/amazon/ssm/amazon-ssm-agent.log | grep -m1 -oE "eks_c:[a-zA-Z0-9_-]+" | sed -E "s/^.*eks_c:([a-zA-Z0-9_-]+)_[a-zA-Z0-9]+.*$/\1/"
kubectl exec eks-connector-1 --container connector-agent -n eks-connector \
  -- cat /var/log/amazon/ssm/amazon-ssm-agent.log | grep -m1 -oE "eks_c:[a-zA-Z0-9_-]+" | sed -E "s/^.*eks_c:([a-zA-Z0-9_-]+)_[a-zA-Z0-9]+.*$/\1/"

기타 명령

다음 명령은 문제 해결에 필요한 정보를 검색하는 데 유용합니다.

Amazon EKS Connector의 Pod에서 사용하는 이미지를 수집하려면 다음 명령을 사용합니다.

kubectl get pods -n eks-connector -o jsonpath="{.items[*].spec.containers[*].image}" | tr -s '[[:space:]]' '\n'

Amazon EKS Connector가 실행 중인 노드 이름을 확인하려면 다음 명령을 사용합니다.

kubectl get pods -n eks-connector -o jsonpath="{.items[*].spec.nodeName}" | tr -s '[[:space:]]' '\n'

Kubernetes 클라이언트 및 서버 버전을 가져오려면 다음 명령을 실행합니다.

kubectl version

노드에 대한 정보를 가져오려면 다음 명령을 실행합니다.

kubectl get nodes -o wide --show-labels

Helm 문제: 403 Forbidden

helm install 명령을 실행할 때 다음 오류가 발생했다면:

Error: INSTALLATION FAILED: unexpected status from HEAD request to https://public.ecr.aws/v2/eks-connector/eks-connector-chart/manifests/0.0.6: 403 Forbidden

다음 줄을 실행해 해결할 수 있어요.

docker logout public.ecr.aws

콘솔 오류: 클러스터가 Pending 상태에서 멈춤

등록 후 클러스터가 Amazon EKS 콘솔에서 Pending 상태로 멈춘다면 Amazon EKS Connector가 아직 클러스터를 AWS에 성공적으로 연결하지 못했기 때문일 수 있어요. 등록된 클러스터에서 Pending 상태는 연결이 성공적으로 설정되지 않았음을 의미합니다. 이 문제를 해결하려면 대상 Kubernetes 클러스터에 매니페스트를 적용했는지 확인하세요. 클러스터에 적용했는데도 여전히 Pending 상태라면 eks-connector StatefulSet이 비정상일 수 있어요. 이 문제를 해결하려면 이 주제의 Amazon EKS Connector Pod 크래시 루프 참조를 확인하세요.

콘솔 오류: User system:serviceaccount:eks-connector:eks-connector can’t impersonate resource users in API group at cluster scope

Amazon EKS Connector는 AWS Management Console의 IAM 보안 주체를 대신해 작업을 수행하기 위해 Kubernetes 사용자 가장(impersonation)을 사용해요. AWS eks-connector 서비스 계정에서 Kubernetes API에 액세스하는 각 보안 주체는 IAM ARN을 Kubernetes 사용자 이름으로 사용하는 해당 Kubernetes 사용자를 가장할 수 있는 권한이 부여되어야 합니다. 다음 예시에서는 IAM ARN이 Kubernetes 사용자에 매핑됩니다.

AWS 계정 111122223333의 IAM 사용자 john은 Kubernetes 사용자에 매핑됩니다. IAM 모범 사례에서는 사용자 대신 역할에 권한을 부여할 것을 권장합니다.

arn:aws:iam::111122223333:user/john

AWS 계정 111122223333의 IAM 역할 admin은 Kubernetes 사용자에 매핑됩니다:

arn:aws:iam::111122223333:role/admin

결과는 AWS STS 세션 ARN이 아닌 IAM 역할 ARN입니다.

매핑된 사용자를 가장할 수 있는 eks-connector 서비스 계정 권한을 부여하도록 ClusterRole과 ClusterRoleBinding을 구성하는 방법에 대한 지침은 Amazon EKS 콘솔에서 Kubernetes 클러스터 리소스 보기 권한 부여를 참고하세요. 템플릿에서 %IAM_ARN%이 AWS Management Console IAM 보안 주체의 IAM ARN으로 바뀌었는지 확인하세요.

콘솔 오류: […] is forbidden: User […] cannot list resource […] in API group at the cluster scope

다음 문제를 고려해 보세요. Amazon EKS Connector가 대상 Kubernetes 클러스터에서 요청한 AWS Management Console IAM 보안 주체를 성공적으로 가장했습니다. 그러나 가장된 보안 주체는 Kubernetes API 작업에 대한 RBAC 권한이 없어요.

이 문제를 해결하려면 추가 사용자에게 권한을 부여하는 두 가지 방법이 있습니다. 이전에 helm 차트로 eks-connector를 설치했다면 다음 명령을 실행해 사용자에게 액세스 권한을 쉽게 부여할 수 있어요. userARN1과 userARN2를 Kubernetes 리소스를 볼 수 있는 액세스 권한을 부여할 IAM 역할 ARN 목록으로 바꿉니다.

helm upgrade eks-connector oci://public.ecr.aws/eks-connector/eks-connector-chart \
    --reuse-values \
    --set 'authentication.allowedUserARNs={userARN1,userARN2}'

또는 클러스터 관리자로서 개별 Kubernetes 사용자에게 적절한 수준의 RBAC 권한을 부여합니다. 자세한 내용과 예시는 Amazon EKS 콘솔에서 Kubernetes 클러스터 리소스 보기 권한 부여를 참고하세요.

콘솔 오류: Amazon EKS can’t communicate with your Kubernetes cluster API server. The cluster must be in an ACTIVE state for successful connection. Try again in a few minutes.

Amazon EKS 서비스가 대상 클러스터의 Amazon EKS Connector와 통신할 수 없다면 다음 이유 중 하나 때문일 수 있어요.

대상 클러스터의 Amazon EKS Connector가 비정상입니다.
대상 클러스터와 AWS 리전 간의 연결 상태가 좋지 않거나 연결이 중단되었습니다.

이 문제를 해결하려면 Amazon EKS Connector 로그를 확인하세요. Amazon EKS Connector에 대한 오류가 보이지 않으면 몇 분 후에 연결을 다시 시도하세요. 대상 클러스터에서 높은 지연 시간이나 간헐적인 연결 문제를 자주 겪는다면 클러스터를 더 가까운 AWS 리전에 다시 등록하는 것을 고려하세요.

Amazon EKS Connector Pod 크래시 루프

Amazon EKS Connector Pod가 CrashLoopBackOff 상태가 되는 데는 여러 이유가 있을 수 있어요. 이 문제는 connector-init 컨테이너와 관련될 가능성이 높습니다. Amazon EKS Connector Pod의 상태를 확인하세요.

kubectl get pods -n eks-connector

출력 예시는 다음과 같습니다.

NAME              READY   STATUS                  RESTARTS   AGE
eks-connector-0   0/2     Init:CrashLoopBackOff   1          7s

출력이 이전 출력과 유사하다면 문제를 해결하려면 Amazon EKS Connector 로그 검사를 참고하세요.

eks-connector 초기화 실패: InvalidActivation

Amazon EKS Connector를 처음 시작하면 activationId와 activationCode를 Amazon Web Services에 등록해요. 등록이 실패하면 connector-init 컨테이너가 다음 오류와 유사한 오류로 크래시할 수 있습니다.

F1116 20:30:47.261469       1 init.go:43] failed to initiate eks-connector: InvalidActivation:

이 문제를 해결하려면 다음 원인과 권장 수정 사항을 고려하세요.

매니페스트 파일에 activationId와 activationCode가 없어 등록이 실패했을 수 있어요. 이 경우 RegisterCluster API 작업에서 반환된 올바른 값인지 확인하고 activationCode가 매니페스트 파일에 있는지 확인하세요. activationCode는 Kubernetes 비밀에 추가되므로 base64로 인코딩되어야 합니다. 자세한 내용은 1단계: 클러스터 등록을 참고하세요.
활성화가 만료되어 등록이 실패했을 수 있어요. 보안상의 이유로 클러스터 등록 후 3일 이내에 Amazon EKS Connector를 활성화해야 하기 때문입니다. 이 문제를 해결하려면 만료 날짜와 시간 전에 Amazon EKS Connector 매니페스트가 대상 Kubernetes 클러스터에 적용되었는지 확인하세요. 활성화 만료 날짜를 확인하려면 DescribeCluster API 작업을 호출합니다.

aws eks describe-cluster --name my-cluster

다음 예시 응답에서 만료 날짜와 시간은 2021-11-12T22:28:51.101000-08:00으로 기록됩니다.

{
    "cluster": {
        "name": "my-cluster",
        "arn": "arn:aws:eks:region:111122223333:cluster/my-cluster",
        "createdAt": "2021-11-09T22:28:51.449000-08:00",
        "status": "FAILED",
        "tags": {
        },
        "connectorConfig": {
            "activationId": "00000000-0000-0000-0000-000000000000",
            "activationExpiry": "2021-11-12T22:28:51.101000-08:00",
            "provider": "OTHER",
            "roleArn": "arn:aws:iam::111122223333:role/my-connector-role"
        }
    }
}

activationExpiry가 지났다면 클러스터 등록을 취소하고 다시 등록합니다. 이렇게 하면 새 활성화가 생성됩니다.

클러스터 노드에 아웃바운드 연결 누락

Amazon EKS Connector가 제대로 작동하려면 여러 AWS 엔드포인트에 대한 아웃바운드 연결이 필요해요. 대상 AWS 리전에 대한 아웃바운드 연결이 없는 프라이빗 클러스터는 연결할 수 없습니다. 이 문제를 해결하려면 필요한 아웃바운드 연결을 추가해야 합니다. Connector 요구 사항에 대한 정보는 Amazon EKS Connector 고려 사항을 참고하세요.

Amazon EKS Connector Pod가 `ImagePullBackOff` 상태

get pods 명령을 실행했는데 Pod가 ImagePullBackOff 상태라면 제대로 작동할 수 없어요. Amazon EKS Connector Pod가 ImagePullBackOff 상태라면 제대로 작동할 수 없습니다. Amazon EKS Connector Pod의 상태를 확인하세요.

kubectl get pods -n eks-connector

출력 예시는 다음과 같습니다.

NAME              READY   STATUS                  RESTARTS   AGE
eks-connector-0   0/2     Init:ImagePullBackOff   0          4s

기본 Amazon EKS Connector 매니페스트 파일은 Amazon ECR Public Gallery의 이미지를 참조합니다. 대상 Kubernetes 클러스터가 Amazon ECR Public Gallery에서 이미지를 가져오지 못할 수 있어요. Amazon ECR Public Gallery의 이미지 가져오기 문제를 해결하거나 선택한 프라이빗 컨테이너 레지스트리에 이미지를 미러링하는 것을 고려하세요.

더 알아보기 (Learn more)

공식 문서

Amazon EKS Connector 문제 해결