Restreindre les téléchargements d'artefacts avec des règles de téléchargement

Cette page explique comment limiter les téléchargements d'artefacts depuis vos dépôts Artifact Registry en créant et en gérant des règles de téléchargement.

Les règles de téléchargement vous permettent d'autoriser ou de refuser les téléchargements d'artefacts à partir de vos dépôts et packages. Vous pouvez également définir des conditions pour que la règle s'applique à des tags ou des versions spécifiques.

Pour en savoir plus sur le fonctionnement des règles de téléchargement, consultez la section Limiter les téléchargements d'artefacts de la présentation "Contrôler l'accès et protéger les artefacts".

Avant de commencer

  1. Si vous n'en avez pas déjà un, créez un dépôt standard au format Docker.
  2. (Facultatif) Configurez les valeurs par défaut pour les commandes Google Cloud CLI.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des règles de téléchargement, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le dépôt :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer des règles de téléchargement

gcloud

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

  • RULE_NAME : nom de la règle. Le nom doit être unique dans votre dépôt, comporter au maximum 256 caractères et être composé de caractères alphanumériques, de caractères encodés en pourcentage ou de caractères de la liste [-, ., _, ~, :, @, +, ^].
  • ACTION : action appliquée à un téléchargement qui correspond à cette règle. Choisissez entre ALLOW, où la règle autorise les téléchargements correspondants, et DENY, où la règle bloque les téléchargements correspondants.
  • PACKAGE : (facultatif) nom du package. S'il est fourni, la règle ne s'applique qu'au package spécifié, et non à l'ensemble du dépôt.
  • CONDITION : (facultatif) expression CEL qui définit une règle de correspondance. Si cette option est fournie, la règle ne s'applique qu'aux téléchargements qui remplissent la condition spécifiée. Par exemple, pkg.version.id < '3.0'.
  • PROJECT : l'ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez Projets limités à un domaine.
  • LOCATION : emplacement régional ou multirégional du dépôt.
  • REPOSITORY : ID du dépôt.

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud artifacts rules create RULE_NAME \
    --action=ACTION \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY \
    --package=PACKAGE \
    --condition="CONDITION"

Windows (PowerShell)

gcloud artifacts rules create RULE_NAME `
    --action=ACTION `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY `
    --package=PACKAGE `
    --condition="CONDITION"

Windows (cmd.exe)

gcloud artifacts rules create RULE_NAME ^
    --action=ACTION ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY ^
    --package=PACKAGE ^
    --condition="CONDITION"
 Une règle est créée avec le résultat suivant : 
Created rule [RULE_NAME].
Pour en savoir plus, consultez la commande gcloud artifacts rules create.

API

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

  • RULE_NAME : nom de la règle. Le nom doit être unique dans votre dépôt, comporter au maximum 256 caractères et être composé de caractères alphanumériques, de caractères encodés en pourcentage ou de caractères de la liste [-, ., _, ~, :, @, +, ^].
  • ACTION : action appliquée à un téléchargement qui correspond à cette règle. Choisissez entre ALLOW, où la règle autorise les téléchargements correspondants, et DENY, où la règle bloque les téléchargements correspondants.
  • PACKAGE : (facultatif) nom du package. S'il est fourni, la règle ne s'applique qu'au package spécifié, et non à l'ensemble du dépôt.
  • CONDITION : (facultatif) expression CEL qui définit une règle de correspondance. Si cette option est fournie, la règle ne s'applique qu'aux téléchargements qui remplissent la condition spécifiée. Par exemple, pkg.version.id < '3.0'.
  • PROJECT : l'ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez Projets limités à un domaine.
  • LOCATION : emplacement régional ou multirégional du dépôt.
  • REPOSITORY : ID du dépôt.

Méthode HTTP et URL : 

POST https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME

Corps JSON de la requête :

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Une règle est créée avec le résultat suivant : 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Pour en savoir plus, consultez la documentation de référence REST.

Répertorier les règles de téléchargement

gcloud

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

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud artifacts rules list \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules list `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules list ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY
 Une liste de règles pour le projet, l'emplacement et le dépôt spécifiés s'affiche, semblable à ce qui suit : 
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Pour en savoir plus, consultez la commande gcloud artifacts rules list.

API

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

Méthode HTTP et URL : 

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules

Pour envoyer votre requête, développez l'une des options suivantes :

Une liste de règles pour le projet, l'emplacement et le dépôt spécifiés s'affiche, semblable à celle-ci : 
{
  "rules": [
    {
      "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule",
      "action": "DENY",
      "operation": "DOWNLOAD",
      "condition": {
        "expression": "pkg.version.id \u003c '3.0'"
      },
      "packageId": "example.com/foo"
    }
  ]
}
Pour en savoir plus, consultez la documentation de référence REST.

Décrire les règles de téléchargement

gcloud

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

  • RULE_NAME : nom de la règle. Le nom doit être unique dans votre dépôt.
  • PROJECT : ID de votre projet Google Cloud. Si l'ID de votre projet contient un signe deux-points (:), consultez Projets limités à un domaine.
  • LOCATION : emplacement régional ou multirégional du dépôt.
  • REPOSITORY : nom du dépôt

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud artifacts rules describe RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules describe RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules describe RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY
 Les détails de la règle s'affichent comme suit : 
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Pour en savoir plus, consultez la commande gcloud artifacts rules describe.

API

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

  • RULE_NAME : nom de la règle. Le nom doit être unique dans votre dépôt.
  • PROJECT : l'ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez Projets limités à un domaine.
  • LOCATION : emplacement régional ou multirégional du dépôt.
  • REPOSITORY : nom du dépôt

Méthode HTTP et URL : 

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

Pour envoyer votre requête, développez l'une des options suivantes :

Les détails de la règle s'affichent comme suit : 
{
  "rules": [
    {
      "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule",
      "action": "DENY",
      "operation": "DOWNLOAD",
      "condition": {
        "expression": "pkg.version.id \u003c '3.0'"
      },
      "packageId": "example.com/foo"
    }
  ]
}
Pour en savoir plus, consultez la documentation de référence REST.

Mettre à jour les règles de téléchargement

gcloud

Supprimez les variables que vous ne souhaitez pas mettre à jour.

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

  • RULE_NAME : nom de la règle. Le nom doit être unique dans votre dépôt.
  • ACTION : action appliquée à un téléchargement qui correspond à cette règle. Choisissez entre ALLOW et DENY.
  • PACKAGE : nom du package. Si vous ne l'indiquez pas, la règle s'applique à l'ensemble du dépôt.
  • CONDITION : expression CEL qui définit une règle de correspondance. Si cette option est fournie, la règle ne s'applique qu'aux téléchargements qui remplissent la condition spécifiée. Par exemple, pkg.version.id < '3.0'.
  • PROJECT : l'ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez Projets limités à un domaine.
  • LOCATION : emplacement régional ou multirégional du dépôt.
  • REPOSITORY : nom du dépôt

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud artifacts rules update RULE_NAME \
    --action=ACTION \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY \
    --package=PACKAGE \
    --condition="CONDITION"

Windows (PowerShell)

gcloud artifacts rules update RULE_NAME `
    --action=ACTION `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY `
    --package=PACKAGE `
    --condition="CONDITION"

Windows (cmd.exe)

gcloud artifacts rules update RULE_NAME ^
    --action=ACTION ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY ^
    --package=PACKAGE ^
    --condition="CONDITION"
 Les détails de la règle mise à jour s'affichent comme suit :
Updated rule [RULE_NAME].
action: ACTION
condition:
  expression: CONDITION
name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME
operation: DOWNLOAD
Pour en savoir plus, consultez la commande gcloud artifacts rules update.

API

Supprimez les variables que vous ne souhaitez pas mettre à jour.

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

  • RULE_NAME : nom de la règle. Le nom doit être unique dans votre dépôt.
  • ACTION : action appliquée à un téléchargement qui correspond à cette règle. Choisissez entre ALLOW et DENY.
  • PACKAGE : nom du package. Si vous ne l'indiquez pas, la règle s'applique à l'ensemble du dépôt.
  • CONDITION : expression CEL qui définit une règle de correspondance. Si cette option est fournie, la règle ne s'applique qu'aux téléchargements qui remplissent la condition spécifiée. Par exemple, pkg.version.id < '3.0'.
  • PROJECT : l'ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez Projets limités à un domaine.
  • LOCATION : emplacement régional ou multirégional du dépôt.
  • REPOSITORY : nom du dépôt

Méthode HTTP et URL : 

PATCH https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

Corps JSON de la requête :

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Les détails de la règle mise à jour s'affichent comme suit : 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Pour en savoir plus, consultez la documentation de référence REST.

Supprimer les règles de téléchargement

gcloud

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

  • RULE_NAME : nom de la règle. Le nom doit être unique dans votre dépôt.
  • PROJECT : l'ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez Projets limités à un domaine.
  • LOCATION : emplacement régional ou multirégional du dépôt.
  • REPOSITORY : nom du dépôt

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

gcloud artifacts rules delete RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules delete RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules delete RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY
 La règle est supprimée avec le résultat suivant : 
You are about to delete rule [RULE_NAME]

Do you want to continue (Y/n)?  Y

Deleted rule [RULE_NAME].
Pour en savoir plus, consultez la commande gcloud artifacts rules delete.

API

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

  • RULE_NAME : nom de la règle. Le nom doit être unique dans votre dépôt.
  • PROJECT : l'ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez Projets limités à un domaine.
  • LOCATION : emplacement régional ou multirégional du dépôt.
  • REPOSITORY : nom du dépôt

Méthode HTTP et URL : 

DELETE https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

Pour envoyer votre requête, développez l'une des options suivantes :

Pour en savoir plus, consultez la documentation de référence REST.

Utiliser CEL pour définir des conditions

Vous pouvez définir des conditions pour vos règles de téléchargement à l'aide du langage CEL (Common Expression Language), un langage Open Source permettant d'évaluer des expressions. Artifact Registry fournit l'objet pkg qui contient les attributs suivants :

  • pkg.id : chaîne représentant le nom du package de l'artefact. Peut être utilisé avec des ensembles de règles définis au niveau du dépôt.
  • pkg.version.id : chaîne représentant la version de l'artefact.
  • pkg.version.tag : chaîne représentant le tag de l'artefact. À utiliser uniquement dans un dépôt Docker.
  • pkg.version.annotations : mappage de chaînes clé-valeur représentant les annotations définies par l'utilisateur sur la version de l'artefact dans un dépôt standard.

Vous pouvez utiliser des opérateurs logiques et des fonctions intégrées avec CEL. Voici quelques exemples d'expressions CEL qui pourraient vous être utiles dans vos règles de téléchargement :

  • Utile pour les règles définies au niveau du dépôt :

      pkg.id == 'myPackage'  #Artifact package matches 'myPackage'
  pkg.id.startsWith('my') #Artifact package must start with 'my'

  • Utilité pour les règles définies sur les packages :

      pkg.version.id != '1.0.0' #Artifact version is not '1.0.0'
  pkg.version.id > '1.0.1' || pkg.version.id < '0.0.1' #Artifact version is greater than '1.0.1' or less than '0.0.1'
  pkg.version.id.startsWith('1.0.') #Artifact version must start with '1.0.'
  pkg.version.id in ['1.0.0', '1.2.0'] #Artifact version must be a member of the list ['1.0.0', '1.2.0']
  pkg.version.tag == 'tag1' #Artifact tag must be 'tag1'
  pkg.version.tag.startsWith('tag') #Artifact tag must start with 'tag'
  pkg.version.tag in ['tag1', 'tag2'] #Artifact tag must be a member of the list ['tag1', 'tag2']
  'quarantined' in pkg.version.annotations && pkg.version.annotations['quarantined'] == 'true' #Artifact version has annotation 'quarantined' set to 'true'

Lorsque vous ajoutez des règles avec des conditions basées sur des tags telles que pkg.version.tag == 'latest' dans vos dépôts Docker, tenez compte des points suivants :

  • Lors de l'extraction par condensé, le client ne fournit pas de tag. Les conditions utilisant des tags seront mises en correspondance avec un tag vide et pourront entraîner un comportement inattendu.
  • Pour les images de conteneurs multi-architectures, les conditions utilisant des tags peuvent ne pas fonctionner comme prévu et doivent être évitées.