為 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 Shell 不適用於 Cloud de Confiance。本機電腦必須安裝 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.14。x86_64 Linux 套件包含預設會優先使用的 Python 解譯器。如要瞭解如何選擇及設定 Python 解譯器，請參閱 gcloud topic startup 說明文件。
  2. 下載下列其中一個檔案：
    平台 套件名稱 大小 SHA256 總和檢查碼
    Linux 64 位元

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 87.6 MB f10d38949faa524a869ed8ed421502d1f8ab922c1061b17504480e9a39bfee56
    Linux 64 位元

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 60.5 MB 65cb6931a8e9c72bc37b1f66d55efb08b5f7e52c5e7f437722efae4b334e6813
    Linux 32 位元

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 60.6 MB 08885ce04209009c9d15b0d060d402d313dba5508dc108d235732589a1b6a264

    如要下載 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.14。

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

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

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

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

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 60.7 MB f9859bc59ccd4e33afd4b387fdec0dedd936f0eccfbaf945f608bc0ba26feb36
    macOS 64 位元

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 60.6 MB 236e8aa065420888fe01152a4e1aff22cfe8e3adea8e64434421d5f390b9bdc4
    macOS 32 位元

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 59.0 MB 180f5688e65a99c9d3e965723113faf3bcd60ee0877acb37f0e72ed6e1327012

    或者，您也可以從指令列下載封存檔。 請將 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.13 和建議的模組。
    • 將 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.14。根據預設，Windows 版 Google Cloud CLI 會隨附 Python 3。如要使用 Google Cloud CLI，作業系統必須能夠執行支援的 Python 版本。
    • 安裝程式會安裝所有必要的依附元件，包括所需的 Python 版本。Google Cloud CLI 預設會安裝及管理 Python 3，但如有需要，您可以取消勾選「安裝隨附 Python」選項，使用現有的 Python 安裝版本。如要瞭解如何使用現有的 Python 安裝版本，請參閱 gcloud topic startup。
  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 前，先設定一些預設屬性，例如預設專案。如果您不想在每次執行指令時指定專案或偏好的運算位置，預設屬性就非常實用。

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

  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 會顯示說明主題，其中包含指令說明、指令標記和引數清單，以及指令使用範例。

後續步驟