기존 클러스터를 새 Kubernetes 버전으로 업데이트하기

Amazon EKS에서 새 Kubernetes 버전을 사용할 수 있게 되면 기존 클러스터를 최신 버전으로 업데이트하는 방법을 알아봐요. 업그레이드 준비, 제어 플레인 업그레이드, 노드·컴포넌트 업데이트의 전 과정을 다뤄요.

출처: 문서

본문

팁: 곧 열릴 Amazon EKS 워크숍에 등록하세요.

Amazon EKS에서 새 Kubernetes 버전을 사용할 수 있게 되면 Amazon EKS 클러스터를 최신 버전으로 업데이트할 수 있어요.

중요: 업그레이드 후 문제가 생기면 7일 안에 이전 버전으로 롤백할 수 있어요. 자세한 내용은 Roll back a cluster to a previous Kubernetes version 참고. 새 Kubernetes 버전으로 업데이트하기 전에 Understand the Kubernetes version lifecycle on EKS의 정보와 이 토픽의 업데이트 단계를 검토할 것을 권장합니다.

새 Kubernetes 버전은 때로 상당한 변경을 도입해요. 따라서 프로덕션 클러스터를 업데이트하기 전에 새 Kubernetes 버전에서 애플리케이션의 동작을 테스트할 것을 권장합니다. 새 Kubernetes 버전으로 이동하기 전에 애플리케이션 동작을 테스트하는 지속적 통합 워크플로우를 만들어 할 수 있어요.

업데이트 과정은 Amazon EKS가 기존 제어 플레인 API 서버 노드를 교체하기 위해 업데이트된 Kubernetes 버전의 새 API 서버 노드를 시작하는 것으로 구성돼요. Amazon EKS는 이 새 노드들에 대해 네트워크 트래픽의 표준 인프라 및 준비 상태 검사를 수행해 예상대로 작동하는지 확인해요. 하지만 클러스터 업그레이드를 시작하면 중지하거나 멈출 수 없어요. 이 검사 중 하나라도 실패하면 Amazon EKS가 인프라 배포를 되돌리며 클러스터는 이전 Kubernetes 버전에 머물러요. 실행 중인 애플리케이션은 영향받지 않으며, 클러스터는 비결정적이거나 복구 불가능한 상태로 남지 않아요. Amazon EKS는 모든 관리형 클러스터를 주기적으로 백업하며 필요 시 클러스터를 복구하는 메커니즘이 존재해요. 우리는 Kubernetes 인프라 관리 프로세스를 지속적으로 평가하고 개선하고 있어요.

클러스터를 업데이트하려면 Amazon EKS가 클러스터 생성 시 지정한 서브넷에서 최대 5개의 사용 가능한 IP 주소가 필요해요. Amazon EKS는 지정한 서브넷 중 아무 곳에나 새 클러스터 탄력적 네트워크 인터페이스(네트워크 인터페이스)를 만들어요. 네트워크 인터페이스는 기존 네트워크 인터페이스와 다른 서브넷에 만들어질 수 있으므로, 보안 그룹 규칙이 클러스터 생성 시 지정한 모든 서브넷에 대해 필요한 클러스터 통신을 허용하는지 확인해 주세요. 클러스터 생성 시 지정한 서브넷 중 하나라도 존재하지 않거나, 사용 가능한 IP 주소가 충분하지 않거나, 필요한 클러스터 통신을 허용하는 보안 그룹 규칙이 없으면 업데이트가 실패할 수 있어요.

클러스터의 API 서버 엔드포인트가 항상 접근 가능하도록 Amazon EKS는 고가용성 Kubernetes 제어 플레인을 제공하고 업데이트 작업 중 API 서버 인스턴스의 롤링 업데이트를 수행해요. Kubernetes API 서버 엔드포인트를 지원하는 API 서버 인스턴스의 변경되는 IP 주소를 처리하려면 API 서버 클라이언트가 재연결을 효과적으로 관리하도록 해야 해요. 공식 지원되는 최신 kubectl 및 Kubernetes 클라이언트 라이브러리 버전은 이 재연결 과정을 투명하게 수행해요.

참고: 클러스터 업데이트에 무엇이 포함되는지 더 알아보려면 EKS 모범 사례 가이드의 Best Practices for Cluster Upgrades를 참고해 주세요. 이 리소스는 업그레이드를 계획하고 클러스터 업그레이드 전략을 이해하는 데 도움을 줘요.

Amazon EKS Auto Mode를 위한 고려 사항 (Considerations for Amazon EKS Auto Mode)

Amazon EKS Auto Mode의 컴퓨트 기능이 노드의 Kubernetes 버전을 제어해요. 제어 플레인을 업그레이드한 후 EKS Auto Mode가 관리 노드를 점진적으로 업데이트하기 시작해요. EKS Auto Mode는 파드 중단 예산(pod disruption budgets)을 준수해요.

컴퓨트 오토스케일링, 블록 스토리지, 로드 밸런싱 기능을 포함한 Amazon EKS Auto Mode의 기능을 수동으로 업그레이드할 필요가 없어요.

참고: 업그레이드 후 문제가 발생하면 롤백을 시작할 수 있어요. EKS Auto Mode를 실행하는 클러스터의 경우 EKS는 제어 플레인을 되돌리기 전에 워커 노드를 자동으로 롤백해요. 자세한 내용은 Roll back a cluster to a previous Kubernetes version 참고.

요약 (Summary)

Amazon EKS 클러스터 업그레이드 과정의 요약:

클러스터가 업그레이드를 지원할 상태인지 확인합니다. 여기에는 클러스터에 배포된 리소스가 사용하는 Kubernetes API 확인, 클러스터에 상태 문제가 없는지 확인이 포함돼요. 업그레이드 준비 상태를 평가할 때 Amazon EKS 업그레이드 인사이트를 사용해야 해요.
제어 플레인을 다음 마이너 버전으로 업그레이드합니다 (예: 1.35에서 1.36으로).
데이터 플레인의 노드를 제어 플레인과 일치하도록 업그레이드합니다.
클러스터에서 실행 중인 추가 애플리케이션을 업그레이드합니다 (예: cluster-autoscaler).
Amazon EKS가 제공하는 애드온(기본 포함 것들)을 업그레이드합니다:
- Amazon VPC CNI 권장 버전
- CoreDNS 권장 버전
- kube-proxy 권장 버전
클러스터와 통신하는 클라이언트를 업그레이드합니다 (예: kubectl).

1단계: 업그레이드 준비 (Step 1: Prepare for upgrade)

클러스터 제어 플레인의 Kubernetes 버전과 노드의 Kubernetes 버전을 비교합니다.

클러스터 제어 플레인의 Kubernetes 버전을 가져옵니다.

kubectl version

노드의 Kubernetes 버전을 가져옵니다. 이 명령은 모든 자체 관리 및 관리형 Amazon EC2, Fargate, 하이브리드 노드를 반환해요. 각 Fargate 파드는 자체 노드로 나열됩니다.

kubectl get nodes

제어 플레인을 새 Kubernetes 버전으로 업데이트하기 전에 클러스터의 관리형 노드와 Fargate 노드의 Kubernetes 마이너 버전이 제어 플레인 버전과 같은지 확인해 주세요. 예를 들어 제어 플레인이 버전 1.29을 실행하고 노드 중 하나가 버전 1.28을 실행한다면, 제어 플레인을 1.30으로 업데이트하기 전에 노드를 버전 1.29로 업데이트해야 해요. 재어 플레인을 업데이트하기 전에 자체 관리 노드와 하이브리드 노드도 제어 플레인과 같은 버전으로 업데이트할 것을 권장합니다. 자세한 내용은 Update a managed node group for your cluster, Update self-managed nodes for your cluster, Upgrade hybrid nodes for your cluster 참고. 제어 플레인 버전보다 낮은 마이너 버전의 Fargate 노드가 있다면 먼저 해당 노드가 나타내는 파드를 삭제한 후 제어 플레인을 업데이트해 주세요. 남은 파드는 재배포 후 새 버전으로 업데이트됩니다.

2단계: 업그레이드 고려 사항 검토 (Step 2: Review upgrade considerations)

Amazon EKS 클러스터 인사이트는 클러스터를 지원 중단된 Kubernetes API 사용 같은 잠재적 Kubernetes 버전 업그레이드 영향 문제 목록에 대해 자동으로 스캔해요. Amazon EKS는 Kubernetes 프로젝트의 변경 평가를 기반으로 수행할 인사이트 검사 목록을 주기적으로 업데이트해요. 또한 새 버전과 함께 Amazon EKS 서비스에 변경이 도입됨에 따라 인사이트 검사 목록을 업데이트해요. 자세한 내용은 Prepare for Kubernetes version upgrades and troubleshoot misconfigurations with cluster insights 참고.

Kubernetes 문서의 Deprecated API Migration Guide을 검토합니다.
업그레이드 인사이트를 검토합니다: 문제를 식별하려면 Amazon EKS 업그레이드 인사이트를 사용합니다. 자세한 내용은 View upgrade insights (Console) 참고.

상세 고려 사항 (Detailed considerations)

Amazon EKS는 고가용성 제어 플레인을 실행하므로 한 번에 한 마이너 버전만 업데이트할 수 있어요. 이 요구 사항에 대한 자세한 내용은 Kubernetes Version and Version Skew Support Policy 참고. 현재 클러스터 버전이 1.28이고 1.30으로 업데이트하려면 먼저 버전 1.28 클러스터를 1.29로, 그다음 버전 1.29 클러스터를 1.30으로 업데이트해야 해요.
노드의 Kubernetes kube-apiserver와 kubelet 사이의 버전 스큐를 검토합니다.
Kubernetes 버전 1.28부터 kubelet은 kube-apiserver보다 최대 세 마이너 버전 더 오래될 수 있어요. Kubernetes upstream version skew policy 참고.
관리형 및 Fargate 노드의 kubelet이 Kubernetes 버전 1.25 이상이면, kubelet 버전을 업데이트하지 않고 클러스터를 최대 세 버전 앞으로 업데이트할 수 있어요. 예를 들어 kubelet이 버전 1.25라면 kubelet이 1.25에 머무는 동안 Amazon EKS 클러스터 버전을 1.25에서 1.26, 1.27, 1.28로 업데이트할 수 있어요.
모범 사례로 업데이트를 시작하기 전에 노드의 kubelet이 제어 플레인과 같은 Kubernetes 버전인지 확인해 주세요.
클러스터가 1.8.0보다 이전 버전의 Kubernetes용 Amazon VPC CNI 플러그인으로 구성되어 있다면 클러스터 업데이트 전에 플러그인을 최신 버전으로 업데이트할 것을 권장합니다. 업데이트는 Assign IPs to Pods with the Amazon VPC CNI 참고.
업그레이드 과정 중 실패 시 Amazon EKS 클러스터 상태와 영구 스토리지를 복원할 수 있도록 Amazon EKS 클러스터를 백업할 수 있어요. Back up your EKS Clusters with AWS Backup 참고.

3단계: 클러스터 제어 플레인 업데이트 (Step 3: Update cluster control plane)

중요: Amazon EKS는 특정 클러스터 인사이트 문제가 있을 때 --force 플래그를 사용해 클러스터를 업그레이드하도록 요구하는 기능을 일시적으로 롤백했어요. 자세한 내용은 GitHub의 Temporary rollback of enforcing upgrade insights on update cluster version 참고.

Amazon EKS는 "last refresh time" 24시간 후에 클러스터 인사이트를 갱신해요. 문제를 해결한 시간과 클러스터 인사이트의 "last refresh time"을 비교할 수 있어요.

또한，지원 중단된 API 사용을 해결한 후 인사이트 상태가 업데이트되는 데 최대 30일이 걸릴 수 있어요. 업그레이드 인사이트는 항상 이동 30일 창에 걸쳐 지원 중단된 API 사용을 찾아요.

다음을 사용해 EKS 제어 플레인 버전 업그레이드 요청을 제출할 수 있어요:

eksctl
AWS 콘솔
AWS CLI

클러스터 업데이트 - eksctl (Update cluster - eksctl)

이 절차는 eksctl 버전 0.215.0 이상이 필요해요. 다음 명령으로 버전을 확인할 수 있어요:

eksctl version

eksctl 설치 및 업데이트 지침은 eksctl 문서의 Installation 참고.

Amazon EKS 제어 플레인의 Kubernetes 버전을 업데이트합니다. <cluster-name>을 클러스터 이름으로, <version>을 업데이트할 Amazon EKS 지원 버전 번호로 바꿔 주세요. 지원 버전 목록은 Amazon EKS supported versions 참고.

eksctl upgrade cluster --name <cluster-name> --version <version> --approve

업데이트는 완료하는 데 몇 분이 걸립니다.

4단계: 클러스터 컴포넌트 업데이트로 계속 진행합니다.

클러스터 업데이트 - AWS 콘솔 (Update cluster - AWS console)

Amazon EKS 콘솔을 엽니다.
업그레이드하려는 클러스터에 대해 Upgrade now를 선택합니다.
클러스터를 업데이트할 버전을 선택하고 Upgrade를 선택합니다.

업데이트는 완료하는 데 몇 분이 걸립니다. 4단계: 클러스터 컴포넌트 업데이트로 계속 진행합니다.

클러스터 업데이트 - AWS CLI (Update cluster - AWS CLI)

AWS CLI가 설치되어 있고 로그인되어 있는지 확인합니다. 자세한 내용은 Installing or updating to the latest version of the AWS CLI 참고.

다음 AWS CLI 명령으로 Amazon EKS 클러스터를 업데이트합니다. 업그레이드할 클러스터의 <cluster-name>과 <region>을 바꿔 주세요. <version>을 업데이트할 Amazon EKS 지원 버전 번호로 바꿉니다. 지원 버전 목록은 Amazon EKS supported versions 참고.

aws eks update-cluster-version --name <cluster-name> \
  --kubernetes-version <version> --region <region>

예시 출력:

{
    "update": {
        "id": "<update-id>",
        "status": "InProgress",
        "type": "VersionUpdate",
        "params": [
            {
                "type": "Version",
                "value": "<version>"
            },
            {
                "type": "PlatformVersion",
                "value": "eks.1"
            }
        ],
[...]
        "errors": []
    }

업데이트는 완료하는 데 몇 분이 걸립니다. 다음 명령으로 클러스터 업데이트 상태를 모니터링합니다. 같은 <cluster-name>과 <region>에 더해 이전 명령이 반환한 <update-id>를 사용합니다.

aws eks describe-update --name <cluster-name> \
   --region <region> --update-id <update-id>

Successful 상태가 표시되면 업데이트가 완료된 거예요.

4단계: 클러스터 컴포넌트 업데이트로 계속 진행합니다.

4단계: 클러스터 컴포넌트 업데이트 (Step 4: Update cluster components)

클러스터 업데이트가 완료된 후 노드를 업데이트된 클러스터와 같은 Kubernetes 마이너 버전으로 업데이트합니다. 자세한 내용은 Update self-managed nodes for your cluster, Update a managed node group for your cluster, Upgrade hybrid nodes for your cluster 참고. Fargate에서 시작되는 새 파드는 클러스터 버전과 일치하는 kubelet 버전을 가져요. 기존 Fargate 파드는 변경되지 않아요.

(선택사항) 클러스터를 업데이트하기 전에 Kubernetes Cluster Autoscaler를 배포했다면 업데이트한 Kubernetes 메이저·마이너 버전과 일치하는 최신 Cluster Autoscaler 버전으로 업데이트합니다.

웹 브라우저에서 Cluster Autoscaler 릴리스 페이지를 열고 클러스터의 Kubernetes 메이저·마이너 버전과 일치하는 최신 Cluster Autoscaler 버전을 찾습니다. 예를 들어 클러스터 Kubernetes 버전이 1.30이라면 1.30으로 시작하는 최신 Cluster Autoscaler 릴리스를 찾습니다. 다음 단계에서 사용할 릴리스의 시맨틱 버전 번호(1.30.n 등)를 기록합니다.
이전 단계에서 기록한 버전으로 다음 명령으로 Cluster Autoscaler 이미지 태그를 설정합니다. 필요한 경우 X.XX.X를 자신의 값으로 바꿉니다.

kubectl -n kube-system set image deployment.apps/cluster-autoscaler cluster-autoscaler=registry.k8s.io/autoscaling/cluster-autoscaler:vX.XX.X

(GPU 노드가 있는 클러스터만 해당) 클러스터에 GPU 지원 노드 그룹(예: p3.2xlarge)이 있다면 클러스터의 Kubernetes용 NVIDIA device plugin DaemonSet을 업데이트해야 해요. 다음 명령을 실행하기 전에 <NVIDIA/k8s-device-plugin-version>을 원하는 NVIDIA/k8s-device-plugin 버전으로 바꿔 주세요.

kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/<version>/deployments/static/nvidia-device-plugin.yml

Kubernetes용 Amazon VPC CNI 플러그인, CoreDNS, kube-proxy 애드온을 업데이트합니다. 애드온을 Service account tokens에 나열된 최소 버전으로 업데이트할 것을 권장합니다.

Amazon EKS 애드온을 사용한다면 Amazon EKS 콘솔에서 Clusters를 선택한 다음 왼쪽 탐색 창에서 업데이트한 클러스터의 이름을 선택합니다. 업데이트할 수 있는 각 애드온에 대해 새 버전을 사용할 수 있음을 알리는 알림이 콘솔에 나타납니다. 애드온을 업데이트하려면 Add-ons 탭을 선택합니다. 업데이트가 있는 애드온 상자 중 하나에서 Update now를 선택하고 사용 가능한 버전을 선택한 다음 Update를 선택합니다.
또는 AWS CLI나 eksctl로 애드온을 업데이트할 수 있어요. 자세한 내용은 Update an Amazon EKS add-on 참고.

필요하면 kubectl 버전을 업데이트합니다. Amazon EKS 클러스터 제어 플레인과 한 마이너 버전 차이 이내의 kubectl 버전을 사용해야 해요.

Amazon EKS 클러스터의 Kubernetes 버전 다운그레이드 (Downgrade the Kubernetes version for an Amazon EKS cluster)

업그레이드 후 7일 이내에 Amazon EKS 클러스터의 Kubernetes 버전을 이전 마이너 버전으로 롤백할 수 있어요. 자세한 내용은 Roll back a cluster to a previous Kubernetes version 참고. 7일 창이 지나면 다운그레이드할 수 없어요. 대신 이전 Amazon EKS 버전에서 새 클러스터를 만들고 워크로드를 마이그레이션합니다.

더 알아보기 (Learn more)

공식 문서