Create remote repositories

This page describes how to create Artifact Registry remote repositories.

Remote repositories store artifacts from external sources such as Docker Hub or PyPI. A remote repository 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.

For more details on how remote repositories work, see the Remote repository overview.

Before you begin

  1. Enable Artifact Registry, including enabling the Artifact Registry API and installing Google Cloud CLI.
  2. Optional: configure defaults for the gcloud CLI commands.
  3. If you require customer-managed-encryption keys (CMEK) to encrypt repository content, create and enable a key in Cloud KMS for the repository.
  4. If you want to authenticate to an upstream repository, enable the Secret Manager API.

    gcloud services enable secretmanager.googleapis.com \
        --project=PROJECT_ID
    
  5. 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 Admin (roles/artifactregistry.admin) on the project
  • Save your upstream repository credentials in a secret version: Secret Manager Admin (roles/secretmanager.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.

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

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. Click Create Repository.

  3. Specify the repository name. For each repository location in a project, repository names must be unique.

  4. In the Format section, select the repository format.

  5. In the Repository mode section, select Remote.

  6. In the Remote repository source section, select your upstream repository source.

  7. If your remote repository format supports authentication, in the Remote repository authentication mode choose one of:

    • Authenticated: to enter your username and secret for authentication to your upstream repository.
    • Unauthenticated: to skip authentication to the upstream repository.
  8. In the Location Type section, 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

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

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

  11. 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.
  12. 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.

Create a remote repository using the 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-username=USERNAME \
    --remote-password-secret-version=SECRET_VERSION \
    --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.

  • USERNAME is your username for authenticating to the upstream repository.

  • SECRET_VERSION is the secret version containing your upstream repository password.

For example, the following command creates a remote repository named my-repo in the region us-east1 in the Google Cloud project my-project and can authenticate to the upstream repository using the username my-username and secret version projects/my-project/secrets/my-secret/versions/1.

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-username=my-username \
    --remote-password-secret-version=projects/my-project/secrets/my-secret/versions/1 \
    --remote-docker-repo=DOCKER-HUB

For more information on authenticating to Docker Hub upstream repositories, see Configure remote repository authentication to 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

Apt (preview)

gcloud artifacts repositories create REMOTE_REPOSITORY_NAME \
    --project=PROJECT_ID \
    --repository-format=apt \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --mode=remote-repository \
    --remote-repo-config-desc="REMOTE_REPOSITORY_DESCRIPTION" \
    --remote-apt-repo=APT_REPOSITORY_BASE \
    --remote-apt-repo-path="APT_REPOSITORY_PATH"

Replace the following:

  • REMOTE_REPOSITORY_NAME with the name of the repository. For each repository location in a project, repository names must be unique.
  • PROJECT_ID with the project ID. If this flag is omitted, the current or default project is used.
  • LOCATION with 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 with an optional description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • REMOTE_REPOSITORY_DESCRIPTION with an optional description for the external repository configuration for this remote repository.
  • APT_REPOSITORY_BASE with one of the supported repository base names listed in the OS package supported upstreams for Apt remote repositories.
  • APT_REPOSITORY_PATH with the remainder of the URL of the upstream repository that you want to cache in your remote repository after the repository base.

For example, the following command creates a remote repository named my-repo to cache the Debian buster repository in the region us-east1 in the Google Cloud project my-project. The full URL of the upstream repository is http://deb.debian.org/debian/dists/buster.

gcloud artifacts repositories create my-repo \
    --project=my-project \
    --repository-format=apt \
    --location=us-east1 \
    --description="Apt remote repository" \
    --mode=remote-repository \
    --remote-repo-config-desc="Debian buster distribution" \
    --remote-apt-repo=DEBIAN \
    --remote-apt-repo-path="debian/dists/buster"

Yum (preview)

gcloud artifacts repositories create REMOTE_REPOSITORY_NAME \
    --project=PROJECT_ID \
    --repository-format=yum \
    --location=LOCATION \
    --description="DESCRIPTION" \
    --mode=remote-repository \
    --remote-repo-config-desc="REMOTE_REPOSITORY_DESCRIPTION" \
    --remote-yum-repo=YUM_REPOSITORY_BASE \
    --remote-yum-repo-path="YUM_REPOSITORY_PATH"

Replace the following:

  • REMOTE_REPOSITORY_NAME with the name of the repository. For each repository location in a project, repository names must be unique.
  • PROJECT_ID with the project ID. If this flag is omitted, the current or default project is used.
  • LOCATION with 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 with an optional description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.
  • REMOTE_REPOSITORY_DESCRIPTION with an optional description for the external repository configuration for this remote repository.
  • YUM_REPOSITORY_BASE with one of the supported repository base names listed in the OS package supported upstreams for Yum remote repositories.
  • YUM_REPOSITORY_PATH with the remainder of the URL of the upstream repository that you want to cache in your remote repository after the repository base.

For example, the following command creates a remote repository for Yum packages named my-repo in the region us-east1 in the Google Cloud project my-project for the upstream repository centos/8-stream/BaseOs/x86_64/os.

gcloud artifacts repositories create my-repo \
    --project=my-project \
    --repository-format=yum \
    --location=us-east1 \
    --description="Yum remote repository" \
    --mode=remote-repository \
    --remote-repo-config-desc="CentOS 8 x86" \
    --remote-yum-repo=CENTOS \
    --remote-yum-repo-path="centos/8-stream/BaseOs/x86_64/os"

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

After you have created the repository, do the following:

Create a remote repository using Terraform

Use the google_artifact_registry_repository resource to create repositories. terraform-provider-google version 5.0.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 don't 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 = "LOCATION"
repository_id = "my-repo"
description = "Maven repository"
format = "MAVEN"
mode = "REMOTE_REPOSITORY"
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.

Apt (Preview)

  provider "google" {
  project = "PROJECT_ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "DESCRIPTION"
  format        = "APT"
  mode          = "REMOTE_REPOSITORY"
  remote_repository_config {
    description = "CONFIG_DESCRIPTION"
    apt_repository {
      public_repository {
        repository_base = "REPOSITORY_BASE"
        repository_path = "REPOSITORY_PATH"
      }
    }
  }
}

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. Don't include sensitive data, since repository descriptions are not encrypted.
  • CONFIG_DESCRIPTION is the optional description of the remote source.
  • REPOSITORY_BASE is the preset public repository base for Apt. Possible values are DEBIAN and UBUNTU.
  • REPOSITORY_PATH is the specific repository from the base. For example debian/dists/buster.

Yum (Preview)

  provider "google" {
  project = "PROJECT_ID"
}

resource "google_artifact_registry_repository" "my-repo" {
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "DESCRIPTION"
  format        = "YUM"
  mode          = "REMOTE_REPOSITORY"
  remote_repository_config {
    description = "CONFIG_DESCRIPTION"
    yum_repository {
      public_repository {
        repository_base = "REPOSITORY_BASE"
        repository_path = "REPOSITORY_PATH"
      }
    }
  }
}

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. Don't include sensitive data, since repository descriptions are not encrypted.
  • CONFIG_DESCRIPTION is the optional description of the remote source.
  • REPOSITORY_BASE is the preset public repository base for Yum. Possible values are CENTOS, CENTOS_DEBUG, CENTOS_VAULT, CENTOS_STREAM, ROCKY, and EPEL.
  • REPOSITORY_PATH is the specific repository from the base. For example "centos/8-stream/BaseOS/x86_64/os.

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:

Edit repository descriptions

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

Console

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. In the repository list, select the repository and click Edit Repository.

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

What's next