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

아티클
09/30/2024

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

개요

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

더 이상 사용되지 않는 API를 사용한 부 버전 변경으로 구성된 업그레이드 작업을 자동으로 중지하고 문제에 대해 경고하도록 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 변경 내용을 무시하는 것입니다.

사용되지 않는 API 사용 제거(권장)

Azure Portal에서 클러스터 리소스로 이동하여 문제 진단 및 해결을 선택합니다.
만들기, 업그레이드, 삭제 및 크기 조정>Kubernetes API 사용 중단을 선택합니다.
마지막으로 사용되지 않는 API 사용량이 표시된 시점으로부터 12시간 정도 기다립니다. 읽기 전용 동사는 더 이상 사용되지 않는 api 사용, 즉 Get/List/Watch에서 제외됩니다.( 컨테이너 인사이트를 사용하도록 설정하고 kube 감사 로그를 탐색하여 과거 API 사용량을 확인할 수도 있습니다.)
클러스터 업그레이드를 다시 시도합니다.

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

참고 항목

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

유효성 검사를 우회하여 API 호환성이 손상되는 변경 내용을 무시하고 업그레이드를 호출합니다. enable-force-upgrade 플래그를 지정하고 upgrade-override-until 속성을 설정하여 유효성 검사가 무시되는 기간의 끝을 정의합니다. 값이 설정되지 않으면 기간이 현재 시간에서 3일 후로 기본 설정됩니다. 지정한 날짜와 시간은 미래여야 합니다.
```
az aks upgrade --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP_NAME --kubernetes-version $KUBERNETES_VERSION --enable-force-upgrade --upgrade-override-until 2023-10-01T13:00:00Z
```
참고 항목

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

다음 단계

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

다음을 통해 공유