為 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.8 MB b0dc27650a82e50321aa7c9d068cdc01443aa348f15489af9e5dec0a94623ae6
    Linux 64 位元

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 89.9 MB c9e8618c9257b3289deb7cb5483479230d5d96230bd68a80fce17f592d0d3012
    Linux 32 位元

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 54.2 MB b9a98b7ce9bc744c7bc955d8e42e2e862747d75d43b58d3b6a0bb16ed39b2da9

    如要下載 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 f6a222b32bac56fca8d787098a01c8e92cd0de52dd8c144ee74ca0c246c65b56
    macOS 64 位元

    (ARM64, Apple silicon)

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

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 52.7 MB e2a62c407607f789770071ac356a34576965571e3bf2451fe7876b56feae60b6

    或者，您也可以透過指令列下載封存檔。 將 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 集區的專屬 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 會顯示說明主題，其中包含指令說明、指令旗標和引數清單，以及指令使用範例。

後續步驟