這項遷移工具可協助將以 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-operator
、apigee-datastore
、apigee-redis
、apigee-telemetry
和apigee-ingress-manager
。 - 針對組織、環境和環境群組的 Helm 發布版本名稱所做的互動式自訂內容,不會在執行作業之間自動保留。您可以編輯暫存檔案,並在日後執行時將其做為選項提供。
-
環境和環境群組篩選功能只會依名稱篩選。在某些情況下,這可能會導致在多個組織叢集中遷移多個環境和環境群組。
舉例來說,在包含
org1
和org2
多個組織的叢集中,如果兩個組織都包含 envprod
,且只指定--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) 如果產生的名稱與其他產生的名稱發生衝突,名稱的字尾會加上 |
自訂 Helm 版本名稱
遷移工具可讓您透過互動式方式自訂 Helm 版本名稱。如果您想以非交互式方式自訂 Helm 版本名稱,請執行下列操作:
-
請執行這項工具一次,並在第一次提示時退出,以便建立包含自動產生版本名稱的暫存檔案。您應該會看到類似以下的內容:
INFO: 21:32:56 using temp file for release names: /tmp/apigee-helm-migration-1229129207-releaseNames
-
移動或複製檔案,然後編輯檔案。執行遷移工具時,您可以使用
-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
-
找出遷移工具。
遷移工具會與
apigeectl
一併封裝在/tools/migration/
下。 -
使用下列其中一個指令解壓縮檔案:
-
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
-
Mac:
-
執行遷移工具。如果您可以接受預設選項,只要不帶任何引數執行工具即可,如果產生的 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
資源。
-
設定屬性變更
在覆寫檔案中進行下列變更:
-
使用
metrics.appStackdriverExporter.*
取代metrics.aggregator.*
。 -
透過 Helm 管理的 Apigee 混合式會使用
apigeeIngressGateway
屬性,設定叢集中的所有 Apigee 入口網關。ingressGateways
屬性會覆寫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.enabled
、gcp.federatedWorkloadIdentity.enabled
、在 GKE 上啟用工作負載身分或在 AKS 和 EKS 上啟用 Workload Identity Federation。
疑難排解
混合型 v1.12 版本的 Helm 遷移工具有已知問題。在問題解決前,Cassandra 備份和還原作業需要額外步驟。
您可以按照下列步驟操作:
- 執行遷移工具前或後
- 安裝 Helm 資訊套件前的注意事項
如要安裝解決方法的修補程式,請按照下列步驟操作:
- 請確認目前的
kubeconfig
指向要遷移的叢集。您可以在任何目錄中執行這些步驟。 - 建立名為
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
- 建立名為
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
- 執行下列
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
- 使用下列指令清除修補檔案:
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