Kubernetes Multi-Cluster Upgrade Runbook 2026

#!/bin/bash
# d7-changelog-review.sh
# 업그레이드 대상 버전의 변경 사항을 정리한다

TARGET_VERSION="v1.33"

echo "=== ${TARGET_VERSION} 변경 사항 체크 ==="

echo ""
echo "[1] Deprecated API 확인"
echo "  - 릴리스 노트에서 Removed/Deprecated 섹션 확인"
echo "  - Endpoints API → EndpointSlice 마이그레이션 필요 여부"
echo "  - flowcontrol.apiserver.k8s.io/v1beta3 → v1 전환"

echo ""
echo "[2] Feature Gate 변경 확인"
echo "  - InPlacePodVerticalScaling: Beta (기본 활성화)"
echo "  - UserNamespacesSupport: Stable"
echo "  - SidecarContainers: Stable"
echo "  - NFTablesProxyMode: Stable"

echo ""
echo "[3] 사용 중인 Addon 호환성 확인"
# 각 addon의 호환성 매트릭스를 확인한다
ADDONS=(
  "calico"
  "cilium"
  "ingress-nginx"
  "cert-manager"
  "external-dns"
  "prometheus-operator"
  "argocd"
)

for addon in "${ADDONS[@]}"; do
  echo "  - $addon: [  ] 호환성 확인 완료"
done

# 멀티클러스터 환경에서 클러스터 목록 확인
kubectl config get-contexts

# 스테이징 클러스터 컨텍스트로 전환
kubectl config use-context staging-cluster

# 스테이징 업그레이드 실행 (관리형 서비스 예시: EKS)
aws eks update-cluster-version \
  --name staging-cluster \
  --kubernetes-version 1.33

# 업그레이드 상태 모니터링
aws eks describe-update \
  --name staging-cluster \
  --update-id <update-id>

- [ ] 모든 노드 Ready
- [ ] 모든 시스템 Pod Running
- [ ] 애플리케이션 Pod 정상 동작
- [ ] Ingress/Service 트래픽 정상
- [ ] CronJob 1회 이상 성공
- [ ] HPA/VPA 정상 동작
- [ ] 모니터링 메트릭 수집 정상
- [ ] 로그 파이프라인 정상
- [ ] Deprecated API 경고 없음
- [ ] 성능 테스트 통과 (응답 시간, 처리량)

#!/bin/bash
# d1-final-prep.sh

echo "=== D-1 최종 준비 ==="

# 1. 변경 공지
echo "[1] 변경 공지 발송 여부: [ ]"
echo "  - 내부 팀 슬랙 공지"
echo "  - 외부 상태 페이지 업데이트"
echo "  - 유지보수 시간대 공유"

# 2. 온콜 담당자 확인
echo "[2] 온콜 담당자:"
echo "  - Primary: ___________"
echo "  - Secondary: ___________"
echo "  - 에스컬레이션 경로: Primary → Secondary → Tech Lead"

# 3. 롤백 준비
echo "[3] 롤백 준비 상태:"
echo "  - [ ] etcd 스냅샷 생성 완료"
echo "  - [ ] 이전 버전 바이너리 보관"
echo "  - [ ] 롤백 절차 문서 확인"
echo "  - [ ] 롤백 소요 시간 추정: ___분"

# 4. 유지보수 시간대
echo "[4] 작업 시간대:"
echo "  - 시작: ___:___ (KST)"
echo "  - 예상 종료: ___:___ (KST)"
echo "  - 최대 허용: ___:___ (KST)"

# 슬랙 웹훅으로 작업 시작 알림
curl -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d '{
    "text": ":wrench: [MAINTENANCE] Kubernetes 업그레이드 시작\n클러스터: prod-cluster-01\n대상 버전: v1.33\n작업자: @oncall\n예상 소요: 2시간"
  }'

업그레이드 순서:
1. canary-cluster (트래픽 5%) ← 먼저 업그레이드, 1시간 관찰
2. prod-cluster-02 (트래픽 30%) ← canary 안정 후
3. prod-cluster-01 (트래픽 65%) ← 마지막

# Control Plane 업그레이드
aws eks update-cluster-version \
  --name prod-cluster-01 \
  --kubernetes-version 1.33

# 업그레이드 완료 대기
aws eks wait cluster-active --name prod-cluster-01

# Managed Node Group 업그레이드
aws eks update-nodegroup-version \
  --cluster-name prod-cluster-01 \
  --nodegroup-name workers-general \
  --kubernetes-version 1.33

# Addon 업그레이드
for ADDON in vpc-cni coredns kube-proxy; do
  LATEST=$(aws eks describe-addon-versions \
    --addon-name $ADDON \
    --kubernetes-version 1.33 \
    --query 'addons[0].addonVersions[0].addonVersion' \
    --output text)

  aws eks update-addon \
    --cluster-name prod-cluster-01 \
    --addon-name $ADDON \
    --addon-version $LATEST
done

# Control Plane 업그레이드
gcloud container clusters upgrade prod-cluster-01 \
  --master \
  --cluster-version 1.33.0-gke.100 \
  --zone asia-northeast3-a

# Node Pool 업그레이드
gcloud container clusters upgrade prod-cluster-01 \
  --node-pool workers-general \
  --cluster-version 1.33.0-gke.100 \
  --zone asia-northeast3-a

# 업그레이드 가능 버전 확인
az aks get-upgrades \
  --resource-group myResourceGroup \
  --name prod-cluster-01 \
  --output table

# Control Plane + Node Pool 동시 업그레이드
az aks upgrade \
  --resource-group myResourceGroup \
  --name prod-cluster-01 \
  --kubernetes-version 1.33.0

#!/bin/bash
# cluster-health-check.sh <cluster-context>
CONTEXT=$1

echo "=== Health Check: $CONTEXT ==="
kubectl --context "$CONTEXT" get nodes -o wide

# 모든 노드 버전 확인
echo ""
echo "Node versions:"
kubectl --context "$CONTEXT" get nodes \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.kubeletVersion}{"\n"}{end}'

# 시스템 Pod 상태
echo ""
echo "System pods:"
FAILING=$(kubectl --context "$CONTEXT" -n kube-system get pods --no-headers | \
  grep -v "Running\|Completed" | wc -l)
echo "Failing system pods: $FAILING"

# 프로덕션 워크로드 상태
echo ""
echo "Production workloads:"
kubectl --context "$CONTEXT" -n production get deployments -o wide

# Pending Pod 확인
echo ""
echo "Pending pods:"
kubectl --context "$CONTEXT" get pods -A --field-selector=status.phase=Pending

# 이벤트 확인 (최근 10분)
echo ""
echo "Recent warnings:"
kubectl --context "$CONTEXT" get events -A --sort-by='.lastTimestamp' \
  --field-selector type=Warning | tail -20

# AWS Route53 가중치 기반 라우팅 예시
# canary 클러스터로 트래픽을 점진적으로 이동

# 단계 1: canary에 5% 트래픽
# prod-cluster-01: weight 65
# prod-cluster-02: weight 30
# canary-cluster: weight 5

# 단계 2: canary 안정 확인 후 30분 대기

# 단계 3: canary에 20% 트래픽
# prod-cluster-01: weight 50
# prod-cluster-02: weight 30
# canary-cluster: weight 20

# Route53 가중치 업데이트
aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890 \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "api.example.com",
        "Type": "A",
        "SetIdentifier": "canary",
        "Weight": 20,
        "AliasTarget": {
          "HostedZoneId": "Z9876543210",
          "DNSName": "canary-alb.ap-northeast-2.elb.amazonaws.com",
          "EvaluateTargetHealth": true
        }
      }
    }]
  }'

# EKS: 이전 버전 노드 그룹 생성
aws eks create-nodegroup \
  --cluster-name prod-cluster-01 \
  --nodegroup-name workers-rollback \
  --kubernetes-version 1.32 \
  --node-role arn:aws:iam::123456789:role/eks-node-role \
  --subnets subnet-abc subnet-def \
  --instance-types m6i.xlarge \
  --scaling-config minSize=3,maxSize=10,desiredSize=5

# 기존 노드 그룹의 Pod를 새 노드 그룹으로 이동
kubectl cordon -l eks.amazonaws.com/nodegroup=workers-general
kubectl drain -l eks.amazonaws.com/nodegroup=workers-general \
  --ignore-daemonsets --delete-emptydir-data

# 기존 노드 그룹 삭제
aws eks delete-nodegroup \
  --cluster-name prod-cluster-01 \
  --nodegroup-name workers-general

# 문제 클러스터의 트래픽 가중치를 0으로 설정
aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890 \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "api.example.com",
        "Type": "A",
        "SetIdentifier": "canary",
        "Weight": 0,
        "AliasTarget": {
          "HostedZoneId": "Z9876543210",
          "DNSName": "canary-alb.ap-northeast-2.elb.amazonaws.com",
          "EvaluateTargetHealth": true
        }
      }
    }]
  }'

$ kubectl drain node-xyz --ignore-daemonsets
error: Cannot evict pod as it would violate the pod's disruption budget.

# PDB 상태 확인
kubectl get pdb -A -o wide

# 출력 예시:
# NAMESPACE   NAME       MIN AVAILABLE   MAX UNAVAILABLE   ALLOWED DISRUPTIONS
# production  web-pdb    3               N/A               0
#                                                          ↑ 0이면 drain 불가

# 옵션 1: 레플리카 수를 먼저 늘려서 여유분 확보
kubectl -n production scale deployment web --replicas=4
# 1~2분 후 다시 drain 시도

# 옵션 2: PDB를 일시적으로 완화 (주의: 가용성 감소)
kubectl -n production patch pdb web-pdb \
  --type=merge -p '{"spec":{"minAvailable":2}}'
# drain 완료 후 원복
kubectl -n production patch pdb web-pdb \
  --type=merge -p '{"spec":{"minAvailable":3}}'

$ kubectl -n kube-system logs ingress-nginx-controller-xyz
Error: the server could not find the requested resource (get ingresses.networking.k8s.io)

# Addon 호환 버전 확인 및 업그레이드
helm repo update

# ingress-nginx 호환 버전 확인
helm search repo ingress-nginx/ingress-nginx --versions | head -10

# 호환 버전으로 업그레이드
helm upgrade ingress-nginx ingress-nginx/ingress-nginx \
  --namespace kube-system \
  --version 4.12.0 \
  --reuse-values

# 클러스터 A: v1.33, 클러스터 B: v1.32
# Istio 멀티클러스터 구성에서 일부 트래픽 라우팅 실패
$ istioctl proxy-status
NAME                   CLUSTER      CDS   LDS   EDS   RDS
web-v1-xyz.production  cluster-a    SYNCED SYNCED SYNCED SYNCED
web-v1-abc.production  cluster-b    STALE  STALE  STALE  STALE

# Istio 호환성 확인
istioctl version

# 양쪽 클러스터에서 지원하는 Istio 버전으로 통일
# Istio 1.24+는 Kubernetes v1.31~v1.33 지원
istioctl upgrade --set revision=1-24-0

$ aws eks update-addon --addon-name vpc-cni ...
An error occurred (InvalidParameterException): Addon version v1.19.0 is not
compatible with cluster version 1.33. Available versions: v1.19.2, v1.20.0

# 호환 가능한 최신 버전 조회
aws eks describe-addon-versions \
  --addon-name vpc-cni \
  --kubernetes-version 1.33 \
  --query 'addons[0].addonVersions[:5].{version:addonVersion,default:compatibilities[0].defaultVersion}' \
  --output table

# 호환 버전으로 업데이트
aws eks update-addon \
  --cluster-name prod-cluster-01 \
  --addon-name vpc-cni \
  --addon-version v1.20.0 \
  --resolve-conflicts OVERWRITE

업그레이드 후 0~2시간: 집중 관찰 (5분 간격 확인)
업그레이드 후 2~24시간: 일반 관찰 (30분 간격)
업그레이드 후 24~72시간: 경계 관찰 (이상 알림 대응)
업그레이드 후 72시간~: 정상 운영 전환, 포스트모템 작성

# 클러스터 업그레이드 포스트모템

## 기본 정보

- 대상 클러스터: \_\_\_
- 이전 버전: v1.32.x → 현재 버전: v1.33.x
- 작업 시간: YYYY-MM-DD HH:MM ~ HH:MM (총 \_\_\_시간)
- 작업자: \_\_\_

## 진행 요약

- [ ] 스테이징 업그레이드: 문제 없음 / 문제 발생 (상세: \_\_\_)
- [ ] 프로덕션 업그레이드: 문제 없음 / 문제 발생 (상세: \_\_\_)
- [ ] 롤백 실행 여부: Yes / No

## 발견된 이슈

| 이슈   | 심각도 | 해결 방법 | 소요 시간 |
| ------ | ------ | --------- | --------- |
| \_\_\_ | P1~P4  | \_\_\_    | \_\_\_분  |

## 개선 사항 (다음 업그레이드에 반영)

1. ***
2. ***
3. ***

## 업데이트 필요한 문서

- [ ] 이 런북
- [ ] 온콜 가이드
- [ ] 모니터링 대시보드

# .github/workflows/cluster-upgrade.yml
name: Kubernetes Cluster Upgrade

on:
  workflow_dispatch:
    inputs:
      target_version:
        description: 'Target Kubernetes version'
        required: true
        default: '1.33'
      cluster:
        description: 'Cluster to upgrade'
        required: true
        type: choice
        options:
          - canary-cluster
          - prod-cluster-02
          - prod-cluster-01
      dry_run:
        description: 'Dry run mode'
        required: true
        type: boolean
        default: true

jobs:
  pre-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ap-northeast-2

      - name: Pre-upgrade checks
        run: |
          aws eks describe-cluster --name ${{ inputs.cluster }} \
            --query 'cluster.{version:version,status:status}' \
            --output table

          # 현재 버전 확인
          CURRENT=$(aws eks describe-cluster --name ${{ inputs.cluster }} \
            --query 'cluster.version' --output text)
          echo "Current version: $CURRENT"
          echo "Target version: ${{ inputs.target_version }}"

          # Addon 호환성 확인
          for ADDON in vpc-cni coredns kube-proxy; do
            echo "Checking $ADDON compatibility..."
            aws eks describe-addon-versions \
              --addon-name $ADDON \
              --kubernetes-version ${{ inputs.target_version }} \
              --query 'addons[0].addonVersions[0].addonVersion' \
              --output text
          done

  upgrade:
    needs: pre-check
    runs-on: ubuntu-latest
    if: ${{ !inputs.dry_run }}
    environment: production # 수동 승인 필요
    steps:
      - name: Upgrade Control Plane
        run: |
          aws eks update-cluster-version \
            --name ${{ inputs.cluster }} \
            --kubernetes-version ${{ inputs.target_version }}

          echo "Waiting for control plane upgrade..."
          aws eks wait cluster-active --name ${{ inputs.cluster }}

      - name: Upgrade Node Groups
        run: |
          NODEGROUPS=$(aws eks list-nodegroups \
            --cluster-name ${{ inputs.cluster }} \
            --query 'nodegroups[]' --output text)

          for NG in $NODEGROUPS; do
            echo "Upgrading node group: $NG"
            aws eks update-nodegroup-version \
              --cluster-name ${{ inputs.cluster }} \
              --nodegroup-name $NG \
              --kubernetes-version ${{ inputs.target_version }}
          done

      - name: Upgrade Addons
        run: |
          for ADDON in vpc-cni coredns kube-proxy; do
            LATEST=$(aws eks describe-addon-versions \
              --addon-name $ADDON \
              --kubernetes-version ${{ inputs.target_version }} \
              --query 'addons[0].addonVersions[0].addonVersion' \
              --output text)

            aws eks update-addon \
              --cluster-name ${{ inputs.cluster }} \
              --addon-name $ADDON \
              --addon-version $LATEST \
              --resolve-conflicts OVERWRITE
          done

  post-verify:
    needs: upgrade
    runs-on: ubuntu-latest
    steps:
      - name: Health Check
        run: |
          aws eks update-kubeconfig --name ${{ inputs.cluster }}

          echo "Node status:"
          kubectl get nodes -o wide

          echo "System pods:"
          kubectl -n kube-system get pods

          echo "Failing pods:"
          kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded

      - name: Notify
        run: |
          curl -X POST "${{ secrets.SLACK_WEBHOOK }}" \
            -H 'Content-type: application/json' \
            -d "{
              \"text\": \":white_check_mark: Cluster upgrade complete\nCluster: ${{ inputs.cluster }}\nVersion: ${{ inputs.target_version }}\"
            }"