EKS 캐퍼빌리티 리소스 다루기

EKS 캐퍼빌리티 리소스 다루기

Amazon EKS 클러스터에서 캐퍼빌리티(capability) 리소스를 나열하고, 상세를 확인하고, 업데이트하고, 삭제하는 방법을 설명합니다.

출처: 문서

본문

EKS 캐퍼빌리티 리소스란

EKS 캐퍼빌리티는 Amazon EKS 클러스터에서 관리형 기능을 제공하는 AWS 리소스입니다. 캐퍼빌리티는 EKS에서 실행되므로 워커 노드에 컨트롤러나 기타 운영 구성 요소를 직접 설치하고 유지 관리할 필요가 없습니다.

캐퍼빌리티는 특정 EKS 클러스터를 위해 생성되며, 전체 수명 주기 동안 해당 클러스터에 계속 연결되어 있습니다.

각 캐퍼빌리티 리소스는 다음 속성을 가집니다.

  • 클러스터 내에서 고유한 이름
  • 캐퍼빌리티 유형(ACK, ARGOCD 또는 KRO)
  • 이름과 유형을 모두 지정하는 Amazon 리소스 이름(ARN)
  • 캐퍼빌리티 IAM 역할
  • 현재 상태를 나타내는 상태(status)
  • 캐퍼빌리티 유형에 공통적인 구성과 특정한 구성

캐퍼빌리티 상태 이해하기

캐퍼빌리티 리소스에는 현재 상태를 나타내는 상태 값이 있습니다. 캐퍼빌리티의 상태와 상태(health)는 EKS 콘솔 또는 AWS CLI에서 확인할 수 있습니다.

콘솔:

  1. https://console.aws.amazon.com/eks/home#/clusters 에서 Amazon EKS 콘솔을 엽니다.
  2. 클러스터 이름을 선택합니다.
  3. Capabilities 탭을 선택하면 모든 캐퍼빌리티의 상태를 볼 수 있습니다.
  4. 자세한 상태(health) 정보를 보려면 Observability 탭을 선택하고, Monitor cluster를 선택한 다음, Capabilities 탭을 선택합니다.

AWS CLI:

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

캐퍼빌리티 상태 값

  • CREATING - 캐퍼빌리티가 설정되는 중입니다. 콘솔에서 다른 페이지로 이동해도 캐퍼빌리티는 백그라운드에서 계속 생성됩니다.
  • ACTIVE - 캐퍼빌리티가 실행 중이며 사용할 준비가 되었습니다. 리소스가 예상대로 작동하지 않으면 리소스 상태와 IAM 권한을 확인하세요. 자세한 내용은 EKS 캐퍼빌리티 문제 해결을 참고하세요.
  • UPDATING - 구성 변경이 적용되는 중입니다. 상태가 ACTIVE로 돌아올 때까지 기다리세요.
  • DELETING - 캐퍼빌리티가 클러스터에서 제거되는 중입니다.
  • CREATE_FAILED - 설정 중 오류가 발생했습니다. 일반적인 원인은 다음과 같습니다.
    • IAM 역할 신뢰 정책이 잘못되었거나 없음
    • IAM 역할이 존재하지 않거나 접근할 수 없음
    • 클러스터 접근 문제
    • 잘못된 구성 매개변수
    • 구체적인 오류 내용은 캐퍼빌리티 상태(health) 섹션을 확인하세요.
  • UPDATE_FAILED - 구성 업데이트가 실패했습니다. 자세한 내용은 캐퍼빌리티 상태(health) 섹션을 확인하고 IAM 권한을 검증하세요.

팁

자세한 문제 해결 가이드는 다음을 참고하세요.

  • EKS 캐퍼빌리티 문제 해결 - 일반적인 캐퍼빌리티 문제 해결
  • ACK 캐퍼빌리티 문제 해결 - ACK 관련 문제
  • Argo CD 캐퍼빌리티 문제 해결 - Argo CD 관련 문제
  • kro 캐퍼빌리티 문제 해결 - kro 관련 문제

캐퍼빌리티 생성하기

클러스터에 캐퍼빌리티를 생성하려면 다음 항목을 참고하세요.

  • ACK 캐퍼빌리티 생성 - Kubernetes API를 사용해 AWS 리소스를 관리하는 ACK 캐퍼빌리티 생성
  • Argo CD 캐퍼빌리티 생성 - GitOps 지속적 전달을 위한 Argo CD 캐퍼빌리티 생성
  • kro 캐퍼빌리티 생성 - 리소스 구성과 오케스트레이션을 위한 kro 캐퍼빌리티 생성

캐퍼빌리티 나열하기

클러스터의 모든 캐퍼빌리티 리소스를 나열할 수 있습니다.

콘솔

  1. https://console.aws.amazon.com/eks/home#/clusters 에서 Amazon EKS 콘솔을 엽니다.
  2. 클러스터 이름을 선택해 클러스터 상세 페이지를 엽니다.
  3. Capabilities 탭을 선택합니다.
  4. Managed capabilities 아래에서 캐퍼빌리티 리소스를 확인합니다.

AWS CLI

list-capabilities 명령을 사용해 클러스터의 모든 캐퍼빌리티를 확인합니다. region-code를 클러스터가 있는 AWS 리전으로, my-cluster를 클러스터 이름으로 바꾸세요.

aws eks list-capabilities \
  --region region-code \
  --cluster-name my-cluster


{
    "capabilities": [
        {
            "capabilityName": "my-ack",
            "arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack/abc123",
            "type": "ACK",
            "status": "ACTIVE",
            "createdAt": "2025-11-02T10:30:00.000000-07:00",
            "modifiedAt": "2025-11-02T10:32:15.000000-07:00"
        },
        {
            "capabilityName": "my-kro",
            "arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/kro/my-kro/abc123",
            "type": "KRO",
            "status": "ACTIVE",
            "version": "v0.6.3",
            "createdAt": "2025-11-02T10:30:00.000000-07:00",
            "modifiedAt": "2025-11-02T10:32:15.000000-07:00"
        },
        {
            "capabilityName": "my-argocd",
            "arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/argocd/my-argocd/abc123",
            "type": "ARGOCD",
            "status": "ACTIVE",
            "version": "3.1.8-eks-1",
            "createdAt": "2025-11-21T08:22:28.486000-05:00",
            "modifiedAt": "2025-11-21T08:22:28.486000-05:00"
        }
    ]
}

캐퍼빌리티 상세 보기

특정 캐퍼빌리티의 구성과 상태를 포함한 상세 정보를 확인합니다.

콘솔

  1. https://console.aws.amazon.com/eks/home#/clusters 에서 Amazon EKS 콘솔을 엽니다.
  2. 클러스터 이름을 선택해 클러스터 상세 페이지를 엽니다.
  3. Capabilities 탭을 선택합니다.
  4. Managed capabilities에서 확인할 캐퍼빌리티를 선택합니다.
  5. 상태, 구성, 생성 시간 등 캐퍼빌리티 상세 정보를 확인합니다.

AWS CLI

describe-capability 명령을 사용해 상세 정보를 확인합니다. region-code를 클러스터가 있는 AWS 리전으로, my-cluster를 클러스터 이름으로, capability-name(예: my-ack, my-argocd, my-kro)을 생성할 때 지정한 캐퍼빌리티 이름으로 바꾸세요.

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

예시 출력:

{
  "capability": {
    "capabilityName": "my-ack",
    "capabilityArn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack/abc123",
    "clusterName": "my-cluster",
    "type": "ACK",
    "roleArn": "arn:aws:iam::111122223333:role/AmazonEKSCapabilityACKRole",
    "status": "ACTIVE",
    "configuration": {},
    "tags": {},
    "health": {
      "issues": []
    },
    "createdAt": "2025-11-19T17:11:30.242000-05:00",
    "modifiedAt": "2025-11-19T17:11:30.242000-05:00",
    "deletePropagationPolicy": "RETAIN"
  }
}

캐퍼빌리티 구성 업데이트하기

생성 후 캐퍼빌리티 구성의 특정 항목을 업데이트할 수 있습니다. 업데이트할 수 있는 구성 옵션은 캐퍼빌리티 유형에 따라 다릅니다.

참고

EKS 캐퍼빌리티 리소스는 패치와 버전 업데이트를 포함해 완전히 관리됩니다. 캐퍼빌리티를 업데이트하면 리소스 구성이 업데이트되며, 관리되는 캐퍼빌리티 구성 요소의 버전은 업데이트되지 않습니다.

AWS CLI

update-capability 명령을 사용해 캐퍼빌리티를 수정합니다.

aws eks update-capability \
  --region region-code \
  --cluster-name my-cluster \
  --capability-name capability-name \
  --role-arn arn:aws:iam::111122223333:role/NewCapabilityRole

참고

모든 캐퍼빌리티 속성이 생성 후 업데이트 가능한 것은 아닙니다. 무엇을 수정할 수 있는지에 대한 자세한 내용은 캐퍼빌리티별 문서를 참고하세요.

캐퍼빌리티 삭제하기

클러스터에서 캐퍼빌리티가 더 이상 필요하지 않으면 캐퍼빌리티 리소스를 삭제할 수 있습니다.

중요

캐퍼빌리티를 삭제하기 전에 클러스터 리소스를 먼저 삭제하세요.

캐퍼빌리티 리소스를 삭제한다고 해서 해당 캐퍼빌리티를 통해 생성된 리소스가 자동으로 삭제되지는 않습니다.

  • 모든 Kubernetes 커스텀 리소스 정의(CRD)는 클러스터에 그대로 설치되어 있습니다.
  • ACK 리소스는 클러스터에 남아 있으며, 해당하는 AWS 리소스도 계정에 남아 있습니다.
  • Argo CD Applications와 그 Kubernetes 리소스는 클러스터에 남아 있습니다.
  • kro ResourceGraphDefinitions와 그 인스턴스는 클러스터에 남아 있습니다.

고아(orphan) 리소스가 생기지 않도록 이런 리소스들을 캐퍼빌리티를 삭제하기 전에 삭제하는 것이 좋습니다. ACK Kubernetes 리소스와 연결된 AWS 리소스를 유지하려면 선택적으로 유지할 수도 있습니다. 자세한 내용은 ACK 고려 사항을 참고하세요.

콘솔

  1. https://console.aws.amazon.com/eks/home#/clusters 에서 Amazon EKS 콘솔을 엽니다.
  2. 클러스터 이름을 선택해 클러스터 상세 페이지를 엽니다.
  3. Capabilities 탭을 선택합니다.
  4. Managed capabilities 목록에서 삭제할 캐퍼빌리티를 선택합니다.
  5. Delete capability를 선택합니다.
  6. 확인 대화 상자에서 삭제를 확인하기 위해 캐퍼빌리티 이름을 입력합니다.
  7. Delete를 선택합니다.

AWS CLI

delete-capability 명령을 사용해 캐퍼빌리티 리소스를 삭제합니다. region-code를 클러스터가 있는 AWS 리전으로, my-cluster를 클러스터 이름으로, capability-name을 삭제할 캐퍼빌리티 이름으로 바꾸세요.

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

다음 단계

  • 캐퍼빌리티 Kubernetes 리소스 - 각 캐퍼빌리티 유형이 제공하는 Kubernetes 리소스 알아보기
  • ACK 개념 - ACK 개념과 리소스 수명 주기 이해하기
  • Argo CD 사용하기 - GitOps 워크플로를 위한 Argo CD 캐퍼빌리티 사용하기
  • kro 개념 - kro 개념과 리소스 구성 이해하기

더 알아보기 (Learn more)