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. Go to the Secret Manager page in the Google Cloud console.

   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 or fully qualified identifier for the secret
• KEY: the annotation key
• VALUE: the corresponding value of the annotation key

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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 or fully qualified identifier for 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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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

To add annotations to an existing secret, see the Edit annotations section of this document.

Annotation keys have the following requirements:

• Keys must be unique to a secret. You can't repeat a key in the same secret.

• Keys must be between 1 and 63 characters long.

• Keys must have a UTF-8 encoding of maximum 128 bytes.

• Keys must begin and end with an alphanumeric character.

• Keys can have dashes, underscores, and dots in between the alphanumerics characters.

• The total size of annotation keys and values must be less than 16KiB.

Edit annotations

To edit annotations, use one of the following methods:

Console

1. Go to the Secret Manager page in the Google Cloud console.

   Go to Secret Manager

2. Locate the secret in the list and click the Actions menu associated with that secret. In the Actions menu, click Edit.

3. On the Edit secret page, go to the Annotations section. Here you can change the value of an existing annotation, delete the annotation, or add a new annotation.

4. After you have made your changes, click Update secret.

gcloud

Edit existing annotations

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

• SECRET_ID: the ID of the secret or fully qualified identifier for the secret
• KEY: the annotation key
• VALUE: the corresponding value of the annotation key

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

The response edits the secret and the annotations.

Remove a specific annotation

To remove annotations, use the following command:

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

Clear all annotations

To clear all annotations, use the following command:

gcloud secrets update SECRET_ID --clear-annotations

REST

To clear all annotations, use the following command:

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 or fully qualified identifier for the secret

HTTP method and URL:

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

Request JSON body:

{'annotations': {}}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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": "\"16211dd90b37e7\""
}

View annotations

To view annotations attached to a secret, use one of the following methods:

Console

1. Go to the Secret Manager page in the Google Cloud console.

   Go to Secret Manager

2. On the Secret Manager page, click on the secret whose annotations you want to view.

3. The secret details page opens. Click the Overview tab. Here you can see the annotations attached to the secret. The keys are listed on the left column while the values are displayed on the right column.

gcloud

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

• SECRET_ID: the ID of the secret or fully qualified identifier for the secret

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets describe SECRET_ID

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets describe SECRET_ID

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud secrets describe SECRET_ID

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 or fully qualified identifier for the secret

HTTP method and URL:

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

Request JSON body:

{}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

curl -X GET \
     -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"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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 GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID" | 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"
  }
}

What's next

• Learn how to manage access to secrets.
• Learn how to set up rotation schedules for secrets.
• Learn how to set up notifications on a secret.