Create and manage annotations

This topic discusses support for annotations in Secret Manager.

Overview

Use annotations to store custom metadata about a secret. For example, you might want to annotate a secret with the filepath it'll be mounted at. Annotations can also be used to aid administration and consumption by workloads.

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.

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.

Console

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

Go to the Secret Manager page
On the Secret Manager page, click Create Secret.
On the Create secret page, under Name, enter a name for the secret (e.g.my-secret).
(Optional) To also add a secret version when creating the initial secret, in the Secret value field, enter a value for the secret (e.g. abcd1234).
Click Add Annotation.
Enter the key and corresponding value.
Leave the Regions section unchanged.
Click the Create secret button.

gcloud CLI

To use Secret Manager on the command line, first install or upgrade to version 378.0.0 or higher of the gcloud CLI. On Compute Engine or Google Kubernetes Engine, you must authenticate with the cloud-platform scope.

 gcloud secrets create mysecret
--annotations= mykey=myval,mykey2=myval2

To add annotations to an existing secret, follow the steps mentioned under Edit annotations.

Note the following about annotation keys:

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 may have dashes, underscores, and dots in between the alphanumerics characters.
The total size of annotation keys and values must be less than 16KiB.

View annotations

Annotations attached to a secret are visible in the Overview tab of the Secret details page.

Console

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

Go to the Secret Manager page
On the Secret Manager page, click on the name of the secret.
The Secret details page opens. Select 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 CLI

 gcloud secrets describe mysecret

Edit annotations

You can update annotations in the Edit Secret page.

Console

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

Go to the Secret Manager page
On the Secret Manager page, click on the name of the secret.
The Secret details page opens. Click Edit Secret and scroll down to Annotations.
You can change the value of an existing annotation, delete the annotation, or add a new annotation.
Click Update Secret to save your changes.

gcloud CLI

 gcloud secrets update mysecret --update-annotations=mykey3=myval3

 gcloud secrets update mysecret --remove-annotations=mykey3=myval3

 gcloud secrets update mysecret --clear-annotations

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.