asmcli 參考資料

注意： 本指南僅支援使用 Istio API 的 Cloud Service Mesh，不支援 Google Cloud API。詳情請參閱 Cloud Service Mesh 總覽。

總覽

asmcli 是 Google 提供的工具，可用於安裝或升級 Cloud Service Mesh。如果允許，asmcli 會依下列方式設定專案和叢集：

• 在Google Cloud 專案中授予您必要的 Identity and Access Management (IAM) 權限。
• 在 Google Cloud 專案中啟用必要的 Google API。
• 在叢集上設定標籤，以識別網格。
• 建立服務帳戶，讓資料平面元件 (例如 Sidecar 代理程式) 安全存取專案的資料和資源。
• 如果叢集尚未註冊至機群，請註冊叢集。

執行 asmcli 時加入 --enable_all 旗標，即可讓工具設定專案和叢集。如要進一步瞭解 asmcli 選項和標記，請參閱 asmcli 參考資料。

接著，asmcli 會使用專案和叢集資訊設定 YAML 檔案。安裝 Cloud Service Mesh 控制平面時，需要這些設定檔。

如果您是 Cloud Service Mesh 和 Istio 的新手，請直接前往「支援的平台」。下一節將說明如何將現有的 Cloud Service Mesh 升級至 1.26。

正在轉換至「asmcli」

asmcli 會取代 istioctl install 和 install_asm。雖然您仍可在 Cloud Service Mesh 1.11 中使用舊版工具，但我們將淘汰這些工具，且 Cloud Service Mesh 1.12 以上版本將不再支援這些工具。請更新指令碼和工具，改用 asmcli。

所有叢集都必須註冊至機群。詳情請參閱「車隊規定」。

從 install_asm 轉換

如果您熟悉 install_asm，asmcli 類似於 install_asm，但有下列顯著差異：

• 您會使用 asmcli install 進行新安裝和升級。 不像 install_asm，--mode 沒有相關選項。執行 asmcli install 時，系統會檢查叢集上是否有現有的控制層。如果沒有現有的控制層，asmcli 會安裝 Cloud Service Mesh。如果叢集已有控制層 (Cloud Service Mesh 控制層或開放原始碼 Istio 控制層)：

  • 如果現有控制層的修訂版本標籤與新控制層的修訂版本標籤不符，asmcli 會執行Canary 升級。

  • 如果控制層修訂版本標籤相同，asmcli 會執行就地升級。

• 大部分的 asmcli 選項和標記行為都與 install_asm 的相同。

從 istioctl install 轉換

如果您熟悉 istioctl install，且通常會透過 -f 指令列引數傳遞 IstioOperator YAML 檔案來設定控制平面，則可以使用 --custom_overlay 選項將檔案傳遞至 asmcli。在 Cloud Service Mesh 說明文件中，這些檔案稱為「疊加檔案」。

注意： 根據預設，asmcli 不會隨控制平面安裝 Ingress 閘道。如為實際工作環境的部署作業，建議您分別安裝閘道。如需詳細資訊和最佳做法，請參閱「安裝及升級閘道」。我們在 anthos-service-mesh 存放區中提供部署、服務、ServiceAccount 和角色設定檔範例，供您開始使用 Ingress 和 Egress 閘道。您可以直接部署這些範本，或視需要自訂範本。

支援的平台

已淘汰： 使用 asmcli 為 GKE 上的代管控制層設定 Cloud Service Mesh Google Cloud 已淘汰。詳情請參閱 Cloud Service Mesh 版本資訊。如要為 GKE 設定代管型 Cloud Service Mesh，請參閱這份指南。

您可以使用 asmcli，設定或升級「支援的平台」清單中的 Cloud Service Mesh 安裝項目。

不過， Google Cloud以外的平台不支援所有功能。詳情請參閱「叢集內控制層支援的功能」。

asmcli 參考資料

本節說明 asmcli 可用的引數。

注意： 執行 ./asmcli -h -v 指令，即可查看可用標記和選項的完整清單，以及相關說明。

選項

找出叢集 您可以透過下列選項找出叢集：

僅限 GKE

-p|--project_id CLUSTER_PROJECT_ID

叢集建立所在的專案 ID。

-n|--cluster_name CLUSTER_NAME

叢集名稱。

-l|--cluster_location CLUSTER_LOCATION

叢集建立所在的區域 (適用於單一可用區叢集) 或地區 (適用於區域叢集)。

所有平台

--kubeconfig KUBECONFIG_FILE kubeconfig 檔案的完整路徑。環境變數 $PWD 在這裡無法運作。

--ctx|--context KUBE_CONTEXT 要使用的 kubeconfig 內容。如未指定，asmcli 會使用預設內容。

警告： 請只使用來源可靠的 kubeconfig 檔案。使用特製的 kubeconfig 檔案可能會導致惡意程式碼執行或檔案曝光。如果必須使用不受信任的 kubeconfig 檔案，請先仔細檢查，就像檢查 Shell 指令碼一樣。

-c|--ca {mesh_ca|gcp_cas|citadel}

用於管理雙向 TLS 憑證的憑證授權單位 (CA)。指定 mesh_ca 使用 Cloud Service Mesh 憑證授權單位 (Cloud Service Mesh 憑證授權單位)、gcp_cas 使用憑證授權單位服務，或 citadel 使用 Istio CA。代管 Cloud Service Mesh 不支援 Istio CA。詳情請參閱下列資訊：

• 選擇憑證授權單位
• Istio CA 自訂憑證選項
• 設定 Cloud Service Mesh 使用 CA 服務

--channel CLOUD_SERVICE_MESH_CHANNEL

使用 --channel 和特定 Cloud Service Mesh 發布版本，佈建與該發布版本相關聯的控制層修訂版本。例如 --channel rapid、--channel regular 和 --channel stable。 在 GKE Autopilot 叢集上設定特定 Cloud Service Mesh 功能時，必須使用這個標記。

如 CSM 版本資訊所述，受管理 Cloud Service Mesh 不再支援 --channel 選項。發布管道取決於 GKE 叢集發布管道。 詳情請參閱「代管 Cloud Service Mesh 發布管道」。

--co|--custom_overlay OVERLAY_FILE

使用 --custom_overly 和 YAML 檔案 (稱為「疊加檔案」) 的名稱，其中包含 IstioOperator 自訂資源，可設定叢內控制平面。您可指定疊加檔案， 啟用預設未啟用的功能。代管 Cloud Service Mesh 不支援 IstioOperator API，因此您無法使用 --custom_overlay 設定代管控制層。asmcli 必須能夠找到疊加檔案，因此該檔案必須與 asmcli 位於同一目錄，或是您可以指定相對路徑。如要新增多個檔案，請指定 --co|--custom_overlay 和檔案名稱，例如： --co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml

--hub-registration-extra-flags HUB_REGISTRATION_EXTRA_FLAGS

如果使用附加的 Amazon EKS 叢集，請使用 --hub-registration-extra-flags 向機群註冊叢集 (如果尚未註冊)。

-k|--key_file FILE_PATH

服務帳戶的金鑰檔案。如果您未使用服務帳戶，請省略這個選項。

--network_id NETWORK_ID

使用 --network_id 設定套用至 istio-system 命名空間的 topology.istio.io/network 標籤。如果是 GKE，--network_id 預設為叢集的網路名稱。其他環境則會使用 default。

-o|--option OVERLAY_FILE

疊加檔案的名稱 (不含 .yaml 副檔名)。asmcli 會從 anthos-service-mesh 存放區下載這個檔案，以啟用選用功能。你必須連上網際網路才能使用「--option」。--option 和 --custom_overlay 選項類似，但行為略有不同：

• 如要變更疊加層檔案中的設定，請使用 --custom_overlay。

• 使用 --option 啟用不需要變更疊加層檔案的功能，例如設定服務的稽核政策。

如要新增多個檔案，請指定 -o|--option 和檔案名稱，例如：-o option_file1 -o option_file2 -o option_file3

-D|--output_dir DIR_PATH

如未指定，asmcli 會建立臨時目錄，下載安裝 Cloud Service Mesh 時所需的檔案和設定。指定 --output-dir 旗標，改為指定要使用的目錄相對路徑。完成後，指定目錄會包含 asm 和 istio-1.26.7-asm.1 子目錄。asm 目錄包含安裝設定。istio-1.26.7-asm.1 目錄包含安裝檔案的解壓縮內容，內含 istioctl、範例和資訊清單。如果您指定 --output-dir，且目錄已包含必要檔案，asmcli 會使用這些檔案，而不是再次下載。

--platform PLATFORM {gcp|multicloud}

Kubernetes 叢集的平台或供應商。預設值為 gcp (適用於 GKE 叢集)。如要使用其他平台，請multicloud。

-r|--revision_name REVISION NAME

修訂版本標籤是控制層上設定的鍵/值組合。修訂版本標籤鍵一律為 istio.io/rev。依預設，asmcli 會根據 Cloud Service Mesh 版本設定修訂版本標籤的值，例如：asm-1267-1。如要覆寫預設值並指定自己的值，請加入這個選項。REVISION NAME 引數必須是 DNS-1035 標籤。也就是說，名稱必須：

• 長度不得超過 63 個字元
• 只能包含小寫英數字元或「-」
• 開頭必須是字母字元
• 結尾為英數字元

用於驗證的規則運算式為：'[a-z]([-a-z0-9]*[a-z0-9])?'

-s|--service_account ACCOUNT

用於安裝 Cloud Service Mesh 的服務帳戶名稱。如未指定，則使用目前 gcloud 設定中的有效使用者帳戶。如要變更使用中帳戶，請執行 gcloud auth login。

Istio CA 自訂憑證的選項

如果您指定 --ca citadel 並使用自訂 CA，請加入下列選項：

• --ca_cert FILE_PATH：中繼憑證
• --ca_key FILE_PATH：中繼憑證的金鑰
• --root_cert FILE_PATH：根憑證
• --cert_chain FILE_PATH：憑證鏈結

詳情請參閱「插入現有 CA 憑證」。

啟用旗標

以 --enable 開頭的旗標可讓 asmcli 啟用必要的 Google API、設定必要的 Identity and Access Management (IAM) 權限，以及更新叢集。或者，您也可以在執行 asmcli 前，自行更新專案和叢集。所有啟用旗標都與 asmcli validate 不相容。如果您在執行 asmcli validate 時指定啟用旗標，指令會終止並顯示錯誤。

-e|--enable_all

允許 asmcli 執行下列所有啟用動作。

--enable_cluster_roles

允許 asmcli 嘗試將執行 asmcli 的 Google Cloud 使用者或服務帳戶繫結至叢集中的cluster-admin角色。asmcli 會從 gcloud config get core/account 指令判斷使用者帳戶。如果您使用使用者帳戶在本機執行 asmcli，請務必先呼叫 gcloud auth login 指令，再執行 asmcli。如要變更使用者帳戶，請執行 gcloud config set core/account GCP_EMAIL_ADDRESS 命令，其中 GCP_EMAIL_ADDRESS 是您用來登入 Google Cloud的帳戶。

--enable_cluster_labels

允許 asmcli 設定必要的叢集標籤。

--enable_gcp_components

允許 asmcli 啟用下列必要 Google Cloud 代管服務和元件：

• Workload Identity，可讓 GKE 應用程式安全地存取 Google Cloud 服務。

• GKE 中的 Cloud Monitoring 和 Cloud Logging。

• 在機群專案中啟用 Cloud Service Mesh 功能。從 asmcli 1.25 以上版本佈建代管標準服務控制器時，必須使用此參數。

--enable_gcp_apis

允許 asmcli 啟用所有必要的 Google API。

--enable_gcp_iam_roles

允許 asmcli 設定必要的 IAM 權限。

--enable_meshconfig_init

允許指令碼代您初始化 meshconfig 端點。--enable_gcp_components 和 --managed 隱含。

--enable_namespace_creation

允許 asmcli 建立根 istio-system 命名空間。

--enable_registration

允許 asmcli 將叢集註冊至叢集所在的專案。如果您未提供這個標記，請按照「註冊叢集」一文中的步驟，手動註冊叢集。請注意，與其他啟用旗標不同，只有在指定需要叢集註冊的選項 (例如 --option hub-meshca) 時，--enable_registration 才會納入 --enable_all。否則，您必須另外指定這個旗標。

其他旗標

--dry_run

列印指令，但不執行。

--fleet_id

使用機群的主機專案 ID，將叢集註冊至機群。如果不是Google Cloud 叢集，就必須設定這個旗標。如果未提供Google Cloud 叢集，則預設為叢集的專案 ID。您可以先執行 asmcli install 和 --fleet_id，再進行安裝，也可以傳遞 --enable-registration 和 --fleet-id 標記，在安裝期間執行。設定完成後即無法變更。

--managed

已淘汰。佈建遠端代管控制層，而非在叢集內安裝控制層。

--offline

使用輸出目錄中預先下載的套件，執行離線安裝。如果未指定目錄或目錄不含必要檔案，指令碼會結束並顯示錯誤。

--only_enable

執行指定步驟來設定目前的使用者/叢集，但不會安裝任何項目。

--only_validate

執行驗證，但不要更新專案或叢集，也不要安裝 Cloud Service Mesh。這個標記與啟用標記不相容。如果您使用任何啟用旗標指定 --only_validate，asmcli 會以錯誤終止。

--print_config

不要安裝 Cloud Service Mesh，而是將所有已編譯的 YAML 列印到標準輸出 (stdout)。所有其他輸出內容都會寫入標準錯誤 (stderr)，即使通常會寫入 stdout 也是如此。asmcli 指定此旗標時，會略過所有驗證和設定。

--disable_canonical_service

已淘汰。系統一律會佈建代管的標準服務控制器。

-h|--help

顯示說明訊息，說明選項和標記，然後結束。

--use_managed_cni

使用受管理 CNI。如果未傳遞這個旗標，asmcli 會套用靜態 CNI 資訊清單。

--use_vpcsc

如果貴機構對專案強制執行 VPC Service Controls，您必須使用 --use_vpcsc 旗標設定代管型 Cloud Service Mesh。否則安裝作業會導致安全控管機制失敗。

-v|--verbose

執行時，會列印下一個要執行的指令。asmcli使用 --verbose 旗標時，asmcli 也會在執行後列印指令。

--version

列印 asmcli 版本並結束。如果沒有最新版本，可以下載最新版 asmcli_1.26。