Crea y administra anotaciones

En esta página, se describe cómo agregar anotaciones a un secreto regional y cómo editarlas y verlas.

Descripción general

Puedes usar anotaciones para almacenar metadatos personalizados sobre un secreto. Por ejemplo, es posible que desees annotated un secreto con la ruta de acceso en la que se montará. Las anotaciones pueden ser útiles de las siguientes maneras:

  • Para categorizar los secretos según su propósito, entorno (desarrollo, etapa de pruebas o producción) o nivel de sensibilidad. Esto facilita la búsqueda, el filtrado y la organización de 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 control.

Por ejemplo, si tienes un secreto que contiene una contraseña de base de datos, puedes agregar 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 el responsable de él. Además, una carga de trabajo que accede 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 en un secreto. Existe una restricción de caracteres y longitud de caracteres cuando se especifican metadatos en una etiqueta. Los metadatos de una anotación pueden ser pequeños o grandes, estructurados o no estructurados, y pueden incluir caracteres que las etiquetas no permiten.

Roles obligatorios

  • Para agregar anotaciones en un secreto y actualizarlas, se requiere el rol de administrador de Secret Manager (roles/secretmanager.admin) en el secreto, el proyecto, la carpeta o la organización.

  • Para ver las anotaciones, se requiere el rol de visor de Secret Manager (roles/secretmanager.viewer) en el secreto, el proyecto, la carpeta o la organización.

No se pueden otorgar roles de Identity and Access Management (IAM) en una versión secreta. Consulta Control de acceso con IAM para obtener más información.

Cómo agregar anotaciones a un Secret

Puedes agregar anotaciones cuando creas un secreto nuevo o actualizas uno existente. Los metadatos de una anotación se almacenan como pares clave-valor. Para agregar anotaciones, usa uno de los siguientes métodos:

Console

  1. Ve a la página de Secret Manager en la consola de Google Cloud.

    Ir a Secret Manager

  2. En la página de Secret Manager, haz clic en la pestaña Secretos regionales y, luego, en Crear secreto regional.

  3. En la página Crear secreto regional, ingresa un nombre para el secreto en el campo Nombre.

  4. Ingresa 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 Secret.

  5. En la lista Región, selecciona la ubicación en la que deseas que se almacene tu Secret regional.

  6. Ve a la sección Anotaciones y, luego, haz clic en Agregar anotación.

  7. Ingresa la clave y el valor correspondiente.

  8. Haz clic en Crear secreto.

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret
  • LOCATION: La ubicación de Google Cloud del secreto
  • KEY: La clave de 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 --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

La respuesta contiene el secreto y las anotaciones.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: La ubicación de Google Cloud del secreto
  • PROJECT_ID: El ID del proyecto de Google Cloud
  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret
  • KEY: La clave de anotación
  • VALUE: El valor correspondiente de la clave de anotación

Método HTTP y URL: 

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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

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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Para agregar anotaciones a un secreto existente, consulta la sección Edita anotaciones de este documento.

Las claves de anotación tienen los siguientes requisitos:

  • Las claves deben ser únicas para un 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 comenzar 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 la anotación debe ser inferior a 16 KiB.

Cómo editar anotaciones

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

Console

  1. Ve a la página de Secret Manager en la consola de Google Cloud.

    Ir a Secret Manager

  2. En la página de Secret Manager, haz clic en la pestaña Secretos regionales.

  3. Busca el secreto en la lista y haz clic en el menú Acciones asociado con él. En el menú Acciones, haz clic en Editar.

  4. En la página Editar secreto, ve a la sección Anotaciones. Aquí puedes cambiar el valor de una anotación existente, borrarla o agregar una nueva.

  5. Después de realizar los cambios, haz clic en Actualizar secreto.

gcloud

Cómo editar anotaciones existentes

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret
  • LOCATION: La ubicación de Google Cloud del secreto
  • KEY: La clave de 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 --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

La respuesta edita el secreto y las anotaciones.

Cómo quitar una anotación específica

Para quitar las anotaciones, usa el siguiente comando:

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

Borrar todas las anotaciones

Para borrar todas las anotaciones, usa el siguiente comando:

gcloud secrets update SECRET_ID --location=LOCATION --clear-annotations

REST

Para borrar todas las anotaciones, usa el siguiente comando:

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: La ubicación de Google Cloud del secreto
  • PROJECT_ID: El ID del proyecto de Google Cloud
  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret

Método HTTP y URL: 

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Cómo ver anotaciones

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

Console

  1. Ve a la página de Secret Manager en la consola de Google Cloud.

    Ir a Secret Manager

  2. En la página de Secret Manager, haz clic en la pestaña Secretos regionales y, luego, en el secreto cuyas anotaciones deseas ver.

  3. Se abrirá la página de detalles del secreto. Haz clic en la pestaña Descripción general. Aquí puedes ver las anotaciones adjuntas al secreto. Las claves se enumeran en la columna de la izquierda, mientras que los valores se muestran en la columna de la derecha.

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret
  • LOCATION: La ubicación de Google Cloud del secreto

Ejecuta el siguiente comando:

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

La respuesta contiene el secreto y las anotaciones.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: La ubicación de Google Cloud del secreto
  • PROJECT_ID: El ID del proyecto de Google Cloud
  • SECRET_ID: El ID del Secret o el identificador completamente calificado del Secret

Método HTTP y URL: 

GET https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

¿Qué sigue?