Criar repositórios virtuais

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

Os repositórios virtuais funcionam 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 do Artifact Registry ou 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 privados, diretamente nos repositórios padrão. É possível fazer o download diretamente de repositórios padrão individuais, mas acessar grupos de repositórios com um repositório virtual simplifica a configuração de ferramentas.
  • Remoto (somente repositórios de pacotes de linguagem): uma extração por cache para artefatos em repositórios públicos, como Maven Central ou PyPI. Ele atua 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 os repositórios virtuais funcionam, consulte a Visão geral do repositório virtual.

Antes de começar

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

Funções exigidas

Para receber 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 receber as permissões necessárias com papéis personalizados ou 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 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 se autenticar em repositórios upstream. Você precisa conceder ao agente de serviço acesso de leitura para 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 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 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 ao agente de serviço um papel com escopo mais restrito, 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 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 de propriedade e gerenciadas pelo Google ou chaves de criptografia gerenciadas pelo cliente. O Artifact Registry usa chaves de propriedade e gerenciadas pelo Google por padrão.

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

Criar 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 repositório 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. 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 para adicionar repositórios upstream com prioridades que estão 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 informações sobre os tipos de locais e os 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 confidenciais, já que 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 do rótulo. É 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.

    • Chave gerenciada pelo Google: criptografe o conteúdo do repositório com uma chave de propriedade e 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 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 na 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 repositório 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 de priority, então o Artifact Registry vai fazer a pesquisa primeiro. upstream-test tem o menor valor priority, então o Artifact Registry vai fazer a pesquisa 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 repositório.

    [{
"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 estão entre os valores atuais. Por exemplo, é possível adicionar um repositório upstream-3 com prioridade 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 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 (pré-lançamento particular)
      • docker
      • maven
      • npm
      • python
      • yum (pré-lançamento 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 é 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 tem experiência 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 do 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 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, chaves de propriedade e 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 envio.

Maven

Se você não especificar uma política de versão, o Artifact Registry criará um repositório Maven que armazena versões de snapshot e de lançamento dos 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 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, chaves de propriedade e 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 envio.

Para armazenar versões de snapshot e de lançamento em diferentes repositórios, 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 pacotes de snapshot e de lançamento. Essa é a configuração padrão.
    • LANÇAMENTO: armazene somente 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 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, chaves de propriedade e 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 envio.

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 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, chaves de propriedade e 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 envio.

O Artifact Registry cria seu 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:

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

  4. Clique em Salvar.

gcloud

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

    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 gcloud artifacts repositories 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 ou multirregional local. Use esta sinalização para ver repositórios em um local específico. Se você configurou um local default, é possível omitir essa sinalização para usar o padrão.
  • DESCRIPTION: uma descrição para o repositório.