Limitare i download di elementi con le regole di download

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

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

Per maggiori dettagli sul funzionamento delle regole di download, consulta la sezione Limita i download degli artefatti della panoramica su come 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 i valori predefiniti per i comandi di 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.

Crea 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 ed essere composto da caratteri alfanumerici, caratteri con codifica percentuale o caratteri nell'elenco [-, ., _, ~, :, @, +, ^].
  • ACTION: l'azione applicata a un download che corrisponde a questa regola. Scegli tra ALLOW, dove la regola consente i download corrispondenti, e DENY, dove la regola blocca i download corrispondenti.
  • 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 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 località 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 sostituzioni seguenti:

  • RULE_NAME: il nome della regola. Il nome deve essere univoco all'interno del repository, avere una lunghezza massima di 256 caratteri ed essere composto da caratteri alfanumerici, caratteri con codifica percentuale o caratteri nell'elenco [-, ., _, ~, :, @, +, ^].
  • ACTION: l'azione applicata a un download che corrisponde a questa regola. Scegli tra ALLOW, dove la regola consente i download corrispondenti, e DENY, dove la regola blocca i download corrispondenti.
  • 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 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 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 saperne di più, consulta il riferimento REST.

Regole per il download degli elenchi

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 sostituzioni seguenti:

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 località 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 sostituzioni seguenti:

  • 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 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.

Aggiorna 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 specificato, 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 località 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 della regola aggiornata vengono visualizzati in modo simile al seguente: 
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 sostituzioni seguenti:

  • 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 specificato, 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 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 vengono visualizzati in modo simile al seguente: 
{
  "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 località 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 sostituzioni seguenti:

  • 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 saperne di più, consulta il riferimento REST.

Utilizza 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'artefatto. Può essere utilizzato con i set di regole impostati 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. Utilizzala solo in un repository Docker.
  • pkg.version.annotations: una mappa di stringhe coppia chiave-valore che rappresentano le annotazioni definite dall'utente sulla versione dell'artefatto in un repository standard.

Puoi utilizzare operatori logici e funzioni integrate con CEL. Di seguito sono riportati alcuni esempi di espressioni CEL che potrebbero essere utili nelle regole di download:

  • Utile per i set di regole a livello di repository:

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

  • Utile per i set di regole impostati 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']
  'quarantined' in pkg.version.annotations && pkg.version.annotations['quarantined'] == 'true' #Artifact version has annotation 'quarantined' set to 'true'

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

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