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 de um ou mais repositórios upstream. Um repositório upstream pode ser padrão do Artifact Registry ou repositório remoto.

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.
  • Remoto (somente repositórios de pacotes de linguagem): uma extração pelo cache de artefatos em repositórios públicos, como o Maven Central ou PyPI. Ele funciona como um proxy dos repositórios públicos para que você tenha mais controle sobre as dependências externas.

Para mais informações sobre como funcionam os repositórios virtuais, 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:

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

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 neles 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.

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

  2. Os repositórios virtuais usam o Agente de serviço do Artifact Registry para autenticar em repositórios upstream. Conceda ao agente de serviço acesso de leitura aos repositórios upstream.

    É possível conceder o papel Leitor do Artifact Registry ao agente de serviço do Artifact Registry no nível do projeto para que não seja necessário 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 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 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 definir as seguintes configurações, que não podem ser alteradas após a criação do repositório:

  • 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 chaves de criptografia 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.

Crie um repositório virtual usando o console do 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 Repository mode, selecione Virtual.

  6. Em Upstreams do 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 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 o nome da prioridade e da política para cada repositório upstream. Os valores de prioridade mais altos têm precedência sobre os 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.

  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 mais informações sobre tipos de locais e locais compatíveis, consulte Locais de 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, porque as descrições do repositório não são criptografadas.

  9. Se você quiser usar rótulos para organizar seus repositórios, clique em Adicionar rótulo e insira o par de chave-valor para o rótulo. Depois de criar o repositório, você poderá adicionar, editar ou remover marcadores.

  10. 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.

  11. Clique em Criar.

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

Depois de criar o repositório:

Criar um repositório virtual usando a CLI gcloud

Para criar um repositório virtual, defina os repositórios upstream em um arquivo de política e, em seguida, 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 da política precisa ter um ID de política 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 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, então o Artifact Registry vai pesquisar por ele 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
}]

    O 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 existentes. Por exemplo, é possível adicionar um repositório upstream-3 com prioridade de 70 para que o Artifact Registry pesquise nele 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 para fazer alterações nas configurações do repositório upstream e rastrear alterações 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 (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
    }
  }
}

Onde

  • 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 sensíveis, 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 pull.

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

Onde

  • 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 sensíveis, 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 pull.

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 configurações a seguir:

  • version_policy define a política de versão com um dos seguintes valores:
    • VERSION_POLICY_UNSPECIFIED: armazenar snapshots e lançar pacotes. Essa é a configuração padrão.
    • LANÇAMENTO: armazenar apenas pacotes de lançamento.
    • SNAPSHOT: armazenar somente pacotes de snapshots.
  • 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
    }
  }
}

Onde

  • 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 sensíveis, 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 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
    }
  }
}

Onde

  • 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 sensíveis, 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 pull.

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:

Atualizar repositórios upstream

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

Console

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

    Abrir a página Repositórios

  2. Na lista de repositórios, selecione o repositório virtual e clique em Editar repositório.

  3. Na lista Virtual Repository Upstream, faça as alterações necessárias. É possível adicionar e remover repositórios ou alterar a prioridade dos repositórios na lista

  4. Clique em Salvar.

gcloud

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

    Se você quiser remover todos os repositórios upstream, o arquivo de política precisará conter um conjunto vazio de repositórios.

    []

  2. 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 para o arquivo de política upstream.

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

Editar descrições do repositório

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

Console

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

    Abrir a página Repositórios

  2. Na lista de repositórios, selecione o repositório e clique em Editar repositório.

  3. 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:

  • 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 para o repositório.