Criar repositórios virtuais

Nesta página, descrevemos como criar repositórios.

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

Os outros modos de repositório são:

  • Padrão: o modo de repositório padrão. Você envia ou publica artefatos como pacotes privados diretamente nos repositórios padrão. É possível fazer o download diretamente de repositórios padrão individuais, o acesso a grupos de repositórios com um repositório virtual simplifica configuração da ferramenta.
  • Remoto (somente repositórios de pacotes de linguagem): um cache de pull para artefatos em repositórios públicos, como Maven Central ou PyPI. Ele atua como um proxy para os repositórios públicos, para 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 do repositório virtual.

Antes de começar

Ative o Artifact Registry, incluindo ativar a API Artifact Registry e instalando a 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 do Google Cloud
  • Conceda acesso a repositórios no nível do projeto: Administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto do Google Cloud
  • Conceda 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 do 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 esses repositórios.

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 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 nos repositórios upstream. É necessário conceder 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 projeto para não precisar conceder acesso a recursos upstream repositórios.

    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 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 de controle de acesso.

Criar um repositório virtual

Ao criar um repositório, é preciso definir as seguintes configurações que não pode ser alterado 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 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íticas da organização que precisam da CMEK para criptografar recursos ou limitar 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 repositório de dados.

    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 de adição repositórios upstream com prioridades que estão entre os valores existentes.

  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, pois as descrições do repositório são e não criptografados.

  9. 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 de dados.

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

  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 upstream repositório na política precisa ter um ID de política exclusivo.

    • UPSTREAM_REPO_RESOURCE_NAME é o nome do upstream repositório 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 repositório de dados.

    • PRIORITY é um número inteiro que indica prioridade do repositório upstream. Prioridade mais alta têm precedência sobre valores menores.

    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 o menor valor de 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á fornecer 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 estão em entre os valores existentes. Por exemplo, é possível 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 que ele possa ser reutilizado posteriormente para fazer alterações nas configurações do repositório upstream e acompanhar as 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 servidor repositório de dados.
    • 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. O seguinte estão disponíveis:
      • apt (pré-lançamento particular)
      • docker
      • maven
      • npm
      • python
      • yum (pré-lançamento privado)

    • 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 a 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 terraform-provider-google 5.0.0 ou mais recente é obrigatória.

Se você não usa o Terraform para o 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 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. Observe que o o repositório virtual e o upstream precisam estar na mesma região ou multirregional.
  • 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 para o servidor repositório de dados. Não inclua dados sensíveis, já que 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. Omit 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 no pull ordem.

Maven

Se você não especificar uma política de versão, o Artifact Registry vai criar um repositório Maven que armazena 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. Observe que o o repositório virtual e o upstream precisam estar na mesma região ou multirregional.
  • 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 para o servidor repositório de dados. Não inclua dados sensíveis, porque as descrições do repositório não são criptografados.
  • 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 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 no pull ordem.

Armazenar versões de snapshot e de lançamento em diferentes os repositórios, especifique uma política de versão para os repositório usando um bloco maven_config. Esse bloco oferece suporte às seguintes configurações:

  • version_policy define a política de versão com um dos seguintes valores:
    • VERSION_POLICY_UNSPECIFIED: armazenar pacotes de snapshot e de lançamento. Essa é a configuração padrão.
    • LANÇAMENTO: armazene somente pacotes de lançamento.
    • SNAPSHOT: armazenar apenas 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 versões existentes no repositório.

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

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. Observe que o o repositório virtual e o upstream precisam estar na mesma região ou multirregional.
  • 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 para o servidor repositório de dados. Não inclua dados sensíveis, já que 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. Omit 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. As 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
    }
  }
}

Onde

  • PROJECT-ID é o ID do projeto do Google Cloud;
  • UPSTREAM_LOCATION é o local do repositório upstream. Observe que o o repositório virtual e o upstream precisam estar na mesma região ou multirregional.
  • 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 para o servidor repositório de dados. Não inclua dados sensíveis, porque as descrições do repositório não são criptografados.
  • 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. Omit 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 no pull ordem.

O Artifact Registry cria seu repositório. Execute o comando a seguir para conferir 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 de em 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 Edit Repository.

  3. Na lista Virtual Repository Upstream, faça as mudanças necessárias. É possível adicionar e remover repositórios ou alterar a prioridade de 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ê 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 precisa 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 de repositórios

É possível mudar 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 regional ou multirregional local. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.
  • DESCRIPTION: uma descrição para o repositório.