将 Apigee Hybrid 从 apigeectl 迁移到 Helm

此迁移工具帮助将基于 apigeectl 的 Hybrid 集群迁移到基于 Helm 的 Hybrid 集群。此工具不会实际替换任何集群组件。它具有幂等性，可以在同一集群上运行多次，每次准备一部分组件和组织。

您可以一次性迁移所有 apigee 组件，并且可以在此工具运行后按组件完成 Helm 升级操作。

如需了解如何管理已使用此工具迁移到 Helm 管理的混合集群，请参阅使用 Helm 图表安装和管理 Apigee Hybrid。

前提条件

  • Helm v3.14.2+ 版。
  • 一个有效的 kubeconfig 文件，指向安装了正常运行的 Apigee Hybrid 1.14 的集群。
  • 修改要迁移的 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) 如果生成的名称与另一个生成的名称冲突，则会添加后缀 -env 或 -env-group。如果名称仍然冲突，则会再添加后缀 -1 或 -2 …。

自定义 Helm 版本名称

迁移工具允许以交互方式自定义 Helm 版本名称。如果您想以非交互方式自定义 Helm 版本名称，请执行以下操作：

  1. 运行一次该工具，并在首次提示时退出，以创建包含自动生成的版本名称的临时文件。您应会看到如下所示的一行内容：
    INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames

  2. 移动或复制该文件，然后进行修改。您可以在运行迁移工具时通过 -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 顶级属性添加到替换文件。

说明

  1. 找到迁移工具。

    迁移工具使用 apigeectl 打包在 /tools/migration/ 下。

  2. 使用以下命令之一将压缩文件解压：

    • 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
  3. 运行迁移工具。如果默认选项可接受，则在不使用任何参数的情况下运行该工具就足够了。如果您对生成的 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 中单个指定入站流量网关的设置。

    参见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 图表之前

如需安装可解决此问题的补丁，请执行以下操作：

  1. 确保当前的 kubeconfig 指向要迁移的集群。您可以从任何目录执行这些步骤。
  2. 创建名为 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
  3. 创建一个名为 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
  4. 运行以下 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
  5. 使用以下命令清理补丁文件： 
    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