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 monté. Les annotations peuvent être utiles pour les raisons suivantes :

  • Pour catégoriser les secrets en fonction de leur objectif, de leur environnement (développement, préproduction, production) ou de leur niveau de sensibilité. Cela facilite la recherche, le filtrage et l'organisation des secrets dans Secret Manager.

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

  • Fournir des indications sur la façon dont le secret doit être utilisé ou sur les considérations particulières concernant son traitement.

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 la personne qui en est 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 sont différentes des libellés. Les libellés servent à trier, filtrer et regrouper les ressources, tandis que les annotations permettent de stocker des métadonnées arbitraires et non identifiantes sur un secret. Lorsque vous spécifiez des métadonnées dans un libellé, vous devez respecter certaines restrictions concernant les caractères et leur longueur. 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 ou modifier des annotations sur un secret, vous devez disposer du rôle "Administrateur 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 Secret Manager (roles/secretmanager.viewer) sur le secret, le projet, le dossier ou l'organisation.

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

Ajouter des annotations à un secret

Vous pouvez ajouter des annotations lorsque vous créez un secret ou que vous en modifiez un. 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. Dans la console Google Cloud , accédez à la page Secret Manager.

    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 : Google Cloud emplacement du secret
  • KEY : clé de l'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 : Google Cloud emplacement du secret
  • PROJECT_ID : ID du projet Google Cloud
  • SECRET_ID : ID du secret ou identifiant complet du secret
  • KEY : clé de l'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 des annotations de ce document.

Les clés d'annotation doivent répondre aux exigences suivantes :

  • Les clés doivent être uniques pour 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 avoir un encodage UTF-8 de 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 Kio.

Modifier les annotations

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

Console

  1. Dans la console Google Cloud , accédez à la page Secret Manager.

    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é. Dans le menu Actions, cliquez sur Modifier.

  4. Sur la page Modifier le secret, accédez à la section Annotations. Vous pouvez y 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 : Google Cloud emplacement du secret
  • KEY : clé de l'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 les 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 : Google Cloud emplacement du secret
  • PROJECT_ID : ID du 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. Dans la console Google Cloud , accédez à la page Secret Manager.

    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'ouvre. Cliquez sur l'onglet Vue d'ensemble. Vous pouvez consulter ici les annotations associées au secret. Les clés sont listées dans la colonne de gauche, tandis que les valeurs sont affichées 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 : Google Cloud emplacement 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 : Google Cloud emplacement du secret
  • PROJECT_ID : ID du 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"
  }
}

Étapes suivantes