Crea repositorios virtuales

En esta página, se describe cómo crear repositorios virtuales de Artifact Registryy.

Los repositorios virtuales actúan como un único punto de acceso para descargar, instalar o implementar artefactos en el mismo formato desde uno o más repositorios ascendentes. Un repositorio upstream puede ser un repositorio remoto o estándar de Artifact Registry.

Los otros modos de repositorio son los siguientes:

Estándar: El modo de repositorio predeterminado. Puedes subir o publicar artefactos como paquetes privados directamente en los repositorios estándar. Aunque puedes descargar directamente desde repositorios estándar individuales, acceder a grupos de repositorios con un repositorio virtual simplifica la configuración de las herramientas.
Remote (solo repositorios de paquetes de lenguajes): Una extracción a través de la caché de artefactos en repositorios públicos, como Maven Central o PyPI. Actúa como un proxy para los repositorios públicos, de manera que tengas más control sobre las dependencias externas.

Para obtener más información sobre cómo funcionan los repositorios virtuales, consulta la Descripción general del repositorio virtual.

Antes de comenzar

Habilita Artifact Registry, incluida la habilitación de la API de Artifact Registry y la instalación de la versión más reciente de Google Cloud CLI.

Funciones obligatorias

Si quieres obtener los permisos que necesitas para administrar repositorios, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Crea repositorios virtuales y otorga acceso a repositorios individuales: Administrador del repositorio de Artifact Registry (roles/artifactregistry.repoAdmin) en el proyecto de Google Cloud
Otorga acceso a los repositorios a nivel de proyecto: Administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) en el proyecto de Google Cloud
Otorga acceso a los repositorios a nivel de la carpeta: Administrador de carpetas (roles/resourcemanager.folderAdmin) en la carpeta
Otorga acceso a los repositorios a nivel de la organización: Administrador de la organización (roles/resourcemanager.organizationAdmin) en la organización de Google Cloud

Si quieres obtener más información para otorgar funciones, consulta Administra el acceso.

Es posible que también puedas obtener los permisos necesarios mediante funciones personalizadas, o bien otras funciones predefinidas.

Si los repositorios upstream se encuentran en otros proyectos, un administrador en los proyectos con repositorios upstream debe tener permisos para administrar el acceso a esos repositorios.

Crea repositorios upstream

Antes de configurar un repositorio virtual, crea los repositorios ascendentes que deseas que estén disponibles con el repositorio virtual.

Crea los repositorios upstream en la misma región de Google Cloud en la que planeas crear el repositorio virtual.
- Crea un repositorio estándar
- Crea un repositorio remoto
Los repositorios virtuales usan el agente de servicio de Artifact Registry para autenticarse en los repositorios ascendentes. Debes otorgar al agente de servicio acceso de lectura a los repositorios upstream.

Puedes otorgar la función de lector de Artifact Registry al agente de servicio de Artifact Registry a nivel del proyecto para que no necesites otorgar acceso a repositorios ascendentes individuales.

En cada proyecto con repositorios upstream, ejecuta el siguiente 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
```
¿Por dónde
- UPSTREAM_PROJECT_ID es el ID del proyecto de Google Cloud con el repositorio upstream.
- VIRTUAL_REPO_PROJECT_NUMBER es el número de proyecto de Google Cloud para tu repositorio virtual.
Como alternativa, si deseas otorgar una función de alcance más limitado al agente de servicio, agrega el permiso artifactregistry.repositories.readViaVirtualRepository a una función personalizada y, luego, otórgale esa función.

Para obtener más información sobre cómo otorgar permisos, consulta la documentación de control de acceso.

Crea un repositorio virtual

Cuando creas un repositorio, debes establecer la siguiente configuración que no se puede cambiar después de crearlo:

Formato del artefacto.
Modo de repositorio, si hay varios modos disponibles para el formato seleccionado
Ubicación del repositorio
Encriptación con claves administradas por Google o claves de encriptación administradas por el cliente Artifact Registry usa claves de encriptación administradas por Google de forma predeterminada.

Artifact Registry aplica restricciones de políticas de la organización que requieren CMEK para encriptar recursos o limitar las claves de Cloud KMS que se pueden usar para la protección de CMEK.

Crea un repositorio virtual con la consola de Google Cloud

Abre la página Repositorios en la consola de Google Cloud.

Abrir la página Repositorios
Haz clic en Crear repositorio.
Especifica el nombre del repositorio. Para la ubicación de cada repositorio en un proyecto, los nombres de los repositorios deben ser únicos.
Selecciona el formato del repositorio.
En Modo de repositorio, selecciona Virtual.
En Upstreams de repositorio virtual, haz clic en Agregar upstream para agregar un repositorio upstream.
- Un repositorio upstream puede ser un repositorio estándar, remoto o virtual.
- Un repositorio upstream debe estar en la misma ubicación que el repositorio virtual, pero puede estar en un proyecto de Google Cloud diferente.
- Un repositorio upstream debe tener el mismo formato de artefacto que el repositorio virtual.
Especifica una prioridad y un nombre de política para cada repositorio upstream. Los valores de mayor prioridad tienen prioridad sobre los valores más bajos. Deja espacio entre los valores de prioridad para que haya flexibilidad a fin de agregar repositorios ascendentes con prioridades que se encuentren entre los valores existentes.
En Tipo de ubicación, elige la ubicación para el repositorio:
1. Elige el tipo de ubicación: Región o Multirregional. La lista de ubicaciones cambia para reflejar tu selección.
2. En la lista Región o Multirregión, selecciona una ubicación.
Para obtener información sobre los tipos de ubicación y las ubicaciones compatibles, consulta Ubicaciones de repositorios.
Agrega una descripción para el repositorio. Las descripciones ayudan a identificar el propósito del repositorio y el tipo de artefactos que contiene.

No incluyas datos sensibles, ya que las descripciones de los repositorios no están encriptadas.
Si quieres usar etiquetas para organizar tus repositorios, haz clic en Agregar etiqueta y, luego, ingresa el par clave-valor de la etiqueta. Puedes agregar, editar o quitar etiquetas después de crear el repositorio.
En la sección Encriptación, elige el mecanismo de encriptación del repositorio.
- Clave administrada por Google: Encripta el contenido de un repositorio mediante una clave de encriptación administrada por Google.
- Clave administrada por el cliente: Encripta el contenido de un repositorio mediante una clave que controlas a través de Cloud Key Management Service. Si deseas obtener instrucciones para la configuración de claves, consulta Configura CMEK para repositorios.
Haz clic en Crear.

Artifact Registry crea el repositorio y lo agrega a la lista de repositorios.

Después de crear el repositorio, sigue estos pasos:

Otorga acceso al repositorio.
Configura Docker, los administradores de paquetes y otros clientes de terceros para autenticarse en los repositorios.
- Imágenes de contenedor: Docker, Helm
- Paquetes de lenguajes: Java, Node.js, Python, Go
- Otro: Plantillas de Kubeflow Pipeline

Crea un repositorio virtual con gcloud CLI

Para crear un repositorio virtual, define tus repositorios ascendentes en un archivo de política y, luego, crea el repositorio con el archivo de políticas.

Crea un archivo de políticas upstream en formato JSON con la siguiente configuración:
```
[{
"id" : "POLICY_ID",
"repository" : "UPSTREAM_REPOSITORY_RESOURCE_NAME",
"priority" : PRIORITY
}, {...}]
```
- POLICY_ID es el nombre de la política. Cada repositorio upstream de la política debe tener un ID de política único.
- UPSTREAM_REPO_RESOURCE_NAME es el nombre del repositorio upstream en el siguiente formato:
```
projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY
```
  - Un repositorio upstream puede ser un repositorio estándar, remoto o virtual.
  - Un repositorio upstream debe estar en la misma ubicación que el repositorio virtual, pero puede estar en un proyecto de Google Cloud diferente.
  - Un repositorio upstream debe tener el mismo formato de artefacto que el repositorio virtual.
- PRIORITY es un número entero que indica la prioridad del repositorio upstream. Los valores de prioridad más alta tienen prioridad sobre los valores más bajos.
En el siguiente ejemplo, se muestra un archivo de política llamado policies.json con cuatro repositorios ascendentes. upstream1 tiene el valor más alto para priority, por lo que Artifact Registry lo buscará primero. upstream-test tiene el valor priority más bajo, por lo que Artifact Registry lo buscará en último lugar. upstream2 y upstream3 tienen la misma prioridad. Si Artifact Registry encuentra un paquete solicitado en repositorios con la misma prioridad, puede entregar el paquete desde cualquiera de los repositorios.
```
[{
"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
}]
```
En este ejemplo, también se deja espacio entre los valores de prioridad. Estas brechas proporcionan flexibilidad para agregar repositorios ascendentes con prioridades que se encuentran entre los valores existentes. Por ejemplo, puedes agregar un repositorio upstream-3 con una prioridad de 70 para que Artifact Registry lo busque antes de upstream-test.

Considera almacenar el archivo de política upstream en el sistema de control de origen para que puedas volver a usarlo más adelante a fin de realizar cambios en la configuración del repositorio upstream y hacer un seguimiento de los cambios históricos.
En el directorio con tu archivo de política upstream, ejecuta el siguiente comando para crear el repositorio virtual:
```
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
```
Reemplaza lo siguiente:
- VIRTUAL-REPOSITORY-NAME es el nombre del repositorio virtual.
- PROJECT_ID es el ID del proyecto en el que crearás el repositorio virtual. Si se omite esta marca, se usa el proyecto actual o predeterminado.
- FORMAT es el formato del repositorio. Los siguientes valores están disponibles:
  - apt (versión preliminar privada)
  - docker
  - maven
  - npm
  - python
  - yum (versión preliminar privada)
- LOCATION es la ubicación regional o multirregional del repositorio. Puedes omitir esta marca si estableces un valor predeterminado. Para ver una lista de las ubicaciones compatibles, ejecuta el siguiente comando:
```
gcloud artifacts locations list
```
- DESCRIPTION es una descripción opcional del repositorio. No incluyas datos sensibles, ya que las descripciones de los repositorios no están encriptadas.
- UPSTREAM_POLICY_FILE es una ruta de acceso al archivo de políticas ascendentes.
Por ejemplo, con el siguiente comando, se crea un repositorio virtual llamado virtual-repo para paquetes de Python en la región us-west1 con la configuración en 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 el repositorio virtual.

Crea un repositorio virtual con Terraform

Usa el recurso google_artifact_registry_repository para crear repositorios. Se requiere la versión 5.0.0 de terraform-provider-google o una posterior.

Si es la primera vez que usas Terraform para Google Cloud, consulta la página Primeros pasos: Google Cloud en el sitio web de HashiCorp.

En el siguiente ejemplo, se define el proveedor: un repositorio virtual con el nombre de recurso de Terraform my-repo y un repositorio upstream con el nombre de recurso de 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
    }
  }
}

¿Por dónde

PROJECT-ID es el ID del proyecto de Google Cloud.
UPSTREAM_LOCATION es la ubicación del repositorio upstream. Ten en cuenta que el repositorio virtual y el upstream deben estar en la misma región o multirregión.
UPSTREAM_REPOSITORY_ID es el ID del repositorio upstream.
UPSTREAM_REPOSITORY_DESCRIPTION es la descripción opcional del repositorio upstream.
LOCATION es la ubicación del repositorio virtual.
REPOSITORY_ID es el ID del repositorio virtual.
DESCRIPTION es la descripción opcional para el repositorio virtual. No incluyas datos sensibles, ya que las descripciones del repositorio no están encriptadas.
KEY es el nombre de la clave de Cloud Key Management Service, si usas claves de encriptación administradas por el cliente (CMEK) para la encriptación. Omite este argumento para usar la configuración predeterminada, las claves de encriptación administradas por Google.
PRIORITY es el valor de prioridad opcional. La prioridad más alta es 1. Las entradas con un valor de prioridad mayor tienen prioridad en el orden de extracción.

Maven

Si no especificas una política de versión, Artifact Registry crea un repositorio de Maven que almacena las versiones de instantánea y de actualización de los paquetes de forma predeterminada.

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
    }
  }
}

¿Por dónde

PROJECT-ID es el ID del proyecto de Google Cloud.
UPSTREAM_LOCATION es la ubicación del repositorio upstream. Ten en cuenta que el repositorio virtual y el upstream deben estar en la misma región o multirregión.
UPSTREAM_REPOSITORY_ID es el ID del repositorio upstream.
UPSTREAM_REPOSITORY_DESCRIPTION es la descripción opcional del repositorio upstream.
LOCATION es la ubicación del repositorio virtual.
REPOSITORY_ID es el ID del repositorio virtual.
DESCRIPTION es la descripción opcional para el repositorio virtual. No incluyas datos sensibles, ya que las descripciones del repositorio no están encriptadas.
KEY es el nombre de la clave de Cloud Key Management Service, si usas claves de encriptación administradas por el cliente (CMEK) para la encriptación. Omite este argumento para usar la configuración predeterminada, las claves de encriptación administradas por Google.
PRIORITY es el valor de prioridad opcional. La prioridad más alta es 1. Las entradas con un valor de prioridad mayor tienen prioridad en el orden de extracción.

Si quieres almacenar versiones de instantáneas y de actualización en diferentes repositorios, especifica una política de versión para el repositorio mediante un bloque maven_config. Este bloque admite la siguiente configuración:

version_policy establece la política de la versión con uno de los siguientes valores:
- VERSION_POLICY_UNSPECIFIED: Almacena instantáneas y paquetes de actualización. Esta es la configuración predeterminada.
- VERSIÓN: Almacena solo paquetes de versión.
- SNAPSHOT: Almacena solo paquetes de instantáneas.
allow_snapshot_overwrites configura un repositorio con una política de versión SNAPSHOT para aceptar instantáneas no únicas que reemplacen las versiones existentes en el repositorio.

En el siguiente ejemplo, se define un repositorio de Maven con una política de versiones de actualización.

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
    }
  }
}

¿Por dónde

PROJECT-ID es el ID del proyecto de Google Cloud.
UPSTREAM_LOCATION es la ubicación del repositorio upstream. Ten en cuenta que el repositorio virtual y el upstream deben estar en la misma región o multirregión.
UPSTREAM_REPOSITORY_ID es el ID del repositorio upstream.
UPSTREAM_REPOSITORY_DESCRIPTION es la descripción opcional del repositorio upstream.
LOCATION es la ubicación del repositorio virtual.
REPOSITORY_ID es el ID del repositorio virtual.
DESCRIPTION es la descripción opcional para el repositorio virtual. No incluyas datos sensibles, ya que las descripciones del repositorio no están encriptadas.
KEY es el nombre de la clave de Cloud Key Management Service, si usas claves de encriptación administradas por el cliente (CMEK) para la encriptación. Omite este argumento para usar la configuración predeterminada, las claves de encriptación administradas por Google.
PRIORITY es el valor de prioridad opcional. La prioridad más alta es 1. Las entradas con un valor de prioridad mayor tienen prioridad en el orden de extracción.

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
    }
  }
}

¿Por dónde

PROJECT-ID es el ID del proyecto de Google Cloud.
UPSTREAM_LOCATION es la ubicación del repositorio upstream. Ten en cuenta que el repositorio virtual y el upstream deben estar en la misma región o multirregión.
UPSTREAM_REPOSITORY_ID es el ID del repositorio upstream.
UPSTREAM_REPOSITORY_DESCRIPTION es la descripción opcional del repositorio upstream.
LOCATION es la ubicación del repositorio virtual.
REPOSITORY_ID es el ID del repositorio virtual.
DESCRIPTION es la descripción opcional para el repositorio virtual. No incluyas datos sensibles, ya que las descripciones del repositorio no están encriptadas.
KEY es el nombre de la clave de Cloud Key Management Service, si usas claves de encriptación administradas por el cliente (CMEK) para la encriptación. Omite este argumento para usar la configuración predeterminada, las claves de encriptación administradas por Google.
PRIORITY es el valor de prioridad opcional. La prioridad más alta es 1. Las entradas con un valor de prioridad mayor tienen prioridad en el orden de extracción.

Artifact Registry crea el repositorio. Ejecuta el siguiente comando para ver una descripción del repositorio:

gcloud artifacts repositories describe REPOSITORY \
    --location=LOCATION

Después de crear el repositorio, sigue estos pasos:

Otorga acceso al repositorio.
Configura Docker, los administradores de paquetes y otros clientes de terceros para autenticarse en los repositorios.
- Imágenes de contenedor: Docker, Helm
- Paquetes de lenguajes: Java, Node.js, Python y Go
- Paquetes de SO: Debian, RPM
- Otro: Plantillas de canalizaciones de Kubeflow

Actualiza los repositorios upstream

Puedes cambiar la lista de repositorios ascendentes o ajustar la prioridad de los repositorios ascendentes.

Consola

Abre la página Repositorios en la consola de Google Cloud.

Abrir la página Repositorios
En la lista de repositorios, selecciona el repositorio virtual y haz clic en Editar repositorio.
En la lista upstream del repositorio virtual, realiza los cambios necesarios. Puedes agregar y quitar repositorios o cambiar la prioridad de los repositorios de la lista.
Haz clic en Guardar.

gcloud

Edita tu archivo de políticas ascendentes con tus cambios. Por ejemplo, es posible que desees agregar un repositorio upstream o ajustar la configuración de prioridad.

Si deseas quitar todos los repositorios upstream, tu archivo de políticas debe contener un conjunto vacío de repositorios.
```
[]
```
Ejecuta el siguiente comando para aplicar los cambios al repositorio virtual.
```
gcloud artifacts repositories update REPOSITORY \
    --upstream-policy-file=UPSTREAM_POLICY_FILE
```
Reemplaza UPSTREAM_POLICY_FILE por la ruta de acceso al archivo de política ascendente.

Para obtener más información sobre el comando, consulta la documentación de referencia de gcloud artifacts repositorios update.

Edita las descripciones del repositorio

Puedes cambiar la descripción del repositorio desde la consola de Google Cloud o la gcloud CLI.

Consola

Abre la página Repositorios en la consola de Google Cloud.

Abrir la página Repositorios
En la lista de repositorios, selecciona el repositorio y haz clic en Editar repositorio.
Edita la descripción del repositorio y haz clic en Guardar.

gcloud

Para actualizar la descripción del repositorio, ejecuta el siguiente comando:

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

Reemplaza los siguientes valores:

REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
PROJECT es el ID del proyecto de Google Cloud. Si se omite esta marca, se usa el proyecto actual o predeterminado.
LOCATION es una ubicación regional o multirregional. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.
DESCRIPTION es una descripción del repositorio.