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 à partir de 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 balises ou 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 encore, créez un dépôt standard au format Docker.
  2. (Facultatif) Configurez des 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 la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via 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, avoir une longueur maximale de 256 caractères et être composé de caractères alphanumériques, de caractères encodés en pourcentage ou de caractères figurant dans la liste [-, ., _, ~, :, @, +, ^].
  • ACTION: action appliquée à un téléchargement correspondant à 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. Si elle est fournie, la règle ne s'applique qu'au package spécifié au lieu de l'ensemble du dépôt.
  • CONDITION: (facultatif) expression CEL qui définit une règle de correspondance. Si elle est fournie, la règle ne s'applique qu'aux téléchargements correspondant à la condition spécifiée. Par exemple, pkg.version.id < '3.0'.
  • PROJECT: ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez la section Projets à l'échelle du 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 ci-dessous, effectuez les remplacements suivants :

  • RULE_NAME: nom de la règle. Le nom doit être unique dans votre dépôt, avoir une longueur maximale de 256 caractères et être composé de caractères alphanumériques, de caractères encodés en pourcentage ou de caractères figurant dans la liste [-, ., _, ~, :, @, +, ^].
  • ACTION: action appliquée à un téléchargement correspondant à 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. Si elle est fournie, 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 elle est fournie, la règle ne s'applique qu'aux téléchargements correspondant à la condition spécifiée. Par exemple, pkg.version.id < '3.0'.
  • PROJECT: ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez la section Projets à l'échelle du 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 la sortie suivante : 
{
  "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 à celle-ci : 
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 ci-dessous, 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 deux-points (:), consultez la section Projets à l'échelle du 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 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 deux-points (:), consultez la section Projets à l'échelle du 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 correspondant à cette règle. Choisissez entre ALLOW et DENY.
  • PACKAGE: nom du package. Si aucune valeur n'est fournie, la règle s'applique à l'ensemble du dépôt.
  • CONDITION: expression CEL qui définit une règle de correspondance. Si elle est fournie, la règle ne s'applique qu'aux téléchargements correspondant à la condition spécifiée. Par exemple, pkg.version.id < '3.0'.
  • PROJECT: ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez la section Projets à l'échelle du 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 se présentent 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 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 correspondant à cette règle. Choisissez entre ALLOW et DENY.
  • PACKAGE: nom du package. Si aucune valeur n'est fournie, la règle s'applique à l'ensemble du dépôt.
  • CONDITION: expression CEL qui définit une règle de correspondance. Si elle est fournie, la règle ne s'applique qu'aux téléchargements correspondant à la condition spécifiée. Par exemple, pkg.version.id < '3.0'.
  • PROJECT: ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez la section Projets à l'échelle du 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 se présentent 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 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.
  • PROJECT: ID de votre projet Google Cloud. Si l'ID de votre projet contient un deux-points (:), consultez la section Projets à l'échelle du 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
 La règle est supprimée, et le résultat est le 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 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 deux-points (:), consultez la section Projets à l'échelle du 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 le langage CEL pour définir des conditions

Vous pouvez définir des conditions pour vos règles de téléchargement avec le Common Expression Language (CEL), un langage Open Source pour l'évaluation 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 règles définies 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 la balise de l'artefact. À utiliser uniquement dans un dépôt Docker.

Vous pouvez utiliser des opérateurs logiques et des fonctions intégrées avec CEL. Voici quelques exemples d'expressions CEL qui peuvent ê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'

  • Utile 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']

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 la récupération par condensé, le client ne fournit pas de balise. Les conditions utilisant des balises seront mises en correspondance avec une balise vide et peuvent 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.