asmcli 參考資料

總覽

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

轉換至 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 選項和標記的運作方式與 install_asm 相同。

從 istioctl install 轉換

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

支援的平台

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

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

asmcli 參考資料

本節將說明 asmcli 的可用引數。

選項

識別叢集 您可以透過下列選項識別叢集：

僅限 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 會使用預設內容。

-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。如需更多資訊，請參閱下列說明：

--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.25.2-asm.3 子目錄。asm 目錄包含安裝設定。istio-1.25.2-asm.3 目錄包含已解壓縮的安裝檔案內容，其中包含 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-1252-3。如果您想覆寫預設值並指定自己的值，請加入這個選項。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 受管理服務和元件：

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