Restringe las descargas de artefactos con reglas de descarga

En esta página, se describe cómo restringir las descargas de artefactos de tus repositorios de Artifact Registry mediante la creación y administración de reglas de descarga.

Las reglas de descarga permiten o rechazan las descargas de artefactos desde tu repositorios y paquetes. También puedes establecer condiciones para que la regla se aplique a etiquetas o versiones específicas.

Para obtener detalles sobre cómo funcionan las reglas de descarga, consulta Restringe la descarga de artefactos. de la descripción general Controlar el acceso y proteger los artefactos.

Antes de comenzar

  1. Si aún no tienes uno, crea un repositorio estándar en formato Docker.
  2. (Opcional) Configura valores predeterminados para los comandos de Google Cloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar reglas de descarga, pídele a tu administrador que te otorgue los siguientes roles de IAM en el repositorio:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Crear reglas de descarga

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • RULE_NAME: Es el nombre de la regla. El nombre debe ser único en tu repositorio, tener una longitud máxima de 256 caracteres y constar de caracteres alfanuméricos, caracteres con codificación porcentual o caracteres de la lista [-, ., _, ~, :, @, +, ^].
  • ACTION: Es la acción que se aplica a una descarga. que coincida con esta regla. Elige entre ALLOW, en el que la regla permite que se produzcan descargas coincidentes, y DENY, en el que la regla bloquea las descargas coincidentes.
  • PACKAGE: Es el nombre del objeto (opcional) . Si se proporciona, la regla se aplica solo al paquete especificado en lugar de al repositorio completo.
  • CONDITION: (opcional) a Expresión CEL que define una coincidencia . Si se proporciona, solo aplica la regla a las descargas que coinciden con la condición especificada. Por ejemplo, pkg.version.id < '3.0'.
  • PROJECT: El ID del proyecto de Google Cloud. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • LOCATION: Es la región o multirregional. location del repositorio.
  • REPOSITORY: Es el ID del repositorio.

Ejecuta el siguiente comando:

Linux, macOS o 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"
 Se crea una regla nueva con el siguiente resultado: 
Created rule [RULE_NAME].
Para obtener más información, consulta el comando gcloud artifacts rules create.

API

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • RULE_NAME: Es el nombre de la regla. El nombre debe ser único en tu repositorio, tener una longitud máxima de 256 caracteres y constar de caracteres alfanuméricos, caracteres con codificación porcentual o caracteres de la lista [-, ., _, ~, :, @, + y ^].
  • ACTION: Es la acción que se aplica a una descarga. que coincida con esta regla. Elige entre ALLOW, en el que la regla permite que se produzcan descargas coincidentes, y DENY, en el que la regla bloquea las descargas coincidentes.
  • PACKAGE: (Opcional) Es el nombre del paquete. Si se proporciona, la regla se aplica solo al paquete especificado en lugar de a todo el paquete. en un repositorio de confianza.
  • CONDITION: (opcional) Es una expresión CEL que define una regla de coincidencia. Si se proporciona, solo aplica la regla a las descargas que coincidan con la condición especificada. Por ejemplo, pkg.version.id < '3.0'.
  • PROJECT: El ID del proyecto de Google Cloud. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • LOCATION: Es la región o multirregional. location del repositorio.
  • REPOSITORY: Es el ID del repositorio.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Se crea una regla nueva con el siguiente resultado: 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Para obtener más información, consulta la referencia de REST.

Muestra una lista de reglas de descarga

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

Ejecuta el siguiente comando:

Linux, macOS o 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
 Se mostrará una lista de reglas para el proyecto, la ubicación y el repositorio especificados de manera similar a la siguiente: 
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Para obtener más información, consulta el comando gcloud artifacts rules list.

API

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Se mostrará una lista de reglas para el proyecto, la ubicación y el repositorio especificados de manera similar a la siguiente: 
{
  "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"
    }
  ]
}
Para obtener más información, consulta la referencia de REST.

Describe las reglas de descarga

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • RULE_NAME: Es el nombre de la regla. El nombre debe ser único en tu repositorio.
  • PROJECT: El ID del proyecto de Google Cloud. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • LOCATION: Es la ubicación regional o multirregional del repositorio.
  • REPOSITORY: Es el nombre del repositorio.

Ejecuta el siguiente comando:

Linux, macOS o 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
 Los detalles de la regla se muestran de la siguiente manera: 
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Para obtener más información, consulta el comando gcloud artifacts rules describe.

API

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • RULE_NAME: Es el nombre de la regla. El nombre debe ser único en tu repositorio.
  • PROJECT: tu Google Cloud ID del proyecto: Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • LOCATION: Es la ubicación regional o multirregional del repositorio.
  • REPOSITORY: Es el nombre del repositorio.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Los detalles de la regla se muestran de la siguiente manera: 
{
  "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"
    }
  ]
}
Para obtener más información, consulta la referencia de REST.

Actualiza las reglas de descarga

gcloud

Quita las variables que no quieras actualizar.

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • RULE_NAME: Es el nombre de la regla. El nombre debe ser único en tu repositorio.
  • ACTION: Es la acción que se aplica a una descarga. que coincida con esta regla. Elige entre ALLOW y DENY.
  • PACKAGE: Es el nombre de la . Si no se proporciona, la regla se aplica a todo el repositorio.
  • CONDITION: un Expresión CEL que define una coincidencia . Si se proporciona, solo aplica la regla a las descargas que coincidan con la condición especificada. Por ejemplo, pkg.version.id < '3.0'.
  • PROJECT: El ID del proyecto de Google Cloud. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • LOCATION: Es la ubicación regional o multirregional del repositorio.
  • REPOSITORY: Es el nombre del repositorio.

Ejecuta el siguiente comando:

Linux, macOS o 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"
 Los detalles de la regla actualizada se muestran de la siguiente manera: 
Updated rule [RULE_NAME].
action: ACTION
condition:
  expression: CONDITION
name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME
operation: DOWNLOAD
Para obtener más información, consulta el comando gcloud artifacts rules update.

API

Quita las variables que no quieras actualizar.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • RULE_NAME: Es el nombre de la regla. El nombre debe ser único dentro de tu repositorio.
  • ACTION: Es la acción que se aplica a una descarga. que coincida con esta regla. Elige entre ALLOW y DENY.
  • PACKAGE: Es el nombre de la . Si no se proporciona, la regla se aplica a todo el repositorio.
  • CONDITION: un Expresión CEL que define una coincidencia . Si se proporciona, solo aplica la regla a las descargas que coincidan con la condición especificada. Por ejemplo, pkg.version.id < '3.0'.
  • PROJECT: El ID del proyecto de Google Cloud. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • LOCATION: Es la ubicación regional o multirregional del repositorio.
  • REPOSITORY: Es el nombre del repositorio.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Los detalles de la regla actualizada se muestran de la siguiente manera: 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Para obtener más información, consulta la referencia de REST.

Borra las reglas de descarga

gcloud

Antes de usar cualquiera de los datos de comando a continuación, realiza los siguientes reemplazos:

  • RULE_NAME: Es el nombre de la regla. El nombre debe ser único dentro de tu repositorio.
  • PROJECT: El ID del proyecto de Google Cloud. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • LOCATION: Es la región o multirregional. location del repositorio.
  • REPOSITORY: Es el nombre del repositorio.

Ejecuta el siguiente comando:

Linux, macOS o 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 regla se borra con el siguiente resultado: 
You are about to delete rule [RULE_NAME]

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

Deleted rule [RULE_NAME].
Para obtener más información, consulta el comando gcloud artifacts rules delete.

API

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • RULE_NAME: Es el nombre de la regla. El nombre debe ser único en tu repositorio.
  • PROJECT: tu Google Cloud ID del proyecto: Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
  • LOCATION: Es la ubicación regional o multirregional del repositorio.
  • REPOSITORY: Es el nombre del repositorio.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Para obtener más información, consulta la referencia de REST.

Usa CEL para definir condiciones

Puedes definir condiciones para tus reglas de descarga con Common Expression Language (CEL), que es un lenguaje de código abierto para la evaluación de expresiones. Artifact Registry proporciona el objeto pkg que contiene los siguientes atributos:

  • pkg.id: Es una cadena que representa el nombre del paquete del artefacto. Se puede usar con reglas establecidas a nivel del repositorio.
  • pkg.version.id: Es una cadena que representa la versión del artefacto.
  • pkg.version.tag: Es una cadena que representa la etiqueta del artefacto. Solo para uso en un repositorio de Docker.

Puedes usar operadores lógicos y funciones integradas con CEL. A continuación, se muestran algunos ejemplos de expresiones CEL que podrían ser útiles en tus reglas de descarga:

  • Es útil para las reglas establecidas a nivel del repositorio:

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

  • Útil para las reglas establecidas en los paquetes:

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

Cuando agregues reglas con condiciones basadas en etiquetas, como pkg.version.tag == 'latest' en tus repositorios de Docker, ten en cuenta lo siguiente:

  • Cuando se extrae por resumen, el cliente no proporciona una etiqueta. Las condiciones que usan etiquetas se compararán con una etiqueta vacía y podrían generar un comportamiento inesperado.
  • En el caso de las imágenes de contenedores de varios arcos, es posible que las condiciones que usan etiquetas no funcionen como se espera y se deban evitar.