Create remote repositories

This page describes setting up and using an Artifact Registry remote repository, a repository that acts as a caching proxy for an external public artifact repository.

Before you begin

Install and initialize Google Cloud CLI. For an existing installation, update components of the Google Cloud CLI with the command:
```
gcloud components update
```
To check your version of the gcloud CLI, run the command:
```
gcloud version
```
Enable the Artifact Registry API if it is not already enabled. Replace PROJECT_ID with your Google Cloud project ID.
```
gcloud services enable artifactregistry.googleapis.com \
    --project=PROJECT_ID
```
If Artifact Registry is in a VPC Service Controls service perimeter, enable the Access Context Manager API if it is not already enabled.
```
gcloud services enable accesscontextmanager.googleapis.com \
    --project=PROJECT_ID
```

Required roles

To get the permissions that you need to manage repositories, ask your administrator to grant you the following IAM roles:

Create remote repositories and grant access to individual repositories: Artifact Registry Administrator (roles/artifactregistry.admin) on the project
Grant access to upstream sources outside a VPC Service Controls service perimeter: Access Context Manager Editor (roles/accesscontextmanager.policyEditor) on the project, folder, or organization where the access policy is applied

For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

Overview

A remote repository is a type of repository that stores artifacts from external sources such as Docker Hub or PyPI. It acts as a proxy for the external source so that you have more control over your external dependencies. The first time that you request a version of a package, Artifact Registry downloads and caches the package in the remote repository. The next time you request the same package version, Artifact Registry serves the cached copy.

The other repository modes are:

Standard: The default repository mode. You upload or publish artifacts such as private packages directly to standard repositories. Although you can download directly from individual standard repositories, accessing groups of repositories with a virtual repository simplifies tool configuration.
Virtual: A repository that acts as a single access point for multiple upstream repositories, including remote and standard repositories.

Remote repositories provide several benefits:

Faster, more reliable access to artifacts

Storing cached copies of your public dependencies in Artifact Registry reduces latency when other Google Cloud services retrieve images. Cached artifacts are also still available if the external public repository is offline due to an outage or other issue.

Safer dependency resolution

Use remote repositories together with virtual repositories to mitigate risks associated with public dependencies. Some tools do not provide a way to control search order when a mix of private and public repositories are configured in the client. This type of configuration is vulnerable to a dependency confusion attack, where someone uploads a new version of a package with bad code to a public repository to trick clients into choosing the bad version.

Instead of configuring clients directly to search multiple repositories, you can configure virtual repositories to prioritize your private repositories over remote repositories.

If Artifact Registry is in a VPC Service Controls service perimeter, Artifact Registry denies access to upstream sources outside the perimeter by default. To allow remote repositories in a specific location to access their configured external sources outside the perimeter, see the instructions for VPC Service Controls configuration.

To learn about other dependency management best practices, see Dependency management.

Updates to package indexes and metadata

Mutable artifacts such as package indexes and metadata are updated from the upstream source when they become more than 72 hours old.

Supported formats

You can create remote repositories for the following Artifact Registry repository formats and corresponding upstream source:

Docker: For public images in Docker Hub.
Maven: For public packages in Maven Central.
npm: For public packages in the npm registry.
Python: for public packages in the Python Package Index (PyPI).

During Preview, other upstream sources are not supported.

The setup process is similar to setting up a standard repository.

Create a remote repository

When you create a repository, you must configure the following settings that cannot be changed after the repository is created:

Artifact format.
Repository mode, if multiple modes are available for the selected format.
Repository location.
Encryption with Google-managed keys or customer-managed encryption keys. Artifact Registry uses Google-managed encryption keys by default.

Artifact Registry enforces organization policy constraints that require CMEK to encrypt resources or limit which Cloud KMS keys can be used for CMEK protection.

Create a remote repository using Google Cloud console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
Click Create Repository.
Specify the repository name. For each repository location in a project, repository names must be unique.
Select the repository format.
Under Repository mode, select Remote.
Under Location Type, choose the location for the repository:
1. Choose the location type: Region or Multi-Region. The list of locations changes to reflect your selection.
2. In the Region or Multi-region list, select a location.
For information about location types and supported locations, see Repository locations
Add a description for the repository. Descriptions help to identify the purpose of the repository and the kind of artifacts it contains.

Do not include sensitive data, since repository descriptions are not encrypted.
If you want to use labels to organize your repositories, click Add Label and enter the key-value pair for the label. You can add, edit, or remove labels after you create the repository.
In the Encryption section, choose the encryption mechanism for the repository.
- Google-managed key - Encrypt repository content with a Google-managed encryption key.
- Customer-managed key - Encrypt repository content with a key that you control through Cloud Key Management Service. For key setup instructions, see Setting up CMEK for repositories.
Click Create.

Artifact Registry creates the repository and adds it to the list of repositories.

After you have created the repository:

Grant access to the repository.
Configure Docker, package managers, and other third-party clients to authenticate to repositories.
- Container images: Docker, Helm
- Language packages: Java, Node.js, Python
- OS packages: Debian, RPM
- Other: Kubeflow Pipeline templates

Create a remote repository using gcloud CLI

To create a repository, run the command for the appropriate repository format:

Docker

gcloud artifacts repositories create REMOTE-REPOSITORY-NAME \
    --project=PROJECT_ID \
    --repository-format=docker \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --mode=remote-repository \
    --remote-repo-config-desc="REMOTE-REPOSITORY-DESCRIPTION" \
    --remote-docker-repo=DOCKER-HUB

Replace the following:

REMOTE-REPOSITORY-NAME is the name of the repository. For each repository location in a project, repository names must be unique.
PROJECT_ID is the project ID. If this flag is omitted, the current or default project is used.
LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command gcloud artifacts locations list.
DESCRIPTION is an optional description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.
REMOTE-REPOSITORY-DESCRIPTION is a description for the external repository configuration for this remote repository.

For example, the following command creates a remote repository named my-repo in the region us-east1 in the Google Cloud project my-project.

gcloud artifacts repositories create my-repo \
    --project=my-project \
    --repository-format=docker \
    --location=us-east1 \
    --description="Remote Docker repository" \
    --mode=remote-repository \
    --remote-repo-config-desc="Docker Hub" \
    --remote-docker-repo=DOCKER-HUB

Maven

gcloud artifacts repositories create REMOTE-REPOSITORY-NAME \
    --project=PROJECT_ID \
    --repository-format=maven \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --mode=remote-repository \
    --remote-repo-config-desc="REMOTE-REPOSITORY-DESCRIPTION" \
    --remote-mvn-repo=MAVEN-CENTRAL

Replace the following:

REMOTE-REPOSITORY-NAME is the name of the repository. For each repository location in a project, repository names must be unique.
PROJECT_ID is the project ID. If this flag is omitted, the current or default project is used.
LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command gcloud artifacts locations list.
DESCRIPTION is an optional description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.
REMOTE-REPOSITORY-DESCRIPTION is a description for the external repository configuration for this remote repository.

For example, the following command creates a remote repository named my-repo in the region us-east1 in the Google Cloud project my-project.

gcloud artifacts repositories create my-repo \
    --project=my-project \
    --repository-format=maven \
    --location=us-east1 \
    --description="Remote Maven repository" \
    --mode=remote-repository \
    --remote-repo-config-desc="Maven Central" \
    --remote-mvn-repo=MAVEN-CENTRAL

npm

gcloud artifacts repositories create REMOTE-REPOSITORY-NAME \
    --project=PROJECT_ID \
    --repository-format=npm \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --mode=remote-repository \
    --remote-repo-config-desc="REMOTE-REPOSITORY-DESCRIPTION" \
    --remote-npm-repo=NPMJS

Replace the following:

REMOTE-REPOSITORY-NAME is the name of the repository. For each repository location in a project, repository names must be unique.
PROJECT_ID is the project ID. If this flag is omitted, the current or default project is used.
LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command gcloud artifacts locations list.
DESCRIPTION is an optional description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.
REMOTE-REPOSITORY-DESCRIPTION is a description for the external repository configuration for this remote repository.

For example, the following command creates a remote repository named my-repo in the region us-east1 in the Google Cloud project my-project.

gcloud artifacts repositories create my-repo \
    --project=my-project \
    --repository-format=npm \
    --location=us-east1 \
    --description="Remote npm repository" \
    --mode=remote-repository \
    --remote-repo-config-desc="Public npm registry" \
    --remote-npm-repo=NPMJS

Python

gcloud artifacts repositories create REMOTE-REPOSITORY-NAME \
    --project=PROJECT_ID \
    --repository-format=python \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --mode=remote-repository \
    --remote-repo-config-desc="REMOTE-REPOSITORY-DESCRIPTION" \
    --remote-python-repo=PYPI

Replace the following:

REMOTE-REPOSITORY-NAME is the name of the repository. For each repository location in a project, repository names must be unique.
PROJECT_ID is the project ID. If this flag is omitted, the current or default project is used.
LOCATION is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command gcloud artifacts locations list.
DESCRIPTION is an optional description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.
REMOTE-REPOSITORY-DESCRIPTION is a description for the external repository configuration for this remote repository.

For example, the following command creates a remote repository named my-repo in the region us-east1 in the Google Cloud project my-project.

gcloud artifacts repositories create my-repo \
    --project=my-project \
    --repository-format=python \
    --location=us-east1 \
    --description="Remote Python repository" \
    --mode=remote-repository \
    --remote-repo-config-desc="PyPI" \
    --remote-python-repo=PYPI

Artifact Registry creates your repository. Run the following command to view a description of the repository:

gcloud artifacts repositories describe REMOTE-REPOSITORY-NAME \
    --location=LOCATION

Grant access to the repository.
Configure Docker, package managers, and other third-party clients to authenticate to repositories.
- Container images: Docker, Helm
- Language packages: Java, Node.js, Python
- OS packages: Debian, RPM
- Other: Kubeflow Pipeline templates

Create a remote repository using Terraform

Use the google_artifact_registry_repository resource to create repositories. terraform-provider-google version 4.61.0 or newer is required.

If you are new to using Terraform for Google Cloud, see the Get Started - Google Cloud page on the HashiCorp website.

The following example defines the provider and a remote repository with the Terraform resource name my-repo.

Docker

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "DESCRIPTION"
  format        = "docker"
  kms_key_name = "KEY"
  mode          = "REMOTE_REPOSITORY"
  remote_repository_config {
    description = "CONFIG_DESCRIPTION"
    docker_repository {
      public_repository = "DOCKER_HUB"
    }
  }
}

Where

PROJECT-ID is the Google Cloud project ID.
LOCATION is the repository location.
REPOSITORY_ID is the repository ID.
DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.
CONFIG_DESCRIPTION is the optional description of the remote source.

Maven

If you do not specify a version policy, Artifact Registry creates a Maven repository that stores both snapshot and release versions of packages by default.

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "DESCRIPTION"
  format        = "maven"
  kms_key_name = "KEY"
  mode          = "REMOTE_REPOSITORY"
  remote_repository_config {
    description = "CONFIG_DESCRIPTION"
    maven_repository {
      public_repository = "MAVEN_CENTRAL"
    }
  }
}

Where

PROJECT-ID is the Google Cloud project ID.
LOCATION is the repository location.
REPOSITORY_ID is the repository ID.
DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.
CONFIG_DESCRIPTION is the optional description of the remote source.

To store snapshot and release versions in different repositories, specify a version policy for the repository using a maven_config block. This block supports the following settings:

version_policy sets the version policy with one of the following values:
- VERSION_POLICY_UNSPECIFIED: Store snapshot and release packages. This is the default setting.
- RELEASE: Store release packages only.
- SNAPSHOT: Store snapshot packages only.
allow_snapshot_overwrites configures a repository with a SNAPSHOT version policy to accept non-unique snapshots that overwrite existing versions in the repository.

The following example defines a Maven repository with a release version policy.

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" {
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "DESCRIPTION"
  format        = "npm"
  kms_key_name = "KEY"
  mode          = "REMOTE_REPOSITORY"
  remote_repository_config {
    description = "CONFIG_DESCRIPTION"
    npm_repository {
      public_repository = "NPMJS"
    }
  }
}

Where

PROJECT-ID is the Google Cloud project ID.
LOCATION is the repository location.
REPOSITORY_ID is the repository ID.
DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.
CONFIG_DESCRIPTION is the optional description of the remote source.

Python

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "DESCRIPTION"
  format        = "python"
  kms_key_name = "KEY"
  mode          = "REMOTE_REPOSITORY"
  remote_repository_config {
    description = "CONFIG_DESCRIPTION"
    python_repository {
      public_repository = "PYPI"
    }
  }
}

Where

PROJECT-ID is the Google Cloud project ID.
LOCATION is the repository location.
REPOSITORY_ID is the repository ID.
DESCRIPTION is the optional description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.
KEY is the name of the Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption. Omit this argument to use the default setting, Google-managed encryption keys.
CONFIG_DESCRIPTION is the optional description of the remote source.

Artifact Registry creates your repository. Run the following command to view a description of the repository:

gcloud artifacts repositories describe REPOSITORY \
    --location=LOCATION

After you have created the repository:

Grant access to the repository.
Configure Docker, package managers, and other third-party clients to authenticate to repositories.
- Container images: Docker, Helm
- Language packages: Java, Node.js, Python
- OS packages: Debian, RPM
- Other: Kubeflow Pipeline templates

Edit repository descriptions

You can change the repository description from Google Cloud console or the gcloud CLI.

Console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
In the repository list, select the repository and click Edit Repository.
Edit the repository description and then click Save.

gcloud

To update the repository description, run the command:

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

Replace the following values:

REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
PROJECT is the Google Cloud project ID. If this flag is omitted, the current or default project is used.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
DESCRIPTION is a description for the repository.

Access to upstream sources in a service perimeter

Services in a VPC Service Controls service perimeter have restricted access to resources outside the perimeter.

You can allow or deny access to upstream sources within a specified Google Cloud project and location.

By default, Artifact Registry denies access to upstream sources if you have not explicitly granted access.

For Artifact Registry the required role is the Artifact Registry Administrator (roles/artifactregistry.admin).

View settings for upstream sources

To view the configuration for a specific project and location combination, run the following command:

gcloud artifacts vpcsc-config describe \
    --project=PROJECT_ID \
    --location=LOCATION

For example, use the following command to view settings for remote repositories in us-east1 in the project my-project:

gcloud artifacts vpcsc-config describe \
    --project=my-project \
    --location=us-east1

Allow access to upstream sources

To allow access to upstream sources in a specified location, run the command:

gcloud artifacts vpcsc-config allow \
    --project=PROJECT_ID \
    --location=LOCATION

For example, use the following command to allow all remote repositories in us-east1 in the project my-project to access their upstream sources outside of the perimeter:

gcloud artifacts vpcsc-config allow \
    --project=my-project \
    --location=us-east1

Deny access to upstream sources

When you deny access to upstream sources, existing cached artifacts in remote repositories are still available.

To deny access to upstream sources in a specified location, run the command:

gcloud artifacts vpcsc-config deny \
    --project=PROJECT_ID \
    --location=LOCATION

For example, use the following command to block access to upstream sources outside of the perimeter for all remote repositories in us-west1 in the project my-project:

gcloud artifacts vpcsc-config deny \
    --project=my-project \
    --location=us-west1