[AWS EKS] 클러스터 버전 업그레이드 실습

EKS 클러스터 버전 업그레이드 실습 (1.30 → 1.31)

들어가며

EKS 클러스터 버전 업그레이드는 크게 세 단계로 진행된다.

  1. Control Plane 업그레이드
  2. Add-ons 업그레이드 (CoreDNS, kube-proxy, VPC CNI)
  3. Managed Node Group 업그레이드

이 글은 EKS Workshop 환경에서 1.30 → 1.31 In-Place 업그레이드를 Terraform으로 진행한 과정을 정리한 것이다. In-Place 업그레이드는 한 번에 한 마이너 버전씩만 가능하므로, 여러 버전을 건너뛰려면 순차적으로 진행해야 한다.

1. 실습 환경 확인

업그레이드를 시작하기 전에 현재 노드 상태를 확인한다.

kubectl get nodes

Fargate 노드 1개와 EC2 기반 노드 6개가 모두 v1.30.14 버전, Ready 상태로 운영 중이다.

워크숍 환경에는 ArgoCD가 배포되어 있어 업그레이드 진행 중 워크로드 상태를 함께 확인할 수 있다. 콘솔 접속에 필요한 자격 증명은 환경 변수로 제공된다.

2. Control Plane 업그레이드

EKS Control Plane 업그레이드는 AWS가 Blue/Green 방식으로 자동 처리한다. 업그레이드 도중 문제가 발생하면 자동으로 롤백되며, 사용자 워크로드는 영향을 받지 않는다.

사전 확인 사항

  • 클러스터가 위치한 서브넷에 최소 5개의 가용 IP가 필요하다. 부족할 경우 UpdateClusterConfiguration API로 서브넷을 추가하거나 VPC CIDR 블록을 추가해야 한다.
  • 클러스터 IAM 역할이 존재하고 필요한 권한이 부여되어 있어야 한다.
  • Secret Encryption을 사용하는 경우 클러스터 IAM 역할에 KMS 키 사용 권한이 있어야 한다.
  • 사전 점검은 EKS Upgrade Insights를 통해 수행할 수 있다.

Terraform으로 업그레이드 진행

variables.tf의 cluster_version을 1.30에서 1.31로 변경한다.

cd ~/environment/terraform
terraform init
terraform plan
terraform apply -auto-approve

적용에는 10~15분 정도 소요된다. 완료 후 EKS 콘솔에서 Kubernetes 버전이 1.31로 변경된 것을 확인할 수 있다.

콘솔의 "업그레이드 인사이트"에는 다음 마이너 버전 업그레이드를 위한 점검 항목이 표시된다.

3. Add-ons 업그레이드

Control Plane 업그레이드 후에는 Kubernetes 버전과 호환되는 Add-on 버전으로 업데이트해야 한다. 이 실습에서는 다음 세 가지를 다룬다.

  • CoreDNS
  • kube-proxy
  • VPC CNI

호환 버전 조회

각 Add-on에 대해 1.31 호환 버전 목록을 조회한다.

aws eks describe-addon-versions --addon-name coredns --kubernetes-version 1.31 --output table \
  --query "addons[].addonVersions[:10].{Version:addonVersion,DefaultVersion:compatibilities[0].defaultVersion}"

aws eks describe-addon-versions --addon-name kube-proxy --kubernetes-version 1.31 --output table \
  --query "addons[].addonVersions[:10].{Version:addonVersion,DefaultVersion:compatibilities[0].defaultVersion}"

addons.tf 수정

조회한 버전을 addons.tf에 반영한다. VPC CNI는 most_recent = true로 두어 최신 버전이 자동 적용되도록 했다.

terraform plan
terraform apply -auto-approve

apply 결과 CoreDNS와 kube-proxy가 변경되었고, 종속성에 따라 Karpenter helm release도 함께 갱신되었다. 총 3개 리소스가 변경된 것을 확인할 수 있다.

EKS 콘솔에서 CoreDNS Add-on이 v1.11.4-eksbuild.33으로 적용된 것을 확인할 수 있다.

4. Managed Node Group 업그레이드

Managed Node Group은 EC2 Auto Scaling Group 기반의 롤링 업데이트로 자동 수행된다. 새 노드가 프로비저닝되어 클러스터에 합류한 뒤 기존 노드가 cordon → drain → terminate 순으로 교체된다.

업그레이드는 내부적으로 4단계로 진행된다.

  1. Setup — 새 Launch Template 버전을 생성하고 ASG에 연결한다. update_config의 max_unavailable 값으로 동시 업그레이드 노드 수를 결정한다 (최대 100개).
  2. Scale up — 새 설정의 노드를 추가한 뒤, 기존 노드를 unschedulable로 표시하고 node.kubernetes.io/exclude-from-external-load-balancers=true 라벨을 붙여 LB 대상에서 제외한다.
  3. Upgrade — 노드를 무작위로 선택해 Pod를 drain한다. 15분 안에 Pod가 비워지지 않으면 PodEvictionFailure로 실패하며, 이 경우 force 플래그로 강제 진행할 수 있다. drain 후 60초 대기 → ASG에 종료 요청 순으로 진행한다.
  4. Scale down — ASG의 max/desired를 업그레이드 이전 값으로 되돌린다.

실습 시나리오

본 환경에는 두 개의 Managed Node Group이 있다.

  • initial-* : cluster_version 미지정 (eks_managed_node_group_defaults 값 사용)
  • blue-mng-* : cluster_version = "1.30" 명시

여기에 Custom AMI를 사용하는 Node Group을 추가로 만들어, 두 가지 업그레이드 방식을 함께 확인한다.

  • 기본 AMI 사용 → mng_cluster_version 변경으로 업그레이드
  • Custom AMI 사용 → ami_id 변경으로 업그레이드

Custom Node Group 생성 (사전 작업)

먼저 1.30용 EKS Optimized AMI ID를 조회한다.

aws ssm get-parameter \
  --name /aws/service/eks/optimized-ami/1.30/amazon-linux-2023/x86_64/standard/recommended/image_id \
  --region $AWS_REGION --query "Parameter.Value" --output text

base.tf의 eks_managed_node_groups 블록에 custom Node Group 정의를 추가한다.

variables.tf의 ami_id에 조회한 AMI ID를 반영한다.

terraform plan
terraform apply -auto-approve

apply 후 EKS 콘솔에서 세 개의 Node Group을 확인할 수 있다. Control Plane이 이미 1.31이기 때문에, 1.30 AMI를 사용하는 initial과 blue-mng는 "지금 업데이트" 안내가 노출된다. custom은 Custom AMI를 사용하므로 AMI ID가 그대로 표시된다.

Node Group 업그레이드 진행

1.31 AMI ID를 조회한다.

aws ssm get-parameter \
  --name /aws/service/eks/optimized-ami/1.31/amazon-linux-2023/x86_64/standard/recommended/image_id \
  --region $AWS_REGION --query "Parameter.Value" --output text

variables.tf에서 두 변수를 함께 수정한다.

  • mng_cluster_version : 1.30 → 1.31 → initial 노드 그룹이 업그레이드됨 (Custom AMI를 사용하는 custom은 영향받지 않음)
  • ami_id : 1.30 AMI → 1.31 AMI → custom 노드 그룹이 새 AMI로 교체됨
terraform plan
terraform apply -auto-approve

전체 적용에는 12~20분 정도 소요된다. blue-mng는 cluster_version = "1.30"이 명시되어 있으므로 별도 변경이 없는 한 1.30 AMI 그대로 유지된다는 점을 유의한다.

정리(Cleanup)

실습 완료 후 base.tf에서 custom 노드 그룹 블록을 제거하고 apply한다.

terraform plan
terraform apply -auto-approve

마무리

EKS 1.30 → 1.31 In-Place 업그레이드의 전체 흐름을 Terraform 기반으로 진행했다. 핵심은 다음과 같이 정리할 수 있다. 다음 버전용 AMI를 미리 준비해두어야 업그레이드가 막히지 않는다.