Crie 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 transferir, instalar ou implementar artefactos no mesmo formato a partir de um ou mais repositórios a montante. Um repositório a montante 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 predefinido. Carregar ou publicar artefactos, como pacotes privados, diretamente em repositórios padrão. Embora possa fazer a transferência diretamente de repositórios padrão individuais, o acesso a grupos de repositórios com um repositório virtual simplifica a configuração das ferramentas.
• Remoto (apenas repositórios de pacotes de idiomas): uma cache de obtenção para artefactos em repositórios públicos, como o Maven Central ou o PyPI. Funciona como um proxy para os repositórios públicos, para que tenha mais controlo sobre as suas dependências externas.

Para mais informações sobre o funcionamento dos repositórios virtuais, consulte a Vista 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 CLI Google Cloud.

Funções necessárias

Para receber as autorizações de que precisa para gerir repositórios, peça ao seu administrador que lhe conceda as seguintes funções de IAM:

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

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Se os repositórios upstream estiverem noutros projetos, um administrador nos projetos com repositórios upstream tem de ter autorizações para gerir o acesso a esses repositórios.

Crie repositórios upstream

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

1. Crie os repositórios upstream na mesma Google Cloud região onde planeia criar o repositório virtual.

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

2. Os repositórios virtuais usam o agente de serviço do Artifact Registry para fazer a autenticação em repositórios a montante. Tem de conceder ao agente de serviço acesso de leitura aos repositórios upstream.

   Pode conceder a função Leitor do Artifact Registry ao agente de serviço do Artifact Registry ao nível do projeto para não ter de 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 com o repositório a montante. Google Cloud
   • VIRTUAL_REPO_PROJECT_NUMBER é o número do projeto do Google Cloud projeto do seu repositório virtual.

   Em alternativa, se quiser conceder uma função com um âmbito mais restrito ao agente do serviço, adicione a autorização artifactregistry.repositories.readViaVirtualRepository a uma função personalizada e, em seguida, conceda essa função ao agente do serviço.

   Para mais informações sobre a concessão de autorizações, consulte a documentação sobre o controlo de acesso.

Crie um repositório virtual

Quando cria um repositório, tem de configurar as seguintes definições que não podem ser alteradas após a criação do repositório:

• Formato do artefacto.
• Modo de repositório, se estiverem disponíveis vários modos para o formato selecionado.
• Localização do repositório.
• Encriptação com chaves de encriptação , pertencentes à Google e baseadas no Google Cloud, ou chaves de encriptação geridas pelo cliente. O Artifact Registry usa chaves de encriptação pertencentes e geridas pela Google por predefinição.

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

Crie um repositório virtual através da consola Google Cloud

1. Abra a página Repositórios na Google Cloud consola.

   Abra a página Repositórios

2. Clique em Criar repositório.

3. Especifique o nome do repositório. Para cada localização do repositório num projeto, os nomes dos repositórios têm de ser exclusivos.

4. Selecione o formato do repositório.

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

6. Em Virtual Repository Upstreams, clique em Add Upstream para adicionar um repositório upstream.

   • Um repositório a montante pode ser um repositório padrão, remoto ou virtual.
   • Um repositório a montante tem de estar na mesma localização que o repositório virtual, mas pode estar num Google Cloud projeto diferente.
   • Um repositório a montante tem de ter o mesmo formato de artefacto que o repositório virtual.

   Especifique uma prioridade e um nome de política para cada repositório a montante. Os valores de prioridade mais elevados 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 a montante com prioridades que estejam entre os valores existentes.

7. Em Tipo de localização, escolha a localização do repositório:

   1. Escolha o tipo de localização: região ou várias regiões. A lista de localizações é alterada para refletir a sua seleção.

   2. Na lista Região ou Várias regiões, selecione uma localização.

   Para obter informações sobre os tipos de localizações e as localizações suportadas, consulte o artigo Localizações de repositórios

8. Adicione uma descrição para o repositório. As descrições ajudam a identificar a finalidade do repositório e o tipo de artefactos que contém.

   Não inclua dados confidenciais, uma vez que as descrições dos repositórios não são encriptadas.

9. Se quiser usar etiquetas para organizar os seus repositórios, clique em Adicionar etiqueta e introduza o par de chave-valor para a etiqueta. Pode adicionar, editar ou remover etiquetas depois de criar o repositório.

10. Na secção Encriptação, escolha o mecanismo de encriptação para o repositório.

    • Google-managed encryption key - Encriptar o conteúdo do repositório com um Google-owned and Google-managed encryption key.
    • Chave gerida pelo cliente: encriptar o conteúdo do repositório com uma chave que controla através do Cloud Key Management Service. Para ver instruções de configuração de chaves, consulte o artigo Configurar CMEK para repositórios.

11. Clique em Criar.

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

Depois de criar o repositório:

• Conceda acesso ao repositório.

• Configure o Docker, os gestores de pacotes e outros clientes de terceiros para se autenticarem em repositórios.

  • Imagens de contentores: Docker, Helm
  • Pacotes de idiomas: Java, Node.js, Python, Go
  • Outros: modelos de pipelines do Kubeflow

Crie um repositório virtual com a CLI gcloud

Para criar um repositório virtual, defina os seus repositórios upstream num ficheiro de políticas e, em seguida, crie o repositório através do ficheiro de políticas.

1. Crie um ficheiro de política a montante no formato JSON com as seguintes definições:

   [{
   "id" : "POLICY_ID",
   "repository" : "UPSTREAM_REPOSITORY_RESOURCE_NAME",
   "priority" : PRIORITY
   }, {...}]
   

   • POLICY_ID é um nome para a política. Cada repositório a montante na política tem de ter um ID da política exclusivo.

   • UPSTREAM_REPO_RESOURCE_NAME é o nome do repositório a montante no formato:

     projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY
     

     • Um repositório a montante pode ser um repositório padrão, remoto ou virtual.
     • Um repositório a montante tem de estar na mesma localização que o repositório virtual, mas pode estar num Google Cloud projeto diferente.
     • Um repositório a montante tem de ter o mesmo formato de artefacto que o repositório virtual.

   • PRIORITY é um número inteiro que indica a prioridade para o repositório a montante. Os valores de prioridade mais elevada têm precedência sobre os valores mais baixos.

   O exemplo seguinte mostra um ficheiro de políticas denominado policies.json com quatro repositórios a montante. upstream1 tem o valor mais elevado para priority, pelo que o Artifact Registry vai pesquisá-lo primeiro. upstream-test tem o valor priority mais baixo, pelo que o Artifact Registry vai pesquisá-lo por último. upstream2 e upstream3 têm a mesma prioridade. Se o Artifact Registry encontrar um pacote pedido em repositórios com a mesma prioridade, pode disponibilizar o pacote a partir 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. Estas lacunas oferecem flexibilidade para adicionar repositórios a montante com prioridades que se encontram entre os valores existentes. Por exemplo, pode adicionar um upstream-3repositório com uma prioridade de 70 para que o Artifact Registry o pesquise antes de upstream-test.

   Considere armazenar o ficheiro de políticas upstream no seu sistema de controlo de origem para que o possa reutilizar mais tarde para fazer alterações às definições do repositório upstream e acompanhar o histórico de alterações.

2. No diretório com o ficheiro de política a montante, 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 o seguinte:

   • VIRTUAL-REPOSITORY-NAME é o nome do repositório virtual.
   • PROJECT_ID é o ID do projeto onde está a criar o repositório virtual. Se esta flag for omitida, é usado o projeto atual ou predefinido.
   • FORMAT é o formato do repositório. Estão disponíveis os seguintes valores:
     • apt (pré-visualização privada)
     • docker
     • go
     • maven
     • npm
     • python
     • yum (pré-visualização privada)

   • LOCATION é a localização regional ou multirregional do repositório. Pode omitir esta sinalização se definir uma predefinição. Para ver uma lista de localizações suportadas, execute o comando:

     gcloud artifacts locations list
     

   • DESCRIPTION é uma descrição opcional do repositório. Não inclua dados confidenciais, uma vez que as descrições dos repositórios não são encriptadas.

   • UPSTREAM_POLICY_FILE é um caminho para o ficheiro de política a montante.

   Por exemplo, o comando seguinte cria um repositório virtual denominado virtual-repo para pacotes Python na região us-west1 com definiçõ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.

Crie um repositório virtual com o Terraform

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

Se for a primeira vez que usa o Terraform para o Google Cloud, consulte a página Introdução - Google Cloud no Website da HashiCorp.

O exemplo seguinte define o fornecedor, um repositório virtual com o nome do recurso do Terraform my-repo e um repositório a montante com o nome do recurso do 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 seu 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 gestores de pacotes e outros clientes de terceiros para se autenticarem em repositórios.

  • Imagens de contentores: Docker, Helm
  • Pacotes de idiomas: Java, Node.js, Python, Go
  • Pacotes de SO: Debian, RPM
  • Outros: modelos de pipelines do Kubeflow

Atualize os repositórios upstream

Pode alterar a lista de repositórios upstream ou ajustar a prioridade dos repositórios upstream.

Edite as descrições dos repositórios

Pode alterar a descrição do repositório a partir da Google Cloud consola ou da CLI gcloud.

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