アノテーションを作成、管理する

このページでは、リージョン シークレットにアノテーションを追加する方法と、これらのアノテーションを編集して表示する方法について説明します。

概要

アノテーションを使用して、シークレットに関するカスタム メタデータを保存できます。たとえば、マウント先のパスを使用して、シークレットにアノテーションを付けることができます。アノテーションは次のような場合に役立ちます。

  • 目的、環境（開発、ステージング、本番）、機密性レベルに基づいてシークレットを分類します。これにより、Secret Manager 内でシークレットの検索、フィルタリング、整理が容易になります。

  • シークレットの値の特定の形式または構造を示します。これにより、ワークロードがシークレットを正しく解釈できます。

  • シークレットの使用方法や、シークレットの処理に関する特別な考慮事項に関するヒントを提供します。

たとえば、データベース パスワードを含むシークレットがある場合は、次のようなアノテーションを追加できます。

  • environment:production

  • purpose:database_access

  • owner:database_team

これらのアノテーションにより、シークレットの目的、環境、担当者を簡単に特定できます。また、このシークレットにアクセスするワークロードは、アノテーションを使用して、本番環境に適したパスワードを使用していることを確認できます。

アノテーションはラベルとは異なります。ラベルはリソースの並べ替え、フィルタリング、グループ化に使用されるのに対し、アノテーションは、シークレットで、識別できない任意のメタデータの保存に使用されます。ラベルにメタデータを指定するときは、文字と文字長の制限があります。アノテーション内のメタデータは、小規模 / 大規模、構造化 / 非構造化のいずれでもかまいません。また、ラベルで許可されていない文字をメタデータに含めることもできます。

必要なロール

  • シークレットにアノテーションを追加して更新するには、シークレット、プロジェクト、フォルダ、または組織に対する Secret Manager 管理者のロール（roles/secretmanager.admin）が必要です。

  • アノテーションを表示するには、シークレット、プロジェクト、フォルダ、または組織に対する Secret Manager 閲覧者のロール（roles/secretmanager.viewer）が必要です。

シークレット バージョンには Identity and Access Management（IAM）ロールを付与できません。詳細については、IAM によるアクセス制御をご覧ください。

シークレットにアノテーションを追加する

アノテーションは、新しいシークレットの作成時または既存のシークレットの更新時に追加できます。アノテーションのメタデータは Key-Value ペアとして保存されます。アノテーションを追加するには、次のいずれかの方法を使用します。

Console

  1. Google Cloud コンソールの [Secret Manager] ページに移動します。

    Secret Manager に移動

  2. [Secret Manager] ページで、[リージョン シークレット] タブをクリックし、[リージョン シークレットを作成] をクリックします。

  3. [リージョン シークレットを作成] ページの [名前] フィールドに、シークレットの名前を入力します。

  4. シークレットの値を入力します（例: abcd1234）。[ファイルをアップロード] オプションを使用して、シークレット値を含むテキスト ファイルをアップロードすることもできます。この操作により、シークレット バージョンが自動的に作成されます。

  5. [リージョン] リストから、リージョン シークレットを保存するロケーションを選択します。

  6. [アノテーション] セクションに移動し、[アノテーションを追加] をクリックします。

  7. キーと対応する値を入力します。

  8. [シークレットの作成] をクリックします。

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

  • SECRET_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: Google Cloud プロジェクト ID
  • SECRET_ID: シークレットの ID またはシークレットの完全修飾識別子
  • KEY: アノテーション キー
  • VALUE: アノテーションキーに対応する値

HTTP メソッドと URL:

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 未満である必要があります。

アノテーションを編集

アノテーションを編集するには、次のいずれかの方法を使用します。

Console

  1. Google Cloud コンソールの [Secret Manager] ページに移動します。

    Secret Manager に移動

  2. [Secret Manager] ページで、[リージョン シークレット] タブをクリックします。

  3. リストでシークレットを見つけて、そのシークレットに関連付けられている [操作] メニューをクリックします。[操作] メニューで [編集] をクリックします。

  4. [シークレットを編集する] ページで、[アノテーション] セクションに移動します。ここでは、既存のアノテーションの値を変更したり、アノテーションを削除したり、新しいアノテーションを追加したりできます。

  5. 変更を加えたら、[シークレットを更新] をクリックします。

gcloud

既存のアノテーションを編集する

後述のコマンドデータを使用する前に、次のように置き換えます。

  • SECRET_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: Google Cloud プロジェクト ID
  • SECRET_ID: シークレットの ID またはシークレットの完全修飾識別子

HTTP メソッドと URL:

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\""
}

アノテーションを表示する

シークレットに適用されているアノテーションを表示するには、次のいずれかの方法を使用します。

Console

  1. Google Cloud コンソールの [Secret Manager] ページに移動します。

    Secret Manager に移動

  2. [Secret Manager] ページで、[リージョン シークレット] タブをクリックし、アノテーションを表示するシークレットをクリックします。

  3. シークレットの詳細ページが開きます。[概要] タブをクリックします。 ここでシークレットに適用されたアノテーションを確認できます。左側の列にキーが表示され、右側の列に値が表示されます。

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

  • SECRET_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: Google Cloud プロジェクト ID
  • SECRET_ID: シークレットの ID またはシークレットの完全修飾識別子

HTTP メソッドと URL:

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"
  }
}

次のステップ