이 마이그레이션 도구는 apigeectl
기반 하이브리드 클러스터를 Helm 기반 하이브리드 클러스터로 마이그레이션하는 데 도움이 됩니다.
이 도구는 클러스터 구성요소를 실제로 교체하지 않습니다. 멱등성이며 같은 클러스터에서 여러 번 실행되므로 매번 구성요소 및 조직의 하위 집합을 준비할 수 있습니다.
모든 apigee
구성요소를 한 번에 마이그레이션할 수 있으며 도구가 실행된 후에 구성요소별로 Helm 업그레이드 작업을 수행할 수 있습니다.
이 도구를 사용하여 Helm 관리로 마이그레이션한 하이브리드 클러스터 관리에 대한 자세한 내용은 Helm 차트를 사용하여 Apigee Hybrid 설치 및 관리를 참조하세요.
기본 요건
- Helm 버전 v3.14.2 이상
-
Apigee Hybrid 1.13 설치가 작동하는 클러스터를 가리키는 작동 중인
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]](1) |
ORG_NAME-ENV_NAME[-env[-n]] (1) |
apigee-virtualhost (envgroup) |
VH_NAME[-env-group[-n]] (1) |
ORG_NAME-VH_NAME[-env-group[-n]] (1) |
(1) 생성된 이름이 생성된 다른 이름과 충돌하면 이름에 |
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 v1.13 이상은 단일 Kubernetes 네임스페이스에서 실행됩니다. 모든 Hybrid 구성요소가 이 네임스페이스에서 실행됩니다. 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
-
Mac:
-
마이그레이션 도구를 실행합니다. 기본 옵션이 허용되면 인수 없이 도구를 실행할 수 있으며 생성된 helm 출시 이름이 충족되면 프롬프트를 승인할 수 있습니다. 다음은 몇 가지 시나리오의 예시입니다.
-
기본
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
의 설정을 재정의합니다.- 클러스터의 모든 인그레스 게이트웨이에 전역적으로 적용되는
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
을 포함해야 합니다. 인그레스 게이트웨이를 인스턴스화해야 합니다. 예를 들면 다음과 같습니다.
ingressGateways: name: INGRESS_GATEWAY_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_NAMESPACE 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_NAMESPACE cronjob apigee-cassandra-backup --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE certificate apigee-cassandra-backup-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-backup-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-backup-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE ServiceAccount apigee-cassandra-backup-sa --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE job apigee-cassandra-restore --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE certificate apigee-cassandra-restore-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-restore-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-restore-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE ServiceAccount apigee-cassandra-restore-sa --patch-file ./migration-datastore-patch.yaml
- 다음 명령어를 사용하여 패치 파일을 삭제합니다.
rm migration-operator-patch.yaml
rm migration-datastore-patch.yaml
다음 단계
Helm 차트로 Apigee Hybrid 설치 및 관리의 안내에 따라 Apigee Hybrid Helm 차트를 계속 설치합니다.
-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