從 apigeectl 將 Apigee Hybrid 遷移至 Helm

這項遷移工具可協助將以 apigeectl 為基礎的混合式叢集，遷移至以 Helm 為基礎的混合式叢集。這項工具不會實際替換任何叢集元件。這項作業具有冪等性，可在同一個叢集上執行多次，每次準備一部分的元件和組織。

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

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

必要條件

  • Helm 3.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 輸入閘道。ingressGateways 屬性會覆寫 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.9"
    • 請務必加入 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 上啟用 Workload Identity Federation。

疑難排解

Hybrid 1.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