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

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

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

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

기본 요건

Helm 버전 v3.10 이상.
Apigee Hybrid 1.11 설치가 작동하는 클러스터를 가리키는 작동 중인 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-tool [--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를 제외한 모든 하이브리드 구성요소는 이 네임스페이스에서 실행됩니다. apigee는 기본 이름입니다. 이러한 구성요소에 대해 커스텀 네임스페이스를 사용할 수 있습니다.
커스텀 네임스페이스를 사용하는 경우 Helm 마이그레이션 도구를 실행할 때 --apigee-namespace my_custom_namespace 플래그로 지정해야 합니다.

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

지침

마이그레이션 도구를 찾습니다.

마이그레이션 도구는 /tools/migration/ 아래에 apigeectl과 함께 패키징됩니다.

다음 명령어 중 하나를 사용하여 압축 파일을 압축 해제합니다.

Mac:

tar -xzf apigee-helm-migration_1.0.2_mac_64.tar.gz

Linux:

tar -xzf apigee-helm-migration_1.0.2_linux_64.tar.gz

Windows:

tar -xzf apigee-helm-migration_1.0.2_windows_64.zip

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

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

대부분의 경우(모든 경우가 아님) 다음 명령어로 설치할 수 있습니다. 도구가 실행된 후 구성요소별로 Helm 업그레이드 작업을 수행할 수 있습니다.
```
./apigee-helm-migration-tool
```
커스텀 네임스페이스를 사용하여 모든 구성요소 마이그레이션:
```
./apigee-helm-migration-tool --apigee-namespace my_custom_namespace
```

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

./apigee-helm-migration-tool --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-tool --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
```
모든 구성요소(단일 조직만)를 마이그레이션합니다.
```
./apigee-helm-migration-tool --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 리소스에 액세스할 수 있는 권한이 있는지 확인합니다.

구성 속성 변경사항

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

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"

apigeeIngressGateway 참조

워크로드 아이덴티티를 사용 설정하는 속성이 변경되었습니다.
- 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 및 Helm을 사용하여 워크로드 아이덴티티 사용 설정을 참조하세요.

다음 단계

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

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

-help 출력

./apigee-helm-migration-tool --help

Usage of ./apigee-helm-migration-tool:
  -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