Crea repository virtuali

Questa pagina descrive come creare repository virtuali di Artifact Registry.

I repository virtuali fungono da singolo punto di accesso per scaricare, installare o eseguire il deployment degli artefatti nello stesso formato da uno o più repository upstream. Un repository a monte può essere un repository standard o remoto di Artifact Registry.

Le altre modalità del repository sono:

  • Standard: la modalità predefinita per il repository. Puoi caricare o pubblicare artefatti come pacchetti privati direttamente nei repository standard. Sebbene sia possibile scaricare direttamente da singoli repository standard, l'accesso a gruppi di repository con un repository virtuale semplifica la configurazione dello strumento.
  • Remote (solo repository di pacchetti di linguaggio): una cache pull-through per gli artefatti nei repository pubblici come Maven Central o PyPI. Agisce da proxy per i repository pubblici, in modo da avere un maggiore controllo sulle dipendenze esterne.

Per ulteriori informazioni sul funzionamento dei repository virtuali, consulta la Panoramica dei repository virtuali.

Prima di iniziare

Abilita Artifact Registry, incluse l'abilitazione dell'API Artifact Registry e l'installazione della versione più recente di Google Cloud CLI.

Ruoli obbligatori

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

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Se i repository a monte si trovano in altri progetti, un amministratore dei progetti con repository a monte deve disporre delle autorizzazioni per gestire l'accesso a questi repository.

Crea repository upstream

Prima di configurare un repository virtuale, crea i repository a monte che vuoi rendere disponibili con il repository virtuale.

  1. Crea i repository a monte nella stessa regione Google Cloud in cui prevedi di creare il repository virtuale.

  2. I repository virtuali utilizzano l'agente di servizio Artifact Registry per l'autenticazione nei repository a monte. Devi concedere all'agente di servizio l'accesso in lettura ai repository upstream.

    Puoi concedere il ruolo Lettore Artifact Registry all'agente di servizio Artifact Registry a livello di progetto in modo da non dover concedere l'accesso ai singoli repository upstream.

    In ogni progetto con repository a monte, esegui questo comando:

    gcloud projects add-iam-policy-binding UPSTREAM_PROJECT_ID \
        --member serviceAccount:service-VIRTUAL-REPO-PROJECT_NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com \
        --role roles/artifactregistry.reader
    

    Dove

    • UPSTREAM_PROJECT_ID è l'ID del progetto Google Cloud con il repository upstream.
    • VIRTUAL_REPO_PROJECT_NUMBER è il numero di progetto del progetto Google Cloud per il repository virtuale.

    In alternativa, se vuoi concedere un ruolo con ambito più limitato all'agente di servizio, aggiungi l'autorizzazione artifactregistry.repositories.readViaVirtualRepository a un ruolo personalizzato e concedi questo ruolo all'agente di servizio.

    Per ulteriori informazioni sulla concessione delle autorizzazioni, consulta la documentazione relativa al controllo dell'accesso.

Crea un repository virtuale

Quando crei un repository, devi configurare le seguenti impostazioni che non possono essere modificate dopo la creazione del repository:

  • Formato dell'artefatto.
  • Modalità repository, se sono disponibili più modalità per il formato selezionato.
  • La località del repository.
  • Crittografia con chiavi gestite da Google o chiavi di crittografia gestite dal cliente. Artifact Registry utilizza chiavi di crittografia gestite da Google per impostazione predefinita.

Artifact Registry applica limiti dei criteri dell'organizzazione che richiedono una CMEK per criptare le risorse o limitare le chiavi Cloud KMS che possono essere utilizzate per la protezione CMEK.

Crea un repository virtuale utilizzando la console Google Cloud

  1. Apri la pagina Repositories nella console Google Cloud.

    Apri la pagina Repository

  2. Fai clic su Crea repository.

  3. Specifica il nome del repository. Per ogni località del repository in un progetto, i nomi dei repository devono essere univoci.

  4. Seleziona il formato del repository.

  5. In Modalità repository, seleziona Virtuale.

  6. In Upstream del repository virtuale, fai clic su Aggiungi upstream per aggiungere un repository upstream.

    • Un repository upstream può essere un repository standard, remoto o virtuale.
    • Un repository a monte deve trovarsi nella stessa località del repository virtuale, ma può trovarsi in un progetto Google Cloud diverso.
    • Un repository a monte deve avere lo stesso formato dell'artefatto del repository virtuale.

    Specifica una priorità e un nome del criterio per ogni repository upstream. I valori di priorità più elevata hanno la precedenza sui valori più bassi. Lascia spazio tra i valori di priorità in modo che vi sia la flessibilità di aggiungere repository upstream con priorità che si trovano tra i valori esistenti.

  7. In Tipo di località, scegli la località del repository:

    1. Scegli il tipo di località: Regione o Più regioni. L'elenco delle località cambia in base alla tua selezione.

    2. Nell'elenco Regione o Più regioni, seleziona una località.

    Per informazioni sui tipi di località e sulle località supportate, consulta Località dei repository

  8. Aggiungi una descrizione per il repository. Le descrizioni aiutano a identificare lo scopo del repository e il tipo di artefatti che contiene.

    Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.

  9. Se vuoi utilizzare etichette per organizzare i repository, fai clic su Aggiungi etichetta e inserisci la coppia chiave-valore per l'etichetta. Puoi aggiungere, modificare o rimuovere le etichette dopo aver creato il repository.

  10. Nella sezione Crittografia, scegli il meccanismo di crittografia del repository.

    • Chiave gestita da Google: cripta i contenuti del repository con una chiave di crittografia gestita da Google.
    • Chiave gestita dal cliente: cripta i contenuti del repository con una chiave che puoi controllare tramite Cloud Key Management Service. Per istruzioni di configurazione della chiave, consulta Configurare CMEK per i repository.
  11. Fai clic su Crea.

Artifact Registry crea il repository e lo aggiunge all'elenco dei repository.

Dopo aver creato il repository:

Crea un repository virtuale utilizzando gcloud CLI

Per creare un repository virtuale, devi definire i repository upstream in un file di criteri, quindi creare il repository utilizzando il file dei criteri.

  1. Crea un file dei criteri upstream in formato JSON con le seguenti impostazioni:

    [{
    "id" : "POLICY_ID",
    "repository" : "UPSTREAM_REPOSITORY_RESOURCE_NAME",
    "priority" : PRIORITY
    }, {...}]
    
    • POLICY_ID è un nome per il criterio. Ogni repository a monte nel criterio deve avere un ID criterio univoco.
    • UPSTREAM_REPO_RESOURCE_NAME è il nome del repository upstream nel formato:

      projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY
      
      • Un repository upstream può essere un repository standard, remoto o virtuale.
      • Un repository a monte deve trovarsi nella stessa località del repository virtuale, ma può trovarsi in un progetto Google Cloud diverso.
      • Un repository a monte deve avere lo stesso formato dell'artefatto del repository virtuale.
    • PRIORITY è un numero intero che indica la priorità per il repository upstream. I valori con priorità più alta hanno la precedenza sui valori più bassi.

    L'esempio seguente mostra un file di criteri denominato policies.json con quattro repository upstream. upstream1 ha il valore più alto per priority, quindi Artifact Registry la cercherà prima. upstream-test ha il valore priority più basso, quindi Artifact Registry lo cercherà per ultimo. upstream2 e upstream3 hanno la stessa priorità. Se Artifact Registry trova un pacchetto richiesto nei repository con la stessa priorità, può gestire il pacchetto da entrambi i repository.

    [{
    "id" : "upstream1",
    "repository" : "projects/myproject/locations/us-west1/repositories/python-repo1",
    "priority" : 100
    }, {
    "id" : "upstream2",
    "repository" : "projects/myproject/locations/us-west1/repositories/python-repo2",
    "priority" : 80
    }, {
    "id" : "upstream3",
    "repository" : "projects/myproject/locations/us-west1/repositories/python-repo2",
    "priority" : 80
    }, {
    "id" : "upstream-test",
    "repository" : "projects/myproject/locations/us-west1/repositories/python-test-repo",
    "priority" : 20
    }]
    

    In questo esempio viene lasciato uno spazio anche tra i valori di priorità. Queste lacune forniscono la flessibilità necessaria per aggiungere repository a monte con priorità che si trovano tra i valori esistenti. Ad esempio, puoi aggiungere un repository upstream-3 con una priorità pari a 70 in modo che Artifact Registry esegua la ricerca prima di upstream-test.

    Prendi in considerazione l'archiviazione del file dei criteri upstream nel tuo sistema di controllo del codice sorgente, in modo da poterlo riutilizzare in un secondo momento per apportare modifiche alle impostazioni del repository a monte e tenere traccia delle modifiche storiche.

  2. Nella directory con il file dei criteri a monte, esegui questo comando per creare il repository virtuale:

    gcloud artifacts repositories create VIRTUAL-REPOSITORY-NAME \
        --project=PROJECT_ID \
        --repository-format=FORMAT \
        --mode=virtual-repository \
        --location=LOCATION \
        --description="DESCRIPTION" \
        --upstream-policy-file=UPSTREAM_POLICY_FILE
    

    Sostituisci quanto segue:

    • VIRTUAL-REPOSITORY-NAME è il nome del repository virtuale.
    • PROJECT_ID è l'ID del progetto in cui stai creando il repository virtuale. Se questo flag viene omesso, viene usato il progetto attuale o predefinito.
    • FORMAT è il formato del repository. Sono disponibili i seguenti valori:
      • apt (anteprima privata)
      • docker
      • maven
      • npm
      • python
      • yum (anteprima privata)
    • LOCATION è la località a livello di una o più regioni per il repository. Puoi omettere questo flag se imposti un valore predefinito. Per visualizzare un elenco delle località supportate, esegui questo comando:

      gcloud artifacts locations list
      
    • DESCRIPTION è una descrizione facoltativa del repository. Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.

    • UPSTREAM_POLICY_FILE è un percorso del file dei criteri upstream.

    Ad esempio, il comando seguente crea un repository virtuale denominato virtual-repo per i pacchetti Python nella regione us-west1 con impostazioni in policies.json.

    gcloud artifacts repositories create virtual-repo \
    --repository-format=python \
    --mode=virtual-repository \
    --location=us-west1 \
    --description="Python virtual repository" \
    --upstream-policy-file=policies.json
    

Artifact Registry crea il repository virtuale.

Creare un repository virtuale utilizzando Terraform

Utilizza la risorsa google_artifact_registry_repository per creare repository. È richiesta la versione terraform-provider-google 5.0.0 o successiva.

Se non hai mai utilizzato Terraform per Google Cloud, consulta la pagina Inizia a utilizzare Google Cloud sul sito web di hashiCorp.

L'esempio seguente definisce il provider, un repository virtuale con il nome risorsa Terraform my-repo e un repository a monte con il nome risorsa Terraform my-repo-upstream.

Docker

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "docker"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "docker"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

Dove

  • PROJECT-ID è l'ID del progetto Google Cloud.
  • UPSTREAM_LOCATION è la località del repository a monte. Tieni presente che il repository virtuale e l'upstream devono trovarsi nella stessa regione o in più regioni.
  • UPSTREAM_REPOSITORY_ID è l'ID repository a monte.
  • UPSTREAM_REPOSITORY_DESCRIPTION è la descrizione facoltativa del repository a monte.
  • LOCATION è la località del repository virtuale.
  • REPOSITORY_ID è l'ID repository virtuale.
  • DESCRIPTION è la descrizione facoltativa per il repository virtuale. Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.
  • KEY è il nome della chiave Cloud Key Management Service, se utilizzi chiavi di crittografia gestite dal cliente (CMEK) per la crittografia. Ometti questo argomento per utilizzare l'impostazione predefinita, le chiavi di crittografia gestite da Google.
  • PRIORITY è il valore di priorità facoltativo. La priorità più alta è 1. Le voci con un valore di priorità maggiore hanno la precedenza nell'ordine di pull.

Maven

Se non specifichi un criterio di versione, Artifact Registry crea un Repository Maven che archivia sia le versioni snapshot e di release dei pacchetti per impostazione predefinita.

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "maven"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "maven"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

Dove

  • PROJECT-ID è l'ID del progetto Google Cloud.
  • UPSTREAM_LOCATION è la località del repository a monte. Tieni presente che il repository virtuale e l'upstream devono trovarsi nella stessa regione o in più regioni.
  • UPSTREAM_REPOSITORY_ID è l'ID repository a monte.
  • UPSTREAM_REPOSITORY_DESCRIPTION è la descrizione facoltativa del repository a monte.
  • LOCATION è la località del repository virtuale.
  • REPOSITORY_ID è l'ID repository virtuale.
  • DESCRIPTION è la descrizione facoltativa per il repository virtuale. Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.
  • KEY è il nome della chiave Cloud Key Management Service, se utilizzi chiavi di crittografia gestite dal cliente (CMEK) per la crittografia. Ometti questo argomento per utilizzare l'impostazione predefinita, le chiavi di crittografia gestite da Google.
  • PRIORITY è il valore di priorità facoltativo. La priorità più alta è 1. Le voci con un valore di priorità maggiore hanno la precedenza nell'ordine di pull.

Per archiviare le versioni di snapshot e release in repository diversi, specifica un criterio di versione per il repository utilizzando un blocco maven_config. Questo blocco supporta le seguenti impostazioni:

  • version_policy imposta il criterio di versione con uno dei seguenti valori:
    • VERSION_POLICY_UNSPECIFIED: archivia snapshot e rilascia pacchetti. Questa è l'impostazione predefinita.
    • RILASCIO: solo pacchetti di release.
    • Istantanea: archivia solo i pacchetti di snapshot.
  • allow_snapshot_overwrites configura un repository con un criterio delle versioni SNAPSHOT per accettare snapshot non univoci che sovrascrivono le versioni esistenti nel repository.

L'esempio seguente definisce un Repository Maven con un criterio di versione di release.

provider "google" {
project = "my-project"
}

resource "google_artifact_registry_repository" "my-repo" {
provider = google-beta

location = "us-central1"
repository_id = "my-repo"
description = "Maven repository"
format = "MAVEN"
maven_config {
  version_policy = "RELEASE"
}
}

npm

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "npm"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "npm"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

Dove

  • PROJECT-ID è l'ID del progetto Google Cloud.
  • UPSTREAM_LOCATION è la località del repository a monte. Tieni presente che il repository virtuale e l'upstream devono trovarsi nella stessa regione o in più regioni.
  • UPSTREAM_REPOSITORY_ID è l'ID repository a monte.
  • UPSTREAM_REPOSITORY_DESCRIPTION è la descrizione facoltativa del repository a monte.
  • LOCATION è la località del repository virtuale.
  • REPOSITORY_ID è l'ID repository virtuale.
  • DESCRIPTION è la descrizione facoltativa per il repository virtuale. Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.
  • KEY è il nome della chiave Cloud Key Management Service, se utilizzi chiavi di crittografia gestite dal cliente (CMEK) per la crittografia. Ometti questo argomento per utilizzare l'impostazione predefinita, le chiavi di crittografia gestite da Google.
  • PRIORITY è il valore di priorità facoltativo. La priorità più alta è 1. Le voci con un valore di priorità maggiore hanno la precedenza nell'ordine di pull.

Python

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "python"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "python"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

Dove

  • PROJECT-ID è l'ID del progetto Google Cloud.
  • UPSTREAM_LOCATION è la località del repository a monte. Tieni presente che il repository virtuale e l'upstream devono trovarsi nella stessa regione o in più regioni.
  • UPSTREAM_REPOSITORY_ID è l'ID repository a monte.
  • UPSTREAM_REPOSITORY_DESCRIPTION è la descrizione facoltativa del repository a monte.
  • LOCATION è la località del repository virtuale.
  • REPOSITORY_ID è l'ID repository virtuale.
  • DESCRIPTION è la descrizione facoltativa per il repository virtuale. Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.
  • KEY è il nome della chiave Cloud Key Management Service, se utilizzi chiavi di crittografia gestite dal cliente (CMEK) per la crittografia. Ometti questo argomento per utilizzare l'impostazione predefinita, le chiavi di crittografia gestite da Google.
  • PRIORITY è il valore di priorità facoltativo. La priorità più alta è 1. Le voci con un valore di priorità maggiore hanno la precedenza nell'ordine di pull.

Artifact Registry crea il repository. Esegui questo comando per visualizzare una descrizione del repository:

gcloud artifacts repositories describe REPOSITORY \
    --location=LOCATION

Dopo aver creato il repository:

Aggiorna repository upstream

Puoi modificare l'elenco dei repository upstream o regolare la priorità dei repository upstream.

Console

  1. Apri la pagina Repositories nella console Google Cloud.

    Apri la pagina Repository

  2. Nell'elenco dei repository, seleziona il repository virtuale e fai clic su Modifica repository.

  3. Nell'elenco Upstream del repository virtuale, apporta le modifiche necessarie. Puoi aggiungere e rimuovere repository o cambiare la priorità dei repository nell'elenco

  4. Fai clic su Salva.

gcloud

  1. Modifica il file dei criteri upstream con le modifiche. Ad esempio, potresti voler aggiungere un repository upstream o regolare le impostazioni di priorità.

    Se vuoi rimuovere tutti i repository upstream, il file del criterio deve contenere un insieme vuoto di repository.

    []
    
  2. Esegui questo comando per applicare le modifiche al repository virtuale.

    gcloud artifacts repositories update REPOSITORY \
        --upstream-policy-file=UPSTREAM_POLICY_FILE
    

    Sostituisci UPSTREAM_POLICY_FILE con il percorso del file del criterio upstream.

    Per ulteriori informazioni sul comando, consulta la documentazione di riferimento per l'aggiornamento degli artefatti di gcloud.

Modifica descrizioni repository

Puoi modificare la descrizione del repository dalla console Google Cloud o da gcloud CLI.

Console

  1. Apri la pagina Repositories nella console Google Cloud.

    Apri la pagina Repository

  2. Nell'elenco dei repository, seleziona il repository e fai clic su Modifica repository.

  3. Modifica la descrizione del repository e fai clic su Salva.

gcloud

Per aggiornare la descrizione del repository, esegui il comando:

gcloud artifacts repositories update REPOSITORY \
    --project=PROJECT] \
    --location=LOCATION \
    --description="DESCRIPTION"

Sostituisci i seguenti valori:

  • REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
  • PROJECT è l'ID del progetto Google Cloud. Se questo flag viene omesso, viene usato il progetto attuale o predefinito.
  • LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.
  • DESCRIPTION è una descrizione del repository.