asmcli 參考資料

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

總覽

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

• 授予您Google Cloud 專案上必要的身分與存取權管理 (IAM) 權限。
• 在 Google Cloud 專案中啟用必要的 Google API。
• 為叢集設定標籤，用於識別網格。
• 建立服務帳戶，讓資料層元件 (例如附屬 Proxy) 可安全存取專案的資料和資源。
• 如果叢集尚未註冊至機群，請向機群註冊。

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

接著，asmcli 會使用專案和叢集資訊設定 YAML 檔案。您必須使用這些設定檔才能安裝 Cloud Service Mesh 控制平面。

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

轉換至 asmcli

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

所有叢集都必須註冊至機群。詳情請參閱車隊需求。

從 install_asm 轉換

如果您熟悉 install_asm，asmcli 與之相似，但有以下顯著差異：

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

  • 如果現有控制平面的修訂版本標籤與新控制平面的修訂版本標籤不符，asmcli 就會執行測試群組升級。

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

• 大部分 asmcli 選項和標記的運作方式與 install_asm 相同。

從 istioctl install 轉換

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

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

支援的平台

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

支援的平台清單中的 Cloud Service Mesh 安裝作業可透過 asmcli 進行設定或升級。

不過， 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

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

如CSM 發布說明所述，Managed 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

asmcli 從 anthos-service-mesh 存放區下載的疊加檔案名稱 (不含 .yaml 副檔名)，用於啟用選用功能。必須連上網際網路才能使用 --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.27.1-asm.5 子目錄。asm 目錄包含安裝設定。istio-1.27.1-asm.5 目錄包含已解壓縮的安裝檔案內容，其中包含 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-1271-5。如果您想覆寫預設值並指定自己的值，請加入這個選項。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。

--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 標記，以便在安裝時執行 asmcli install。這項設定設定完成後即無法變更。

--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

已淘汰。系統一律會佈建受管理的 Canonical Service Controller。

-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.27。