crea repository virtuali

Questa pagina descrive come creare repository virtuali Artifact Registry.

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

Le altre modalità del repository sono:

  • Standard: la modalità di repository predefinita. Puoi caricare o pubblicare gli artefatti, come i 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 degli strumenti.
  • 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, consentendoti di avere un maggiore controllo sulle dipendenze esterne.

Per ulteriori informazioni su come funzionano i 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 seguenti ruoli IAM:

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 upstream si trovano in altri progetti, un amministratore dei progetti con repository upstream deve disporre delle autorizzazioni per gestire l'accesso a questi repository.

Crea repository upstream

Prima di configurare un repository virtuale, crea i repository upstream 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 eseguire 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 concedere l'accesso a singoli repository upstream.

    In ogni progetto con repository upstream, 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 sul 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 artefatto.
  • Modalità repository, se sono disponibili più modalità per il formato selezionato.
  • Posizione 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 vincoli 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 posizione del repository di 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 upstream deve trovarsi nella stessa località del repository virtuale, ma può trovarsi in un progetto Google Cloud diverso.
    • Un repository upstream deve avere lo stesso formato di artefatto del repository virtuale.

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

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

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

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

    Per informazioni sui tipi di località e sulle località supportate, consulta Località del 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 le etichette per organizzare i repository, fai clic su Aggiungi etichetta e inserisci la coppia chiave-valore dell'etichetta. Puoi aggiungere, modificare o rimuovere le etichette dopo aver creato il repository.

  10. Nella sezione Crittografia, scegli il meccanismo di crittografia per il 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 le istruzioni di configurazione delle chiavi, 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 e quindi creare il repository utilizzando il file dei criteri.

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

    [{
"id" : "POLICY_ID",
"repository" : "UPSTREAM_REPOSITORY_RESOURCE_NAME",
"priority" : PRIORITY
}, {...}]
    • POLICY_ID è il nome del criterio. Ogni repository upstream 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 upstream deve trovarsi nella stessa località del repository virtuale, ma può trovarsi in un progetto Google Cloud diverso.
      • Un repository upstream deve avere lo stesso formato di 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 su quelli più bassi.

    L'esempio seguente mostra un file del criterio denominato policies.json con quattro repository upstream. upstream1 ha il valore più alto per priority, quindi Artifact Registry lo 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 in 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 anche uno spazio tra i valori di priorità. Queste lacune offrono la flessibilità necessaria per aggiungere repository upstream con priorità che si trovano tra i valori esistenti. Ad esempio, puoi aggiungere un repository upstream-3 con priorità 70, in modo che Artifact Registry esegua le ricerche prima del giorno upstream-test.

    Prendi in considerazione l'archiviazione del file dei criteri upstream nel sistema di controllo del codice sorgente, in modo da poterlo riutilizzare in un secondo momento per apportare modifiche alle impostazioni del repository upstream e monitorare le modifiche cronologiche.

  2. Nella directory con il file dei criteri upstream, 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 corrente 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 default. Per visualizzare un elenco delle località supportate, esegui il 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. È necessaria la versione terraform-provider-google 5.0.0 o successiva.

Se è la prima volta che utilizzi 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 della risorsa Terraform my-repo e un repository upstream con il nome della 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 progetto Google Cloud.
  • UPSTREAM_LOCATION è la località del repository upstream. Tieni presente che il repository virtuale e l'upstream devono trovarsi nella stessa regione o in più regioni.
  • UPSTREAM_REPOSITORY_ID è l'ID repository upstream.
  • 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 progetto Google Cloud.
  • UPSTREAM_LOCATION è la località del repository upstream. Tieni presente che il repository virtuale e l'upstream devono trovarsi nella stessa regione o in più regioni.
  • UPSTREAM_REPOSITORY_ID è l'ID repository upstream.
  • 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 rilasciare 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.
    • RILASCIA: archivia solo i pacchetti di rilascio.
    • SNAPSHOT: archivia solo i pacchetti di snapshot.
  • allow_snapshot_overwrites configura un repository con un criterio di versione 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 progetto Google Cloud.
  • UPSTREAM_LOCATION è la località del repository upstream. Tieni presente che il repository virtuale e l'upstream devono trovarsi nella stessa regione o in più regioni.
  • UPSTREAM_REPOSITORY_ID è l'ID repository upstream.
  • 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 progetto Google Cloud.
  • UPSTREAM_LOCATION è la località del repository upstream. Tieni presente che il repository virtuale e l'upstream devono trovarsi nella stessa regione o in più regioni.
  • UPSTREAM_REPOSITORY_ID è l'ID repository upstream.
  • 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 tuo 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 oppure modificare 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 modificare le impostazioni di priorità.

    Se vuoi rimuovere tutti i repository upstream, il file dei criteri dovrebbe contenere un set 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 dei criteri upstream.

    Per ulteriori informazioni sul comando, consulta la documentazione di riferimento gcloud artefatti repository update.

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 quanto segue:

  • REPOSITORY: il nome del repository. Se hai configurato un repository default, 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 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 il valore predefinito.
  • DESCRIPTION: una descrizione del repository.