從 apigeectl 將 Apigee Hybrid 遷移至 Helm

Version 1.15 (latest)

   Supported versions:

• v1.15 (latest)                        
• v1.14                        
• v1.13                         
• List of supported versions

   Unsupported versions:

• v1.12                         
• v1.11                         
• v1.10                                      
• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

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

重要事項：請務必先執行這個遷移工具， 再執行 Helm 升級指令。

混合式 v1.12 版的 Helm 遷移工具存在已知問題。在解決問題之前，Cassandra 備份和還原需要解決方法，請參閱「疑難排解」一節，瞭解如何安裝解決方法。

您可以一次遷移所有 apigee 元件，工具執行完畢後，即可逐一升級 Helm 元件。

如要瞭解如何使用這項工具管理已遷移至 Helm 管理的混合式叢集，請參閱「使用 Helm 圖表安裝及管理 Apigee Hybrid」。

必要條件

• Helm 版本 v3.14.2 以上。
• 指向叢集的有效 kubeconfig 檔案，且已安裝 Apigee Hybrid 1.15 版。
• 修改要遷移的混合元件 Kubernetes 資源中繼資料和註解的權限。

範圍

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

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

限制

• 這個工具不支援為下列混合式元件自訂 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 Chart 都必須有發布名稱，且該名稱在命名空間中不得重複。相較於圖表名稱，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 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
     

   • 只遷移 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 Ingress 閘道。ingressGateways 屬性會覆寫個別具名 Ingress 閘道的 apigeeIngressGateway 設定。

  查看apigeeIngressGateway

  • 將叢集中所有 Ingress 閘道的任何 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.15.1"
    

  • 請務必加入 ingressGateways.name。您必須例項化 Ingress 閘道。例如：

  ingressGateways:
    name: INGRESS_GATEWAY_NAME
  

• 啟用 Workload Identity 的屬性已變更：
  • gcp.workloadIdentity.enabled 取代 gcp.workloadIdentityEnabled。
  • 如果所有元件都使用單一服務帳戶，可以透過下列方式指定： gcp.workloadIdentity.gsa。例如：

    gcp:
      workloadIdentity:
        enabled: true
        gsa: "[e-mail]"
    

  • 如果您為每個元件使用個別的服務帳戶 (大多數正式版安裝作業的標準)，請使用元件的 gsa 屬性指定服務帳戶。例如：

    logger:
      gsa: "[e-mail]"
    

  請參閱： gcp.workloadIdentity.enabled、gcp.federatedWorkloadIdentity.enabled、在 GKE 上啟用工作負載身分或在 AKS 和 EKS 上啟用工作負載身分聯盟。

疑難排解

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

   注意：您可以忽略任何 not found 錯誤。
5. 使用下列指令清除修補程式檔案：

   rm migration-operator-patch.yaml
   rm migration-datastore-patch.yaml

下一步

請按照「使用 Helm 資訊套件安裝及管理 Apigee Hybrid」一文的指示，繼續安裝 Apigee Hybrid Helm 資訊套件。

重要事項： 按照已遷移叢集的指示操作時，請務必從所有 Helm 指令中省略 ‑‑atomic 旗標，以免 helm upgrade 指令失敗時，意外刪除資源。

-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