apigeectl에서 Apigee Hybrid를 Helm으로 마이그레이션

이 마이그레이션 도구는 apigeectl 기반 하이브리드 클러스터를 Helm 기반 하이브리드 클러스터로 마이그레이션하는 데 도움이 됩니다. 이 도구는 클러스터 구성요소를 실제로 교체하지 않습니다. 멱등성이며 같은 클러스터에서 여러 번 실행되므로 매번 구성요소 및 조직의 하위 집합을 준비할 수 있습니다.

모든 apigee 구성요소를 한 번에 마이그레이션할 수 있으며 도구가 실행된 후에 구성요소별로 Helm 업그레이드 작업을 수행할 수 있습니다.

이 도구를 사용하여 Helm 관리로 마이그레이션한 하이브리드 클러스터 관리에 대한 자세한 내용은 Helm 차트를 사용하여 Apigee Hybrid 설치 및 관리를 참조하세요.

기본 요건

Helm 버전 v3.14.2 이상
Apigee Hybrid 1.12 설치가 작동하는 클러스터를 가리키는 작동 중인 kubeconfig 파일
마이그레이션하려는 하이브리드 구성요소의 Kubernetes 리소스에서 메타데이터와 주석을 수정할 수 있는 권한

범위

이 도구는 런타임에 다음 옵션을 지원합니다.

apigee 리소스의 네임스페이스 맞춤설정. 기본 네임스페이스: apigee
선택한 하이브리드 구성요소만 마이그레이션. 기본값: 모든 구성요소 마이그레이션
단일 조직만 마이그레이션
단일 환경만 마이그레이션
단일 환경 그룹(apigee-virtualhost)만 마이그레이션
조직, 환경, 환경 그룹의 Helm 출시 이름 맞춤설정

제한사항

이 도구는 apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry, apigee-ingress-manager 하이브리드 구성요소의 Helm 출시 이름 맞춤설정을 지원하지 않습니다.
조직, 환경, 환경 그룹의 Helm 출시 이름에 대한 대화형 맞춤설정은 실행 간에 자동으로 유지되지 않습니다. 임시 파일을 수정하고 나중에 실행할 때 옵션으로 제공할 수 있습니다.
환경 및 환경 그룹 필터링은 이름을 기준으로만 수행됩니다. 경우에 따라 멀티 조직 클러스터에서 여러 환경과 환경 그룹이 마이그레이션될 수 있습니다.

예를 들어 조직 org1 및 org2가 있는 멀티 조직 클러스터에서 환경 prod가 두 조직에 있고 --env=prod만 지정된 경우 두 환경 모두 마이그레이션됩니다. 단일 환경만 마이그레이션하려면 조직 필터 --org=org1 또는 --org=org2도 지정해야 합니다.

사용

구문

apigee-helm-migration [--apigee-namespace=] [--components=] [--dry-run] [--env=org1] [--env-group=org2] [--org=baz] [--kubeconfig=] [-y] [-v] [-f /path/to/releaseNames.yaml]

생성된 Helm 출시 이름

클러스터에 배포되는 모든 Helm 차트에는 네임스페이스 내에서 고유해야 하는 출시 이름이 있어야 합니다. Helm 출시 이름에는 차트 이름과 관련된 이름 지정 규칙이나 제한사항이 없습니다. 마이그레이션 도구는 모든 구성요소에 고유한 Helm 출시 이름을 생성합니다.

차트	단일 조직 클러스터	멀티 조직 클러스터
`apigee-operator`	`operator`	`operator`
`apigee-datastore`	`datastore`	`datastore`
`apigee-telemetry`	`telemetry`	`telemetry`
`apigee-redis`	`redis`	`redis`
`apigee-ingress-manager`	`ingress-manager`	`ingress-manager`
`apigee-org`	`ORG_NAME`	`ORG_NAME`
`apigee-env`	`ENV_NAME[-env[-n]]⁽¹⁾`	`ORG_NAME-ENV_NAME[-env[-n]]`⁽¹⁾
`apigee-virtualhost (envgroup)`	`VH_NAME[-env-group[-n]]`⁽¹⁾	`ORG_NAME-VH_NAME[-env-group[-n]]`⁽¹⁾
⁽¹⁾ 생성된 이름이 생성된 다른 이름과 충돌하면 이름에 `-env` 또는 `-env-group` 서픽스가 추가됩니다. 계속 충돌하면 `-1` 또는 `-2 …` 서픽스가 추가됩니다.

Helm 출시 이름 맞춤설정

마이그레이션 도구는 Helm 출시 이름의 대화형 맞춤설정을 허용합니다. Helm 출시 이름을 비대화형으로 맞춤설정하려면 다음 안내를 따르세요.

도구를 한 번 실행하고 첫 번째 프롬프트에서 종료하여 자동 생성된 출시 이름이 포함된 임시 파일을 만듭니다. 다음과 같은 줄이 표시됩니다.
```
INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
```
이 파일을 이동하거나 복사한 후에 수정합니다. 마이그레이션 도구를 실행할 때 -f 옵션을 사용하여 이 수정된 파일을 전달할 수 있습니다. 자동 생성된 출시 이름은 다음과 같습니다.
```
orgs:
  example-apigee-org:
    helmReleaseName: example-apigee-org
    envs:
      prod:
        helmReleaseName: prod
    envGroups:
      prod-envgroup:
        helmReleaseName: prod-envgroup
```
조직, 환경 또는 환경 그룹의 Helm 출시 이름을 맞춤설정하려면 해당 객체의 helmReleaseName 필드를 수정합니다. 예를 들어 조직 출시 이름을 custom-org로, 환경 출시 이름을 custom-env로, 환경 그룹 출시 이름을 custom-group으로 바꾸면 결과 파일은 다음과 같습니다.
```
orgs:
  example-apigee-org:
    helmReleaseName: custom-org
    envs:
      prod:
        helmReleaseName: custom-env
    envGroups:
      prod-envgroup:
        helmReleaseName: custom-group
```

커스텀 네임스페이스 사용

Apigee Hybrid는 두 개의 Kubernetes 네임스페이스에서 실행됩니다.

apigee-system: apigee-operator 구성요소는 항상 apigee-system 네임스페이스에서 실행됩니다. Helm 마이그레이션 도구는 --apigee-namespace 플래그로 지정한 항목에 관계없이 apigee-system 네임스페이스의 apigee-operator 구성요소를 업데이트합니다.
apigee: apigee-operator를 제외한 모든 Hybrid 구성요소가 이 네임스페이스에서 실행됩니다. apigee는 기본 이름입니다. 이러한 구성요소에 대해 커스텀 네임스페이스를 사용할 수 있습니다.
커스텀 네임스페이스를 사용하는 경우 Helm 마이그레이션 도구를 실행할 때 --apigee-namespace my_custom_namespace 플래그와 함께 커스텀 마이그레이션을 지정해야 합니다.

또한 namespace: my_custom_namespace 최상위 속성을 재정의 파일에 추가해야 합니다.

지침

마이그레이션 도구를 다운로드합니다.
Linux
1. 다음 명령어를 사용하여 최신 버전 번호를 변수에 저장합니다.
  export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
2. 다음 명령어를 사용하여 변수가 버전 번호로 채워졌는지 확인합니다. 다른 버전을 사용하려면 대신 환경 변수에 저장하면 됩니다.
  echo $VERSION
  예를 들면 다음과 같습니다.
  echo $VERSION 1.0.5
3. 다음 명령어를 사용하여 운영체제용 출시버전 패키지를 다운로드합니다.
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_linux_64.tar.gz
4. 다음 명령어를 사용하여 압축 파일을 압축 해제합니다.
  tar -xzf apigee-helm-migration_linux_64.tar.gz
Mac OS
1. 다음 명령어를 사용하여 최신 버전 번호를 변수에 저장합니다.
  export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
2. 다음 명령어를 사용하여 변수가 버전 번호로 채워졌는지 확인합니다. 다른 버전을 사용하려면 대신 환경 변수에 저장하면 됩니다.
  echo $VERSION
  예를 들면 다음과 같습니다.
  echo $VERSION 1.0.5
3. 다음 명령어를 사용하여 운영체제용 출시버전 패키지를 다운로드합니다.
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_mac_64.tar.gz
4. 다음 명령어를 사용하여 압축 파일을 압축 해제합니다.
  tar -xzf apigee-helm-migration_mac_64.tar.gz
Windows
1. 다음 명령어를 사용하여 최신 버전 번호를 변수에 저장합니다.
  for /f "tokens=*" %a in ('curl -s https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt') do set VERSION=%a
2. 다음 명령어를 사용하여 변수가 버전 번호로 채워졌는지 확인합니다. 다른 버전을 사용하려면 대신 환경 변수에 저장하면 됩니다.
  echo %VERSION%
  예를 들면 다음과 같습니다.
  echo %VERSION% 1.0.5
3. 다음 명령어를 사용하여 운영체제용 출시버전 패키지를 다운로드합니다.
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/%VERSION%/apigee-helm-migration_windows_64.tar.gz
4. 다음 명령어를 사용하여 압축 파일을 압축 해제합니다.
  tar xzvf apigee-helm-migration_windows_64.tar.gz

마이그레이션 도구를 실행합니다. 기본 옵션이 허용되면 인수 없이 도구를 실행할 수 있으며 생성된 helm 출시 이름이 충족되면 프롬프트를 승인할 수 있습니다. 다음은 몇 가지 시나리오의 예시입니다.

멀티 조직 업데이트의 경우 모든 조직과 환경 구성요소를 업그레이드하는 옵션을 사용하지 않고 apigee-helm-migration을 실행하는 것이 좋습니다.

기본 kubeconfig(~/.kube/config), 기본 apigee 네임스페이스, 기본 Helm 출시 이름을 사용하는 간단한 설치

대부분의 경우(모든 경우가 아님) 다음 명령어로 설치할 수 있습니다. 도구가 실행된 후 구성요소별로 Helm 업그레이드 작업을 수행할 수 있습니다.
```
./apigee-helm-migration
```

커스텀 네임스페이스를 사용하여 모든 구성요소 마이그레이션:
```
./apigee-helm-migration --apigee-namespace my_custom_namespace
```

operator 및 datastore 구성요소만 마이그레이션합니다.

./apigee-helm-migration --components operator,datastore

  INFO: 00:22:48 using kubeconfig file  /usr/local/google/home/example/.kube/config
  INFO: 00:22:48 namespace for apigee resources:
  INFO: 00:22:48 	 apigee
  INFO: 00:22:48 processing all organizations in cluster
  INFO: 00:22:48 Components to migrate:
  INFO: 00:22:48 	 operator,datastore
  INFO: 00:22:48 dry-run:
  INFO: 00:22:48 	 false
  Continue with patching apigee resources for Helm migration? [y/n]: y
  INFO: 00:22:52 Processing component:  operator
  INFO: 00:22:54 Processing component:  datastore
  INFO: 00:22:55 Migration successful!

특정 kubeconfig 파일을 가리키고 apigee 네임스페이스에 다른 이름을 지정합니다.
```
./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
```
모든 구성요소(단일 조직만)를 마이그레이션합니다.
```
./apigee-helm-migration --org=some-test-org
```

다음은 성공적인 마이그레이션 출력 예시입니다.

INFO: 21:32:55 using kubeconfig file  /usr/local/google/home/example/.kube/config
INFO: 21:32:55 namespace for apigee resources:
INFO: 21:32:55 	 apigee
INFO: 21:32:55 processing all organizations in cluster
INFO: 21:32:55 processing all components
INFO: 21:32:55 dry-run:
INFO: 21:32:55 	 false
INFO: 21:32:55 cluster Apigee information:
INFO: 21:32:55 Apigee Organizations found:
INFO: 21:32:56 	 example-hybrid-dev
INFO: 21:32:56 Apigee Environments found (org: env):
INFO: 21:32:56 	 example-hybrid-dev : prod
INFO: 21:32:56 Apigee EnvGroups(apigeerouteconfigs) found (org: envGroup):
INFO: 21:32:56 	 example-hybrid-dev : prod-envgroup
INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
INFO: 21:32:56 Helm release names for Apigee orgs/envs/envgroups:
orgs:
example-hybrid-dev:
helmReleaseName: example-hybrid-dev
envs:
  prod:
    helmReleaseName: prod
envGroups:
  prod-envgroup:
    helmReleaseName: prod-envgroup
Make changes to the release names for Apigee orgs/env/envgroups? [y/n]: n
Continue with patching apigee resources for Helm migration? [y/n]: y
INFO: 21:32:59 Processing component:  operator
INFO: 21:33:01 Processing component:  datastore
INFO: 21:33:01 Processing component:  redis
INFO: 21:33:02 Processing component:  ingress-manager
INFO: 21:33:02 Processing component:  telemetry
INFO: 21:33:03 Processing component:  orgs
INFO: 21:33:05 Processing component:  envs
INFO: 21:33:06 Processing component:  env-groups
INFO: 21:33:07 Migration successful!

발생할 수 있는 오류는 다음과 같습니다.

출시 이름 파일 파싱 오류: 전달된 출시 이름 파일을 확인합니다.
리소스를 찾을 수 없음: Apigee Hybrid가 완전히 설치되었고 apigee 리소스에 액세스할 수 있는 권한이 있는지 확인합니다.

구성 속성 변경사항

재정의 파일을 다음과 같이 변경합니다.

Helm으로 관리되는 Apigee Hybrid는 apigeeIngressGateway 속성을 사용하여 클러스터의 모든 Apigee 인그레스 게이트웨이를 구성합니다. ingressGateways 속성은 이름이 지정된 개별 인그레스 게이트웨이에 대해 apigeeIngressGateway의 설정을 재정의합니다.
apigeeIngressGateway 참조
- 클러스터의 모든 인그레스 게이트웨이에 전역적으로 적용되는 ingressGateways 속성에 대해 재정의 파일에서 추가적인 apigeeIngressGateway 스탠자를 만듭니다. 예를 들면 다음과 같습니다.
```
apigeeIngressGateway:
  image:
    url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
    tag: "TAG"
```
  예를 들면 다음과 같습니다.
```
apigeeIngressGateway:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
    tag: "1.17.8-asm.20-distroless"
```
- ingressGateways.name을 포함해야 합니다. 인그레스 게이트웨이를 인스턴스화해야 합니다. 예를 들면 다음과 같습니다.
워크로드 아이덴티티를 사용 설정하는 속성이 변경되었습니다.
- gcp.workloadIdentity.enabled이 gcp.workloadIdentityEnabled를 대체합니다.
- 모든 구성요소에 단일 서비스 계정을 사용하는 경우 gcp.workloadIdentity.gsa로 이 계정을 지정할 수 있습니다. 예를 들면 다음과 같습니다.
```
gcp:
  workloadIdentity:
    enabled: true
    gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
```
- 각 구성요소에 대해 별도의 서비스 계정(대부분의 프로덕션 설치에 대한 표준)을 사용하는 경우 구성요소의 gsa 속성을 사용하여 서비스 계정을 지정합니다. 예를 들면 다음과 같습니다.
```
logger:
  gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"
```
gcp.workloadIdentity.enabled, gcp.federatedWorkloadIdentity.enabled, GKE에서 워크로드 아이덴티티 사용 설정 또는 AKS 및 EKS에서 워크로드 아이덴티티 제휴 사용 설정을 참조하세요.

문제 해결

Hybrid v1.12 출시 버전의 Helm 마이그레이션 도구에 알려진 문제가 있습니다. 문제가 해결될 때까지 Cassandra 백업 및 복원에 추가 단계가 필요합니다.

다음 단계를 수행합니다.

마이그레이션 도구를 실행하기 전 또는 후
Helm 차트를 설치하기 전에

해결 방법을 위해 패치를 설치하려면 다음 안내를 따르세요.

현재 kubeconfig가 마이그레이션하려는 클러스터를 가리키는지 확인합니다. 모든 디렉터리에서 다음 단계를 수행할 수 있습니다.

다음 콘텐츠로 migration-operator-patch.yaml라는 파일을 만듭니다.

# migration-operator-patch.yaml
metadata:
  annotations:
    meta.helm.sh/release-name: operator
    meta.helm.sh/release-namespace: apigee-system
  labels:
    app.kubernetes.io/managed-by: Helm

다음 콘텐츠로 migration-datastore-patch.yaml이라는 파일을 만듭니다.

# migration-datastore-patch.yaml
metadata:
  annotations:
    meta.helm.sh/release-name: datastore
    meta.helm.sh/release-namespace: apigee
  labels:
    app.kubernetes.io/managed-by: Helm

다음 kubectl 명령어를 실행합니다.

kubectl patch clusterrole apigee-cassandra-backup --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrole apigee-cassandra-restore --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrolebinding apigee-cassandra-backup --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrolebinding apigee-cassandra-restore --patch-file ./migration-operator-patch.yaml
kubectl patch -n apigee cronjob apigee-cassandra-backup --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee certificate apigee-cassandra-backup-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n apigee secret apigee-cassandra-backup-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee secret apigee-cassandra-backup-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee ServiceAccount apigee-cassandra-backup-sa --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee job apigee-cassandra-restore --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee certificate apigee-cassandra-restore-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n apigee secret apigee-cassandra-restore-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee secret apigee-cassandra-restore-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee ServiceAccount apigee-cassandra-restore-sa --patch-file ./migration-datastore-patch.yaml

참고: not found 오류는 무시해도 됩니다.

다음 명령어를 사용하여 패치 파일을 삭제합니다.

rm migration-operator-patch.yaml
rm migration-datastore-patch.yaml

다음 단계

Helm 차트로 Apigee Hybrid 설치 및 관리의 안내에 따라 Apigee Hybrid Helm 차트를 계속 설치합니다.

중요: 마이그레이션된 클러스터에 대한 안내를 따를 때는 helm upgrade 명령어가 실패할 경우 실수로 리소스를 삭제하지 않도록 Helm 명령어에서 ‑‑atomic 플래그를 생략해야 합니다.

-help 출력

./apigee-helm-migration --help

Usage of ./apigee-helm-migration:
  -apigee-namespace string
      namespace used for apigee resources (default "apigee")
  -components string
      CSV of components to migrate. If empty then all components are migrated. Valid values are: operator,datastore,redis,ingress-manager,telemetry,orgs,envs,env-groups
  -dry-run
      perform a dry-run
  -env string
      restrict migration to a singular supplied env. If empty then all envs detected in the cluster are migrated
  -env-group string
      restrict migration to a singular supplied envGroup. If empty then all envGroups detected in the cluster are migrated
  -kubeconfig string
      (optional) absolute path to the kubeconfig file (default "/usr/local/google/home/example/.kube/config")
  -org string
      restrict migration to a singular supplied org. If empty then all orgs detected in the cluster are migrated
  -v	Increased logging verbosity
  -y	don't prompt for confirmation or for configuration of Helm releases