管理服務帳戶

Google Distributed Cloud (GDC) 實體隔離方案中的服務身分，可為工作負載或服務提供專屬身分，以程式輔助方式安全存取資源和微服務。這是應用程式或工作負載使用的特殊身分，而非人員身分，無法用於登入。與使用者帳戶類似，您可以將權限和角色授予服務身分，藉此定義服務身分的授權存取範圍。

您可能會發現這個概念有兩個名稱。GDC 控制台主要使用「服務身分」一詞，而 gdcloud 指令和 API 互動則經常使用「服務帳戶」一詞。後者反映的是基礎 Kubernetes 自訂資源的名稱 ProjectServiceAccount。這兩個詞彙指的是同一件事：工作負載的非真人身分。本文主要使用「服務身分」一詞。

服務身分可用於管理 GDC 基礎架構，例如：

內部 Distributed Cloud 服務和工作負載，可安全存取 Distributed Cloud 控制層應用程式設計介面 (API)。舉例來說，資料庫服務會與 Kubernetes API 互動，以建立及刪除資料庫。
Distributed Cloud 中的客戶工作負載，可存取 Distributed Cloud 服務，並發出授權的應用程式程式設計介面 (API) 呼叫。舉例來說，服務身分可以透過 Vertex AI Workbench 筆記本管理客戶，並使用 Speech-to-Text API 轉錄音訊檔案。
要與 Distributed Cloud 連結的外部工作負載。舉例來說，服務身分可以管理 Distributed Cloud 外部的應用程式，該應用程式會將文件數位化，但想使用光學字元辨識 (OCR) API 取代目前的 OCR 引擎。
Distributed Cloud 服務或系統控制器，可安全存取客戶資源或使用者叢集。舉例來說，服務身分可以管理驗證和授權工作流程，其中在管理員叢集中執行的服務控制器，需要在客戶管理的使用者叢集中執行工作負載。

您可以使用 GDC 控制台、gdcloud CLI 或 API 管理服務身分帳戶。使用 gdcloud CLI 時，服務身分功能是以全域 ProjectServiceAccount API 為基礎建構而成。由於 ProjectServiceAccount 資源是全域設定，因此可在 gdcloud 宇宙的所有區域運作。

事前準備

您只能在專案中建立服務身分。如要瞭解如何建立專案，請參閱「建立專案」一文。

管理服務身分包括服務身分 (以 ProjectServiceAccount 資源表示) 和相關聯的憑證 (公開和私密金鑰組)。如要取得管理服務身分和憑證所需的權限，請要求組織 IAM 管理員或專案 IAM 管理員，在該專案中授予您專案 IAM 管理員 (project-iam-admin) 角色。

建立服務身分

建立服務身分包括建立帳戶和相關聯的憑證。

建立帳戶

如要為服務身分建立帳戶，請使用 GDC 控制台、gdcloud CLI 或 API，在專案中建立 ProjectServiceAccount 資源。

控制台

登入 GDC 控制台。
在導覽選單中，依序選取「身分與存取權」>「服務身分」。
按一下「Create Service Identity」(建立服務身分)。「服務身分詳細資料」頁面隨即開啟。
在「服務身分名稱」欄位中，輸入服務身分的名稱。例如：testserviceidentity。
點選「建立」。

gdcloud

建立帳戶：

gdcloud iam service-accounts create NAME \
    --project=PROJECT

替換下列值：

NAME： ProjectServiceAccount的名稱。專案命名空間中的名稱不得重複。
PROJECT：要在其中建立服務身分的專案。如果已設定 gdcloud init，請省略 --project 旗標。

這個指令會在 Management API 伺服器上的專案命名空間中建立 ProjectServiceAccount。

API

建立 ProjectServiceAccount 自訂資源 YAML 檔案，例如 my-project-sa.yaml：
```
apiVersion: resourcemanager.global.gdc.goog/v1
kind: ProjectServiceAccount
metadata:
  name: NAME
  namespace: PROJECT
spec:
  keys:
  - algorithm: ALGORITHM
  id: KEY_ID
  key: BASE64_ENCODED_KEY
  validAfter: "START_TIME"
  validBefore: "EXPIRATION_TIME"
```
請替換下列變數：
- NAME：資源的名稱。ProjectServiceAccount專案命名空間中的名稱不得重複。
- PROJECT：要在其中建立服務身分的專案。
- ALGORITHM：金鑰的演算法。僅支援 ES256 金鑰。
- KEY_ID：金鑰的專屬 ID。這個 ID 用於判斷要驗證的金鑰。
- BASE64_ENCODED_KEY：採用 Base64 編碼的 PEM 格式公開金鑰，用於驗證。用於產生這個公開金鑰的私密金鑰應為 ECDSA P256 PEM 格式。
- START_TIME：金鑰生效的開始時間，例如 2025-02-07T00:59:34Z。
- EXPIRATION_TIME：金鑰的到期時間，例如 2026-02-07T00:59:34Z。
將 ProjectServiceAccount 自訂資源套用至全域 API 伺服器：
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
將 GLOBAL_API_SERVER_KUBECONFIG 變數替換為全域 API 伺服器的 kubeconfig 檔案路徑。

建立憑證

如要讓工作負載或應用程式以服務身分 (以您建立的帳戶表示) 進行驗證，您需要產生憑證。建立憑證時，需要產生加密編譯私密金鑰和公開金鑰配對，並將公開金鑰與服務身分建立關聯。

如要為服務身分建立憑證，請使用 GDC 控制台、gdcloud CLI 或 API。

控制台

登入 GDC 控制台。
在導覽選單中，依序選取「身分與存取權」>「服務身分」。
按一下要新增至金鑰的服務身分名稱。
按一下「建立新金鑰」。
新金鑰會顯示在「金鑰」清單中，對話方塊也會確認您已成功建立金鑰。

gdcloud

gdcloud 指令會建立應用程式預設憑證 JSON 檔案，以及公開和私密金鑰組：

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

替換下列值：

APPLICATION_DEFAULT_CREDENTIALS_FILENAME：JSON 檔案的名稱。
PROJECT：選取要建立金鑰的專案。如果已設定 gdcloud init，則可以省略 --project 旗標。
NAME：要新增金鑰的服務身分識別名稱。
CA_CERTIFICATE_PATH：選用：憑證授權單位 (CA) 憑證路徑，用於驗證驗證端點。如未指定這個路徑，系統會使用 CA 憑證。您必須在系統 CA 憑證中安裝 CA。

Distributed Cloud 會將公開金鑰新增至您用來驗證私密金鑰簽署的 JSON Web Token (JWT) 的金鑰。ProjectServiceAccount私密金鑰會寫入應用程式預設憑證 JSON 檔案。

以下範例顯示應用程式預設憑證 JSON 檔案：

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "/path/to/ca.crt",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

本範例使用下列值：

project：機構中的專案命名空間。
private_key_id：指派給金鑰的 ID。
private_key：CLI 產生的 PEM 格式 ECDSA P256 私密金鑰。
name：服務身分的名稱。
ca_cert_path：用於驗證驗證端點的憑證授權單位 (CA) 憑證路徑。
token_uri：驗證端點的位址。

API

產生公開和私密金鑰組。下列指令以 openssl 為例，這是用於此目的的常見工具。

openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
openssl ec -in "key.pem" -pubout > "pub.pem"

以 Base64 編碼公開金鑰，並擷取金鑰 ID：

KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
BASE64_ENCODED_KEY=$(cat pub.pem | base64)

建立或更新 ProjectServiceAccount 自訂資源 YAML 檔案，包括上一個步驟中產生的金鑰資訊：
```
apiVersion: resourcemanager.global.gdc.goog/v1
kind: ProjectServiceAccount
metadata:
  name: NAME
  namespace: PROJECT
spec:
  keys:
  - algorithm: ALGORITHM
  id: KEY_ID
  key: BASE64_ENCODED_KEY
  validAfter: "START_TIME"
  validBefore: "EXPIRATION_TIME"
```
請替換下列變數：
- NAME：資源的名稱。ProjectServiceAccount專案命名空間中的名稱不得重複。
- PROJECT：您要在其中建立金鑰的專案。
- ALGORITHM：金鑰的演算法。僅支援 ES256 金鑰。
- KEY_ID：金鑰的專屬 ID。這個 ID 用於判斷要驗證的金鑰。
- BASE64_ENCODED_KEY：採用 Base64 編碼的 PEM 格式公開金鑰，用於驗證。用於產生這個公開金鑰的私密金鑰應為 ECDSA P256 PEM 格式。
- START_TIME：金鑰生效的開始時間，例如 2025-02-07T00:59:34Z。
- EXPIRATION_TIME：金鑰的到期時間，例如 2026-02-07T00:59:34Z。
將 ProjectServiceAccount 自訂資源套用至全域 API 伺服器：
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
將 GLOBAL_API_SERVER_KUBECONFIG 變數替換為全域 API 伺服器的 kubeconfig 檔案路徑。
建立內含私密金鑰的應用程式預設憑證 JSON 檔案。確認 JSON 檔案中的 KEY_ID 變數設為與 ProjectServiceAccount 規格中使用的 KEY_ID 變數相同的值。
```
cat <<EOF > "key_file.json"
{
  "format_version": "1",
  "name": "NAME",
  "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')",
  "private_key_id": "KEY_ID",
  "project": "PROJECT",
  "token_uri": "AUTH_URL",
  "type": "gdch_service_account"
}
EOF
```
請替換下列變數：
- NAME：服務身分的名稱。
- KEY_ID：金鑰的專屬 ID。ID 用於判斷要驗證的鍵，且必須與 ProjectServiceAccount 規格中使用的 KEY_ID 值相符。
- PROJECT：機構中的專案命名空間。
- AUTH_URL：驗證端點的地址。

如要瞭解如何使用產生的金鑰檔案，以這個服務身分驗證 gdcloud CLI，請參閱「使用金鑰授權服務身分」一節。

查看服務身分

本節說明如何查看服務身分及其相關聯的公開金鑰。

查看服務身分清單

如要查看專案中的服務身分清單，請使用 GDC 主控台或 gdcloud CLI。

控制台

登入 GDC 控制台。
選取專案。
在導覽選單中，依序點選「身分識別與存取權」>「服務身分」，即可查看專案的服務身分清單。

gdcloud

列出專案中的服務身分帳戶：

gdcloud iam service-accounts list \
    --project=PROJECT

將 PROJECT 替換為專案 ID。

查看服務身分的公開金鑰清單

列出專案中向服務身分帳戶註冊的公開金鑰：

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

更改下列內容：

PROJECT：專案 ID。
NAME：要使用的服務身分帳戶名稱。

授予服務身分權限

如要授予服務身分權限，請使用 GDC 控制台或 gdcloud CLI 建立角色繫結，將一或多個角色指派給服務身分。

控制台

登入 GDC 控制台。
選取專案。
在導覽選單中，依序選取「身分與存取權」>「存取權」。
在「成員」清單中，按一下「新增成員」。系統會顯示「使用者與角色」頁面。
在「成員類型」清單中選取「服務身分」。
在「Service identity」(服務身分) 清單中，選取要指派角色繫結的服務身分。
在「角色」清單中，選取要指派給服務身分的角色，例如「備份建立者」。
選用：如要新增其他角色，請按一下「Add another role」(新增其他角色)。選取其他角色。
按一下「新增」。

gdcloud

您可以將服務身分帳戶繫結至專案命名空間中的角色，或繫結至不同命名空間中的角色。

將帳戶繫結至專案命名空間中的角色：
```
gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --iam-account=NAME
```
更改下列內容：
- PROJECT：要在其中建立角色綁定的專案。如果已設定 gdcloud init，則可以省略 --project 旗標。
- ROLE：要指派給帳戶的預先定義角色。以 Role/name 格式指定角色，其中 Role 是 Kubernetes 類型 IAMRole，而 name 是預先定義角色的名稱。舉例來說，如要指派專案檢視者角色，請將角色設為 IAMRole/project-viewer。
- NAME：要使用的服務身分帳戶名稱。
將帳戶繫結至其他命名空間中的角色：
```
gdcloud iam service-accounts add-iam-policy-binding \
    --role=ROLE \
    --role-namespace=ROLE_NAMESPACE \
    --iam-account=NAME
```
更改下列內容：
- ROLE：要指派給帳戶的預先定義角色。以 Role/name 格式指定角色，其中 Role 是 Kubernetes 類型 IAMRole，而 name 是預先定義角色的名稱。舉例來說，如要指派專案檢視者角色，請將角色設為 IAMRole/project-viewer。
- ROLE_NAMESPACE：要與帳戶繫結的角色命名空間，而非專案命名空間。
- NAME：要使用的服務身分帳戶名稱。

驗證及使用服務身分

如要將 gdcloud 和其他工具設定為以服務身分運作，請先使用服務身分的金鑰檔案向 gdcloud 進行驗證。完成驗證後，您可以使用服務身分的憑證產生符記或 kubeconfig 檔案。

使用金鑰授權服務身分

gdcloud auth activate-service-account 指令會使用服務身分驗證 gdcloud CLI。這樣一來，您就能使用服務身分帳戶權限，對 Distributed Cloud 資源執行動作，而不必使用使用者帳戶。

使用金鑰授權服務身分：

如果還沒有憑證金鑰檔案，請建立一個。
執行下列指令，啟用服務身分：
```
gdcloud auth activate-service-account --key-file=KEY_FILE
```
將 KEY_FILE 替換為憑證金鑰檔案的路徑，通常為 JSON 格式。

啟用成功後，gdcloud 會使用服務身分的憑證，而非您的使用者憑證。

列印服務身分的 ID 權杖

授權服務身分後，您就可以列印該身分的身分權杖。您可以將這個權杖做為不記名權杖，驗證 HTTP 要求。也就是說，只要持有權杖，任何一方都能存取 AUDIENCES 參數中定義的服務。

為指定的服務身分帳戶列印身分權杖：

gdcloud auth print-identity-token --audiences=AUDIENCES

將 AUDIENCES 替換為權杖的預期接收者或服務。只能指定一個目標對象。

產生 kubeconfig 檔案

授權服務身分後，即可產生 kubeconfig 檔案，向叢集進行驗證。

設定 gdcloud core/organization_console_url 屬性：
```
gdcloud config set core/organization_console_url
https://GDC_URL
```
將 GDC_URL 替換為貴機構的網址。
產生 kubeconfig 檔案，使用有效服務身分存取叢集：
- 區域叢集：
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
```
  更改下列內容：
  - KUBECONFIG_PATH：您要儲存所產生 kubeconfig 檔案的路徑。
  - CLUSTER_NAME：區域叢集名稱。
    
    注意： 叢集名稱清單位於登入設定網址：
    https://GDC_URL/.well-known/login-config。
  - ZONE：叢集所在的區域名稱。
- 全球 API 伺服器：
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials global-api
```
  將 KUBECONFIG_PATH 替換為要儲存所產生 kubeconfig 檔案的路徑。

系統會產生 kubeconfig 檔案，並設定為以服務身分驗證。以下是 YAML 檔案範例：

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <REDACTED>
    server: <REDACTED>
  name: cluster-name
contexts:
- context:
    cluster: cluster-name
    user: gdch_console-<REDACTED>_cluster-name
  name: cluster-name-gdch_console-<REDACTED>_cluster-name
current-context: cluster-name-gdch_console-gdc1-staging-gpcdemolabs-com_cluster-name
kind: Config
preferences: {}
users:
- name: gdch_console-<REDACTED>_cluster-name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - --audience=<REDACTED>
      command: gdcloud-k8s-auth-plugin
      env: null
      installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use
        plugin
      interactiveMode: Never
      provideClusterInfo: false

刪除服務身分

刪除服務身分後，系統會刪除 ProjectServiceAccount 和相關聯的公開金鑰，現有的私密金鑰會失效，應用程式也無法再透過該服務身分存取專案資源。

如要刪除服務身分，請使用 GDC 控制台或 gdcloud CLI。

控制台

登入 GDC 控制台。
在導覽選單中，依序選取「身分與存取權」>「服務身分」。
找到您要刪除的服務身分，並選取旁邊的核取方塊。
按一下「Delete」(刪除)。
確認對話方塊隨即顯示。在「Confirm by typing the following below」(如要確認，請在下方輸入以下內容) 欄位中，輸入 remove。
按一下「Delete」(刪除)。

gdcloud

執行下列指令來刪除服務身分：

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

更改下列內容：

NAME：要刪除的服務身分帳戶名稱。
PROJECT：專案 ID。

刪除憑證

如要停用特定金鑰組，但不想刪除整個服務身分帳戶，可以從服務身分帳戶中刪除公開金鑰。這項操作會使對應的私密金鑰失效。

如要刪除公開金鑰，請使用 GDC 控制台或 gdcloud CLI。

控制台

登入 GDC 控制台。
在導覽選單中，依序選取「身分與存取權」>「服務身分」。
按一下要刪除金鑰的服務身分名稱。
按一下「刪除」。
在確認對話方塊中按一下「刪除」。

gdcloud

從專案的服務身分帳戶中，移除具有金鑰 ID 的公開金鑰：

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME

更改下列內容：

KEY_ID：金鑰的專屬 ID。
PROJECT：專案 ID。
NAME：服務身分帳戶的名稱。

管理服務帳戶 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

建立服務身分

建立帳戶

控制台

gdcloud

API

建立憑證

控制台

gdcloud

API

查看服務身分

查看服務身分清單

控制台

gdcloud

查看服務身分的公開金鑰清單

授予服務身分權限

控制台

gdcloud

驗證及使用服務身分

使用金鑰授權服務身分

列印服務身分的 ID 權杖

產生 kubeconfig 檔案

刪除服務身分

控制台

gdcloud

刪除憑證

控制台

gdcloud

管理服務帳戶