建立及管理註解

本頁說明如何為區域密鑰新增註解，以及如何編輯及查看這些註解。

總覽

您可以使用註解，儲存有關密鑰的自訂中繼資料。舉例來說，您可能想使用密鑰要掛接的路徑為密鑰加上註解。註解有助於：

  • 根據用途、環境 (開發、暫存、實際工作環境) 或機密程度分類密鑰。方便您在 Secret Manager 中搜尋、篩選及整理密鑰。

  • 指出密碼值的特定格式或結構，協助工作負載正確解讀密碼值。

  • 提供有關如何使用密鑰的提示，或處理密鑰時的任何特殊考量。

舉例來說，如果您的密碼含有資料庫密碼，可以新增下列註解：

  • environment:production

  • purpose:database_access

  • owner:database_team

這些註解可協助您輕鬆識別密鑰的用途、環境，以及負責人。此外，存取這項密鑰的工作負載可以使用註解，確認自己使用的是正確的正式環境密碼。

註解與標籤不同。標籤用於排序、篩選及分組資源，而註解則用於在密鑰上儲存任意非識別的中繼資料。在標籤中指定中繼資料時，字元和字元長度會受到限制。註解中的中繼資料可以是各種規模的結構化或非結構化資料，也可以加入標籤不允許的字元。

必要的角色

  • 如要在密鑰上新增註解及更新註解，您必須具備密鑰、專案、資料夾或機構的 Secret Manager 管理員角色 (roles/secretmanager.admin)。

  • 如要查看註解，您必須擁有密鑰、專案、資料夾或機構的 Secret Manager 檢視者角色 (roles/secretmanager.viewer)。

您無法在密鑰版本上授予身分與存取權管理 (IAM) 角色。詳情請參閱「使用 IAM 控管存取權」。

為密鑰新增註解

建立新密鑰或更新現有密鑰時，您可以新增註解。 註解中的中繼資料會以鍵/值組合形式儲存。如要新增註解，請使用下列其中一種方法：

控制台

  1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

    前往 Secret Manager

  2. 在「Secret Manager」頁面中，按一下「區域性密鑰」分頁標籤，然後按一下「建立區域性密鑰」。

  3. 在「建立區域密鑰」頁面的「名稱」欄位中，輸入密鑰名稱。

  4. 輸入密鑰值 (例如 abcd1234)。您也可以使用「上傳檔案」選項，上傳含有密鑰值的文字檔。這項動作會自動建立密鑰版本。

  5. 從「Region」(區域) 清單中，選取要儲存區域密鑰的位置。

  6. 前往「備註」部分，然後按一下「新增備註」。

  7. 輸入鍵和對應的值。

  8. 按一下「建立密鑰」。

gcloud

使用下方的任何指令資料之前，請先替換以下項目：

  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
  • LOCATION：密鑰的 Google Cloud 位置
  • KEY：註解鍵
  • VALUE：註解鍵的對應值

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets create SECRET_ID --location=LOCATION \
    --set-annotations=KEY1=VAL1,KEY2=VAL2

Windows (PowerShell)

gcloud secrets create SECRET_ID --location=LOCATION `
    --set-annotations=KEY1=VAL1,KEY2=VAL2

Windows (cmd.exe)

gcloud secrets create SECRET_ID --location=LOCATION ^
    --set-annotations=KEY1=VAL1,KEY2=VAL2

回應會包含密鑰和註解。

REST

使用任何要求資料之前，請先替換以下項目：

  • LOCATION：密鑰的 Google Cloud 位置
  • PROJECT_ID：專案 ID Google Cloud
  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
  • KEY：註解鍵
  • VALUE：註解鍵的對應值

HTTP 方法和網址：

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations

JSON 要求主體：

{'annotations': {'KEY1': 'VALUE1', 'KEY2': 'VALUE2' }}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

如要為現有密鑰新增註解，請參閱本文件的「編輯註解」一節。

註解鍵必須符合下列規定：

  • 密鑰不得重複。您無法在同一個密鑰中重複使用金鑰。

  • 鍵的長度必須介於 1 至 63 個字元之間。

  • 索引鍵的 UTF-8 編碼長度不得超過 128 個位元組。

  • 金鑰開頭和結尾必須為英數字元。

  • 鍵的英數字元之間可以有破折號、底線和半形句號。

  • 註解鍵和值的總大小必須小於 16 KiB。

編輯註解

如要編輯註解，請使用下列其中一種做法：

控制台

  1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

    前往 Secret Manager

  2. 在「Secret Manager」頁面中，按一下「區域性密鑰」分頁標籤。

  3. 在清單中找出密鑰，然後點選與該密鑰相關的「動作」選單。在「動作」選單中，按一下「編輯」。

  4. 在「Edit secret」(編輯密鑰) 頁面，前往「Annotations」(註解) 區段。您可以在這裡變更現有註解的值、刪除註解或新增註解。

  5. 完成變更後，按一下「更新密鑰」。

gcloud

編輯現有註解

使用下方的任何指令資料之前，請先替換以下項目：

  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
  • LOCATION：密鑰的 Google Cloud 位置
  • KEY：註解鍵
  • VALUE：註解鍵的對應值

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION --update-annotations= KEY=VAL

回應會編輯密鑰和註解。

移除特定註解

如要移除註解，請使用下列指令：

gcloud secrets update SECRET_ID --location=LOCATION --remove-annotations= KEY=VAL

清除所有註解

如要清除所有註解，請使用下列指令：

gcloud secrets update SECRET_ID --location=LOCATION --clear-annotations

REST

如要清除所有註解，請使用下列指令：

使用任何要求資料之前，請先替換以下項目：

  • LOCATION：密鑰的 Google Cloud 位置
  • PROJECT_ID：專案 ID Google Cloud
  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID

HTTP 方法和網址：

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations

JSON 要求主體：

{'annotations': {}}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dd90b37e7\""
}

查看註解

如要查看附加至密鑰的註解，請使用下列其中一種方法：

控制台

  1. 前往 Google Cloud 控制台的「Secret Manager」頁面。

    前往 Secret Manager

  2. 在「Secret Manager」頁面中，按一下「區域密鑰」分頁標籤，然後按一下要查看註解的密鑰。

  3. 系統會開啟密鑰詳細資料頁面。按一下「總覽」分頁標籤。 您可以在這裡查看附加至密鑰的註解。鍵會列在左欄，值則會顯示在右欄。

gcloud

使用下方的任何指令資料之前，請先替換以下項目：

  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID
  • LOCATION：密鑰的 Google Cloud 位置

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets describe SECRET_ID --location=LOCATION

回應會包含密鑰和註解。

REST

使用任何要求資料之前，請先替換以下項目：

  • LOCATION：密鑰的 Google Cloud 位置
  • PROJECT_ID：專案 ID Google Cloud
  • SECRET_ID：密鑰的 ID 或密鑰的完整 ID

HTTP 方法和網址：

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID

JSON 要求主體：

{}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

後續步驟