Créer et gérer des annotations

Cette page explique comment ajouter des annotations à un secret, 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 dans les cas suivants : différentes manières:

  • Classer les secrets en fonction de leur objectif, de l'environnement (développement, préproduction et production) ou de sensibilité. Cela facilite la recherche, le filtrage et l'organisation des 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 l'utilisation du secret ou toute autre considération spéciale concernant 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 le bon mot de passe pour l'environnement de production.

Les annotations sont différentes des libellés. Les étiquettes sont utilisées pour trier, filtrer et regrouper les ressources, tandis que les annotations sont utilisées pour stocker des métadonnées arbitraires ne permettant pas d’identification sur un secret. Il y a un restriction de caractères et la longueur des caractères lors de la spécification des métadonnées dans un libellé. Les métadonnées de Une annotation peut être petite ou grande, structurée ou non structurée, et peut contenir des caractères non autorisés par libellé.

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 la création ou de la mise à jour d'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 les 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 Créer un secret.

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

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

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

  6. Saisissez la clé et la valeur correspondante.

  7. 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
  • 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 \
    --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 réponse contient le secret et les annotations.

REST

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

  • 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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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 présentent les exigences suivantes:

  • Les clés doivent être uniques à 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 utiliser un encodage UTF-8 de 128 octets au 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. Accédez à la page Secret Manager dans la console Google Cloud.

    Accéder à Secret Manager

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

  3. 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.

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

gcloud

Modifier les 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
  • 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 --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 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 --remove-annotations= KEY=VAL

Effacer toutes les annotations

Pour effacer toutes les annotations, utilisez la commande suivante :

gcloud secrets update SECRET_ID --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 :

  • 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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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 le secret dont vous souhaitez afficher les annotations.

  3. La page d'informations sur le secret s'ouvre. 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

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud secrets describe SECRET_ID

Windows (PowerShell)

gcloud secrets describe SECRET_ID

Windows (cmd.exe)

gcloud secrets describe SECRET_ID

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 :

  • 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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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