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

클러스터의 Kubernetes 버전을 업데이트하려면 다음을 수행합니다.

1. 클러스터 컨트롤 플레인의 Kubernetes 버전과 사용자 노드의 Kubernetes 버전을 비교합니다.

   • 클러스터 컨트롤 플레인의 Kubernetes 버전을 가져옵니다.

     kubectl version
     

   • 노드의 Kubernetes 버전을 가져옵니다. 이 명령은 자체 관리형 및 관리형 Amazon EC2 및 Fargate 노드를 모두 반환합니다. 각 Fargate Pod는 자체 노드로 나열됩니다.

     kubectl get nodes
     

   컨트롤 플레인을 새 Kubernetes 버전으로 업데이트하기 전에 클러스터에 있는 관리형 노드 및 Fargate 노드 모두의 Kubernetes 마이너 버전이 컨트롤 플레인의 현재 버전과 동일한지 확인합니다. 예를 들어 컨트롤 플레인에서 버전 1.30을 실행 중이고 노드 중 하나에서 버전 1.29을 실행 중인 경우에는 컨트롤 플레인을 1.31으로 업데이트하기 전에 노드를 버전 1.30로 업데이트해야 합니다. 또한 제어 플레인을 업데이트하기 전에 자체 관리형 노드를 컨트롤 평면과 동일한 버전으로 업데이트하는 것이 좋습니다. 자세한 내용은 클러스터에 대한 관리형 노드 그룹 업데이트 및 클러스터의 자체 관리형 노드 업데이트 단원을 참조하세요. 컨트롤 플레인 버전보다 낮은 마이너 버전이 적용된 Fargate 노드가 있는 경우 먼저 이 노드로 대표되는 Pod을(를) 삭제합니다. 그런 다음 컨트롤 플레인을 업데이트합니다. 나머지 Pods는 모두 다시 배포한 후 새 버전으로 업데이트됩니다.

2. 원래 클러스터를 배포한 Kubernetes 버전이 Kubernetes 1.25 이상인 경우 이 단계를 건너뜁니다.

   기본적으로 Pod 보안 정책 승인 컨트롤러는 Amazon EKS 클러스터에 사용 설정되어 있습니다. 클러스터를 업데이트하기 전에 적절한 Pod 보안 정책이 있는지 확인하세요. 이는 잠재적인 보안 문제를 방지하기 위함입니다. kubectl get psp eks.privileged 명령을 사용하여 기본 정책을 확인할 수 있습니다.

   kubectl get psp eks.privileged
   

   다음 오류가 표시되는 경우 계속하기 전에 Amazon EKS 기본 Pod 보안 정책 단원을 참조하십시오.

   Error from server (NotFound): podsecuritypolicies.extensions "eks.privileged" not found

3. 원래 클러스터를 배포한 Kubernetes 버전이 Kubernetes 1.18 이상인 경우 이 단계를 건너뜁니다.

   중단된 용어를 CoreDNS 매니페스트에서 제거해야 할 수 있습니다.

   1. CoreDNS 매니페스트에 upstream이라는 단어만 있는 줄이 있는지 확인합니다.

      kubectl get configmap coredns -n kube-system -o jsonpath='{$.data.Corefile}' | grep upstream
      

      결과가 반환되지 않으면 매니페스트에 해당 줄이 없는 것입니다. 이 경우 다음 단계로 건너뜁니다. upstream이라는 단어가 반환되면 줄을 제거합니다.

   2. configmap 파일에서 upstream이라는 단어만 있는 파일의 맨 위 근처의 줄을 제거합니다. 파일에서 다른 것을 변경하지 마세요. 줄을 제거한 후 변경 사항을 저장하세요.

      kubectl edit configmap coredns -n kube-system -o yaml
      

4. eksctl, AWS Management Console 또는 AWS CLI를 사용하여 클러스터를 업데이트합니다.

   중요

   • 버전 1.23으로 업데이트하고 클러스터에서 Amazon EBS 볼륨을 사용하는 경우 워크로드 중단을 방지하기 위해 클러스터를 버전 1.23으로 업데이트하기 전에 클러스터에 Amazon EBS CSI 드라이버를 설치해야 합니다. 자세한 내용은 Kubernetes 1.23 및 Amazon EBS를 사용한 Kubernetes 볼륨 저장 단원을 참조하세요.

   • Kubernetes 1.24 이상에서는 containerd를 기본 컨테이너 런타임으로 사용한다. containerd 런타임으로 전환하고 Container Insights에 대해 Fluentd를 이미 구성한 경우 클러스터를 업데이트하기 전에 Fluentd를 Fluent Bit로 마이그레이션해야 합니다. Fluentd 구문 분석기는 JSON 형식의 로그 메시지만 구문 분석하도록 구성됩니다. dockerd와 달리 containerd 컨테이너 런타임에는 JSON 형식이 아닌 로그 메시지가 있습니다. Fluent Bit로 마이그레이션하지 않으면 구성된 Fluentd's 구문 분석기 중 일부가 Fluentd 컨테이너 내에서 엄청난 양의 오류를 생성합니다. 마이그레이션에 대한 자세한 내용은 Set up Fluent Bit as a DaemonSet to send logs to CloudWatch Logs를 참조하세요.

   • Amazon EKS는 가용성 높은 제어 영역을 실행하므로 한 번에 하나의 마이너 버전만 업데이트할 수 있습니다. 이 요구 사항에 대한 자세한 내용을 알아보려면 Kubernetes 버전 및 버전 차이 지원 정책을 참조하세요. 현재 클러스터 버전이 1.29 버전이고 1.31 버전으로 업데이트하려는 경우를 예로 들어보겠습니다. 먼저 1.29 버전 클러스터를 1.30 버전으로 업데이트한 다음에 1.30 버전 클러스터를 1.31 버전으로 업데이트해야 합니다.

   • 노드의 kubelet 및 Kubernetes kube-apiserver 사이에서 버전 차이를 검토합니다.

     • Kubernetes 버전 1.28부터 kubelet 버전은 kube-apiserver보다 오래된 최대 3개의 마이너 버전에 해당할 수 있습니다. Kubernetes upstream version skew policy를 참조하세요.

     • Fargate 노드 및 관리형 노드의 kubelet가 Kubernetes 버전 1.25 이상인 경우 kubelet 버전으로 업데이트하지 않고 최대 3개 버전까지 클러스터를 업데이트할 수 있습니다. 예를 들어 kubelet 버전이 1.25인 경우 kubelet 버전은 1.25로 유지하면서 Amazon EKS 클러스터 버전을 1.25에서 1.26, 1.27, 1.28로 업데이트할 수 있습니다.

     • Fargate 노드 및 관리형 노드의 Kubernetes가 kubelet 버전 1.24 이상인 경우 kube-apiserver 이상의 최대 2개 마이너 버전만 가능합니다. 즉, kubelet이 버전 1.24 이상인 경우 클러스터를 향후 최대 2개 버전만 업데이트할 수 있습니다. 예를 들어 kubelet 버전이 1.21인 경우 kubelet 버전은 1.21로 유지하면서 Amazon EKS 클러스터 버전을 1.21에서 1.22, 1.23으로 업데이트할 수 있지만, 1.24로는 업데이트할 수 없습니다.

   • 업데이트를 시작하기 전에 모범 사례는 노드의 kubelet 버전이 컨트롤 플레인과 동일한지 Kubernetes 버전인지 확인하는 것입니다.

   • 클러스터가 1.8.0 이전 버전의 Amazon VPC CNI plugin for Kubernetes로 구성된 경우에는 클러스터를 업데이트하기 전에 플러그인을 최신 버전으로 업데이트하는 것이 좋습니다. 플러그인을 업데이트하려면 Amazon VPC CNI를 통해 Pods에 IP 할당을 참조하십시오.

   • 클러스터를 버전 1.25 이상으로 업데이트하고 클러스터에 AWS Load Balancer Controller를 배포한 경우, 클러스터 버전을 1.25로 업데이트하기 전에 컨트롤러를 버전 2.4.7 이상으로 업데이트하십시오. 자세한 내용은 Kubernetes 1.25 릴리스 정보를 참조하세요.

   eksctl

   이 절차에는 eksctl 버전 0.191.0 이상이 필요합니다. 버전은 다음 명령을 통해 확인할 수 있습니다.

   eksctl version
   

   eksctl 설치 또는 업데이트에 대한 지침은 eksctl 설명서에서 Installation을 참조하세요.

   Amazon EKS 컨트롤 플레인의 Kubernetes 버전을 업데이트합니다. my-cluster을 클러스터 이름으로 교체합니다. 1.31을 클러스터를 업데이트하려는 Amazon EKS에서 지원하는 버전 번호로 바꿉니다. 지원되는 버전 번호 목록은 EKS의 Kubernetes 버전 수명 주기 이해 섹션을 참조하세요.

   eksctl upgrade cluster --name my-cluster --version 1.31 --approve
   

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

   AWS Management Console

   1. https://console.aws.amazon.com/eks/home#/clusters에서 Amazon EKS 콘솔을 엽니다.

   2. 업데이트할 Amazon EKS 클러스터의 이름을 선택한 다음 클러스터 버전 업데이트(Update cluster version)를 선택합니다.

   3. Kubernetes 버전에서 클러스터를 업데이트할 버전을 선택하고 업데이트(Update)를 선택합니다.

   4. 클러스터 이름(Cluster name)에 클러스터 이름을 입력하고 확인(Confirm)을 선택합니다.

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

   AWS CLI

   1. 다음 AWS CLI 명령을 사용하여 Amazon EKS 클러스터를 업데이트합니다. example values을 사용자의 값으로 교체합니다. 1.31을 클러스터를 업데이트하려는 Amazon EKS에서 지원하는 버전 번호로 바꿉니다. 지원되는 버전 번호 목록은 EKS의 Kubernetes 버전 수명 주기 이해 섹션을 참조하세요.

      aws eks update-cluster-version --region region-code --name my-cluster --kubernetes-version 1.31
      

      예제 출력은 다음과 같습니다.

      {
          "update": {
              "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f",
              "status": "InProgress",
              "type": "VersionUpdate",
              "params": [
                  {
                      "type": "Version",
                      "value": "1.31"
                  },
                  {
                      "type": "PlatformVersion",
                      "value": "eks.1"
                  }
              ],
      [...]
              "errors": []
          }
      }

   2. 다음 명령을 사용하여 클러스터의 업데이트 상태를 모니터링할 수 있습니다. 이전 명령에서 반환된 클러스터 이름과 업데이트 ID를 사용합니다. Successful 상태가 표시되면 업데이트가 완료됩니다. 업데이트를 완료하는 데 몇 분 정도 걸립니다.

      aws eks describe-update --region region-code --name my-cluster --update-id b5f0ba18-9a87-4450-b5a0-825e6e84496f
      

      예제 출력은 다음과 같습니다.

      {
          "update": {
              "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f",
              "status": "Successful",
              "type": "VersionUpdate",
              "params": [
                  {
                      "type": "Version",
                      "value": "1.31"
                  },
                  {
                      "type": "PlatformVersion",
                      "value": "eks.1"
                  }
              ],
      [...]
              "errors": []
          }
      }

5. 클러스터 업데이트가 완료된 후 업데이트한 클러스터와 동일한 Kubernetes 마이너 버전으로 노드를 업데이트합니다. 자세한 내용은 클러스터의 자체 관리형 노드 업데이트 및 클러스터에 대한 관리형 노드 그룹 업데이트 섹션을 참조하세요. Fargate에서 시작된 새 Pods에는 클러스터 버전과 일치하는 kubelet 버전이 있습니다. 기존 Fargate Pods는 변경되지 않습니다.

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

   1. 웹 브라우저에서 Cluster Autoscaler 릴리스 페이지를 열고 클러스터의 Kubernetes 메이저 및 마이너 버전과 일치하는 최신 Cluster Autoscaler 버전을 검색합니다. 예를 들어 클러스터의 Kubernetes 버전이 1.31이라면 1.31으로 시작하는 Cluster Autoscaler 릴리스를 검색합니다. 다음 단계에서 사용할 해당 릴리스의 의미 체계 버전 번호(예: 1.31.n)를 기록합니다.

   2. 다음 명령을 사용하여 Cluster Autoscaler 이미지 태그를 이전 단계에서 적어 둔 버전으로 설정합니다. 필요한 경우 1.31.n을 고유 값으로 바꿉니다.

      kubectl -n kube-system set image deployment.apps/cluster-autoscaler cluster-autoscaler=registry.k8s.io/autoscaling/cluster-autoscaler:v1.31.n
      

7. (GPU 노드가 있는 클러스터만 해당) 클러스터에 GPU 지원이 포함된 노드 그룹이 있는 경우(예: p3.2xlarge), 클러스터에서 Kubernetes용 NVIDIA 디바이스 플러그인 DaemonSet을(를) 업데이트해야 합니다. 다음 명령을 실행하기 전에 vX.X.X을(를) 원하는 NVIDIA/k8s-device-plugin 버전으로 교체합니다.

   kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/vX.X.X/deployments/static/nvidia-device-plugin.yml
   

8. Amazon VPC CNI plugin for Kubernetes, CoreDNS 및 kube-proxy 추가 기능을 업데이트합니다. 서비스 계정 토큰에 나열된 최소 버전으로 추가 기능을 업데이트하는 것이 좋습니다.

   • Amazon EKS 추가 기능을 사용하는 경우 Amazon EKS 콘솔에서 Clusters(클러스터)를 선택한 다음 왼쪽 검색 창에서 업데이트한 클러스터의 이름을 선택합니다. 콘솔에 알림이 표시됩니다. 사용 가능한 업데이트가 있는 추가 기능마다 새 버전을 사용할 수 있다는 알림이 표시됩니다. 추가 기능을 업데이트하려면 추가 기능(Add-ons) 탭을 선택합니다. 사용 가능한 업데이트가 있는 추가 기능의 상자 중 하나에서 [지금 업데이트(Update now)]를 선택하고 사용 가능한 버전을 선택한 다음 [업데이트(Update)]를 선택합니다.

   • AWS CLI 또는 eksctl을 사용하여 추가 기능을 업데이트할 수도 있습니다. 자세한 내용은 Amazon EKS 추가 기능 업데이트 단원을 참조하십시오.

9. 필요하면 kubectl의 버전을 업데이트합니다. Amazon EKS 클러스터 제어 영역과 마이너 버전이 하나 다른 kubectl 버전을 사용해야 합니다. 예를 들어 1.30 kubectl 클라이언트는 Kubernetes 1.29, 1.30, 1.31 클러스터와 함께 작동합니다. 현재 설치된 버전은 다음과 같은 명령으로 확인할 수 있습니다.

   kubectl version --client