AKS 클러스터 마이그레이션

GKE 연결 클러스터의 이전 버전을 GKE 연결 클러스터(이전 세대)라고 합니다. 이전 버전의 GKE 연결 클러스터에서 현재 세대로 마이그레이션하면 수명 주기 관리 및 Fleet 등록을 포함하여 이 기능에 액세스할 수 있습니다. 마이그레이션은 단방향 작업입니다. GKE 연결 클러스터의 현재 세대로 마이그레이션한 다음에는 GKE 연결 클러스터(이전 세대)로 돌아갈 방법이 없습니다.

버전 번호 지정 정책

이 문서에서는 Kubernetes 버전과 구분하기 위해 GKE 연결 클러스터 버전을 플랫폼 버전이라고 부릅니다. GKE 연결 클러스터는 1.21.5-gke.1과 같이 GKE와 동일한 버전 번호 지정 규칙을 따릅니다. 클러스터를 연결하거나 업데이트할 때는 부 버전이 클러스터의 Kubernetes 버전보다 한 단계 낮거나 동일한 플랫폼 버전을 선택해야 합니다. 예를 들어 Kubernetes v1.22.*를 실행하는 클러스터를 GKE 연결 클러스터 플랫폼 버전 1.21.* 또는 1.22.*와 연결할 수 있습니다.

이렇게 하면 GKE 연결 클러스터를 업그레이드하기 전에 다음 부 버전으로 클러스터를 업그레이드할 수 있습니다.

워크로드 아이덴티티가 사용 설정되어 있는지 확인

GKE 연결 클러스터(이전 세대)의 기존 클러스터가 현재 세대의 GKE 연결 클러스터로 마이그레이션되기 전 워크로드 아이덴티티가 사용 설정되어 있어야 합니다.

WI가 사용 설정되어 있는지 확인하려면 다음 명령어를 실행하고 워크로드 아이덴티티 필드의 출력을 확인합니다.

gcloud container hub memberships describe MEMBERSHIP_NAME

워크로드 아이덴티티가 사용 설정되어 있지 않으면 멤버십을 업데이트하여 이를 사용 설정해야 합니다.

클러스터 멤버십을 업데이트하는 명령어는 기본 비공개 OIDC 발급기관 또는 실험용 공개 OIDC 발급기관으로 구성했는지 여부에 따라 약간 달라집니다. 클러스터에 적용되는 탭을 선택합니다.

비공개 OIDC 발급기관(기본값)

gcloud container hub memberships register MEMBERSHIP_NAME \
--context=KUBECONFIG_CONTEXT \
--kubeconfig=KUBECONFIG_PATH \
--enable-workload-identity \
--has-private-issuer

다음과 같이 바꿉니다.

MEMBERSHIP_NAME: 클러스터의 멤버십 이름
KUBECONFIG_CONTEXT: AKS 클러스터에 액세스하기 위한 kubeconfig의 컨텍스트
KUBECONFIG_PATH: kubeconfig 파일의 경로

공개 OIDC 발급기관

다음 명령어를 사용하여 클러스터의 OIDC 발급기관 URL을 검색합니다.

  az aks show -n CLUSTER_NAME \
    -g RESOURCE_GROUP \
    --query "oidcIssuerProfile.issuerUrl" -otsv

이 명령어의 출력은 OIDC 발급기관의 URL입니다. 나중에 사용할 수 있도록 이 값을 저장하세요.

멤버십을 업데이트합니다.

gcloud container fleet memberships register MEMBERSHIP_NAME \
--context=KUBECONFIG_CONTEXT \
--kubeconfig=KUBECONFIG_PATH \
--enable-workload-identity \
--public-issuer-url=OIDC_URL

다음과 같이 바꿉니다.

MEMBERSHIP_NAME: 클러스터의 멤버십 이름
KUBECONFIG_CONTEXT: AKS 클러스터에 액세스하기 위한 kubeconfig의 컨텍스트
KUBECONFIG_PATH: kubeconfig 경로
OIDC_URL: 앞에서 검색한 OIDC URL

클러스터 마이그레이션

GKE 연결 클러스터(이전 세대)에서 GKE 연결 클러스터로 클러스터를 마이그레이션하려면 다음 안내를 따르세요.

클러스터의 kubeconfig 컨텍스트를 추출하고 이를 KUBECONFIG_CONTEXT 환경 변수에 저장합니다.
```
KUBECONFIG_CONTEXT=$(kubectl config current-context)
```
다음 명령어를 실행하여 클러스터를 GKE 연결 클러스터의 현재 세대로 마이그레이션합니다. 이 명령어는 클러스터 구성의 관련 세부정보를 추출하고 클러스터를 Google Fleet Management에 등록하고, 수명 주기 에이전트와 같은 모든 필수 소프트웨어를 클러스터에 설치하거나 업그레이드합니다.
```
gcloud container attached clusters import \
  --location=GOOGLE_CLOUD_REGION \
  --fleet-membership=FLEET_MEMBERSHIP \
  --platform-version=PLATFORM_VERSION \
  --distribution=CLUSTER_DISTRIBUTION \
  --context=KUBECONFIG_CONTEXT \
  [--kubeconfig=KUBECONFIG_PATH]
```
다음과 같이 바꿉니다.
- GOOGLE_CLOUD_REGION: 클러스터가 관리되는 Google Cloud 위치
- FLEET_MEMBERSHIP: 등록된 클러스터의 정규화된 멤버십 지정자입니다(아래 참조).
- PLATFORM_VERSION: 마이그레이션할 GKE 연결 클러스터의 버전입니다(예: v1.22.0-gke.1).
- CLUSTER_DISTRIBUTION: 클러스터 유형 - AWS의 Elastic Kubernetes Service의 경우 eks, Azure Kubernetes Service의 경우 aks, 또는 기타 배포의 경우 generic입니다.
- KUBECONFIG_CONTEXT: 클러스터를 연결할 kubeconfig의 컨텍스트 이름입니다.
- KUBECONFIG_PATH: kubeconfig 파일의 위치. 지정하지 않으면 기본값이 ~/.kube/config입니다.
멤버십 지정자는 연결된 클러스터를 고유하게 식별하는 projects/PROJECT_NUMBER/locations/global/memberships/MEMBERSHIP_ID 형식의 문자열입니다. 자세한 내용은 다음과 같습니다.
- PROJECT_NUMBER: Fleet 호스트 프로젝트 번호입니다. 클러스터가 현재 속한 것과 동일한 프로젝트 번호를 지정해야 합니다.
- MEMBERSHIP_ID: 기존 클러스터의 Fleet 멤버십 ID여야 합니다. GKE 연결 클러스터에서 이 값이 클러스터 이름으로 사용됩니다.

Azure 워크로드 아이덴티티 지원

Azure는 공개 미리보기 버전으로 WI 지원을 제공합니다. 이 기능을 사용 설정하면 클러스터의 OIDC 발급자 URL이 변경됩니다. 이전 OIDC URL로 클러스터를 이미 등록한 경우 해당 필드를 현재 업데이트할 수 없으므로 새 URL로 업데이트할 수 없습니다.

이 문제를 해결하려면 다음 안내를 따르세요.

워크로드 아이덴티티가 사용 설정된 클러스터를 다시 만듭니다.
AKS 클러스터를 연결합니다.
워크로드를 새 클러스터로 마이그레이션합니다.
이전 클러스터를 삭제합니다.