ACK 개념

ACK가 Kubernetes API를 통해 AWS 리소스를 관리하는 기본 개념을 설명합니다.

출처: 문서

본문

ACK는 매니페스트의 원하는 상태와 AWS의 실제 상태를 지속적으로 조정(reconcile)해 Kubernetes API를 통해 AWS 리소스를 관리합니다. Kubernetes 커스텀 리소스를 생성하거나 업데이트하면 ACK가 해당하는 AWS 리소스를 만들거나 수정하는 데 필요한 AWS API 호출을 수행하고, 이후 드리프트를 모니터링하며 Kubernetes 상태(status)를 현재 상태에 맞게 업데이트합니다. 이 접근 방식을 사용하면 익숙한 Kubernetes 도구와 워크플로로 인프라를 관리하면서 클러스터와 AWS 간의 일관성을 유지할 수 있습니다.

ACK 시작하기

ACK 캐퍼빌리티를 만든 후(ACK 캐퍼빌리티 생성 참고), 클러스터에서 Kubernetes 매니페스트를 사용해 AWS 리소스 관리를 시작할 수 있습니다.

예를 들어, 고유한 버킷 이름을 선택해 bucket.yaml에 이 S3 버킷 매니페스트를 생성합니다.

apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: my-test-bucket
  namespace: default
spec:
  name: my-unique-bucket-name-12345

매니페스트를 적용합니다.

kubectl apply -f bucket.yaml

상태를 확인합니다.

kubectl get bucket my-test-bucket
kubectl describe bucket my-test-bucket

AWS에서 버킷이 생성되었는지 확인합니다.

aws s3 ls | grep my-unique-bucket-name-12345

Kubernetes 리소스를 삭제합니다.

kubectl delete bucket my-test-bucket

AWS에서 버킷이 삭제되었는지 확인합니다.

aws s3 ls | grep my-unique-bucket-name-12345

버킷이 목록에 더 이상 나타나지 않아야 하며, 이는 ACK가 AWS 리소스의 전체 수명 주기를 관리함을 보여줍니다. ACK 시작에 대한 자세한 내용은 ACK 웹사이트의 Getting Started with ACK를 참고하세요.

리소스 수명 주기와 리컨실리에이션

ACK는 지속적인 리컨실리에이션 루프를 사용해 AWS 리소스가 Kubernetes 매니페스트에 정의된 원하는 상태와 일치하도록 보장합니다.

리컨실리에이션 작동 방식:

Kubernetes 커스텀 리소스(예: S3 Bucket)를 생성하거나 업데이트합니다.
ACK가 변경을 감지하고 원하는 상태와 AWS의 실제 상태를 비교합니다.
차이가 있으면 ACK가 AWS API 호출로 그 차이를 조정합니다.
ACK가 현재 상태를 반영하도록 Kubernetes의 리소스 상태를 업데이트합니다.
루프가 보통 몇 시간마다 지속적으로 반복됩니다.

리컨실리에이션은 새 Kubernetes 리소스를 생성할 때, 기존 리소스의 spec을 업데이트할 때, 또는 ACK 외부에서 이루어진 수동 변경으로 AWS 드리프트를 감지할 때 트리거됩니다. 또한 ACK는 10시간의 재동기화(resync) 주기로 주기적인 리컨실리에이션을 수행합니다. Kubernetes 리소스의 변경은 즉시 리컨실리에이션을 트리거하는 반면, 업스트림 AWS 리소스 변경의 수동적 드리프트 감지는 주기적 재동기화 동안 일어납니다.

위의 시작하기 예시를 진행할 때 ACK는 다음 단계를 수행합니다.

AWS에 버킷이 존재하는지 확인합니다.
없으면 s3:CreateBucket을 호출합니다.
버킷 ARN과 상태로 Kubernetes 상태를 업데이트합니다.
드리프트 모니터링을 계속합니다.

ACK 작동 방식에 대한 자세한 내용은 ACK 웹사이트의 ACK Reconciliation을 참고하세요.

상태 조건(status conditions)

ACK 리소스는 상태 조건을 사용해 자신의 상태를 알립니다. 이 조건을 이해하면 문제를 해결하고 리소스 상태(health)를 파악하는 데 도움이 됩니다.

Ready - 리소스를 사용할 준비가 되었음을 나타냅니다(표준화된 Kubernetes 조건).
ACK.ResourceSynced - 리소스 스펙이 AWS 리소스 상태와 일치함을 나타냅니다.
ACK.Terminal - 복구할 수 없는 오류가 발생했음을 나타냅니다.
ACK.Adopted - 리소스가 새로 생성된 것이 아니라 기존 AWS 리소스에서 어답션되었음을 나타냅니다.
ACK.Recoverable - 스펙을 업데이트하지 않아도 해결될 수 있는 복구 가능한 오류를 나타냅니다.
ACK.Advisory - 리소스에 대한 조언 정보를 제공합니다.
ACK.LateInitialized - 필드의 늦은 초기화가 완료되었는지 여부를 나타냅니다.
ACK.ReferencesResolved - 모든 AWSResourceReference 필드가 해결되었는지 여부를 나타냅니다.
ACK.IAMRoleSelected - 이 리소스를 관리하기 위해 IAMRoleSelector가 선택되었는지 여부를 나타냅니다.

리소스 상태를 확인합니다.

# Check if resource is ready
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'

# Check for terminal errors
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="ACK.Terminal")]}'

상태 예시:

status:
  conditions:
  - type: Ready
    status: "True"
    lastTransitionTime: "2024-01-15T10:30:00Z"
  - type: ACK.ResourceSynced
    status: "True"
    lastTransitionTime: "2024-01-15T10:30:00Z"
  - type: ACK.Terminal
    status: "False"
  ackResourceMetadata:
    arn: arn:aws:s3:::my-unique-bucket-name
    ownerAccountID: "111122223333"
    region: us-west-2

ACK 상태와 조건에 대한 자세한 내용은 ACK 웹사이트의 ACK Conditions를 참고하세요.

삭제 정책(deletion policy)

ACK의 삭제 정책은 Kubernetes 리소스를 삭제할 때 AWS 리소스에 일어나는 일을 제어합니다.

Delete(기본값)

Kubernetes 리소스를 삭제하면 AWS 리소스도 삭제됩니다. 이것이 기본 동작입니다.

# No annotation needed - this is the default
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: temp-bucket
spec:
  name: temporary-bucket

이 리소스를 삭제하면 AWS의 S3 버킷도 삭제됩니다.

Retain

Kubernetes 리소스를 삭제해도 AWS 리소스는 유지됩니다.

apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: important-bucket
  annotations:
    services.k8s.aws/deletion-policy: "retain"
spec:
  name: production-data-bucket

이 리소스를 삭제하면 Kubernetes에서는 제거되지만 AWS의 S3 버킷은 남아 있습니다.

retain 정책은 Kubernetes 리소스보다 더 오래 유지해야 하는 프로덕션 데이터베이스, 여러 애플리케이션이 사용하는 공유 리소스, 실수로 삭제되면 안 되는 중요한 데이터가 있는 리소스, 또는 리소스를 어답션해 구성한 후 수동 관리로 되돌리는 임시 ACK 관리에 유용합니다. ACK 삭제 정책에 대한 자세한 내용은 ACK 웹사이트의 ACK Deletion Policy를 참고하세요.

리소스 어답션(resource adoption)

어답션을 사용하면 기존 AWS 리소스를 다시 만들지 않고 ACK 관리 하에 가져올 수 있습니다.

어답션을 사용할 때:

기존 인프라를 ACK 관리로 마이그레이션
Kubernetes에서 리소스를 실수로 삭제한 경우 고아가 된 AWS 리소스 복구
다른 도구(CloudFormation, Terraform)가 만든 리소스 가져오기

어답션 작동 방식:

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가 AWS에 해당 이름의 버킷이 존재하는지 확인합니다.
발견되면 ACK가 어답션합니다(생성 API 호출 없음).
ACK가 AWS에서 현재 구성을 읽습니다.
ACK가 실제 상태를 반영하도록 Kubernetes 상태를 업데이트합니다.
이후 업데이트는 리소스를 정상적으로 조정합니다.

일단 어답션되면 리소스는 다른 ACK 리소스처럼 관리되며, retain 삭제 정책을 사용하지 않는 한 Kubernetes 리소스를 삭제하면 AWS 리소스도 삭제됩니다. 리소스를 어답션할 때는 AWS 리소스가 이미 존재해야 하며 ACK가 이를 발견할 수 있는 읽기 권한이 필요합니다. adopt-or-create 정책은 리소스가 존재하면 어답션하고, 존재하지 않으면 생성합니다. 이는 리소스 존재 여부와 관계없이 동작하는 선언적 워크플로를 원할 때 유용합니다. ACK 리소스 어답션에 대한 자세한 내용은 ACK 웹사이트의 ACK Resource Adoption을 참고하세요.

교차 계정 및 교차 리전 리소스

ACK는 단일 클러스터에서 서로 다른 AWS 계정과 리전의 리소스를 관리할 수 있습니다.

교차 리전 리소스 어노테이션

어노테이션을 사용해 AWS 리소스의 리전을 지정할 수 있습니다.

apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: eu-bucket
  annotations:
    services.k8s.aws/region: eu-west-1
spec:
  name: my-eu-bucket

특정 네임스페이스에서 생성되는 모든 AWS 리소스의 리전도 지정할 수 있습니다.

네임스페이스 어노테이션

네임스페이스의 모든 리소스에 기본 리전을 설정합니다.

apiVersion: v1
kind: Namespace
metadata:
  name: production
  annotations:
    services.k8s.aws/default-region: us-west-2

이 네임스페이스에서 생성된 리소스는 리소스 수준 어노테이션으로 덮어쓰지 않는 한 이 리전을 사용합니다.

교차 계정

IAM Role Selector를 사용해 특정 IAM 역할을 네임스페이스에 매핑합니다.

apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
  name: target-account-config
spec:
  arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
  namespaceSelector:
    names:
      - production

매핑된 네임스페이스에서 생성된 리소스는 자동으로 지정된 역할을 사용합니다. IAM Role Selector에 대한 자세한 내용은 ACK Cross-Account Resource Management를 참고하세요. 교차 계정 구성에 대한 자세한 내용은 ACK 권한 구성을 참고하세요.

오류 처리와 재시도 동작

ACK는 일시적 오류를 자동으로 처리하고 실패한 작업을 재시도합니다.

재시도 전략:

일시적 오류(속도 제한, 일시적 서비스 문제, 권한 부족)는 자동 재시도를 트리거합니다.
지수 백오프(exponential backoff)로 AWS API에 과부하가 걸리는 것을 방지합니다.
최대 재시도 횟수는 오류 유형에 따라 다릅니다.
영구 오류(잘못된 매개변수, 리소스 이름 충돌)는 재시도하지 않습니다.

kubectl describe로 리소스 상태에서 오류 세부 정보를 확인합니다.

kubectl describe bucket my-bucket

오류 메시지가 있는 상태 조건, 최근 리컨실리에이션 시도를 보여주는 이벤트, 실패를 설명하는 상태 조건의 message 필드를 찾아보세요. 일반적인 오류로는 IAM 권한 부족, AWS의 리소스 이름 충돌, spec의 잘못된 구성 값, AWS 서비스 할당량 초과가 있습니다. 일반적인 오류 문제 해결은 ACK 캐퍼빌리티 문제 해결을 참고하세요.

kro로 리소스 구성하기

여러 ACK 리소스를 구성하고 연결하려면 kro(Kube Resource Orchestrator)용 EKS 캐퍼빌리티를 사용하세요. kro는 리소스 그룹을 정의하는 선언적 방식을 제공해 리소스 간에 구성을 전달하며 복잡한 인프라 패턴을 간단히 관리할 수 있습니다. ACK 리소스로 커스텀 리소스 구성을 만드는 자세한 예시는 kro 개념을 참고하세요.

다음 단계

EKS용 ACK 고려 사항 - EKS별 패턴과 통합 전략

더 알아보기 (Learn more)

공식 문서