ACK 캐퍼빌리티 문제 해결

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

출처: 문서

본문

참고

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

캐퍼빌리티는 ACTIVE인데 리소스가 생성되지 않음

ACK 캐퍼빌리티가 ACTIVE 상태인데도 AWS에 리소스가 생성되지 않으면 캐퍼빌리티 상태(health), 리소스 상태, IAM 권한을 확인하세요.

캐퍼빌리티 상태(health) 확인:

캐퍼빌리티 상태(health)와 상태 문제는 EKS 콘솔 또는 AWS CLI에서 볼 수 있습니다.

콘솔:

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

AWS CLI:

# View capability status and health
aws eks describe-capability \
  --region region-code \
  --cluster-name my-cluster \
  --capability-name my-ack

# Look for issues in the health section

일반적인 원인:

IAM 권한 누락 - 캐퍼빌리티 역할에 해당 AWS 서비스 권한이 없음
잘못된 네임스페이스 - 적절한 IAMRoleSelector 없이 네임스페이스에서 리소스를 생성함
잘못된 리소스 스펙 - 검증 오류가 있는지 리소스 상태 조건 확인
API 스로틀링 - AWS API 속도 제한에 도달함
어드미션 웹훅 - 어드미션 웹훅이 컨트롤러의 리소스 상태 패치를 차단함

리소스 상태 확인:

# Describe the resource to see conditions and events
kubectl describe bucket my-bucket -n default

# Look for status conditions
kubectl get bucket my-bucket -n default -o jsonpath='{.status.conditions}'

# View resource events
kubectl get events --field-selector involvedObject.name=my-bucket -n default

IAM 권한 확인:

# View the Capability Role's policies
aws iam list-attached-role-policies --role-name my-ack-capability-role
aws iam list-role-policies --role-name my-ack-capability-role

# Get specific policy details
aws iam get-role-policy --role-name my-ack-capability-role --policy-name policy-name

AWS에는 리소스가 생성됐는데 Kubernetes에 안 보임

ACK는 Kubernetes 매니페스트를 통해 자체가 생성하는 리소스만 추적합니다. 기존 AWS 리소스를 ACK로 관리하려면 어답션 기능을 사용하세요.

apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: existing-bucket
  annotations:
    services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
  name: my-existing-bucket-name

리소스 어답션에 대한 자세한 내용은 ACK 개념을 참고하세요.

교차 계정 리소스 생성 안 됨

IAM Role Selector를 사용할 때 대상 AWS 계정에서 리소스가 생성되지 않으면 신뢰 관계와 IAMRoleSelector 구성을 확인하세요.

신뢰 관계 확인:

# Check the trust policy in the target account role
aws iam get-role --role-name cross-account-ack-role --query 'Role.AssumeRolePolicyDocument'

신뢰 정책이 소스 계정의 캐퍼빌리티 역할이 이를 가정하도록 허용해야 합니다.

IAMRoleSelector 구성 확인:

# List IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector

# Describe specific selector
kubectl describe iamroleselector my-selector

네임스페이스 정렬 확인:

IAMRoleSelector는 클러스터 범위 리소스이지만 특정 네임스페이스를 대상으로 합니다. ACK 리소스가 IAMRoleSelector의 네임스페이스 셀렉터와 일치하는 네임스페이스에 있는지 확인하세요.

# Check resource namespace
kubectl get bucket my-cross-account-bucket -n production

# List all IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector

# Check which namespace the selector targets
kubectl get iamroleselector my-selector -o jsonpath='{.spec.namespaceSelector}'

IAMRoleSelected 조건 확인:

ACK.IAMRoleSelected 조건을 확인해 IAMRoleSelector가 리소스와 성공적으로 일치했는지 검증합니다.

# Check if IAMRoleSelector was matched
kubectl get bucket my-cross-account-bucket -n production -o jsonpath='{.status.conditions[?(@.type=="ACK.IAMRoleSelected")]}'

조건이 False이거나 없으면 IAMRoleSelector의 네임스페이스 셀렉터가 리소스의 네임스페이스와 일치하지 않는 것입니다. 셀렉터의 namespaceSelector가 리소스의 네임스페이스 라벨과 일치하는지 확인하세요.

캐퍼빌리티 역할 권한 확인:

캐퍼빌리티 역할에 대상 계정 역할에 대한 sts:AssumeRole과 sts:TagSession 권한이 필요합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sts:AssumeRole", "sts:TagSession"],
      "Resource": "arn:aws:iam::444455556666:role/cross-account-ack-role"
    }
  ]
}

자세한 교차 계정 구성은 ACK 권한 구성을 참고하세요.

다음 단계

EKS용 ACK 고려 사항 - ACK 고려 사항과 모범 사례
ACK 권한 구성 - IAM 권한과 멀티 계정 패턴 구성
ACK 개념 - ACK 개념과 리소스 수명 주기 이해하기
EKS 캐퍼빌리티 문제 해결 - 일반적인 캐퍼빌리티 문제 해결 안내

더 알아보기 (Learn more)

공식 문서