EKS 캐퍼빌리티 문제 해결

EKS 캐퍼빌리티에서 발생하는 일반적인 문제를 해결하는 방법을 설명합니다.

출처: 문서

본문

참고

EKS 캐퍼빌리티는 완전 관리형이며 클러스터 밖에서 실행됩니다. 컨트롤러 네임스페이스에 직접 접근할 수 없습니다. 문제 해결은 캐퍼빌리티 상태, 리소스 상태, 구성, 그리고 컨트롤러 로그에 초점을 맞춥니다. 컨트롤러 로그 전달을 구성해 컨트롤러 동작에 대한 가시성을 얻을 수 있습니다. 자세한 내용은 EKS 캐퍼빌리티 컨트롤러 로그 접근을 참고하세요.

일반적인 문제 해결 접근 방식

EKS 캐퍼빌리티 문제를 해결할 때는 다음의 일반적인 접근 방식을 따르세요.

캐퍼빌리티 상태 확인: aws eks describe-capability를 사용해 캐퍼빌리티 상태와 상태 문제를 봅니다.
리소스 상태 확인: 생성한 Kubernetes 리소스(CRD)에서 상태 조건과 이벤트를 확인합니다.
컨트롤러 로그 검토: 로그 전달을 구성했다면 컨트롤러 로그에서 오류와 조정 세부 정보를 조회합니다.
IAM 권한 검토: 캐퍼빌리티 역할이 필요한 권한을 보유했는지 확인합니다.
구성 확인: 캐퍼빌리티별 구성이 올바른지 검증합니다.

컨트롤러 로그를 사용한 문제 해결

컨트롤러 로그 전달을 구성했다면 로그를 조회해 조정 오류, 리소스 충돌, 구성 문제를 식별할 수 있습니다.

모든 컨트롤러에서 오류 조회:

fields @timestamp, controller, message, error
| filter level = "error"
| sort @timestamp desc
| limit 50

특정 ACK 서비스 컨트롤러의 로그 필터링에는 controllerGroup 필드를 사용합니다:

fields @timestamp, message, error
| filter controllerGroup = "s3.services.k8s.aws"
| filter level = "error"
| sort @timestamp desc

리소스 종류로 더 필터링하려면(예: EC2 컨트롤러의 SecurityGroup 로그만):

fields @timestamp, message, error
| filter controllerGroup = "ec2.services.k8s.aws"
| filter controllerKind = "SecurityGroup"
| sort @timestamp desc
| limit 100

특정 Argo CD 애플리케이션 로그 필터링에는 application 필드를 사용합니다:

fields @timestamp, message, error
| filter application = "my-application"
| sort @timestamp desc
| limit 100

특정 리소스의 조정 추적에는 reconcileID 필드를 사용합니다:

fields @timestamp, level, message, error
| filter reconcileID = "your-reconcile-id"
| sort @timestamp asc

문제를 나타내는 일반적인 로그 패턴

반복되는 조정 오류 — 컨트롤러가 리소스의 desired state에 도달하지 못합니다. error 필드에서 IAM 권한 실패나 잘못된 리소스 구성 같은 세부 정보를 확인하세요.
AWS API 오류가 있는 "Reconciler error" — 캐퍼빌리티 역할에 특정 AWS 서비스 작업 권한이 없을 수 있습니다. 오류 메시지를 검토하고 IAM 정책을 업데이트하세요.
리소스에 대한 로그 항목이 없음 — 컨트롤러가 조정할 것으로 예상하는 리소스에 대한 로그가 보이지 않으면 캐퍼빌리티가 ACTIVE 상태이고, 리소스가 캐퍼빌리티가 접근할 수 있는 네임스페이스에 존재하는지 확인하세요.

캐퍼빌리티 상태 확인

모든 EKS 캐퍼빌리티는 EKS 콘솔과 describe-capability API를 통해 상태 정보를 제공합니다.

콘솔:

Amazon EKS 콘솔(https://console.aws.amazon.com/eks/home#/clusters)을 엽니다.
클러스터 이름을 선택합니다.
Observability 탭을 선택합니다.
Monitor cluster를 선택합니다.
Capabilities 탭을 선택해 모든 캐퍼빌리티의 상태를 봅니다.

Capabilities 탭은 캐퍼빌리티 이름과 유형, 현재 상태, 설명이 포함된 상태 문제를 보여줍니다.

AWS CLI:

aws eks describe-capability \
  --region region-code \
  --cluster-name my-cluster \
  --capability-name my-capability-name

응답에는 다음이 포함됩니다.

status: 현재 캐퍼빌리티 상태(CREATING, ACTIVE, UPDATING, DELETING, CREATE_FAILED, UPDATE_FAILED)
health: 캐퍼빌리티가 감지한 문제를 포함한 상태 정보

일반적인 캐퍼빌리티 상태

CREATING: 캐퍼빌리티가 설정 중입니다.
ACTIVE: 캐퍼빌리티가 실행 중이며 사용할 준비가 되었습니다. 리소스가 예상대로 작동하지 않으면 리소스 상태와 IAM 권한을 확인하세요.
UPDATING: 구성 변경이 적용 중입니다. 상태가 ACTIVE로 돌아올 때까지 기다리세요.
CREATE_FAILED 또는 UPDATE_FAILED: 설정 또는 업데이트에서 오류가 발생했습니다. 상태 섹션에서 세부 정보를 확인하세요. 일반적인 원인은 다음과 같습니다.
- IAM 역할 신뢰 정책이 잘못되었거나 없음
- IAM 역할이 존재하지 않거나 접근할 수 없음
- 클러스터 접근 문제
- 잘못된 구성 매개변수

Kubernetes 리소스 상태 확인

EKS 캐퍼빌리티는 클러스터에서 CRD를 생성하고 관리합니다. 문제를 해결하려면 생성한 리소스의 상태를 확인하세요.

# 특정 유형의 리소스 나열
kubectl get resource-kind -A

# 특정 리소스를 설명해 조건과 이벤트 확인
kubectl describe resource-kind resource-name -n namespace

# 리소스 상태 조건 보기
kubectl get resource-kind resource-name -n namespace -o jsonpath='{.status.conditions}'

# 리소스 관련 이벤트 보기
kubectl get events --field-selector involvedObject.name=resource-name -n namespace

리소스 상태 조건은 리소스 준비 여부, 발생한 오류, 현재 조정 상태에 대한 정보를 제공합니다.

IAM 권한과 클러스터 접근 검토

많은 캐퍼빌리티 문제는 IAM 권한 문제나 누락된 클러스터 접근 구성에서 발생합니다. 캐퍼빌리티 역할 권한과 클러스터 접근 항목을 모두 확인하세요.

IAM 역할 권한 확인:

# 연결된 관리형 정책 나열
aws iam list-attached-role-policies --role-name my-capability-role

# 인라인 정책 나열
aws iam list-role-policies --role-name my-capability-role

# 특정 정책 세부 정보 가져오기
aws iam get-role-policy --role-name my-capability-role --policy-name policy-name

# 역할의 신뢰 정책 보기
aws iam get-role --role-name my-capability-role --query 'Role.AssumeRolePolicyDocument'

신뢰 정책은 capabilities.eks.amazonaws.com 서비스 주체를 허용해야 합니다:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "capabilities.eks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

EKS 액세스 항목과 액세스 정책 확인

모든 캐퍼빌리티는 작동하는 클러스터에 올바른 EKS 액세스 항목과 액세스 정책이 필요합니다.

액세스 항목 존재 확인:

aws eks list-access-entries \
  --cluster-name my-cluster \
  --region region-code

목록에서 캐퍼빌리티 역할 ARN을 찾으세요. 없으면 캐퍼빌리티가 클러스터에 접근할 수 없습니다.

액세스 항목에 연결된 액세스 정책 확인:

aws eks list-associated-access-policies \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::111122223333:role/my-capability-role \
  --region region-code

모든 캐퍼빌리티는 적절한 액세스 정책이 필요합니다.

ACK: Kubernetes 리소스를 생성하고 관리할 권한 필요
kro: Kubernetes 리소스를 생성하고 관리할 권한 필요
Argo CD: Application을 생성하고 관리할 권한 필요, 멀티 클러스터 배포를 위해 원격 대상 클러스터에 액세스 항목이 필요

Argo CD 멀티 클러스터 배포의 경우 원격 클러스터에 배포한다면 각 대상 클러스터에 캐퍼빌리티 역할의 액세스 항목이 있는지 확인하세요:

# 대상 클러스터의 액세스 항목 확인
aws eks describe-access-entry \
  --cluster-name target-cluster \
  --principal-arn arn:aws:iam::111122223333:role/argocd-capability-role \
  --region region-code

대상 클러스터에 액세스 항목이 없으면 Argo CD가 해당 클러스터에 애플리케이션을 배포할 수 없습니다. 자세한 내용은 대상 클러스터 등록을 참고하세요.

캐퍼빌리티별 문제 해결

각 캐퍼빌리티 유형에 대한 자세한 문제 해결 안내:

ACK 캐퍼빌리티 문제 해결 — ACK 리소스 생성, IAM 권한, 교차 계정 접근 문제 해결
Argo CD 캐퍼빌리티 문제 해결 — 애플리케이션 동기화, 리포지토리 인증, 멀티 클러스터 배포 문제 해결
kro 캐퍼빌리티 문제 해결 — ResourceGraphDefinitions, CEL expressions, RBAC 권한 문제 해결

모든 캐퍼빌리티의 일반적인 문제

CREATING 상태에 머무르는 캐퍼빌리티

캐퍼빌리티가 예상보다 오래 CREATING 상태로 남아 있다면:

콘솔(Observability > Monitor cluster > Capabilities 탭) 또는 AWS CLI로 캐퍼빌리티 상태에서 특정 문제를 확인합니다:

aws eks describe-capability \
  --region region-code \
  --cluster-name my-cluster \
  --capability-name my-capability-name \
  --query 'capability.health'

IAM 역할이 존재하고 올바른 신뢰 정책을 보유했는지 확인합니다.
클러스터가 접근 가능하고 정상인지 확인합니다.
캐퍼빌리티 설정을 막을 수 있는 클러스터 수준 문제가 있는지 확인합니다.

리소스가 생성되거나 업데이트되지 않는 문제

캐퍼빌리티가 ACTIVE인데도 리소스가 생성되거나 업데이트되지 않는다면:

리소스 상태에서 오류 조건을 확인합니다.
특정 AWS 서비스(ACK)나 리포지토리(Argo CD)에 대한 IAM 권한을 확인합니다.
기본 리소스 생성에 대한 RBAC 권한을 확인합니다(kro).
검증 오류가 있는지 리소스 사양을 검토합니다.

캐퍼빌리티 상태에 문제가 표시되는 경우

describe-capability로 상태 문제가 표시된다면:

문제 설명을 주의 깊게 읽으세요. 종종 구체적인 문제를 나타냅니다.
근본 원인(IAM 권한, 구성 오류 등)을 해결합니다.
문제가 해결되면 캐퍼빌리티는 자동으로 복구됩니다.

더 알아보기 (Learn more)

공식 문서