Esta página se ha traducido con Cloud Translation API.

Crear y gestionar anotaciones

En esta página se describe cómo añadir anotaciones a un secreto y cómo editar y ver estas anotaciones.

Información general

Puedes usar anotaciones para almacenar metadatos personalizados sobre un secreto. Por ejemplo, puede que quieras anotar un secreto con la ruta en la que se montará. Las anotaciones pueden ser útiles de las siguientes formas:

Para categorizar los secretos en función de su finalidad, entorno (desarrollo, staging o producción) o nivel de sensibilidad. De esta forma, será más fácil buscar, filtrar y organizar secretos en Secret Manager.
Para indicar el formato o la estructura específicos del valor del secreto, lo que ayuda a la carga de trabajo a interpretarlo correctamente.
Para proporcionar sugerencias sobre cómo se debe usar el secreto o cualquier consideración especial para su gestión.

Por ejemplo, si tienes un secreto que contiene una contraseña de base de datos, puedes añadir anotaciones como las siguientes:

environment:production
purpose:database_access
owner:database_team

Estas anotaciones facilitan la identificación del propósito del secreto, su entorno y quién es responsable de él. Además, una carga de trabajo que acceda a este secreto puede usar las anotaciones para confirmar que está usando la contraseña correcta para el entorno de producción.

Las anotaciones no son lo mismo que las etiquetas. Las etiquetas se usan para ordenar, filtrar y agrupar recursos, mientras que las anotaciones se usan para almacenar metadatos arbitrarios que no identifican un secreto. Hay una restricción de caracteres y de longitud de caracteres al especificar metadatos en una etiqueta. Los metadatos de una anotación pueden ser pequeños o grandes, estructurados o no estructurados, y pueden incluir caracteres no permitidos por las etiquetas.

Roles obligatorios

Para añadir anotaciones a un secreto y actualizar anotaciones, se necesita el rol Administrador de Secret Manager (roles/secretmanager.admin) en el secreto, el proyecto, la carpeta o la organización.
Para ver las anotaciones, se necesita el rol Lector de Secret Manager (roles/secretmanager.viewer) en el secreto, el proyecto, la carpeta o la organización.

Los roles de Gestión de Identidades y Accesos (IAM) no se pueden conceder en una versión de un secreto. Para obtener más información, consulta Control de acceso con la gestión de identidades y accesos.

Añadir anotaciones a un secreto

Puedes añadir anotaciones al crear un secreto o al actualizar uno que ya tengas. Los metadatos de una anotación se almacenan como pares clave-valor. Para añadir anotaciones, utilice uno de los siguientes métodos:

Consola

En la Google Cloud consola, ve a la página Secret Manager.

Ir a Secret Manager
En la página Secret Manager, haz clic en Crear secreto.
En la página Crear secreto, introduce un nombre para el secreto en el campo Nombre.
Introduce un valor para el secreto (por ejemplo, abcd1234). También puedes subir un archivo de texto que contenga el valor del secreto con la opción Subir archivo. Esta acción crea automáticamente la versión del secreto.
Ve a la sección Anotaciones y haz clic en Añadir anotación.
Introduce la clave y el valor correspondiente.
Haz clic en Crear secreto.

gcloud

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

SECRET_ID: el ID del secreto o el identificador completo del secreto
KEY: la clave de la anotación
VALUE: el valor correspondiente de la clave de anotación

Ejecuta el siguiente comando:

Linux, macOS o 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

La respuesta contiene el secreto y las anotaciones.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

PROJECT_ID: el ID del proyecto Google Cloud
SECRET_ID: el ID del secreto o el identificador completo del secreto
KEY: la clave de la anotación
VALUE: el valor correspondiente de la clave de anotación

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la siguiente:

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

Para añadir anotaciones a un secreto, consulta la sección Editar anotaciones de este documento.

Las claves de anotación deben cumplir los siguientes requisitos:

Las claves deben ser únicas para cada secreto. No puedes repetir una clave en el mismo secreto.
Las claves deben tener entre 1 y 63 caracteres.
Las claves deben tener una codificación UTF-8 de 128 bytes como máximo.
Las claves deben empezar y terminar con un carácter alfanumérico.
Las claves pueden tener guiones, guiones bajos y puntos entre los caracteres alfanuméricos.
El tamaño total de las claves y los valores de las anotaciones debe ser inferior a 16 KiB.

Editar anotaciones

Para editar anotaciones, utilice uno de los siguientes métodos:

Consola

En la Google Cloud consola, ve a la página Secret Manager.

Ir a Secret Manager
Busca el secreto en la lista y haz clic en el menú Acciones asociado a ese secreto. En el menú Acciones, haz clic en Editar.
En la página Editar secreto, ve a la sección Anotaciones. Aquí puedes cambiar el valor de una anotación, eliminarla o añadir una nueva.
Cuando haya hecho los cambios, haga clic en Actualizar secreto.

gcloud

Editar anotaciones

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

SECRET_ID: el ID del secreto o el identificador completo del secreto
KEY: la clave de la anotación
VALUE: el valor correspondiente de la clave de anotación

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

La respuesta edita el secreto y las anotaciones.

Eliminar una anotación específica

Para quitar anotaciones, usa el siguiente comando:

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

Borrar todas las anotaciones

Para borrar todas las anotaciones, usa el siguiente comando:

gcloud secrets update SECRET_ID --clear-annotations

REST

Para borrar todas las anotaciones, usa el siguiente comando:

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

PROJECT_ID: el ID del proyecto Google Cloud
SECRET_ID: el ID del secreto o el identificador completo del secreto

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{'annotations': {}}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la siguiente:

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

Ver anotaciones

Para ver las anotaciones asociadas a un secreto, utiliza uno de los siguientes métodos:

Consola

En la Google Cloud consola, ve a la página Secret Manager.

Ir a Secret Manager
En la página Secret Manager, haz clic en el secreto cuyas anotaciones quieras ver.
Se abrirá la página de detalles del secreto. Haga clic en la pestaña Descripción general. Aquí puede ver las anotaciones adjuntas al secreto. Las claves se muestran en la columna de la izquierda, mientras que los valores se muestran en la columna de la derecha.

gcloud

Antes de usar los datos de los comandos que se indican a continuación, haz los siguientes cambios:

SECRET_ID: el ID del secreto o el identificador completo del secreto

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud secrets describe SECRET_ID

Windows (PowerShell)

gcloud secrets describe SECRET_ID

Windows (cmd.exe)

gcloud secrets describe SECRET_ID

La respuesta contiene el secreto y las anotaciones.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

PROJECT_ID: el ID del proyecto Google Cloud
SECRET_ID: el ID del secreto o el identificador completo del secreto

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la siguiente:

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

Siguientes pasos

Consulta cómo gestionar el acceso a los secretos.
Consulta cómo configurar las rotaciones de secretos.
Consulta cómo configurar notificaciones en un secreto.

Crear y gestionar anotaciones Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Información general

Roles obligatorios

Añadir anotaciones a un secreto

Consola

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

Editar anotaciones

Consola

gcloud

Editar anotaciones

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Eliminar una anotación específica

Borrar todas las anotaciones

REST

curl

PowerShell

Ver anotaciones

Consola

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

Siguientes pasos

Crear y gestionar anotaciones