EKS Auto Mode 클러스터 롤백하기

EKS Auto Mode를 실행하는 클러스터에서 버전 롤백을 시작하면 Amazon EKS가 제어 플레인을 되돌리기 전에 Auto Mode 워커 노드의 롤백을 자동으로 관리하는 방법을 알아봐요. 노드 롤백이 어떻게 동작하는지, 속도를 높이는 방법, 필요시 취소하는 방법을 설명해요.

출처: 문서

본문

일반적인 버전 롤백 정보(사전 조건, 인사이트 검사, 전체 롤백 과정 포함)는 Roll back a cluster to a previous Kubernetes version을 참고해 주세요.

Auto Mode 롤백이 어떻게 동작하는지 (How Auto Mode rollback works)

EKS Auto Mode는 Karpenter 기반 시스템을 사용해 워커 노드 인프라(Kubernetes 버전 업그레이드와 롤백 포함)를 관리해요. Auto Mode가 활성화된 클러스터에서 UpdateClusterVersion을 이전(N-1) 버전으로 호출하면 EKS는 다음 순서를 수행해요:

사전 조건을 검증하고 롤백 준비 인사이트를 갱신합니다.
구성된 중단 제어를 존중하며 Karpenter 기반 시스템으로 노드를 원하는 롤백 버전으로 드리프트시킵니다.
모든 노드가 원하는 롤백 버전의 Kubernetes 버전 스큐 정책 안에 들어오면 EKS가 인사이트를 다시 확인하고 제어 플레인 롤백을 진행합니다.

노드가 롤백되는 동안 제어 플레인은 현재(더 새) 버전에 머물며 정상적으로 트래픽을 계속 서빙해요. Kubernetes 버전 스큐 정책은 노드가 kube-apiserver보다 최대 세 마이너 버전 더 오래될 수 있도록 허용하므로 이 중간 상태는 유효해요.

참고: 롤백은 Roll back a cluster to a previous Kubernetes version에 설명된 것과 같은 API와 과정으로 트리거해요. Auto Mode 노드 롤백을 위한 별도 API는 없어요.

참고: 노드 롤백 단계(2단계)는 중단 제어에 따라 몇 분에서 7일까지 걸릴 수 있어요. 노드 롤백이 구성된 타임아웃 내에 완료되지 않으면 업데이트가 실패로 표시돼요.

참고: 롤백이 진행 중인 동안 다른 고객 트리거 제어 플레인 업데이트는 차단돼요. 다른 업데이트를 수행하려면 먼저 CancelUpdate API로 롤백을 취소해 주세요.

롤백 중 클러스터 상태 (Cluster status during rollback)

단계	클러스터 상태	무슨 일이 일어나나
노드 롤백 진행 중	ACTIVE	Karpenter가 이전 버전 AMI의 노드로 교체 중. 제어 플레인은 현재 버전에서 정상이고 트래픽 서빙 중.
제어 플레인 롤백	UPDATING	API 서버와 제어 플레인 컴포넌트가 이전 버전으로 되돌아가는 중.
롤백 완료	ACTIVE	클러스터가 완전히 이전 버전에 있음.

노드 롤백 단계 동안 클러스터 상태는 ACTIVE로 유지돼요. 롤백이 진행 중인지 확인하려면 ListUpdates 또는 DescribeUpdate를 사용하세요. Amazon EKS 콘솔에서 클러스터로 이동해 Update history 탭을 열어 롤백과 연결된 업데이트 ID의 상태를 확인할 수 있어요.

롤백 중 개별 노드 진행 상황을 추적하려면 Auto Mode 노드의 Kubernetes 버전을 확인하세요:

kubectl get nodes -l karpenter.sh/nodepool=<pool-name> -o wide

중단 제어 (Disruption controls)

Auto Mode 롤백은 모든 기존 중단 제어를 존중해요. 이 제어는 노드가 교체되는 속도를 결정하며 롤백 기간에 크게 영향을 줄 수 있어요.

NodePool 중단 예산 (NodePool Disruption Budgets)

NodePool 중단 예산은 동시에 중단할 수 있는 노드 수를 제어해요. 롤백 중 Karpenter는 노드를 이전 버전으로 드리프트시킬 때 이 예산을 존중해요.

드리프트에 대한 nodes: 0 예산은 롤백을 무기한 차단해요. 이는 ERROR 인사이트를 트리거해요.
제한적인 예산(예: nodes: 1)은 롤백을 느리게 하지만 진행은 허용해요.

한 번에 노드의 10%를 교체할 수 있게 하는 중단 예산이 있는 NodePool 예시:

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  disruption:
    budgets:
      - nodes: "10%"
        reasons:
          - Drifted

NodePool 중단 예산 구성에 대한 자세한 내용은 Create a Node Pool for EKS Auto Mode와 Karpenter 중단 예산 문서를 참고해 주세요.

PodDisruptionBudgets

노드 교체 중 Kubernetes PodDisruptionBudgets가 존중돼요. PDB가 파드 축출을 방지하면 노드 중단은 TerminationGracePeriod까지 지연돼요.

maxUnavailable: 0인 PDB는 노드 중단을 지연시켜요. 이는 WARNING 인사이트를 트리거해요.
PDB는 롤백을 영구적으로 차단하지 않지만 크게 느리게 할 수 있어요.

자세한 내용은 Protect critical workloads with a PDB와 Kubernetes PDB 문서를 참고해 주세요.

do-not-disrupt 어노테이션

karpenter.sh/do-not-disrupt 어노테이션은 노드나 파드에 설정할 수 있어요:

노드에: 노드 중단을 무기한 차단해요. 이는 ERROR 인사이트를 트리거하며 해당 노드에서 롤백이 진행되기 전에 제거해야 해요.
파드에: 노드 중단을 TerminationGracePeriod까지 지연시켜요. 이는 WARNING 인사이트를 트리거하지만 롤백을 영구적으로 차단하지는 않아요.

Karpenter 중단 동작에 대한 자세한 내용은 Karpenter 중단 문서를 참고해 주세요.

롤백 속도 높이기 (Speeding up rollback)

롤백이 예상보다 오래 걸린다면 롤백이 진행되는 동안 중단 제어를 조정할 수 있어요.

NodePool 중단 예산 늘리기

NodePool 리소스를 편집해 더 많은 동시 노드 교체를 허용하세요:

kubectl edit nodepool default

예산을 더 높은 값으로 변경하세요:

spec:
  disruption:
    budgets:
      - nodes: "50%"
        reasons:
          - Drifted

노드에서 do-not-disrupt 어노테이션 제거하기

어노테이션이 있는 노드를 나열하고 제거하세요:

# List nodes with the annotation
kubectl get nodes -o json | jq '.items[] | select(.metadata.annotations["karpenter.sh/do-not-disrupt"] == "true") | .metadata.name'

# Remove from a specific node
kubectl annotate node <node-name> karpenter.sh/do-not-disrupt-

PodDisruptionBudgets 조정하기

PDB가 파드 축출을 늦추는 경우 임시로 조정하세요:

kubectl edit pdb <pdb-name> -n <namespace>

경고: 중단 제어를 조정하면 애플리케이션 가용성 보장에 영향을 줘요. 프로덕션에서 변경하기 전에 영향을 이해했는지 확인해 주세요.

중단 제어 관리에 대한 자세한 내용은 Preventing pod and node disruption in Amazon EKS Auto Mode를 참고해 주세요.

롤백 취소하기 (Canceling a rollback)

롤백은 노드가 롤백되는 동안에만 취소 가능한 상태예요. 이 단계에서 CancelUpdate를 사용해 작업을 중지할 수 있어요.

aws eks cancel-update \
  --name my-cluster \
  --update-id <update-id> \
  --region us-west-2

취소 동작 (Cancel behavior)

측면	동작
취소 가능 시점	Auto Mode 노드가 롤백되는 동안만 (제어 플레인 롤백 시작 전)
의미	Best-effort 중지. 노드 롤백 작업을 중지.
중단 중간의 노드	취소 시점에 중단 중인 노드는 현재 작업을 완료.
취소 후 상태	업데이트가 `Cancelling`에서 `Cancelled`로 전환.
클러스터 상태	전체 과정에서 `ACTIVE` 유지.
취소 후	취소 성공 시 노드가 평소처럼 현재 클러스터 버전으로 드리프트. 업데이트가 `Cancelling`에서 `Cancelled`로 전환.

취소 후 즉시 다음을 할 수 있어요:

롤백 재시도 (7일 자격 창 내에 있다면).
다른 클러스터 업데이트 수행.
클러스터를 현재 버전 그대로 둠.

취소가 불가능한 경우

노드 롤백이 이미 완료되고 제어 플레인 롤백이 시작됐거나, 업데이트가 이미 Successful 또는 Failed 상태로 완료된 경우 취소는 실패해요.

참고: CloudFormation과 Terraform은 CancelUpdate API를 직접 지원하지 않아요. IaC로 시작한 롤백을 취소해야 한다면 API를 직접 호출해야 해요.

롤백 타임아웃 (Rollback timeout)

Auto Mode 노드 롤백에는 rollbackConfig의 timeoutMinutes 파라미터로 제어되는 구성 가능한 타임아웃이 있어요. 기본 타임아웃은 720분(12시간)이에요. 120분(2시간)에서 10080분(7일) 사이의 값을 설정할 수 있어요. 타임아웃은 최소 경계 속성으로, 지정한 시간보다 일찍 발생하지 않지만 그 직후에 발생할 수 있어요.

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --rollback-config timeoutMinutes=1440 \
  --region us-west-2

모든 노드가 지정된 타임아웃 내에 롤백을 완료하지 않으면:

롤백이 타임아웃됩니다.
노드가 현재 클러스터 버전으로 다시 드리프트하기 시작합니다.
제어 플레인은 현재 버전에 남습니다 (롤백된 적이 없음).
업데이트 상태가 Failed로 전환됩니다.

타임아웃 후 원래 업그레이드로부터 7일 롤백 자격 창 내에 있다면 롤백을 재시도할 수 있어요. 실제로는 노드 롤백이 7일째에 타임아웃되면 둘 다 7일이므로 롤백 자격 창도 만료됐을 가능성이 높아요.

타임아웃을 피하려면 롤백을 시작하기 전에 롤백 준비 인사이트를 검토해 주세요. 이 인사이트는 노드 롤백 과정을 늦출 수 있는 중단 예산이나 어노테이션에 대해 경고해요.

`--force` 플래그와 Auto Mode (The --force flag and Auto Mode)

UpdateClusterVersion의 --force 플래그는 클러스터 인사이트 검사만 우회해요. Auto Mode 노드 중단 동작에는 효과가 없어요.

--force를 사용해도:

NodePool 중단 예산은 여전히 존중됩니다.
PodDisruptionBudgets는 여전히 존중됩니다.
do-not-disrupt 어노테이션은 여전히 존중됩니다.
7일 노드 롤백 타임아웃은 여전히 적용됩니다.

노드 롤백을 빠르게 하는 유일한 방법은 중단 제어 자체를 조정하는 거예요. 자세한 내용은 Speeding up rollback을 참고해 주세요.

IaC 타임아웃 충돌 (IaC timeout conflicts)

Infrastructure-as-Code 도구에는 Auto Mode 롤백 기간과 충돌할 수 있는 타임아웃 제한이 있어요. CloudFormation은 리소스당 최대 36시간을 허용해요. 작업이 타임아웃되면 CloudFormation은 이를 no-op으로 취급해 템플릿이 실제 클러스터 버전을 반영하지 않는 드리프트된 상태로 클러스터를 남길 수 있어요. 버전 롤백은 명시적으로 시작해야 해요. Terraform Enterprise/Cloud는 약 24시간 타임아웃이 있지만, 클라이언트 측 타임아웃은 자격 증명 만료와 다른 요인에 따라 달라질 수 있어요.

롤백 기간을 IaC 도구와 맞추려면 rollbackConfig의 timeoutMinutes 파라미터로 적절한 타임아웃을 설정해 주세요. IaC 도구가 타임아웃되면 CancelUpdate API를 직접 사용해 제어를 회복하세요. 제한적인 중단 예산이 있다면 IaC 대신 CLI나 API로 롤백을 직접 시작하는 것을 고려해 주세요.

노드 롤백 중 시스템 업데이트 (System updates during node rollback)

Auto Mode 노드가 롤백되는 동안 EKS는 제어 플레인을 계속 안전하고 이용 가능하게 유지해요.

노드 롤백이 진행되는 동안 고객 트리거 업데이트(예: UpdateClusterVersion 또는 UpdateClusterConfig)는 차단돼요. 우선순위가 높은 업데이트를 수행해야 한다면 먼저 CancelUpdate로 롤백을 취소하고, 업데이트를 수행한 다음, 자격 창 내에 있다면 롤백을 다시 시작하세요.

Roll back a cluster to a previous Kubernetes version
EKS Auto Mode overview
Create a Node Pool for EKS Auto Mode
Update the Kubernetes Version of an EKS Auto Mode cluster
Preventing pod and node disruption in Amazon EKS Auto Mode
Troubleshoot EKS Auto Mode
Karpenter 중단 문서
Kubernetes PodDisruptionBudgets

더 알아보기 (Learn more)

공식 문서

EKS Auto Mode 클러스터 롤백하기