将 Apigee Hybrid 从 apigeectl 迁移到 Helm

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

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

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

前提条件

  • Helm v3.10+ 版。
  • 一个有效的 kubeconfig 文件,指向安装了正常运行的 Apigee Hybrid 1.13 的集群。
  • 修改要迁移的 Hybrid 组件的 Kubernetes 资源上的元数据和注解的权限。

范围

此工具在运行时支持以下选项:

  • 自定义 apigee 资源的命名空间。默认命名空间:apigee
  • 仅迁移选定的 Hybrid 组件。默认选项:迁移所有组件
  • 仅迁移单个组织
  • 仅迁移单个环境
  • 仅迁移单个环境组 (apigee-virtualhost)
  • 为组织、环境和环境组自定义 Helm 版本名称。

限制

  • 此工具不支持为以下 Hybrid 组件自定义 Helm 版本名称:apigee-operatorapigee-datastoreapigee-redisapigee-telemetryapigee-ingress-manager
  • 为组织、环境和环境组对 Helm 版本名称进行的交互式自定义不会在各次运行之间自动保留。您可以修改临时文件,并在后续运行中将其作为选项提供。
  • 环境和环境组仅按名称进行过滤。在某些情况下,这可能会导致多组织集群上的多个环境和环境组被迁移。

    例如,在具有组织 org1org2 的多组织集群上,如果两个组织中都存在环境 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
      
    • 仅迁移 operatordatastore 组件:

      ./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.enabledgcp.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