Criar repositórios virtuais

Nesta página, descrevemos como criar repositórios virtuais do Artifact Registry.

Os repositórios virtuais funcionam como um ponto de acesso único para fazer o download, instalar ou implantar artefatos no mesmo formato a partir de um ou mais repositórios upstream. Um repositório upstream pode ser um repositório padrão ou remoto do Artifact Registry.

Os outros modos de repositório são:

Padrão: o modo de repositório padrão. Faça upload ou publique artefatos, como pacotes particulares, diretamente em repositórios padrão. É possível fazer o download diretamente de repositórios padrão individuais, mas o acesso a grupos de repositórios com um repositório virtual simplifica a configuração da ferramenta.
Remote (somente repositórios de pacotes de linguagem): uma extração por cache para artefatos em repositórios públicos, como o Maven Central ou o PyPI. Ele atua como um proxy para os repositórios públicos, para que você tenha mais controle sobre as dependências externas.

Para mais informações sobre como os repositórios virtuais funcionam, consulte a Visão geral do repositório virtual.

Antes de começar

Ativar o Artifact Registry, incluindo ativar a API Artifact Registry e instalar a versão mais recente da Google Cloud CLI.

Funções exigidas

Para ter as permissões necessárias para gerenciar repositórios, peça ao administrador para conceder a você os seguintes papéis do IAM:

Crie repositórios virtuais e conceda acesso a repositórios individuais: Administrador de repositórios do Artifact Registry (roles/artifactregistry.repoAdmin) no projeto do Google Cloud
Conceda acesso aos repositórios no nível do projeto: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto do Google Cloud
Conceda acesso aos repositórios no nível da pasta: Administrador de pasta (roles/resourcemanager.folderAdmin) na pasta
Conceder acesso aos repositórios no nível da organização: Administrador da organização (roles/resourcemanager.organizationAdmin) na organização do Google Cloud

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Talvez você também consiga receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Se os repositórios upstream estiverem em outros projetos, um administrador dos projetos com repositórios upstream precisará ter permissões para gerenciar o acesso a esses repositórios.

Criar repositórios upstream

Antes de configurar um repositório virtual, crie os repositórios upstream que você quer disponibilizar com o repositório virtual.

Crie os repositórios upstream na mesma região do Google Cloud em que planeja criar o repositório virtual.
- Crie um repositório padrão
- Criar um repositório remoto
Os repositórios virtuais usam o agente de serviço do Artifact Registry para autenticar em repositórios upstream. Você precisa conceder ao agente de serviço acesso de leitura aos repositórios upstream.

É possível conceder o papel de leitor do Artifact Registry ao agente de serviço do Artifact Registry no nível do projeto para que você não precise conceder acesso a repositórios upstream individuais.

Em cada projeto com repositórios upstream, execute o seguinte 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
- UPSTREAM_PROJECT_ID é o ID do projeto do Google Cloud com o repositório upstream.
- VIRTUAL_REPO_PROJECT_NUMBER é o número do projeto do Google Cloud para seu repositório virtual.
Como alternativa, se você quiser conceder um papel de escopo mais restrito ao agente de serviço, adicione a permissão artifactregistry.repositories.readViaVirtualRepository a um papel personalizado e conceda esse papel ao agente de serviço.

Para mais informações sobre como conceder permissões, consulte a documentação sobre controle de acesso.

Criar um repositório virtual

Ao criar um repositório, é preciso definir as configurações a seguir que não poderão ser alteradas após a criação:

Formato do artefato.
Modo de repositório, se vários modos estiverem disponíveis para o formato selecionado.
Local do repositório.
criptografia com chaves gerenciadas pelo Google ou gerenciadas pelo cliente; O Artifact Registry usa chaves de criptografia gerenciadas pelo Google por padrão.

O Artifact Registry aplica restrições da política da organização que exigem que a CMEK criptografe recursos ou limite quais chaves do Cloud KMS podem ser usadas para proteção de CMEK.

Criar um repositório virtual usando o console do Google Cloud

Abra a página Repositórios no console do Google Cloud.

Abrir a página Repositórios
Clique em Criar repositório.
Especifique o nome do repositório. Para cada local de repositório em um projeto, os nomes dos repositórios precisam ser exclusivos.
Selecione o formato do repositório.
Em Repository mode, selecione Virtual.
Em Upstreams de repositório virtual, clique em Adicionar upstream para adicionar um repositório upstream.
- Um repositório upstream pode ser um repositório padrão, remoto ou virtual.
- Um repositório upstream precisa estar no mesmo local que o virtual, mas pode estar em um projeto diferente do Google Cloud.
- Um repositório upstream precisa ter o mesmo formato de artefato que o repositório virtual.
Especifique uma prioridade e um nome de política para cada repositório upstream. Valores de prioridade mais altos têm precedência sobre valores mais baixos. Deixe espaço entre os valores de prioridade para que haja flexibilidade de adicionar repositórios upstream com prioridades que estejam entre os valores atuais.
Em Tipo de local, escolha o local do repositório:
1. Escolha o tipo de local: Região ou multirregião. A lista de locais muda para refletir a seleção.
2. Na lista Região ou Multirregião, selecione um local.
Para informações sobre tipos de locais e locais compatíveis, consulte Locais de repositório.
Adicione uma descrição para o repositório. As descrições ajudam a identificar a finalidade do repositório e o tipo de artefatos que ele contém.

Não inclua dados confidenciais, porque as descrições do repositório não são criptografadas.
Se você quiser usar rótulos para organizar os repositórios, clique em Adicionar rótulo e insira o par de chave-valor para o rótulo. É possível adicionar, editar ou remover rótulos depois de criar o repositório.
Na seção Criptografia, escolha o mecanismo de criptografia do repositório.
- Chave gerenciada pelo Google: criptografe o conteúdo do repositório com uma chave de criptografia gerenciada pelo Google.
- Chave gerenciada pelo cliente: criptografe o conteúdo do repositório com uma chave controlada por você por meio do Cloud Key Management Service. Para instruções de configuração de chaves, consulte Como configurar CMEK para repositórios.
Clique em Criar.

O Artifact Registry cria e adiciona o repositório à lista de repositórios.

Depois de criar o repositório:

Conceda acesso ao repositório.
Configure o Docker, os gerenciadores de pacotes e outros clientes de terceiros para autenticação em repositórios.
- Imagens de contêiner: Docker, Helm
- Pacotes de linguagem: Java, Node.js, Python e Go
- Outro: Modelos do Kubeflow Pipelines

Criar um repositório virtual usando a CLI gcloud

Para criar um repositório virtual, defina seus repositórios upstream em um arquivo de política e, em seguida, crie o repositório usando esse arquivo.

Crie um arquivo de política upstream no formato JSON com as seguintes configurações:
```
[{
"id" : "POLICY_ID",
"repository" : "UPSTREAM_REPOSITORY_RESOURCE_NAME",
"priority" : PRIORITY
}, {...}]
```
- POLICY_ID é um nome para a política. Cada repositório upstream da política precisa ter um ID exclusivo.
- UPSTREAM_REPO_RESOURCE_NAME é o nome do repositório upstream no formato:
```
projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY
```
  - Um repositório upstream pode ser um repositório padrão, remoto ou virtual.
  - Um repositório upstream precisa estar no mesmo local que o virtual, mas pode estar em um projeto diferente do Google Cloud.
  - Um repositório upstream precisa ter o mesmo formato de artefato que o repositório virtual.
- PRIORITY é um número inteiro que indica a prioridade do repositório upstream. Valores de prioridade mais altos têm precedência sobre valores mais baixos.
O exemplo a seguir mostra um arquivo de política chamado policies.json com quatro repositórios upstream. upstream1 tem o valor mais alto para priority, então o Artifact Registry vai pesquisar primeiro. upstream-test tem o menor valor de priority, portanto, o Artifact Registry vai pesquisar por último. upstream2 e upstream3 têm a mesma prioridade. Se o Artifact Registry encontrar um pacote solicitado em repositórios com a mesma prioridade, ele poderá disponibilizar o pacote de qualquer um dos repositórios.
```
[{
"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
}]
```
Esse exemplo também deixa espaço entre os valores de prioridade. Essas lacunas oferecem flexibilidade para adicionar repositórios upstream com prioridades que estejam entre os valores atuais. Por exemplo, é possível adicionar um repositório upstream-3 com prioridade de 70 para que o Artifact Registry o pesquise antes de upstream-test.

Considere armazenar o arquivo de política upstream no sistema de controle de origem para que possa reutilizá-lo mais tarde e fazer alterações nas configurações do repositório upstream e rastrear alterações históricas.
No diretório com o arquivo de política upstream, execute o seguinte comando para criar o repositório 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
```
Substitua:
- VIRTUAL-REPOSITORY-NAME é o nome do repositório virtual.
- PROJECT_ID é o ID do projeto em que você está criando o repositório virtual. Se essa sinalização for omitida, o projeto atual ou padrão será usado.
- FORMAT é o formato do repositório. Os seguintes valores estão disponíveis:
  - apt (visualização particular)
  - docker
  - maven
  - npm
  - python
  - yum (visualização particular)
- LOCATION é o local regional ou multirregional do repositório. É possível omitir essa sinalização se você definir um padrão. Para ver uma lista de locais compatíveis, execute o comando:
```
gcloud artifacts locations list
```
- DESCRIPTION é uma descrição opcional do repositório. Não inclua dados sensíveis, porque as descrições do repositório não são criptografadas.
- UPSTREAM_POLICY_FILE é um caminho para o arquivo de política upstream.
Por exemplo, o comando a seguir cria um repositório virtual chamado virtual-repo para pacotes Python na região us-west1 com configurações em 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
```

O Artifact Registry cria o repositório virtual.

Criar um repositório virtual usando o Terraform

Use o recurso google_artifact_registry_repository para criar repositórios. É necessário ter a versão 5.0.0 ou mais recente do terraform-provider-google.

Se você não está familiarizado com o Terraform para Google Cloud, consulte a página Primeiros passos - Google Cloud no site da HashiCorp.

O exemplo a seguir define o provedor, um repositório virtual com o nome de recurso do Terraform my-repo e um repositório upstream com o nome de recurso do 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

PROJECT-ID é o ID do projeto do Google Cloud;
UPSTREAM_LOCATION é o local do repositório upstream. O repositório virtual e o upstream precisam estar na mesma região ou multirregião.
UPSTREAM_REPOSITORY_ID é o ID do repositório upstream.
UPSTREAM_REPOSITORY_DESCRIPTION é a descrição opcional do repositório upstream.
LOCATION é o local do repositório virtual.
REPOSITORY_ID é o ID do repositório virtual.
DESCRIPTION é a descrição opcional do repositório virtual. Não inclua dados confidenciais, porque as descrições do repositório não são criptografadas.
KEY é o nome da chave do Cloud Key Management Service, se você estiver usando chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) para criptografia. Omita esse argumento para usar a configuração padrão, as chaves de criptografia gerenciadas pelo Google.
PRIORITY é o valor de prioridade opcional. A prioridade mais alta é 1. Entradas com um valor de prioridade maior têm precedência na ordem de extração.

Maven

Se uma política de versão não for especificada, o Artifact Registry criará um repositório Maven que armazena as versões de snapshot e de lançamento de pacotes por padrão.

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

PROJECT-ID é o ID do projeto do Google Cloud;
UPSTREAM_LOCATION é o local do repositório upstream. O repositório virtual e o upstream precisam estar na mesma região ou multirregião.
UPSTREAM_REPOSITORY_ID é o ID do repositório upstream.
UPSTREAM_REPOSITORY_DESCRIPTION é a descrição opcional do repositório upstream.
LOCATION é o local do repositório virtual.
REPOSITORY_ID é o ID do repositório virtual.
DESCRIPTION é a descrição opcional do repositório virtual. Não inclua dados confidenciais, porque as descrições do repositório não são criptografadas.
KEY é o nome da chave do Cloud Key Management Service, se você estiver usando chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) para criptografia. Omita esse argumento para usar a configuração padrão, as chaves de criptografia gerenciadas pelo Google.
PRIORITY é o valor de prioridade opcional. A prioridade mais alta é 1. Entradas com um valor de prioridade maior têm precedência na ordem de extração.

Para armazenar versões de snapshot e de lançamento em repositórios diferentes, especifique uma política de versão para o repositório usando um bloco maven_config. Esse bloco é compatível com as seguintes configurações:

version_policy define a política de versão com um destes valores:
- VERSION_POLICY_UNSPECIFIED: armazena snapshots e pacotes de lançamento. Essa é a configuração padrão.
- LANÇAMENTO: somente pacotes de lançamento na loja.
- SNAPSHOT: armazenar apenas pacotes de snapshot.
allow_snapshot_overwrites configura um repositório com uma política de versão SNAPSHOT para aceitar snapshots não exclusivos que substituem as versões atuais no repositório.

O exemplo a seguir define um repositório Maven com uma política de versão de lançamento.

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

PROJECT-ID é o ID do projeto do Google Cloud;
UPSTREAM_LOCATION é o local do repositório upstream. O repositório virtual e o upstream precisam estar na mesma região ou multirregião.
UPSTREAM_REPOSITORY_ID é o ID do repositório upstream.
UPSTREAM_REPOSITORY_DESCRIPTION é a descrição opcional do repositório upstream.
LOCATION é o local do repositório virtual.
REPOSITORY_ID é o ID do repositório virtual.
DESCRIPTION é a descrição opcional do repositório virtual. Não inclua dados confidenciais, porque as descrições do repositório não são criptografadas.
KEY é o nome da chave do Cloud Key Management Service, se você estiver usando chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) para criptografia. Omita esse argumento para usar a configuração padrão, as chaves de criptografia gerenciadas pelo Google.
PRIORITY é o valor de prioridade opcional. A prioridade mais alta é 1. Entradas com um valor de prioridade maior têm precedência na ordem de extração.

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

PROJECT-ID é o ID do projeto do Google Cloud;
UPSTREAM_LOCATION é o local do repositório upstream. O repositório virtual e o upstream precisam estar na mesma região ou multirregião.
UPSTREAM_REPOSITORY_ID é o ID do repositório upstream.
UPSTREAM_REPOSITORY_DESCRIPTION é a descrição opcional do repositório upstream.
LOCATION é o local do repositório virtual.
REPOSITORY_ID é o ID do repositório virtual.
DESCRIPTION é a descrição opcional do repositório virtual. Não inclua dados confidenciais, porque as descrições do repositório não são criptografadas.
KEY é o nome da chave do Cloud Key Management Service, se você estiver usando chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) para criptografia. Omita esse argumento para usar a configuração padrão, as chaves de criptografia gerenciadas pelo Google.
PRIORITY é o valor de prioridade opcional. A prioridade mais alta é 1. Entradas com um valor de prioridade maior têm precedência na ordem de extração.

O Artifact Registry cria o repositório. Execute o seguinte comando para ver uma descrição do repositório:

gcloud artifacts repositories describe REPOSITORY \
    --location=LOCATION

Depois de criar o repositório:

Conceda acesso ao repositório.
Configure o Docker, os gerenciadores de pacotes e outros clientes de terceiros para autenticação em repositórios.
- Imagens de contêiner: Docker, Helm
- Pacotes de linguagem: Java, Node.js, Python, Go
- Pacotes do SO: Debian, RPM
- Outro: modelos do Kubeflow Pipeline

Atualizar repositórios upstream

É possível alterar a lista de repositórios upstream ou ajustar a prioridade dos repositórios upstream.

Console

Abra a página Repositórios no console do Google Cloud.

Abrir a página Repositórios
Na lista de repositórios, selecione o repositório virtual e clique em Editar repositório.
Na lista Upstream do repositório virtual, faça as alterações necessárias. É possível adicionar e remover repositórios ou alterar a prioridade dos repositórios na lista
Clique em Save.

gcloud

Edite o arquivo de política upstream com as mudanças. Por exemplo, talvez você queira adicionar um repositório upstream ou ajustar as configurações de prioridade.

Para remover todos os repositórios upstream, o arquivo de política precisa conter um conjunto vazio de repositórios.
```
[]
```
Execute o comando a seguir para aplicar as alterações ao repositório virtual.
```
gcloud artifacts repositories update REPOSITORY \
    --upstream-policy-file=UPSTREAM_POLICY_FILE
```
Substitua UPSTREAM_POLICY_FILE pelo caminho do arquivo de política upstream.

Para mais informações sobre o comando, consulte a documentação de referência de gcloudartifact datasets update.

Editar descrições de repositório

É possível alterar a descrição do repositório no console do Google Cloud ou na CLI gcloud.

Console

Abra a página Repositórios no console do Google Cloud.

Abrir a página Repositórios
Na lista de repositórios, selecione o repositório e clique em Editar repositório.
Edite a descrição do repositório e clique em Salvar.

gcloud

Para atualizar a descrição do repositório, execute o comando:

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

Substitua os seguintes valores:

REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, será possível omitir essa sinalização para usar o padrão.
PROJECT é o ID do projeto do Google Cloud; Se essa sinalização for omitida, o projeto atual ou padrão será usado.
LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
DESCRIPTION é uma descrição do repositório.