Limitare i download di elementi con le regole di download

Questa pagina descrive come limitare i download di artefatti dai repository Artifact Registry creando e gestendo regole di download.

Le regole di download ti consentono di consentire o negare i download di artefatti dai tuoi repository e pacchetti. Puoi anche impostare condizioni in modo che la regola si applichi a tag o versioni specifici.

Per informazioni dettagliate sul funzionamento delle regole di download, consulta la sezione Limitare i download degli artefatti della panoramica Controllare l'accesso e proteggere gli artefatti.

Prima di iniziare

  1. Se non ne hai già uno, crea un repository standard in formato Docker.
  2. (Facoltativo) Configura le impostazioni predefinite per i comandi Google Cloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire le regole di download, chiedi all'amministratore di concederti i seguenti ruoli IAM nel repository:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Creare regole di download

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository, avere una lunghezza massima di 256 caratteri e contenere caratteri alfanumerici, caratteri codificati in percentuale o caratteri nell'elenco [-, ., _, ~, :, @, +, ^].
  • ACTION: l'azione applicata a un download che corrisponde a questa regola. Scegli tra ALLOW, in cui la regola consente di eseguire il matching dei download, e DENY, in cui la regola blocca il matching dei download.
  • PACKAGE: (facoltativo) il nome del pacchetto. Se fornita, la regola si applica solo al pacchetto specificato anziché all'intero repository.
  • CONDITION: (facoltativo) un'espressione CEL che definisce una regola di corrispondenza. Se fornita, applica la regola solo ai download che soddisfano la condizione specificata. Ad esempio: pkg.version.id < '3.0'.
  • PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
  • LOCATION: la posizione regionale o multiregionale del repository.
  • REPOSITORY: l'ID repository.

Esegui questo 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"
 Viene creata una nuova regola con il seguente output: 
Created rule [RULE_NAME].
Per ulteriori informazioni, consulta il comando gcloud artifacts rules create.

API

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository, avere una lunghezza massima di 256 caratteri e contenere caratteri alfanumerici, caratteri codificati in percentuale o caratteri nell'elenco [-, ., _, ~, :, @, +, ^].
  • ACTION: l'azione applicata a un download che corrisponde a questa regola. Scegli tra ALLOW, in cui la regola consente di eseguire il matching dei download, e DENY, in cui la regola blocca il matching dei download.
  • PACKAGE: (facoltativo) il nome del pacchetto. Se fornita, la regola si applica solo al pacchetto specificato anziché all'intero repository.
  • CONDITION: (facoltativo) un'espressione CEL che definisce una regola di corrispondenza. Se fornita, applica la regola solo ai download che soddisfano la condizione specificata. Ad esempio: pkg.version.id < '3.0'.
  • PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
  • LOCATION: la posizione regionale o multiregionale del repository.
  • REPOSITORY: l'ID repository.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Viene creata una nuova regola con il seguente output: 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Per saperne di più, consulta il riferimento REST.

Elenca regole di download

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

Esegui questo 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
 Viene visualizzato un elenco di regole per il progetto, la località e il repository specificati, simile al seguente: 
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Per ulteriori informazioni, consulta il comando gcloud artifacts rules list.

API

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Viene visualizzato un elenco di regole per il progetto, la località e il repository specificati, simile al seguente: 
{
  "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"
    }
  ]
}
Per saperne di più, consulta il riferimento REST.

Descrivi le regole di download

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository.
  • PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
  • LOCATION: la posizione regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Esegui questo 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
 I dettagli della regola vengono visualizzati in modo simile al seguente: 
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
Per ulteriori informazioni, consulta il comando gcloud artifacts rules describe.

API

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository.
  • PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
  • LOCATION: la posizione regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

I dettagli della regola vengono visualizzati in modo simile al seguente: 
{
  "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"
    }
  ]
}
Per saperne di più, consulta il riferimento REST.

Aggiornare le regole di download

gcloud

Rimuovi le variabili che non vuoi aggiornare.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository.
  • ACTION: l'azione applicata a un download che corrisponde a questa regola. Scegli tra ALLOW e DENY.
  • PACKAGE: il nome del pacchetto. Se non viene fornito, la regola si applica all'intero repository.
  • CONDITION: un'espressione CEL che definisce una regola di corrispondenza. Se fornita, applica la regola solo ai download che soddisfano la condizione specificata. Ad esempio: pkg.version.id < '3.0'.
  • PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
  • LOCATION: la posizione regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Esegui questo 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"
 I dettagli aggiornati della regola vengono visualizzati in modo simile a quanto segue: 
Updated rule [RULE_NAME].
action: ACTION
condition:
  expression: CONDITION
name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME
operation: DOWNLOAD
Per ulteriori informazioni, consulta il comando gcloud artifacts rules update.

API

Rimuovi le variabili che non vuoi aggiornare.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository.
  • ACTION: l'azione applicata a un download che corrisponde a questa regola. Scegli tra ALLOW e DENY.
  • PACKAGE: il nome del pacchetto. Se non viene fornito, la regola si applica all'intero repository.
  • CONDITION: un'espressione CEL che definisce una regola di corrispondenza. Se fornita, applica la regola solo ai download che soddisfano la condizione specificata. Ad esempio: pkg.version.id < '3.0'.
  • PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
  • LOCATION: la posizione regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

I dettagli aggiornati della regola vengono visualizzati in modo simile a quanto segue: 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Per saperne di più, consulta il riferimento REST.

Elimina regole di download

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository.
  • PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
  • LOCATION: la posizione regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Esegui questo 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
 La regola viene eliminata con il seguente output: 
You are about to delete rule [RULE_NAME]

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

Deleted rule [RULE_NAME].
Per ulteriori informazioni, consulta il comando gcloud artifacts rules delete.

API

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository.
  • PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
  • LOCATION: la posizione regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Per saperne di più, consulta il riferimento REST.

Utilizzare CEL per definire le condizioni

Puoi definire le condizioni per le regole di download con Common Expression Language (CEL), un linguaggio open source per la valutazione delle espressioni. Artifact Registry fornisce l'oggetto pkg che contiene i seguenti attributi:

  • pkg.id: una stringa che rappresenta il nome del pacchetto dell'artefatto. Può essere utilizzato con le regole impostate a livello di repository.
  • pkg.version.id: una stringa che rappresenta la versione dell'artefatto.
  • pkg.version.tag: una stringa che rappresenta il tag dell'artefatto. Utilizza solo in un repository Docker.

Puoi utilizzare operatori logici e funzioni integrate con CEL. Di seguito sono riportate alcune espressioni CEL di esempio che potrebbero essere utili nelle regole di download:

  • Utile per le regole impostate a livello di repository:

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

  • Utile per le regole impostate sui pacchetti:

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

Quando aggiungi regole con condizioni basate su tag come pkg.version.tag == 'latest' nei repository Docker, tieni presente quanto segue:

  • Quando il pull viene eseguito per digest, il client non fornisce un tag. Le condizioni che utilizzano i tag verranno confrontate con un tag vuoto e potrebbero comportare un comportamento imprevisto.
  • Per le immagini container multi-architettura, le condizioni che utilizzano i tag potrebbero non funzionare come previsto e devono essere evitate.