從 apigeectl 將 Apigee Hybrid 遷移至 Helm

這項遷移工具可協助將以 apigeectl 為基礎的混合叢集遷移至以 Helm 為基礎的混合叢集。這項工具不會實際取代任何叢集元件。這項作業是冪等的,可以在同一個叢集中執行多次,每次都會準備一組子元件和機構。

您可以一次遷移所有 apigee 元件,並在工具執行後,依個別元件執行 Helm 升級作業。

如要瞭解如何管理已透過此工具遷移至 Helm 管理的混合叢集,請參閱「使用 Helm 圖表安裝及管理 Apigee 混合叢集」。

必要條件

  • Helm 版本 3.14.2 以上版本。
  • 可用的 kubeconfig 檔案,會指向叢集,其中包含可用的 Apigee Hybrid 1.13 安裝作業。
  • 您要遷移的混合型元件 Kubernetes 資源的中繼資料和註解的修改權限。

範圍

這項工具在執行階段支援下列選項:

  • 自訂 apigee 資源的命名空間。預設命名空間:apigee
  • 僅限遷移所選混合型元件。預設:所有元件都會遷移
  • 僅遷移單一機構
  • 僅遷移單一環境
  • 僅遷移單一 env-group (apigee-virtualhost)
  • 為組織、環境和環境群組自訂 Helm 版本名稱。

限制

  • 此工具不支援為下列混合式元件自訂 Helm 版本名稱:apigee-operatorapigee-datastoreapigee-redisapigee-telemetryapigee-ingress-manager
  • 針對組織、環境和環境群組的 Helm 發布版本名稱所做的互動式自訂內容,不會在執行作業之間自動保留。您可以編輯暫存檔案,並在日後執行時將其做為選項提供。
  • 環境和環境群組篩選功能只會依名稱篩選。在某些情況下,這可能會導致在多個組織叢集中遷移多個環境和環境群組。

    舉例來說,在包含 org1org2 多個組織的叢集中,如果兩個組織都包含 env 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

    如要為機構、env 或 envgroup 自訂 Helm 版本名稱,請編輯該物件的 helmReleaseName 欄位。舉例來說,如要將 org 版本重新命名為 custom-org、env 版本為 custom-env,以及 envgroup 版本為 custom-group,產生的檔案如下所示:

    orgs:
      example-apigee-org:
        helmReleaseName: custom-org
        envs:
          prod:
            helmReleaseName: custom-env
        envGroups:
          prod-envgroup:
            helmReleaseName: custom-group

使用自訂命名空間

Apigee Hybrid 1.13 以上版本會在單一 Kubernetes 命名空間中執行。所有混合元件都會在這個命名空間中執行。apigee 是預設名稱。您可以為這些元件使用任何自訂命名空間。

如果您使用自訂命名空間,則必須在執行 Helm 遷移工具時,使用 --apigee-namespace my_custom_namespace 標記指定該命名空間。

您也必須在覆寫檔案中加入 namespace: my_custom_namespace 頂層屬性。

Directions

  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 資源。

設定屬性變更

在覆寫檔案中進行下列變更:

  • 使用 metrics.appStackdriverExporter.* 取代 metrics.aggregator.*
  • 透過 Helm 管理的 Apigee 混合式會使用 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。您必須將此值設為 ingress 閘道的例項化。例如:
    • 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 上啟用工作負載身分在 AKS 和 EKS 上啟用 Workload Identity Federation

疑難排解

混合型 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