클러스터용 하이브리드 노드 업그레이드

하이브리드 노드의 Kubernetes 버전을 업그레이드하는 방법(cutover 마이그레이션 및 인플레이스)을 설명합니다.

출처: 문서

본문

하이브리드 노드 업그레이드 지침은 Amazon EC2에서 실행되는 자체 관리형 Amazon EKS 노드와 유사합니다. 대상 Kubernetes 버전에 새 하이브리드 노드를 만들고, 기존 애플리케이션을 새 Kubernetes 버전의 하이브리드 노드로 원활하게 마이그레이션한 다음, 이전 Kubernetes 버전의 하이브리드 노드를 클러스터에서 제거할 것을 권장합니다. 업그레이드를 시작하기 전에 반드시 Amazon EKS Best Practices for upgrades를 검토하세요. Amazon EKS Hybrid Nodes는 클라우드 노드가 있는 Amazon EKS 클러스터와 동일한 Kubernetes 버전 지원을 가지며, 표준 및 확장 지원을 포함합니다.

Amazon EKS Hybrid Nodes는 노드에 대해 업스트림 Kubernetes와 동일한 버전 스큐(skew) 정책을 따릅니다. Amazon EKS Hybrid Nodes는 Amazon EKS 컨트롤 플레인보다 최신 버전일 수 없으며, 하이브리드 노드는 Amazon EKS 컨트롤 플레인 마이너 버전보다 최대 3개 Kubernetes 마이너 버전까지 오래될 수 있습니다.

cutover 마이그레이션 업그레이드 전략을 위해 대상 Kubernetes 버전에 새 하이브리드 노드를 만들 여유 용량이 없다면 Amazon EKS Hybrid Nodes CLI(nodeadm)로 하이브리드 노드의 Kubernetes 버전을 인플레이스로 업그레이드할 수 있습니다.

중요

nodeadm으로 하이브리드 노드를 인플레이스로 업그레이드한다면, 이전 버전의 Kubernetes 구성 요소가 종료되고 새 Kubernetes 버전 구성 요소가 설치되고 시작되는 과정에서 노드에 가동 중단 시간이 발생합니다.

SSM 자격 증명 공급자에 필요한 nodeadm 버전

AWS Systems Manager(SSM)를 하이브리드 노드의 자격 증명 공급자로 사용한다면 새 설치와 업그레이드에 nodeadm 버전 1.0.19 이상을 사용해야 합니다. 이전 버전의 nodeadm은 오래된 SSM 서명 키를 포함하고 있으며 nodeadm install 및 nodeadm upgrade 중 다음 서명 검증 오류로 실패합니다.

{"msg":"Command failed","error":"failed to install ssm installer: validating ssm-setup-cli signature: Signature Verification Error: No matching signature"}

이 오류를 해결하려면 nodeadm install 또는 nodeadm upgrade를 실행하기 전에 최신 버전의 nodeadm을 다운로드하세요.

사전 요구 사항

업그레이드 전에 다음 사전 요구 사항을 완료했는지 확인하세요.

하이브리드 노드 업그레이드의 대상 Kubernetes 버전은 Amazon EKS 컨트롤 플레인 버전과 같거나 작아야 합니다.
cutover 마이그레이션 업그레이드 전략을 따르는 경우 대상 Kubernetes 버전에 설치하는 새 하이브리드 노드는 하이브리드 노드 사전 요구 사항 설정 요구 사항을 충족해야 합니다. 여기에는 Amazon EKS 클러스터 생성 중 전달한 Remote Node Network CIDR 내의 IP 주소가 포함됩니다.
cutover 마이그레이션과 인플레이스 업그레이드 모두에서 하이브리드 노드는 새 하이브리드 노드 의존성 버전을 가져오기 위해 필요한 도메인에 접근할 수 있어야 합니다.
Amazon EKS Kubernetes API 엔드포인트와 상호 작용하는 데 사용하는 로컬 머신 또는 인스턴스에 kubectl이 설치되어 있어야 합니다.
CNI 버전이 업그레이드 대상 Kubernetes 버전을 지원해야 합니다. 지원하지 않는다면 하이브리드 노드를 업그레이드하기 전에 CNI 버전을 업그레이드하세요. 자세한 내용은 하이브리드 노드용 CNI 구성을 참조하세요.

Cutover 마이그레이션(블루-그린) 업그레이드

cutover 마이그레이션 업그레이드는 대상 Kubernetes 버전으로 새 호스트에 새 하이브리드 노드를 만들고, 기존 애플리케이션을 대상 Kubernetes 버전의 새 하이브리드 노드로 원활하게 마이그레이션한 다음, 이전 Kubernetes 버전의 하이브리드 노드를 클러스터에서 제거하는 과정을 말합니다. 이 전략을 블루-그린 마이그레이션이라고도 합니다.

하이브리드 노드 연결 단계에 따라 새 호스트를 하이브리드 노드로 연결합니다. nodeadm install 명령을 실행할 때 대상 Kubernetes 버전을 사용하세요.
대상 Kubernetes 버전의 새 하이브리드 노드와 이전 Kubernetes 버전의 하이브리드 노드 사이의 통신을 활성화합니다. 이 구성은 워크로드를 대상 Kubernetes 버전의 하이브리드 노드로 마이그레이션하는 동안 Pod가 서로 통신할 수 있게 합니다.
대상 Kubernetes 버전의 하이브리드 노드가 클러스터에 성공적으로 조인했고 Ready 상태인지 확인합니다.
다음 명령을 사용하여 제거하려는 각 노드를 스케줄링 불가(unschedulable)로 표시합니다. 이렇게 하면 교체 중인 노드에 새 Pod가 스케줄링되거나 재스케줄링되지 않습니다. 자세한 내용은 Kubernetes 문서의 kubectl cordon을 참조하세요. NODE_NAME을 이전 Kubernetes 버전의 하이브리드 노드 이름으로 바꾸세요.

kubectl cordon NODE_NAME

특정 Kubernetes 버전(여기서는 1.28)의 모든 노드를 식별하고 cordon하려면 다음 코드 스니펫을 사용할 수 있습니다.

K8S_VERSION=1.28
for node in $(kubectl get nodes -o json | jq --arg K8S_VERSION "$K8S_VERSION" -r '.items[] | select(.status.nodeInfo.kubeletVersion | match("\($K8S_VERSION)")).metadata.name')
do
    echo "Cordoning $node"
    kubectl cordon $node
done

현재 배포에서 하이브리드 노드에 CoreDNS 복제본이 2개 미만으로 실행 중이라면 배포를 최소 2개의 복제본으로 확장합니다. 정상 운영 중 탄력성을 위해 하이브리드 노드에 최소 2개의 CoreDNS 복제본을 실행할 것을 권장합니다.

kubectl scale deployments/coredns --replicas=2 -n kube-system

다음 명령으로 클러스터에서 제거하려는 이전 Kubernetes 버전의 각 하이브리드 노드를 드레인(drain)합니다. 노드 드레인에 대한 자세한 내용은 Kubernetes 문서의 노드 안전하게 드레인(Safely Drain a Node)을 참조하세요. NODE_NAME을 이전 Kubernetes 버전의 하이브리드 노드 이름으로 바꾸세요.

kubectl drain NODE_NAME --ignore-daemonsets --delete-emptydir-data

특정 Kubernetes 버전(여기서는 1.28)의 모든 노드를 식별하고 드레인하려면 다음 코드 스니펫을 사용할 수 있습니다.

K8S_VERSION=1.28
for node in $(kubectl get nodes -o json | jq --arg K8S_VERSION "$K8S_VERSION" -r '.items[] | select(.status.nodeInfo.kubeletVersion | match("\($K8S_VERSION)")).metadata.name')
do
    echo "Draining $node"
    kubectl drain $node --ignore-daemonsets --delete-emptydir-data
done

nodeadm을 사용하여 호스트에서 하이브리드 노드 아티팩트를 중지하고 제거할 수 있습니다. root/sudo 권한이 있는 사용자로 nodeadm을 실행해야 합니다. 기본적으로 노드에 남아 있는 Pod가 있으면 nodeadm uninstall은 진행하지 않습니다. 자세한 내용은 Hybrid nodes nodeadm reference를 참조하세요.

nodeadm uninstall

하이브리드 노드 아티팩트가 중지되고 제거되었으면 클러스터에서 노드 자원을 제거합니다.

kubectl delete node node-name

특정 Kubernetes 버전(여기서는 1.28)의 모든 노드를 식별하고 삭제하려면 다음 코드 스니펫을 사용할 수 있습니다.

K8S_VERSION=1.28
for node in $(kubectl get nodes -o json | jq --arg K8S_VERSION "$K8S_VERSION" -r '.items[] | select(.status.nodeInfo.kubeletVersion | match("\($K8S_VERSION)")).metadata.name')
do
    echo "Deleting $node"
    kubectl delete node $node
done

CNI 선택에 따라 위 단계를 실행한 후 하이브리드 노드에 남아 있는 아티팩트가 있을 수 있습니다. 자세한 내용은 하이브리드 노드용 CNI 구성을 참조하세요.

인플레이스 업그레이드

인플레이스 업그레이드 과정은 새 물리적 또는 가상 호스트와 cutover 마이그레이션 전략 없이 nodeadm upgrade로 하이브리드 노드의 Kubernetes 버전을 업그레이드하는 것을 말합니다. nodeadm upgrade 과정은 하이브리드 노드에서 실행 중인 기존 이전 Kubernetes 구성 요소를 종료하고, 기존 이전 Kubernetes 구성 요소를 제거하며, 새 대상 Kubernetes 구성 요소를 설치하고, 새 대상 Kubernetes 구성 요소를 시작합니다. 하이브리드 노드에서 실행되는 애플리케이션에 대한 영향을 최소화하려면 한 번에 하나의 노드만 업그레이드할 것을 적극 권장합니다. 이 과정의 기간은 네트워크 대역폭과 지연 시간에 따라 다릅니다.

다음 명령을 사용하여 업그레이드 중인 노드를 스케줄링 불가로 표시합니다. 이렇게 하면 업그레이드 중인 노드에 새 Pod가 스케줄링되거나 재스케줄링되지 않습니다. 자세한 내용은 Kubernetes 문서의 kubectl cordon을 참조하세요. NODE_NAME을 업그레이드 중인 하이브리드 노드의 이름으로 바꾸세요.

kubectl cordon NODE_NAME

다음 명령으로 업그레이드 중인 노드를 드레인합니다. 노드 드레인에 대한 자세한 내용은 Kubernetes 문서의 노드 안전하게 드레인(Safely Drain a Node)을 참조하세요. NODE_NAME을 업그레이드 중인 하이브리드 노드의 이름으로 바꾸세요.

kubectl drain NODE_NAME --ignore-daemonsets --delete-emptydir-data

업그레이드 중인 하이브리드 노드에서 nodeadm upgrade를 실행합니다. root/sudo 권한이 있는 사용자로 nodeadm을 실행해야 합니다. 노드 이름은 AWS SSM과 AWS IAM Roles Anywhere 자격 증명 공급자 모두에서 업그레이드 과정을 통해 유지됩니다. 업그레이드 과정에서 자격 증명 공급자를 변경할 수 없습니다. nodeConfig.yaml의 구성 값은 Hybrid nodes nodeadm reference를 참조하세요. K8S_VERSION을 업그레이드하려는 대상 Kubernetes 버전으로 바꾸세요.

nodeadm upgrade K8S_VERSION -c file://nodeConfig.yaml

업그레이드 후 노드에 Pod가 스케줄링될 수 있도록 다음을 입력합니다. NODE_NAME을 노드 이름으로 바꾸세요.

kubectl uncordon NODE_NAME

하이브리드 노드의 상태를 관찰하고 노드가 종료되어 새 Kubernetes 버전에서 Ready 상태로 다시 시작될 때까지 기다립니다.

kubectl get nodes -o wide -w

더 알아보기 (Learn more)

공식 문서