Créer et gérer des annotations

Cette page explique comment ajouter des annotations à un secret régional, et comment les modifier et les afficher.

Présentation

Vous pouvez utiliser des annotations pour stocker des métadonnées personnalisées sur un secret. Par exemple, vous pouvez annoter un secret avec le chemin d'accès où il sera installé. Les annotations peuvent être utiles de différentes manières:

  • Pour classer les secrets en fonction de leur objectif, de leur environnement (développement, préproduction, production) ou de leur niveau de sensibilité. Vous pouvez ainsi rechercher, filtrer et organiser plus facilement les secrets dans Secret Manager.

  • Pour indiquer le format ou la structure spécifique de la valeur du secret, ce qui aide la charge de travail à l'interpréter correctement.

  • Pour fournir des indications sur la façon dont le secret doit être utilisé ou sur les considérations particulières à prendre en compte pour sa gestion.

Par exemple, si vous disposez d'un secret contenant un mot de passe de base de données, vous pouvez ajouter des annotations telles que les suivantes:

  • environment:production

  • purpose:database_access

  • owner:database_team

Ces annotations permettent d'identifier facilement l'objectif du secret, son environnement et son responsable. De plus, une charge de travail accédant à ce secret peut utiliser les annotations pour confirmer qu'elle utilise le bon mot de passe pour l'environnement de production.

Les annotations ne sont pas les mêmes que les libellés. Les libellés sont utilisés pour trier, filtrer et regrouper des ressources, tandis que les annotations permettent de stocker des métadonnées arbitraires ne permettant pas d'identifier l'utilisateur sur un secret. La longueur et le nombre de caractères sont limités lorsque vous spécifiez des métadonnées dans un libellé. Les métadonnées d'une annotation peuvent être petites, volumineuses, structurées ou non structurées, et peuvent inclure des caractères non autorisés par les libellés.

Rôles requis

  • Pour ajouter des annotations à un secret et les mettre à jour, vous devez disposer du rôle "Administrateur de Secret Manager" (roles/secretmanager.admin) sur le secret, le projet, le dossier ou l'organisation.

  • Pour afficher les annotations, vous devez disposer du rôle "Lecteur de Secret Manager" (roles/secretmanager.viewer) sur le secret, le projet, le dossier ou l'organisation.

Les rôles IAM (Identity and Access Management) ne peuvent pas être attribués au niveau de la version d'un secret. Pour en savoir plus, consultez la page Contrôle des accès avec IAM.

Ajouter des annotations à un secret

Vous pouvez ajouter des annotations au moment de créer un secret ou de mettre à jour un secret existant. Les métadonnées d'une annotation sont stockées sous forme de paires clé-valeur. Pour ajouter des annotations, utilisez l'une des méthodes suivantes:

Console

  1. Accédez à la page Secret Manager dans la console Google Cloud.

    Accéder à Secret Manager

  2. Sur la page Secret Manager, cliquez sur l'onglet Secrets régionaux, puis sur Créer un secret régional.

  3. Sur la page Créer un secret régional, saisissez un nom pour le secret dans le champ Nom.

  4. Saisissez une valeur pour le secret (par exemple, abcd1234). Vous pouvez également importer un fichier texte contenant la valeur du secret à l'aide de l'option Importer un fichier. Cette action crée automatiquement la version du secret.

  5. Dans la liste Région, sélectionnez l'emplacement où vous souhaitez stocker votre secret régional.

  6. Accédez à la section Annotations, puis cliquez sur Ajouter une annotation.

  7. Saisissez la clé et la valeur correspondante.

  8. Cliquez sur Créer un secret.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • SECRET_ID: ID du secret ou identifiant complet du secret
  • LOCATION: emplacement Google Cloud du secret
  • KEY: clé d'annotation
  • VALUE: valeur correspondante de la clé d'annotation

Exécutez la commande suivante :

Linux, macOS ou 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 réponse contient le secret et les annotations.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION: emplacement Google Cloud du secret
  • PROJECT_ID : ID de projet Google Cloud
  • SECRET_ID: ID du secret ou identifiant complet du secret
  • KEY: clé d'annotation
  • VALUE: valeur correspondante de la clé d'annotation

Méthode HTTP et URL : 

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

Corps JSON de la requête : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Pour ajouter des annotations à un secret existant, consultez la section Modifier les annotations de ce document.

Les clés d'annotation doivent respecter les exigences suivantes:

  • Les clés doivent être propres à un secret. Vous ne pouvez pas répéter une clé dans le même secret.

  • Les clés doivent comporter entre 1 et 63 caractères.

  • Les clés doivent être encodées en UTF-8 sur 128 octets maximum.

  • Les clés doivent commencer et se terminer par un caractère alphanumérique.

  • Les clés peuvent contenir des tirets, des traits de soulignement et des points entre les caractères alphanumériques.

  • La taille totale des clés et des valeurs d'annotation doit être inférieure à 16 Ko.

Modifier les annotations

Pour modifier des annotations, utilisez l'une des méthodes suivantes:

Console

  1. Accédez à la page Secret Manager dans la console Google Cloud.

    Accéder à Secret Manager

  2. Sur la page Secret Manager, cliquez sur l'onglet Secrets régionaux.

  3. Recherchez le secret dans la liste, puis cliquez sur le menu Actions associé à ce secret. Dans le menu Actions, cliquez sur Modifier.

  4. Sur la page Modifier le secret, accédez à la section Annotations. Vous pouvez modifier la valeur d'une annotation existante, la supprimer ou en ajouter une.

  5. Une fois les modifications effectuées, cliquez sur Mettre à jour le secret.

gcloud

Modifier des annotations existantes

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • SECRET_ID: ID du secret ou identifiant complet du secret
  • LOCATION: emplacement Google Cloud du secret
  • KEY: clé d'annotation
  • VALUE: valeur correspondante de la clé d'annotation

Exécutez la commande suivante :

Linux, macOS ou 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 réponse modifie le secret et les annotations.

Supprimer une annotation spécifique

Pour supprimer des annotations, utilisez la commande suivante:

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

Effacer toutes les annotations

Pour effacer toutes les annotations, utilisez la commande suivante:

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

REST

Pour effacer toutes les annotations, utilisez la commande suivante:

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION: emplacement Google Cloud du secret
  • PROJECT_ID : ID de projet Google Cloud
  • SECRET_ID: ID du secret ou identifiant complet du secret

Méthode HTTP et URL : 

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

Corps JSON de la requête : 

{'annotations': {}}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Afficher les annotations

Pour afficher les annotations associées à un secret, utilisez l'une des méthodes suivantes:

Console

  1. Accédez à la page Secret Manager dans la console Google Cloud.

    Accéder à Secret Manager

  2. Sur la page Secret Manager, cliquez sur l'onglet Secrets régionaux, puis sur le secret dont vous souhaitez afficher les annotations.

  3. La page des détails du secret s'affiche. Cliquez sur l'onglet Vue d'ensemble. Vous pouvez voir ici les annotations associées au secret. Les clés sont listées dans la colonne de gauche, tandis que les valeurs s'affichent dans la colonne de droite.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • SECRET_ID: ID du secret ou identifiant complet du secret
  • LOCATION: emplacement Google Cloud du secret

Exécutez la commande suivante :

Linux, macOS ou 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 réponse contient le secret et les annotations.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION: emplacement Google Cloud du secret
  • PROJECT_ID : ID de projet Google Cloud
  • SECRET_ID: ID du secret ou identifiant complet du secret

Méthode HTTP et URL : 

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

Corps JSON de la requête : 

{}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Étape suivante