為 Cloud de Confiance 設定 Google Cloud CLI

本指南說明如何設定 Google Cloud CLI (gcloud CLI)，以便與Cloud de Confiance搭配使用。透過 gcloud CLI，您可以在指令列中建立及使用資源。 Cloud de Confiance

如要進一步瞭解如何設定及使用 gcloud CLI，請參閱 Google Cloud CLI 說明文件。

與 Google Cloud 設定的差異

如果您已熟悉如何設定及使用 CLI 搭配 Google Cloud，請注意下列事項：

  • 如要搭配使用 gcloud CLI 與 Cloud de Confiance，您需要完成一些額外的初始設定，詳情請參閱本指南。
  • Cloud de Confiance不支援 Cloud Shell。本機電腦必須安裝 gcloud CLI。
  • 無法使用 gcloud init 一次完成 gcloud CLI 初始化。
  • 如果某項功能或產品在 Cloud de Confiance中無法使用，對應的 gcloud CLI 指令和參數也無法使用。

事前準備

除了 Cloud de Confiance的登入詳細資料外，您還需要下列資訊，才能首次設定 gcloud CLI。如果您不是貴機構的管理員，請向管理員索取這項資訊。

  • 貴機構的workload identity pool 名稱。
  • 貴機構的身分識別提供者 (IdP)。

安裝 gcloud CLI

按照作業系統的說明安裝 gcloud CLI。

Linux
  1. 確認您使用的是支援的 Python 版本。Google Cloud CLI 需使用 Python 3.10 至 3.15 版。x86_64 Linux 套件內含預設會優先使用的 Python 解譯器。如要瞭解如何選擇及設定 Python 解譯器，請參閱 gcloud topic startup 說明文件。
  2. 下載下列其中一個檔案：
    平台 套件名稱 大小 SHA256 核對和
    Linux 64 位元

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 93.5 MB 817026aec0adea0e2ee8ed3a1ba3eabfe9e5177581fbe16595a8fe495a601300
    Linux 64 位元

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 54.1 MB c7b9abef0649e0fccc70bf2aaaa031a0aa6202863e45fabe938698dc93d4934c
    Linux 32 位元

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 54.1 MB 69f2e18bd0e706a6b31d005381bdf6b17ede01bcf6ce1804a42e2e7cef09bd9c

    如要下載 Linux 封存檔案，請執行下列指令： 

    curl -O https://storage.s3nsapis.fr/cloud-sdk-release/google-cloud-cli-linux-x86_64.tar.gz

    請參閱上表，並將 google-cloud-cli-linux-x86_64.tar.gz 替換為適用於您設定的 *.tar.gz 套件名稱。

  3. 如要將檔案內容解壓縮至檔案系統，請執行下列指令： 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
     如要取代現有安裝項目，請刪除現有的 google-cloud-sdk 目錄，然後將封存檔解壓縮到相同位置。
  4. 從解壓縮的資料夾根目錄執行安裝指令碼： 
    ./google-cloud-sdk/install.sh
     指令碼會提示您執行下列設定動作。如要接受，請在系統提示時回答「Y」。
    • 將 gcloud CLI 新增至 PATH。
    • 啟用指令完成功能。
    • 選擇加入傳送匿名使用統計資料，協助改善 gcloud CLI。
    您也可以提供旗標，以非互動方式執行安裝作業。 如要查看可用的旗標，請執行：
    ./google-cloud-sdk/install.sh --help
  5. 選用：如果您在上一步更新了 PATH，請開啟新的終端機，讓變更生效。
macOS
  1. 確認您使用的是支援的 Python 版本。Google Cloud CLI 需使用 Python 3.10 至 3.15 版。

    如要檢查 Python 版本，請執行 python3 -V 或 python -V。

    gcloud 安裝程式預設會安裝 Python 3.14 版和必要的擴充功能模組。

    如要進一步瞭解如何設定 Python 直譯器，請參閱 gcloud topic startup 說明文件。

  2. 下載下列其中一個檔案：
    平台 套件 大小 SHA256 總和檢查碼
    macOS 64 位元

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 54.3 MB b49e8cb9d348267d46fade7b9c916a1aed7ce0ec07e142ce41cc0d24a95a9651
    macOS 64 位元

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 54.2 MB 71b37ca07ab0f9bc43898e42c913e10f143166230ab31e0bbea3632dbc77b010
    macOS 32 位元

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 52.6 MB bc9d328fbf56f650b57d9a70eb267993c98d0a9cbd15864b0b8fee949ea1039f

    或者，您也可以透過指令列下載封存檔。 將 FILE_NAME 替換為上表中的平台套件名稱。

    curl -O https://storage.s3nsapis.fr/cloud-sdk-release/FILE_NAME
  3. 將檔案內容擷取至檔案系統中的偏好位置。常見做法是將檔案解壓縮至主目錄。

    在 macOS 上，只要在偏好的位置開啟下載的 .tar.gz 檔案，或者，您也可以從指令列執行： 

    tar -xf FILE_NAME

    如要取代現有安裝項目，請刪除現有的 google-cloud-sdk 目錄，然後將封存檔解壓縮至相同位置。

  4. 從解壓縮的資料夾根目錄執行安裝指令碼： 
    ./google-cloud-sdk/install.sh
     指令碼會提示您執行下列設定動作。如要接受，請在系統提示時回答「Y」。
    • 視需要安裝 Python 3.14 和建議的模組。
    • 將 gcloud CLI 新增至 PATH，並啟用指令完成功能。
    • 選擇加入傳送匿名使用統計資料，協助改善 gcloud CLI。
    您也可以提供旗標，以非互動方式執行安裝作業。 如要查看可用的旗標，請執行：
    ./google-cloud-sdk/install.sh --help
     如要啟用螢幕閱讀器模式並執行安裝指令碼，請按照下列步驟操作： 
    ./google-cloud-sdk/install.sh --screen-reader=true
  5. 選用：如果您在上一步更新了 PATH，請開啟新的終端機，讓變更生效。
Windows

如要在 Windows 使用 Google Cloud CLI，必須安裝 Windows 8.1 以上版本，或 Windows Server 2012 以上版本。

  1. 下載 Google Cloud CLI 安裝程式。

    或者，開啟 PowerShell 終端機並執行下列 PowerShell 指令： 

    (New-Object Net.WebClient).DownloadFile("https://storage.s3nsapis.fr/cloud-sdk-release/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")

& $env:Temp\GoogleCloudSDKInstaller.exe

  2. 啟動安裝程式並按照提示操作。這個安裝程式是由 Google LLC 簽署。

    • 如果你使用螢幕閱讀器，請勾選「開啟螢幕閱讀器模式」核取方塊。這個選項會設定 gcloud 使用狀態追蹤器，而非 Unicode 旋轉符號，並以百分比顯示進度，以及將表格扁平化。詳情請參閱無障礙功能指南。
    • Google Cloud CLI 需要 Python，支援的版本為 Python 3.10 至 3.15。根據預設，Windows 版 Google Cloud CLI 隨附 Python 3。如要使用 Google Cloud CLI，作業系統必須能夠執行支援的 Python 版本。
    • 安裝程式會安裝所有必要依附元件，包括所需的 Python 版本。 Google Cloud CLI 預設會安裝及管理 Python 3，但如有需要，您可以取消勾選「Install Bundled Python」(安裝隨附的 Python) 選項，使用現有的 Python 安裝項目。請參閱 gcloud topic startup，瞭解如何使用現有的 Python 安裝。
  3. 安裝完成後，安裝程式會提供選項，讓您建立「開始」選單和桌面捷徑、啟動 Google Cloud CLI 殼層，以及設定 gcloud CLI。保留啟動殼層和設定安裝作業的選項。安裝程式會啟動終端機視窗，並執行 gcloud init 指令來初始化、授權及設定 gcloud CLI。
  4. 預設安裝作業不會包含使用 gcloud 指令部署應用程式時所需的 App Engine 擴充功能。您可以使用 gcloud CLI 元件管理員安裝這些元件。

疑難排解提示

  • 如果因系統無法辨識 find 指令而導致安裝失敗，請確認 PATH 環境變數已設為包含 find 的資料夾。通常是 C:\WINDOWS\system32;。
  • 如果您已解除安裝 gcloud CLI，必須先重新啟動系統，才能再次安裝 gcloud CLI。
  • 如果解壓縮失敗，請以管理員身分執行安裝程式。

(選用) 建立宇宙專屬設定

如要搭配多個宇宙使用安裝的 gcloud CLI (例如 Google Cloud 和Cloud de Confiance)，可以為Cloud de Confiance 設定建立特定的 gcloud CLI 設定。

如要建立並切換至新設定，請執行下列指令：

gcloud config configurations create CONFIG_NAME
gcloud config configurations activate CONFIG_NAME

更改下列內容：

  • CONFIG_NAME：您為設定選擇的不重複名稱。

如果不建立宇宙專屬設定，其餘步驟會使用預設的 gcloud CLI 設定 (名為 default)。

建立登入設定檔

如要設定宇宙的存取權，您必須為 gcloud CLI 建立 JSON 設定檔，包括 Cloud de Confiance使用的網域，以及為組織設定的 IdP。

如要建立登入設定檔，請按照下列步驟操作：

  • 在有效設定中，設定 gcloud CLI 的宇宙網域：

    gcloud config set universe_domain s3nsapis.fr

  • 執行下列指令：

    AUDIENCE=locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID
UNIVERSE_WEB_DOMAIN="cloud.s3nscloud.fr"
UNIVERSE_API_DOMAIN="s3nsapis.fr"

gcloud iam workforce-pools create-login-config \
$AUDIENCE \
--universe-cloud-web-domain="$UNIVERSE_WEB_DOMAIN" \
--universe-domain="$UNIVERSE_API_DOMAIN" \
--output-file="wif-login-config.json"

    更改下列內容：

    • POOL_ID：組織 workload identity pool 的專屬 ID。
    • PROVIDER_ID：貴機構的識別資訊提供者 (IdP)。

輸出結果會與下列內容相似：

Created login configuration file [wif-login-config.json].

建立設定檔後，只要從同一部機器登入，就不必重複這個步驟。

使用 gcloud CLI 登入 Cloud de Confiance

現在，每次需要登入 Cloud de Confiance時，都可以使用設定檔：

  • 如要透過指令列登入，請執行下列指令：

    gcloud auth login --login-config=wif-login-config.json

  • 如需使用應用程式預設憑證 (ADC) (執行 Terraform 模組時必須使用)，請執行下列指令：

    gcloud auth application-default login --login-config=wif-login-config.json

網頁隨即開啟，您可以在該頁面輸入登入詳細資料。登入後，您可以按照其餘說明文件所述，繼續設定及使用 gcloud CLI。

(選用) 設定預設屬性

設定 gcloud CLI 時，系統會提供名為 default 的設定，可用於屬性，提供預設旗標值或控管工具的行為。雖然這是選用步驟，但建議您在使用工具前，先為 gcloud CLI 設定一些預設屬性，例如預設專案。如果您不想在每次執行指令時指定專案或偏好的運算位置，預設屬性就非常實用。

下列步驟會設定與 gcloud init 為 Google Cloud 使用者設定的相同屬性：

  1. 如要設定預設專案，請執行下列指令，並指定所選專案 ID：

    gcloud config set project PROJECT_ID

  2. 如果您使用 Compute Engine 或 GKE，部分指令會要求您指定運算區域或可用區。如要設定指令的預設區域，請執行下列指令：

    gcloud config set compute/region u-france-east1

    如要設定預設可用區，請執行下列指令：

    gcloud config set compute/zone ZONE

  3. 如要查看目前設定的屬性 (包括已驗證的使用者)，請執行下列指令：

    gcloud config list

如要瞭解 gcloud CLI 設定的運作方式，以及如何建立和使用其他設定，請參閱「管理 gcloud CLI 設定」。如要進一步瞭解如何指定屬性，請參閱「管理 gcloud CLI 屬性」。

(選用) 執行指令

執行核心指令，查看 gcloud CLI 安裝相關資訊：

  1. 列出憑證儲存在本機系統的帳戶：

    gcloud auth list

    gcloud CLI 會顯示已儲存憑證的帳戶清單：

    Credentialed Accounts
ACTIVE             ACCOUNT
*                  principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com

  2. 列出 gcloud CLI 有效設定中的屬性：

    gcloud config list

    gcloud CLI 會顯示屬性清單：

    [core]
account = principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/my-user@example.com
disable_usage_reporting = False
project = my-project

  3. 查看 gcloud 指令和其他主題的相關資訊：

    gcloud help

    舉例來說，如要查看 gcloud compute instances create 的說明：

    gcloud help compute instances create

    gcloud CLI 會顯示說明主題，其中包含指令說明、指令旗標和引數清單，以及指令使用範例。

後續步驟