此迁移工具帮助将基于 apigeectl
的 Hybrid 集群迁移到基于 Helm 的 Hybrid 集群。此工具不会实际替换任何集群组件。它具有幂等性,可以在同一集群上运行多次,每次准备一部分组件和组织。
您可以一次性迁移所有 apigee
组件,并且可以在此工具运行后按组件完成 Helm 升级操作。
如需了解如何管理已使用此工具迁移到 Helm 管理的混合集群,请参阅使用 Helm 图表安装和管理 Apigee Hybrid。
前提条件
- Helm v3.14.2+ 版。
-
一个有效的
kubeconfig
文件,指向安装了正常运行的 Apigee Hybrid 1.13 的集群。 - 修改要迁移的 Hybrid 组件的 Kubernetes 资源上的元数据和注解的权限。
范围
此工具在运行时支持以下选项:
-
自定义
apigee
资源的命名空间。默认命名空间:apigee
- 仅迁移选定的 Hybrid 组件。默认选项:迁移所有组件
- 仅迁移单个组织
- 仅迁移单个环境
-
仅迁移单个环境组 (
apigee-virtualhost
) - 为组织、环境和环境组自定义 Helm 版本名称。
限制
-
此工具不支持为以下 Hybrid 组件自定义 Helm 版本名称:
apigee-operator
、apigee-datastore
、apigee-redis
、apigee-telemetry
和apigee-ingress-manager
。 - 为组织、环境和环境组对 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
顶级属性添加到替换文件。
说明
-
找到迁移工具。
迁移工具使用
apigeectl
打包在/tools/migration/
下。 -
使用以下命令之一将压缩文件解压:
-
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
- 将集群中所有入站流量网关的任何全局
- 用于启用 Workload Identity 的属性已更改:
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 上启用 Workload Identity 或在 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