En esta página, se describe cómo restringir las descargas de artefactos desde tus repositorios de Artifact Registry creando y administrando reglas de descarga.
Las reglas de descarga te permiten permitir o rechazar las descargas de artefactos desde tus 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 la sección Restringe las descargas de artefactos de la descripción general de Controla el acceso y protege los artefactos.
Antes de comenzar
- Si aún no tienes uno, crea un repositorio estándar con formato de Docker.
- Configura los valores predeterminados para los comandos de Google Cloud CLI (opcional).
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:
-
Crea, actualiza, obtén, enumera y borra reglas:
Administrador del repositorio de Artifact Registry (
roles/artifactregistry.repoAdmin) -
Obtén y enumera reglas:
Lector de Artifact Registry (
roles/artifactregistry.reader)
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 a través de roles personalizados o cualquier otro rol predefinido.
Cómo crear reglas de descarga
gcloud
Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
RULE_NAME: Es el nombre de la regla. El nombre debe ser único dentro de tu repositorio, tener una longitud máxima de 256 caracteres y constar de caracteres alfanuméricos, caracteres codificados por porcentaje o caracteres de la lista [-,.,_,~,:,@,+,^].ACTION: Es la acción que se aplica a una descarga que coincide con esta regla. Elige entreALLOW, en la que la regla permite que se realicen las descargas que coincidan, yDENY, en la que la regla bloquea las descargas que coincidan.PACKAGE: Es el nombre del paquete (opcional). Si se proporciona, la regla se aplica solo al paquete especificado, en lugar de a todo el repositorio.CONDITION: (opcional) Es una expresión de 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: Es el ID del proyecto de Google Cloud. Si el ID del proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.LOCATION: Es la ubicación regional o multirregional 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"
Created rule [RULE_NAME].
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 dentro de tu repositorio, tener una longitud máxima de 256 caracteres y constar de caracteres alfanuméricos, caracteres codificados por porcentaje o caracteres de la lista [-,.,_,~,:,@,+,^].ACTION: Es la acción que se aplica a una descarga que coincide con esta regla. Elige entreALLOW, en la que la regla permite que se realicen las descargas que coincidan, yDENY, en la que la regla bloquea las descargas que coincidan.PACKAGE: Es el nombre del paquete (opcional). Si se proporciona, la regla se aplica solo al paquete especificado, en lugar de a todo el repositorio.CONDITION: Es una expresión de CEL que define una regla de coincidencia (opcional). 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: Es el ID del proyecto de Google Cloud. Si el ID del proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.LOCATION: Es la ubicación regional o multirregional 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"
}
Reglas de descarga de listas
gcloud
Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
PROJECT: Es el ID del proyecto de Google Cloud. Si el ID del 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 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
RULE: my-rule PACKAGE: example.com/foo ACTION: DENY OPERATION: DOWNLOAD CONDITION: pkg.version.id < '3.0'
gcloud artifacts rules list.
API
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
PROJECT: Es el ID del proyecto de Google Cloud. Si el ID del 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
Para enviar tu solicitud, expande una de estas opciones:
Se muestra una lista de reglas para el proyecto, la ubicación y el repositorio especificados, 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"
}
]
}
Describe las reglas de descarga
gcloud
Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
RULE_NAME: Es el nombre de la regla. El nombre debe ser único dentro de tu repositorio.PROJECT: Es el ID del proyecto de Google Cloud. Si el ID del 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
RULE: my-rule PACKAGE: example.com/foo ACTION: DENY OPERATION: DOWNLOAD CONDITION: pkg.version.id < '3.0'
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 dentro de tu repositorio.PROJECT: Es el ID del proyecto de Google Cloud. Si el ID del 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 forma 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"
}
]
}
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, haz 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 coincide con esta regla. Elige entreALLOWyDENY.PACKAGE: Es el nombre del paquete. Si no se proporciona, la regla se aplica a todo el repositorio.CONDITION: Es una expresión de 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: Es el ID del proyecto de Google Cloud. Si el ID del 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"
Updated rule [RULE_NAME]. action: ACTION condition: expression: CONDITION name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME operation: DOWNLOAD
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 coincide con esta regla. Elige entreALLOWyDENY.PACKAGE: Es el nombre del paquete. Si no se proporciona, la regla se aplica a todo el repositorio.CONDITION: Es una expresión de 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: Es el ID del proyecto de Google Cloud. Si el ID del 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 forma similar a la siguiente:
{
"name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
"action": ACTION,
"operation": "DOWNLOAD"
}
Borra las reglas de descarga
gcloud
Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
RULE_NAME: Es el nombre de la regla. El nombre debe ser único dentro de tu repositorio.PROJECT: Es el ID del proyecto de Google Cloud. Si el ID del 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 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
You are about to delete rule [RULE_NAME] Do you want to continue (Y/n)? Y Deleted rule [RULE_NAME].
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 dentro de tu repositorio.PROJECT: Es el ID del proyecto de Google Cloud. Si el ID del 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 el conjunto de reglas 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. Úsala solo en un repositorio de Docker.pkg.version.annotations: Es un mapa de cadenas de par clave-valor que representan anotaciones definidas por el usuario en la versión del artefacto en un repositorio estándar.
Puedes usar operadores lógicos y funciones integradas con CEL. A continuación, se muestran algunos ejemplos de expresiones de CEL que podrían ser útiles en tus reglas de descarga:
Útiles para los conjuntos de reglas establecidos a nivel del repositorio:
pkg.id == 'myPackage' #Artifact package matches 'myPackage' pkg.id.startsWith('my') #Artifact package must start with 'my'Útiles para los conjuntos de reglas establecidos 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'] 'quarantined' in pkg.version.annotations && pkg.version.annotations['quarantined'] == 'true' #Artifact version has annotation 'quarantined' set to 'true'
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 usen etiquetas se compararán con una etiqueta vacía y podrían generar un comportamiento inesperado.
- En el caso de las imágenes de contenedor multiarquitectura, es posible que las condiciones que usan etiquetas no funcionen como se espera y se deben evitar.