Create and manage annotations

This page describes how to add annotations to a secret and how to edit and view these annotations.

Overview

You can use annotations to store custom metadata about a secret. For example, you might want to annotate a secret with the path it'll be mounted at. Annotations can be helpful in the following ways:

  • To categorize secrets based on their purpose, environment (development, staging, production), or sensitivity level. This makes it easier to search, filter, and organize secrets within Secret Manager.

  • To indicate the specific format or structure of the secret's value, helping the workload interpret it correctly.

  • To provide hints about how the secret should be used or any special considerations for its handling.

For example, if you have a secret containing a database password, you can add annotations such as the following:

  • environment:production

  • purpose:database_access

  • owner:database_team

These annotations make it easy to identify the secret's purpose, its environment, and who's responsible for it. Additionally, a workload accessing this secret can use the annotations to confirm that it's using the right password for the production environment.

Annotations are not the same as labels. Labels are used for sorting, filtering, and grouping resources, whereas annotations are used to store arbitrary, non-identifying metadata on a secret. There is a restriction of characters and character length when specifying metadata in a label. The metadata in an annotation can be small or large, structured or unstructured, and can include characters not permitted by labels.

Required roles

  • Adding annotations on a secret and updating annotations requires the Secret Manager Admin role (roles/secretmanager.admin) on the secret, project, folder, or organization.

  • Viewing annotations requires the Secret Manager Viewer role (roles/secretmanager.viewer) on the secret, project, folder, or organization.

Identity and Access Management (IAM) roles can't be granted on a secret version. See Access control with IAM for more information.

Add annotations to a secret

You can add annotations at the time of creating a new secret or updating an existing secret. The metadata in an annotation is stored as key-value pairs. To add annotations, use one of the following methods:

Console

  1. In the Google Cloud console, go to the Secret Manager page.

    Go to Secret Manager

  2. On the Secret Manager page, click Create secret.

  3. On the Create secret page, enter a name for the secret in the Name field.

  4. Enter a value for the secret (for example, abcd1234). You can also upload a text file containing the secret value using the Upload file option. This action automatically creates the secret version.

  5. Go to the Annotations section, and then click Add annotation.

  6. Enter the key and corresponding value.

  7. Click Create secret.

gcloud

Before using any of the command data below, make the following replacements:

  • SECRET_ID: the ID of the secret
  • KEY: the annotation key
  • VALUE: the corresponding value of the annotation key

Execute the following command:

Linux, macOS, or Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

The response contains the secret and the annotations.

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the Google Cloud project ID
  • SECRET_ID: the ID of the secret
  • KEY: the annotation key
  • VALUE: the corresponding value of the annotation key

HTTP method and URL: 

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

Request JSON body: 

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

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

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

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

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

C#

To run this code, first set up a C# development environment and install the Secret Manager C# SDK. On Compute Engine or GKE, you must authenticate with the cloud-platform scope. 


using Google.Api.Gax.ResourceNames;
using Google.Cloud.SecretManager.V1;
using System.Collections.Generic;

public class CreateSecretWithAnnotationsSample
{
    public Secret CreateSecretWithAnnotations(
      string projectId = "my-project"