從 apigeectl 將 Apigee Hybrid 遷移至 Helm

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

您可以一次遷移所有 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: "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 上啟用工作負載身分或在 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
  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