API 호환성이 손상되는 변경에서 AKS(Azure Kubernetes Service) 클러스터 업그레이드를 자동으로 중지

  • 아티클

지원되는 Kubernetes 버전 내에서 유지하려면 클러스터를 일년에 한 번 이상 업그레이드하고 가능한 모든 중단에 대비해야 합니다. 이러한 중단에는 API 호환성이 손상되는 변경, 사용 중단, Helm 및 CSI(Container Storage Interface)와 같은 종속성으로 인한 중단이 포함됩니다. 가동 중지 시간 없이 이러한 중단을 예상하고 중요한 워크로드를 마이그레이션하는 것은 어려울 수 있습니다.

이제 AKS는 사용되지 않는 API를 사용하여 부 버전 변경으로 구성된 업그레이드 작업을 자동으로 중지하고 문제에 대해 경고하는 오류 메시지를 보냅니다.

시작하기 전에

시작하기 전에 다음 필수 조건을 충족하는지 확인합니다.

  • 업그레이드 작업은 클러스터 컨트롤 플레인에 대한 Kubernetes 부 버전 변경입니다.
  • 업그레이드하는 Kubernetes 버전은 1.26 이상입니다.
  • 업그레이드하려는 대상 버전에 대해 사용되지 않는 API의 마지막으로 확인된 사용량은 업그레이드 작업 전 12시간 이내에 발생해야 합니다. AKS는 시간당 사용량을 기록하므로 1시간 이내에 사용되지 않는 API의 사용량은 검색에 표시되지 않을 수 있습니다.

중지된 업그레이드 작업 완화

필수 구성 요소를 충족하는 경우 업그레이드를 시도하고 다음 예제 오류 메시지와 유사한 오류 메시지를 수신합니다.

Bad Request({
  "code": "ValidationError",
  "message": "Control Plane upgrade is blocked due to recent usage of a Kubernetes API deprecated in the specified version. Please refer to https://kubernetes.io/docs/reference/using-api/deprecation-guide to migrate the usage. To bypass this error, set enable-force-upgrade in upgradeSettings.overrideSettings. Bypassing this error without migrating usage will result in the deprecated Kubernetes API calls failing. Usage details: 1 error occurred:\n\t* usage has been detected on API flowcontrol.apiserver.k8s.io.prioritylevelconfigurations.v1beta1, and was recently seen at: 2023-03-23 20:57:18 +0000 UTC, which will be removed in 1.26\n\n",
  "subcode": "UpgradeBlockedOnDeprecatedAPIUsage"
})

문제를 완화하는 두 가지 옵션이 있습니다. 사용되지 않는 API의 사용을 제거(권장)하거나 유효성 검사를 바이패스하여 API 변경 내용을 무시할 수 있습니다.

  1. Azure Portal 클러스터의 개요 페이지로 이동하고 문제 진단 및 해결을 선택합니다.

  2. 만들기, 업그레이드, 삭제 및 크기 조정 범주로 이동하고 Kubernetes API 사용 중단을 선택합니다.

    A screenshot of the Azure portal showing the 'Selected Kubernetes API deprecations' section.

  3. 마지막으로 사용되지 않는 API 사용량이 표시된 시점으로부터 12시간 정도 기다립니다. 사용되지 않는 API 사용량의 동사를 확인하여 조사식인지 확인합니다.

  4. 클러스터 업그레이드를 다시 시도합니다.

컨테이너 인사이트를 사용하도록 설정하고 kube 감사 로그를 탐색하여 과거 API 사용량을 확인할 수도 있습니다. 사용되지 않는 API 사용량의 동사를 확인하여 조사식 사용 사례인지 파악합니다.

유효성 검사를 바이패스하여 API 변경 내용 무시

참고 항목

이 방법을 사용하려면 Azure CLI 버전 2.53 이상을 사용해야 합니다. aks-preview CLI 확장이 설치된 경우 버전 0.5.154 이상으로 업데이트해야 합니다. 대상 Kubernetes 버전에서 사용되지 않는 API가 장기적으로 작동하지 않을 수 있으므로 이 방법은 권장되지 않습니다. 업그레이드가 완료된 후 가능한 한 빨리 제거하는 것이 좋습니다.

  • az aks update 명령을 사용하여 API 호환성이 손상되는 변경을 무시하려면 유효성 검사를 무시합니다. enable-force-upgrade 플래그를 지정하고 upgrade-override-until 속성을 설정하여 유효성 검사가 무시되는 기간의 끝을 정의합니다. 값이 설정되지 않으면 기간이 현재 시간에서 3일 후로 기본 설정됩니다. 지정한 날짜와 시간은 미래여야 합니다.

    az aks update --name myAKSCluster --resource-group myResourceGroup --enable-force-upgrade --upgrade-override-until 2023-10-01T13:00:00Z

    참고 항목

    Z는 'Zulu' 시간이라고도 하는 UTC/GMT 오프셋 0에 대한 영역 지정자입니다. 이 예제에서는 기간 끝을 13:00:00 GMT로 설정합니다. 자세한 내용은 결합된 날짜 및 시간 표현을 참조하세요.

  • 이전 명령이 성공하면 업그레이드 작업을 다시 시도할 수 있습니다.

    az aks upgrade --name myAKSCluster --resource-group myResourceGroup --kubernetes-version <KUBERNETES_VERSION>

다음 단계

이 문서에서는 API 호환성이 손상되는 변경에서 AKS 클러스터 업그레이드를 자동으로 중지하는 방법을 보여 줍니다. AKS 클러스터에 대한 업그레이드 옵션에 대한 자세한 내용은 AKS(Azure Kubernetes Service) 클러스터에 대한 업그레이드 옵션을 참조하세요.