AKS(Azure Kubernetes Service) 클러스터 업그레이드

AKS 클러스터 수명 주기 중 일부에는 최신 Kubernetes 버전으로 정기적으로 업그레이드하는 작업이 포함됩니다. 최신 기능을 가져오려면 최신 보안 릴리스를 적용하고 업그레이드하는 것이 중요합니다. 이 문서에서는 AKS 클러스터에 대한 업그레이드를 확인, 적용하는 방법을 보여 줍니다.

Kubernetes 버전 업그레이드

두 개 이상의 부 버전을 건너뛰는 지원되지 않는 버전 에서 업그레이드를 수행하는 경우 업그레이드는 기능을 보장하지 않으며 서비스 수준 계약 및 제한된 보증에서 제외됩니다. 버전이 만료된 경우 대신 클러스터를 다시 만드는 것이 좋습니다.

시작하기 전에

• Azure CLI를 사용하는 경우 이 문서에서는 Azure CLI 버전 2.34.1 이상이 필요합니다. az --version을 실행하여 버전을 찾습니다. 설치 또는 업그레이드해야 하는 경우 Azure CLI 설치를 참조하세요.
• Azure PowerShell을 사용하는 경우 이 문서에서는 Azure PowerShell 버전 5.9.0 이상이 필요합니다. Get-InstalledModule -Name Az을 실행하여 버전을 찾습니다. 설치 또는 업그레이드해야 하는 경우 Azure PowerShell 설치를 참조하세요.
• 업그레이드 작업을 수행하려면 Microsoft.ContainerService/managedClusters/agentPools/write RBAC 역할이 필요합니다. Azure RBAC 역할에 대한 자세한 내용은 Azure 리소스 공급자 작업을 참조하세요.
• 1.30 kubernetes 버전 및 1.27 LTS 버전부터 베타 API는 업그레이드할 때 기본적으로 사용하지 않도록 설정됩니다.

사용할 수 있는 AKS 클러스터 업그레이드를 위한 확인

자주 묻는 질문(FAQ)

컨트롤 플레인만 업그레이드했습니다. 노드도 업그레이드된 이유는 무엇인가요?

AKS는 클러스터를 준수하고 정상 상태로 유지하기 위해 제어 평면 업그레이드와 함께 또는 이후에 롤링 노드(에이전트 풀) 업그레이드를 트리거할 수 있습니다. 이는 일반적으로 이전 노드 업그레이드가 실패하거나 혼합 버전에서 노드를 떠난 경우에 발생합니다.

AKS 클러스터 업그레이드 오류 메시지 문제 해결

The 'appservice-kube' extension is not compatible with this version of the CLI.
You have CLI core version 2.0.81 and this extension requires a min of 2.34.1.
Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

ERROR: Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

AKS 클러스터 업그레이드

클러스터 업그레이드 프로세스 중에 AKS는 다음 작업을 수행합니다.

• 지정된 Kubernetes 버전을 실행하는 클러스터에 새 버퍼 노드(또는 최대 증가량으로 구성된 노드 수)를 추가합니다.
• 실행 중인 애플리케이션의 중단을 최소화하기 위해 이전 노드 중 하나를 격리하고 드레인합니다. 최대 서지를 사용하는 경우 지정된 버퍼 노드 수만큼 동시에 많은 노드를 격리 및 해제합니다.
• 장기 실행 Pod의 경우 노드 드레이닝 시간 제한을 구성하여 Pod 제거 시 사용자 지정 대기 시간을 허용하고 노드당 정상 종료를 수행할 수 있습니다. 지정하지 않은 경우 기본값은 30분입니다. 허용되는 최소 제한 시간 값은 5분입니다. 드레인 타임아웃의 최대 시간은 24시간입니다.
• 이전 노드가 완전히 드레이닝되면 새 버전을 수신하도록 이미지로 다시 설치되고 다음 노드를 업그레이드할 버퍼 노드가 됩니다.
• 필요에 따라 노드를 드레이닝하고 이미지로 다시 설치하며 다음 노드로 이동하는 동안 대기하는 시간을 설정할 수 있습니다. 간격이 짧으면 업그레이드 프로세스 중에 Grafana 대시보드에서 애플리케이션 상태를 확인하는 등의 다른 작업을 완료할 수 있습니다. 업그레이드 프로세스는 가능한 한 적정하게 0분에 가까운 짧은 시간을 권장합니다. 그렇지 않으면 노드 흡수 시간이 길어질수록 문제를 검색하는 데까지 걸리는 시간에 영향을 줍니다. 최소/최대 흡수 시간 값은 각각 0분과 30분입니다. 지정하지 않은 경우 기본값은 0분입니다.
• 클러스터의 모든 노드가 업그레이드될 때까지 이 프로세스를 반복합니다.
• 프로세스가 끝나면 마지막 버퍼 노드가 삭제되어 기존 에이전트 노드 수와 영역 균형이 유지됩니다.

자동 업그레이드 채널 설정

클러스터에서 자동 업그레이드 채널을 설정할 수 있습니다. 자세한 내용은 AKS 클러스터 자동 업그레이드를 참조하세요.

노드 서지 업그레이드 사용자 지정

기본적으로 AKS는 추가 노드를 한 가지 사용하여 서지로 업그레이드를 구성합니다. 최대 서지 설정의 기본값 1을 사용하면 AKS가 현재 실행 중인 애플리케이션을 cordon 및 드레인하기 전에 추가 노드를 생성하여 이전 버전의 노드를 교체함으로써 워크로드 중단을 최소화할 수 있습니다. 노드 풀당 최대 서지 값을 사용자 지정할 수 있습니다. 최대 서지 값을 늘리면 업그레이드 프로세스가 더 빨리 완료되고 업그레이드 프로세스 중에 중단이 발생할 수 있습니다.

예를 들어, 최대 서지 값 100%은 가능한 가장 빠른 업그레이드 프로세스를 제공하지만, 노드 풀의 모든 노드를 동시에 비웁니다. 테스트 환경에 이와 같은 더 높은 값을 사용할 수 있습니다. 프로덕션 노드 풀의 경우, max_surge 설정을 33%로 설정하는 것을 권장합니다.

AKS는 정수 값과 최대 서지의 백분율 값을 모두 허용합니다. 예를 들어, 정수 값 5는 5개의 추가 노드가 증가할 것을 나타냅니다. 백분율 값 50%은 풀의 현재 노드 수의 절반에 해당하는 급증 값을 의미합니다. 최대 서지 백분율 값은 최소 1% 값 및 최대 100%값일 수 있습니다. 백분율 값은 가장 가까운 노드 수로 반올림 됩니다. 최대 서지 값이 업그레이드에 필요한 노드 수보다 큰 경우 업그레이드할 노드 수를 최대 서지 값으로 사용합니다. 업그레이드하는 동안 최소 서지 값은 0이고 최대 값은 노드 풀의 노드 수와 같을 수 있습니다. 더 큰 값을 설정할 수 있지만, 최대 서지 수에 사용되는 최대 노드 수를 업그레이드 시 풀의 노드 수보다 크게 설정할 수는 없습니다.

최대 서지 값 설정

• az aks nodepool add 또는 az aks nodepool update 명령을 사용하여 새 노드 풀 또는 기존 노드 풀의 최대 서지 값을 설정합니다.

  # Set max surge for a new node pool
  az aks nodepool add --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33%
  
  # Update max surge for an existing node pool 
  az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 5
  

업그레이드하는 동안 사용할 수 없는 노드 사용자 지정

AKS는 서지 노드를 사용하지 않도록 업그레이드를 구성하고 현재 위치에서 노드를 업그레이드할 수도 있습니다. 이 maxUnavailable 값을 사용하여 기존 노드 풀 노드에서 코드 및 드레이닝할 수 있는 노드 수를 결정할 수 있습니다.

AKS는 정수 값과 백분율 값을 maxUnavailable모두 허용합니다. 예를 들어, 5의 정수 값은 노드 풀의 기존 노드에서 5개의 노드가 제한될 것임을 나타냅니다. 백분율 값은 50% 풀에서 현재 노드 수의 절반 값을 나타냅니다 maxUnavailable . maxUnavailable 백분율 값은 최소 1% 값과 최대 100%값일 수 있습니다. 백분율 값은 가장 가까운 노드 수로 반올림 됩니다. 업그레이드하는 동안 값은 maxUnavailable 노드 풀의 0 노드 수와 같은 최소값 및 최대값일 수 있습니다.

maxUnavailable 값 설정

• maxUnvailable 또는 az aks nodepool add 명령을 사용하여 새 노드 풀 또는 기존 노드 풀에 az aks nodepool update 값을 설정합니다.

  # Set maxUnavailable for a new node pool
  az aks nodepool add --name mynodepool --resource-group myResourceGroup --cluster-name myManagedCluster --max-surge 0 --max-unavailable 5
  # Update maxUnavailable for an existing node pool 
  az aks nodepool update --name mynodepool --resource-group myResourceGroup --cluster-name myManagedCluster --max-surge 0 --max-unavailable 5
  # Set maxUnavailable at upgrade time for an existing node pool
  az aks nodepool upgrade --name mynodepool --resource-group myResourceGroup --cluster-name myManagedCluster --max-surge 0 --max-unavailable 5
  

노드 드레이닝 시간 제한 값 설정

경우에 따라 특정 Pod에 장기 실행 워크로드가 있을 수 있으며 런타임 중에 다른 노드로 다시 예약할 수 없습니다(예: 실행을 완료해야 하는 메모리 집약적 상태 저장 워크로드). 이러한 경우 AKS가 업그레이드 워크플로에서 준수할 노드 드레이닝 시간 초과를 구성할 수 있습니다. 노드 드레이닝 시간 제한 값을 지정하지 않으면 기본값은 30분입니다. 허용되는 최소 드레이닝 시간 제한 값은 5분이고 최대 드레이닝 제한 시간은 24시간입니다.

드레이닝 시간 제한 값을 경과하여 Pod가 계속 실행 중인 경우 업그레이드 작업이 중지됩니다. 이후의 PUT 작업에서는 중지된 업그레이드를 다시 시작합니다. 장기 실행 Pod의 경우 [terminationGracePeriodSeconds][https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/]를 구성하는 것도 좋습니다.

• az aks nodepool add 또는 az aks nodepool update 명령을 사용하여 신규 또는 기존 노드 풀에 대한 노드 드레이닝의 시간 초과를 설정합니다.

  # Set drain time-out for a new node pool
  az aks nodepool add --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster  --drain-time-out 100
  
  # Update drain time-out for an existing node pool
  az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --drain-time-out 45
  

노드 흡수 시간 값 설정

노드를 드레이닝하고 이미지로 다시 설치하며 다음 노드로 이동하는 동안 대기하는 시간을 허용하려면 0분에서 30분 사이 값으로 흡수 시간을 설정하면 됩니다. 노드 흡수 시간 값이 지정되지 않은 경우 기본값은 0분입니다.

• az aks nodepool add, az aks nodepool update 또는 az aks nodepool upgrade 명령을 사용하여 새 노드 풀 또는 기존 노드 풀의 노드 흡수 시간을 설정합니다.

  # Set node soak time for a new node pool
  az aks nodepool add --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --node-soak-duration 10
  
  # Update node soak time for an existing node pool
  az aks nodepool update --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 5
  
  # Set node soak time when upgrading an existing node pool
  az aks nodepool upgrade --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 20
  

중요한 버전 드리프트를 통해 업그레이드

지원되지 않는 버전의 Kubernetes에서 지원되는 버전으로 업그레이드하는 경우 대상 버전에서 워크로드를 테스트하는 것이 중요합니다. AKS는 컨트롤 플레인 및 데이터 평면을 업그레이드하기 위해 모든 노력을 기울이지만 워크로드가 계속 작동할 것이라는 보장은 없습니다. 워크로드가 더 이상 사용되지 않는 Kubernetes API를 사용하는 경우 플랫폼은 호환성이 손상되는 변경 또는 동작(AKS 릴리스 정보에 설명되어 있음)을 도입했습니다. 이러한 문제는 해결해야 합니다.

이러한 상황에서는 클러스터의 현재 위치 업그레이드를 수행하기 전에 새 버전에서 워크로드를 테스트하고 버전 문제를 해결하는 것이 좋습니다.

이 상황에서 일반적인 패턴은 지원되는 Kubernetes 버전에 있는 새 클러스터에 수정된 워크로드의 파란색/녹색 배포를 수행하고 요청을 새 클러스터로 라우팅하는 것입니다.

업그레이드 이벤트 확인

• kubectl get events 명령을 사용하여 업그레이드 이벤트를 확인합니다.

  kubectl get events 
  

  다음 예제 출력은 업그레이드 중에 발생하는 상기 이벤트 중 일부를 보여 줍니다.

  ...
  default 2m1s Normal Drain node/aks-nodepool1-96663640-vmss000001 Draining node: [aks-nodepool1-96663640-vmss000001]
  ...
  default 1m45s Normal Upgrade node/aks-nodepool1-96663640-vmss000001   Soak duration 5m0s after draining node: aks-nodepool1-96663640-vmss000001
  ...
  default 9m22s Normal Surge node/aks-nodepool1-96663640-vmss000002 Created a surge node [aks-nodepool1-96663640-vmss000002 nodepool1] for agentpool nodepool1
  ...
  

kubectl에 대한 Client-Server 버전 호환성

호환성을 유지하기 위해 kubectl 클라이언트가 AKS 컨트롤 플레인(API 서버)의 ±1 부 버전 내에 있는지 확인합니다. 지원되는 버전 기울이기를 초과하면 명령 오류 또는 예기치 않은 동작이 발생할 수 있습니다. 다음 명령은 클라이언트 버전과 서버 버전을 모두 표시하고 동기화가 없으면 경고합니다.

kubectl version

버전이 일치하지 않는 경우:

• kubectl을 업데이트하거나 다운그레이드하여 서버 버전에 맞춥니다.
• 또는 로컬 kubectl을 변경할 수 없는 경우 Azure CLI의 az aks command invoke 명령을 사용하여 클러스터에서 kubectl 명령을 원격으로 실행하는 것이 좋습니다.

다음 단계

자동 업그레이드를 구성하는 방법을 알아보려면 AKS 클러스터에 대한 자동 업그레이드 구성을 참조하세요.

업그레이드 모범 사례 및 기타 고려 사항에 대한 자세한 내용은 AKS 패치 및 업그레이드 지침을 참조하세요.