Criar repositórios virtuais

Esta página descreve como criar repositórios virtuais do Artifact Registry.

Os repositórios virtuais atuam como um único ponto de acesso para fazer o download, instalar ou implantar artefatos no mesmo formato 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. Você faz upload ou publica artefatos, como pacotes particulares, diretamente em repositórios padrão. Embora seja possível fazer o download diretamente de repositórios padrão individuais, acessar grupos de repositórios com um repositório virtual simplifica a configuração da ferramenta.
• Remoto (somente repositórios de pacotes de linguagem): um cache de pull-through para artefatos em repositórios públicos, como Maven Central ou PyPI. Ele funciona como um proxy para os repositórios públicos, permitindo que você tenha mais controle sobre suas dependências externas.

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

Antes de começar

Ative o Artifact Registry, incluindo a ativação daAPI Artifact Registryy e a instalação da versão mais recente da Google Cloud CLI.

Funções exigidas

Para conseguir 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 do Artifact Registry (roles/artifactregistry.admin) no projeto Google Cloud
• Conceder acesso a repositórios no nível do projeto: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto Google Cloud
• Conceder acesso a repositórios no nível da pasta: Administrador de pastas (roles/resourcemanager.folderAdmin) na pasta
• Conceder acesso a repositórios no nível da organização: Administrador da organização (roles/resourcemanager.organizationAdmin) na organização Google Cloud

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

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

Criar repositórios upstream

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

1. Crie os repositórios upstream na mesma região Google Cloudem que você planeja criar o repositório virtual.

   • Criar um repositório padrão
   • Criar um repositório remoto

2. 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 não precisar 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
   

   Onde

   • UPSTREAM_PROJECT_ID é o ID do Google Cloud projeto com o repositório upstream.
   • VIRTUAL_REPO_PROJECT_NUMBER é o número do projeto do projeto Google Cloud para seu repositório virtual.

   Como alternativa, se você quiser conceder um papel com 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 de controle de acesso.

Criar um repositório virtual

Ao criar um repositório, é preciso configurar as seguintes opções, que não podem ser alteradas depois da 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 de criptografia do Google Cloud ou gerenciadas pelo cliente. O Artifact Registry usa chaves de criptografiacom tecnologia do Google Cloud por padrão.

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

Criar um repositório virtual usando o console Google Cloud

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

   Abrir a página Repositórios

2. Clique em Criar repositório.

3. Especifique o nome do repositório. Para cada local de repositório em um projeto, os nomes dos repositórios precisam ser exclusivos.

4. Selecione o formato do repositório.

5. Em Modo de repositório, selecione Virtual.

6. Em Upstreams de repositório virtual, clique em Adicionar upstream para adicionar um repositório upstream.

   • Um repositório upstream pode ser padrão, remoto ou virtual.
   • Um repositório upstream precisa estar no mesmo local que o repositório virtual, mas pode estar em um Google Cloud projeto diferente.
   • 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 alta têm precedência sobre valores mais baixos. Deixe espaço entre os valores de prioridade para ter flexibilidade ao adicionar repositórios upstream com prioridades intermediárias.

7. 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 local e locais compatíveis, consulte Locais do repositório.

8. 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 sensíveis, já que as descrições de repositórios não são criptografadas.

9. Se quiser usar rótulos para organizar os repositórios, clique em Adicionar rótulo e insira o par de chave-valor. É possível adicionar, editar ou remover rótulos depois de criar o repositório.

10. Na seção Criptografia, escolha o mecanismo de criptografia do repositório.

    • Google-managed encryption key: criptografa o conteúdo do repositório com um Google-owned and Google-managed encryption key.
    • 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.

11. Clique em Criar.

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

Depois de criar o repositório:

• Conceda acesso ao repositório.

• Configure o Docker, gerenciadores de pacotes e outros clientes de terceiros para autenticar em repositórios.

  • Imagens de contêiner: Docker, Helm
  • Pacotes de linguagem: Java, Node.js, Python, Go
  • Outros: modelos de pipeline do Kubeflow

Criar um repositório virtual usando CLI gcloud

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

1. 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 na 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 padrão, remoto ou virtual.
     • Um repositório upstream precisa estar no mesmo local que o repositório virtual, mas pode estar em um Google Cloud projeto diferente.
     • 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 alta 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, então o Artifact Registry vai pesquisá-lo 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
   }]
   

   Este exemplo também deixa espaço entre os valores de prioridade. Essas lacunas oferecem flexibilidade para adicionar repositórios upstream com prioridades que estão entre os valores atuais. Por exemplo, você pode adicionar um repositório upstream-3 com uma 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 reutilizá-lo depois e fazer mudanças nas configurações do repositório upstream e rastrear mudanças históricas.

2. 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 (prévia particular)
     • docker
     • go
     • maven
     • npm
     • python
     • yum (prévia 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, já que as descrições do repositório não são criptografadas.

   • UPSTREAM_POLICY_FILE é o 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. A versão 5.0.0 ou mais recente do terraform-provider-google é obrigatória.

Se você não usa 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 do recurso Terraform my-repo e um repositório upstream com o nome do recurso Terraform my-repo-upstream.

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

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

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

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

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

O Artifact Registry cria o repositório. Execute o comando a seguir 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, gerenciadores de pacotes e outros clientes de terceiros para autenticar em repositórios.

  • Imagens de contêineres: Docker, Helm
  • Pacotes de idioma: Java, Node.js, Python, Go
  • Pacotes do SO: Debian, RPM
  • Outros: Modelos de pipeline do Kubeflow

Atualizar repositórios upstream

É possível mudar a lista de repositórios upstream ou ajustar a prioridade deles.

Editar descrições de repositório

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

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