Limitare i download di elementi con le regole di download

Questa pagina descrive come limitare i download degli elementi dai tuoi repository Artifact Registry creando e gestendo le regole di download.

Le regole di download ti consentono di consentire o negare i download di elementi 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 elementi della panoramica Controlla l'accesso e proteggi gli elementi.

Prima di iniziare

  1. Se non ne hai già uno, crea un repository standard in formato Docker.
  2. (Facoltativo) Configura i valori predefiniti 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 Gestire 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 essere costituito da caratteri alfanumerici, caratteri codificati in percentuale o caratteri nell'elenco [-, ., _, ~, :, @, +, ^].
  • ACTION: l'azione applicata a un download corrispondente a questa regola. Scegli tra ALLOW, se la regola consente i download corrispondenti, e DENY, se la regola ne impedisce l'esecuzione.
  • PACKAGE: (facoltativo) il nome del pacchetto. Se specificato, la regola si applica solo al pacchetto specificato anziché all'intero repository.
  • CONDITION: (facoltativo) un'espressione CEL che definisce una regola di corrispondenza. Se specificato, applica la regola solo ai download che corrispondono alla 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 località regionale o multiregionale del repository.
  • REPOSITORY: l'ID repository.

Esegui il seguente 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 essere costituito da caratteri alfanumerici, caratteri codificati in percentuale o caratteri nell'elenco [-, ., _, ~, :, @, +, ^].
  • ACTION: l'azione applicata a un download corrispondente a questa regola. Scegli tra ALLOW, se la regola consente i download corrispondenti, e DENY, se la regola ne impedisce l'esecuzione.
  • PACKAGE: (facoltativo) il nome del pacchetto. Se specificato, la regola si applica solo al pacchetto specificato anziché all'intero repository.
  • CONDITION: (facoltativo) un'espressione CEL che definisce una regola di corrispondenza. Se specificato, applica la regola solo ai download che corrispondono alla 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 località 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 ulteriori informazioni, consulta la documentazione di riferimento REST.

Elenca regole di download

gcloud

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

Esegui il seguente 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 ulteriori informazioni, consulta la documentazione di 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 località regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Esegui il seguente 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 sono simili ai seguenti: 
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 località 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 sono simili ai seguenti: 
{
  "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 ulteriori informazioni, consulta la documentazione di 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 corrispondente a questa regola. Scegli tra ALLOW e DENY.
  • PACKAGE: il nome del pacchetto. Se non specificato, la regola si applica all'intero repository.
  • CONDITION: un'espressione CEL che definisce una regola di corrispondenza. Se specificato, applica la regola solo ai download che corrispondono alla 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 località regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Esegui il seguente 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 della regola aggiornata sono simili ai seguenti: 
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 corrispondente a questa regola. Scegli tra ALLOW e DENY.
  • PACKAGE: il nome del pacchetto. Se non specificato, la regola si applica all'intero repository.
  • CONDITION: un'espressione CEL che definisce una regola di corrispondenza. Se specificato, applica la regola solo ai download che corrispondono alla 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 località 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 della regola aggiornata sono simili ai seguenti: 
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
Per ulteriori informazioni, consulta la documentazione di riferimento REST.

Eliminare 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 località regionale o multiregionale del repository.
  • REPOSITORY: il nome del repository.

Esegui il seguente 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 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 località 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 ulteriori informazioni, consulta il riferimento REST.

Utilizzare CEL per definire le condizioni

Puoi definire le condizioni per le regole di download con il 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'elemento. Può essere utilizzato con le regole impostate a livello di repository.
  • pkg.version.id: una stringa che rappresenta la versione dell'elemento.
  • pkg.version.tag: una stringa che rappresenta il tag dell'elemento. Utilizzare solo in un repository Docker.

Con CEL puoi utilizzare operatori logici e funzioni integrate. Di seguito sono riportati alcuni esempi di espressioni CEL 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 tuoi repository Docker, tieni presente quanto segue:

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