이 페이지 개선에 도움 주기

이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 GitHub에서 이 페이지 편집 링크를 선택합니다.

클러스터를 이전 Kubernetes 버전으로 롤백

Amazon EKS 버전 롤백을 사용하면 현재 위치 업그레이드를 수행한 후 클러스터의 Kubernetes 컨트롤 플레인을 이전 마이너 버전으로 되돌릴 수 있습니다. 업그레이드 후 애플리케이션 비호환성, 더 이상 사용되지 않는 API 사용, 예상치 못한 동작과 같은 문제가 발생하는 경우 롤백하여 클러스터를 알려진 정상 상태로 복원할 수 있습니다.

롤백 중에 Amazon EKS는 모든 etcd 데이터, 고객 워크로드, 영구 볼륨을 유지하면서 Kubernetes API 서버 및 컨트롤 플레인 구성 요소를 이전 버전으로 되돌립니다.

롤백되는 항목

다음 구성 요소가 롤백됩니다.

롤백되지 않는 항목

다음 구성 요소는 롤백되지 않습니다.

사전 조건

클러스터를 롤백하려면 먼저 다음 조건을 모두 충족해야 합니다.

위의 요구 사항 외에도 특정 조건에서는 --force 플래그를 사용해도 롤백이 불가능합니다. 이러한 조건에는 클러스터가 현재 버전에서 생성되었거나, 업그레이드 후 7일이 경과했거나, 클러스터가 이미 최신 버전으로 다시 업그레이드되었거나, 현재 버전 경계에서 이전 버전과 호환되지 않는 EKS 기능이 활성화된 경우가 포함됩니다.

요약

다음은 Amazon EKS 클러스터 롤백 프로세스를 대략적으로 요약한 것입니다.

1단계: 롤백 준비 인사이트 검토

Amazon EKS는 일련의 특정 시점 롤백 준비 검사를 기준으로 클러스터를 자동으로 평가하고 ROLLBACK_READINESS 범주 아래의 클러스터 인사이트를 통해 문제를 표시합니다. 이러한 인사이트는 업그레이드를 수행한 후 표시되며 7일 롤백 자격 기간 동안 계속 사용할 수 있습니다.

롤백 준비 인사이트 보기

AWS 콘솔:

AWS CLI:

aws eks list-insights \
  --cluster-name my-cluster \
  --region us-west-2 \
  --filter '{"categories": ["ROLLBACK_READINESS"]}'

특정 인사이트에 대한 세부 정보를 가져오려면:

aws eks describe-insight \
  --cluster-name my-cluster \
  --region us-west-2 \
  --id <insight-id>

인사이트 새로 고침

Amazon EKS는 인사이트를 24시간마다 새로 고칩니다. 문제를 해결한 후 Amazon EKS 콘솔에서 새로 고침 버튼을 선택하거나 CLI를 사용하여 수동으로 새로 고침을 트리거할 수 있습니다.

aws eks start-insights-refresh \
  --cluster-name my-cluster \
  --region us-west-2

인사이트 상태 동작

다음 표에서는 각 인사이트 상태의 의미와 롤백에 미치는 영향을 설명합니다.

ERROR 또는 UNKNOWN 상태의 인사이트는 롤백을 차단합니다. PASSING 또는 WARNING 상태의 인사이트는 롤백을 차단하지 않습니다.

롤백 준비 검사

Amazon EKS는 롤백 준비 인사이트의 일부로 일련의 검사를 수행합니다. 이러한 검사는 API 사용 호환성(필드 수준 변경 감지 포함), 클러스터 상태, kubelet 버전 차이, kube-proxy 버전 차이, 추가 기능 버전 호환성을 평가합니다. EKS Auto Mode를 실행하는 클러스터의 경우 추가 검사는 NodePool 중단 예산, do-not-disrupt 주석, PodDisruptionBudget 구성을 평가합니다.

--force 플래그 사용

롤백 준비 인사이트에 ERROR 상태가 표시되지만 문제를 해결하지 않고 계속 진행하려는 경우 --force 플래그를 사용하여 모든 인사이트 검사를 우회할 수 있습니다.

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --force \
  --region us-west-2

--force 플래그는 인사이트 검사만 우회합니다. 7일 기간, 생성 버전 확인 또는 순차적 롤백 확인과 같은 사전 조건 검증은 우회하지 않습니다. Auto Mode 클러스터의 경우 --force는 중단 제어를 재정의하지 않습니다. NodePool 중단 예산, PDB 및 do-not-disrupt 주석은 계속 준수됩니다.

2단계: 워커 노드 준비

컨트롤 플레인을 롤백하기 전에 워커 노드가 대상 버전과 호환되는지 확인합니다. Kubernetes 버전 차이 정책에 따라 워커 노드는 컨트롤 플레인보다 최신 버전을 실행할 수 없습니다.

EKS Auto Mode

작업이 필요하지 않습니다. 롤백을 시작하면 Amazon EKS는 컨트롤 플레인보다 먼저 Auto Mode 노드를 자동으로 롤백합니다. 자세한 내용은 EKS Auto Mode 클러스터 롤백 섹션을 참조하세요.

관리형 노드 그룹(MNG)

컨트롤 플레인을 롤백하기 전에 관리형 노드 그룹을 이전 버전으로 롤백해야 합니다. UpdateNodegroupVersion API를 사용합니다.

aws eks update-nodegroup-version \
  --cluster-name my-cluster \
  --nodegroup-name my-nodegroup \
  --kubernetes-version 1.30 \
  --region us-west-2

노드 그룹 업데이트는 구성된 업데이트 설정(maxUnavailable 또는 maxUnavailablePercentage) 및 업데이트 전략(롤링 또는 강제)을 준수합니다.

자체 관리형 노드 및 하이브리드 노드

자체 관리형 노드 및 하이브리드 노드 롤백은 사용자의 책임입니다. 컨트롤 플레인을 롤백하기 전에 이전 Kubernetes 버전을 사용하도록 노드 AMI 또는 구성을 업데이트합니다.

Fargate

Fargate 워커 노드에는 버전 롤백이 지원되지 않습니다. Fargate를 사용하는 클러스터의 컨트롤 플레인을 롤백할 수 있지만 컨트롤 플레인과 동일한 Kubernetes 버전을 실행하는 Fargate 포드는 ERROR 상태로 kubelet 버전 차이 인사이트를 트리거합니다.

Amazon EKS는 Fargate 포드를 이전 kubelet 버전으로 자동으로 롤백할 수 없습니다.

해결 방법: Fargate 포드가 컨트롤 플레인과 동일한 Kubernetes 버전을 실행하는 경우 롤백을 시작하기 전에 해당 포드를 삭제합니다. 그런 다음 컨트롤 플레인을 롤백합니다. 나머지 포드는 재배포할 때 롤백된 버전으로 시작됩니다.

또는 --force를 사용하여 인사이트 검사를 우회합니다. 그러나 kubelet 버전 차이 위반에서 계속 진행하면 해당 포드가 교체될 때까지 Fargate 워크로드에서 예기치 않은 동작이 발생할 수 있습니다.

3단계: 클러스터 컨트롤 플레인 롤백

AWS 콘솔, AWS CLI 또는 EKS API를 사용하여 롤백을 시작할 수 있습니다.

AWS 콘솔을 사용하여 클러스터 롤백

롤백을 완료하는 데 몇 분 정도 걸립니다. Auto Mode 클러스터의 경우 노드 롤백 단계가 더 오래 걸릴 수 있습니다. 자세한 내용은 EKS Auto Mode 클러스터 롤백 섹션을 참조하세요.

AWS CLI를 사용하여 클러스터 롤백

기존 update-cluster-version 명령을 이전(N-1) Kubernetes 버전에서 사용합니다.

aws eks update-cluster-version \
  --name my-cluster \
  --kubernetes-version 1.30 \
  --region us-west-2

응답 예제:

{
    "update": {
        "id": "e4091a28-ea14-48fd-a8c7-975aeb469e8a",
        "status": "InProgress",
        "type": "VersionRollback",
        "params": [
            {
                "type": "Version",
                "value": "1.30"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.16"
            }
        ],
        "createdAt": "2026-05-12T16:56:01.082000-04:00",
        "errors": []
    }
}

4단계: 롤백 진행 상황 모니터링

Amazon EKS 콘솔 또는 AWS CLI를 사용하여 클러스터 롤백 상태를 모니터링할 수 있습니다.

AWS CLI:

aws eks describe-update \
  --name my-cluster \
  --region us-west-2 \
  --update-id e4091a28-ea14-48fd-a8c7-975aeb469e8a

AWS 콘솔:

상태 전환

표준 클러스터의 경우(Auto Mode 제외):

InProgress → Successful
InProgress → Failed

Auto Mode 클러스터의 경우 노드가 롤백되는 동안 클러스터 상태가 ACTIVE로 유지되고 컨트롤 플레인 롤백이 시작될 때만 UPDATING으로 변경됩니다. describe-update를 사용하여 전체 롤백 진행 상황을 추적합니다. 자세한 내용은 EKS Auto Mode 클러스터 롤백 섹션을 참조하세요.

Successful 상태가 표시되면 롤백이 완료된 것입니다.

고려 사항 및 경고

인사이트는 최선의 노력 및 특정 시점을 기준으로 합니다

클러스터 인사이트는 롤백이 트리거될 때 평가됩니다. 인사이트를 확인한 후 롤백이 완료되기 전에 클러스터를 변경하는 경우(예: 새 API를 사용하여 리소스 생성), 이러한 변경 사항은 초기 인사이트 검사에서 캡처되지 않으며 롤백이 완료된 후 문제가 발생할 수 있습니다.

etcd 데이터 보존

Amazon EKS는 롤백 중에 etcd 데이터를 보존합니다. --force 플래그를 사용하여 우회한 호환되지 않는 리소스는 계속 유지되며 폐영역 회수되지 않습니다.

확장 지원 요금

표준 지원 버전에서 확장 지원 버전으로 롤백하면 클러스터에 확장 지원 요금이 발생하기 시작합니다. 예를 들어 1.30(확장 지원)에서 1.31(표준 지원)로 업그레이드한 다음 1.30으로 롤백하면 확장 지원 요금 부과가 재개됩니다.

롤백에 대한 공동 책임 모델

Amazon EKS는 Kubernetes 컨트롤 플레인을 원하는 버전으로 롤백합니다. 공동 책임 모델의 일환으로 애플리케이션의 이전 버전 호환성을 확인할 책임은 사용자에게 있습니다.

CloudFormation 스택 롤백 동작

AWS CloudFormation 스택 업데이트가 실패하고 스택 롤백을 트리거하는 경우 더 낮은 Kubernetes 버전을 지정하는 이전 템플릿 버전으로 되돌리기는 클러스터 버전 롤백을 트리거하지 않습니다. UpdateClusterVersion API, CLI 또는 콘솔을 통해 버전 롤백을 명시적으로 시작해야 합니다.

롤백 및 추가 기능

Amazon EKS는 클러스터 버전 롤백 중에 추가 기능 버전을 자동으로 롤백하지 않습니다. 추가 기능 버전을 별도로 관리해야 합니다.

컨트롤 플레인을 롤백하기 전에:

관련 리소스