기본 문제 해결 Helm 문제: 403 Forbidden 콘솔 오류: 클러스터가 보류 중 상태에서 멈춰 있음 콘솔 오류: 사용자 system:serviceaccount:eks-connector:eks-connector가 클러스터 범위에서 API 그룹의 리소스 사용자를 가장할 수 없습니다.콘솔 오류: [...] 금지됨: 사용자 [...]이(가) 클러스터 범위에서 API 그룹의 [...] 리소스를 나열할 수 없음 콘솔 오류: Amazon EKS가 Kubernetes 클러스터 API 서버와 통신할 수 없습니다. 연결에 성공하려면 클러스터가 ACTIVE 상태여야 합니다. 몇 분 후에 다시 시도하세요.Amazon EKS 커넥터 포드가 크래시 반복됨 eks-connector 시작 실패: InvalidActivation 클러스터 노드에 아웃바운드 연결이 없습니다.Amazon EKS 커넥터 포드의 상태가 ImagePullBackOff임

Amazon EKS Connector 이슈 문제 해결

이 주제에서는 해결 방법에 대한 지침과 해결 방법을 포함하여 Amazon EKS 커넥터를 사용하는 동안 발생할 수 있는 몇 가지 일반적인 오류를 설명합니다.

기본 문제 해결

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

Amazon EKS 커넥터 상태 확인

Amazon EKS 커넥터 상태를 확인하려면 다음과 같이 입력합니다.


kubectl get pods -n eks-connector

Amazon EKS 커넥터 로그 검사

Amazon EKS 커넥터 포드는 3개의 컨테이너로 구성됩니다. 이러한 컨테이너를 모두 검사할 수 있도록 전체 로그를 검색하려면 다음 명령을 실행합니다.

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 커넥터의 포드에서 사용하는 이미지를 수집합니다.


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

다음과 같은 명령을 사용하여 Amazon EKS 커넥터가 실행 중인 노드 이름을 확인합니다.
```
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

콘솔 오류: 클러스터가 보류 중 상태에서 멈춰 있음

클러스터를 등록한 후 Amazon EKS 콘솔에서 클러스터가 Pending 상태로 멈추는 경우 Amazon EKS 커넥터가 아직 클러스터를 AWS에 성공적으로 연결하지 않았기 때문일 수 있습니다. 등록된 클러스터의 경우 Pending 상태는 연결이 성공적으로 설정되지 않았음을 의미합니다. 이 문제를 해결하려면 대상 Kubernetes 클러스터에 매니페스트를 적용했는지 확인하세요. 클러스터에 적용했지만 클러스터가 여전히 Pending 상태인 경우에는 eks-connector statefulset가 비정상 상태일 수 있습니다. 이 문제를 해결하려면 이 주제의 Amazon EKS 커넥터 포드가 크래시 반복됨 섹션을 참조하세요.

콘솔 오류: 사용자 system:serviceaccount:eks-connector:eks-connector가 클러스터 범위에서 API 그룹의 리소스 사용자를 가장할 수 없습니다.

Amazon EKS 커넥터는 Kubernetes 사용자 가장을 사용하여 AWS Management Console에서 IAM 위탁자를 대신합니다. 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으로 바뀌었는지 확인합니다.

콘솔 오류: [...] 금지됨: 사용자 [...]이(가) 클러스터 범위에서 API 그룹의 [...] 리소스를 나열할 수 없음

다음 문제를 고려하세요. Amazon EKS 커넥터가 대상 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가 Kubernetes 클러스터 API 서버와 통신할 수 없습니다. 연결에 성공하려면 클러스터가 ACTIVE 상태여야 합니다. 몇 분 후에 다시 시도하세요.

Amazon EKS 서비스가 대상 클러스터의 Amazon EKS 커넥터와 통신할 수 없는 경우 다음과 같은 사유 중 하나 때문일 수 있습니다.

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

이 문제를 해결하려면 Amazon EKS 커넥터 로그를 확인하세요. Amazon EKS 커넥터에 대한 오류가 표시되지 않으면 몇 분 후에 연결을 다시 시도하세요. 대상 클러스터에 대해 긴 대기 시간 또는 간헐적인 연결이 정기적으로 발생하는 경우 가까운 AWS 리전에 클러스터를 다시 등록하는 것이 좋습니다.

Amazon EKS 커넥터 포드가 크래시 반복됨

여러 가지 사유로 Amazon EKS 커넥터 포드가 CrashLoopBackOff 상태로 전환될 수 있습니다. 이 문제는 connector-init 컨테이너와 관련이 있을 수 있습니다. Amazon EKS 커넥터 포드의 상태를 확인합니다.


kubectl get pods -n eks-connector

예제 출력은 다음과 같습니다.


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

출력이 이전 출력과 비슷한 경우 Amazon EKS 커넥터 로그 검사의 내용을 참조하여 문제를 해결합니다.

eks-connector 시작 실패: InvalidActivation

Amazon EKS 커넥터를 처음 시작할 때 Amazon Web Services에 activationId 및 activationCode를 등록합니다. 등록에 실패하여 다음과 같은 오류와 비슷한 오류로 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 커넥터를 활성화해야 하기 때문입니다. 이 문제를 해결하려면 만료 날짜 및 시간 전에 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 커넥터에 여러 AWS 엔드포인트에 대한 아웃바운드 연결이 필요합니다. 대상 AWS 리전에 대한 아웃바운드 연결 없이 프라이빗 클러스터를 연결할 수 없습니다. 이 문제를 해결하려면 필요한 아웃바운드 연결을 추가해야 합니다. 커넥터 요구 사항에 대한 자세한 내용은 Amazon EKS Connector 고려 사항 섹션을 참조하세요.

Amazon EKS 커넥터 포드의 상태가 `ImagePullBackOff`임

get pods 명령을 실행하고 포드의 상태가 ImagePullBackOff이면 제대로 작동하지 않습니다. Amazon EKS 커넥터 포드의 상태가 ImagePullBackOff이면 제대로 작동하지 않습니다. Amazon EKS 커넥터 포드의 상태를 확인합니다.


kubectl get pods -n eks-connector

예제 출력은 다음과 같습니다.


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

기본 Amazon EKS 커넥터 매니페스트 파일은 Amazon ECR Public Gallery의 이미지를 참조합니다. 대상 Kubernetes 클러스터가 Amazon ECR 퍼블릭 갤러리에서 이미지를 가져올 수 없는 가능성이 있습니다. Amazon ECR Public Gallery 이미지 풀 문제를 해결하거나 선택한 프라이빗 컨테이너 레지스트리의 이미지 미러링을 고려하세요.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

클러스터 등록 취소

자주 묻는 질문(FAQ)