**이 페이지 개선에 도움 주기**
이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **GitHub에서 이 페이지 편집** 링크를 선택합니다.
# 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 커넥터 포드가 크래시 반복됨](#symp-loop) 섹션을 참조하세요.
## 콘솔 오류: 사용자 system:serviceaccount:eks-connector:eks-connector가 클러스터 범위에서 API 그룹의 리소스 사용자를 가장할 수 없습니다.
Amazon EKS 커넥터는 Kubernetes [사용자 가장](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation)을 사용하여 AWS Management Console에서 [IAM 위탁자](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#iam-term-principal)를 대신합니다. AWS `eks-connector` 서비스 계정에서 Kubernetes API에 액세스하는 각 위탁자에 IAM ARN을 Kubernetes 사용자 이름으로 사용하여 해당 Kubernetes 사용자를 가장할 수 있는 권한이 부여되어야 합니다. 다음 예에서 IAM ARN은 Kubernetes 사용자에게 매핑됩니다.
+ AWS 계정 *111122223333*의 IAM 사용자 *john*은 Kubernetes 사용자에게 매핑됩니다. [IAM 모범 사례](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)에서는 되도록 사용자 대신 역할에 권한을 부여하세요.
```
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 클러스터 리소스를 볼 수 있는 액세스 권한 부여](connector-grant-access.md) 섹션을 참조하세요. 템플릿에서 `%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 클러스터 리소스를 볼 수 있는 액세스 권한 부여](connector-grant-access.md) 섹션을 참조하세요.
## 콘솔 오류: Amazon EKS가 Kubernetes 클러스터 API 서버와 통신할 수 없습니다. 연결에 성공하려면 클러스터가 ACTIVE 상태여야 합니다. 몇 분 후에 다시 시도하세요.
Amazon EKS 서비스가 대상 클러스터의 Amazon EKS 커넥터와 통신할 수 없는 경우 다음과 같은 사유 중 하나 때문일 수 있습니다.
+ 대상 클러스터의 Amazon EKS 커넥터가 비정상입니다.
+ 대상 클러스터와 AWS 리전 간의 연결 상태가 좋지 않거나 연결이 중단되었습니다.
이 문제를 해결하려면 [Amazon EKS 커넥터 로그](#tsc-logs)를 확인하세요. 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 커넥터 로그 검사](#tsc-logs)의 내용을 참조하여 문제를 해결합니다.
## 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단계: 클러스터 등록](connecting-cluster.md#connector-connecting) 섹션을 참조하세요.
+ 정품 인증이 만료되어 등록에 실패했을 수 있습니다. 보안상의 이유로 클러스터를 등록한 후 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 고려 사항](eks-connector.md#connect-cluster-reqts) 섹션을 참조하세요.
## 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](https://gallery.ecr.aws/)의 이미지를 참조합니다. 대상 Kubernetes 클러스터가 Amazon ECR 퍼블릭 갤러리에서 이미지를 가져올 수 없는 가능성이 있습니다. Amazon ECR Public Gallery 이미지 풀 문제를 해결하거나 선택한 프라이빗 컨테이너 레지스트리의 이미지 미러링을 고려하세요.