Repository overview

Artifact Registry enables you to store different artifact types, create multiple repositories in a single project, and associate a specific region or multi-region with each repository. This page describes considerations to help you plan the locations and organization of your repositories.

Consider both internal processes for creating your artifacts and the usage by consumers of your artifacts when you create your repositories.

Repository formats

Each repository is associated with a specific artifact format. For example, a Python repository stores Python packages. You can create multiple repositories for each format in the same Google Cloud project.

Repository modes

There are several repository modes. Each mode serves a different purpose, so you cannot change the repository mode after you have created a repository.

Standard repository
Standard repositories are regular Artifact Registry repositories for your private artifacts. You upload and download artifacts directly with these repositories and use Artifact Analysis to scan for vulnerabilities and other metadata.
Remote repository

A read-only repository that acts as a proxy for an external source, such as Docker Hub, Maven Central, or the Python Package Index (PyPI). The first time you request an artifact version, the repository downloads it from the external source and caches a copy of it. The repository serves the cached copy when the same version is requested again.

Remote repositories reduce latency and improve availability for builds and deployments on Google Cloud. You can also use Artifact Analysis to scan for vulnerabilities and other metadata.

Virtual repository

A read-only repository that acts as a single access point to download, install, or deploy artifacts of the same format from one or more upstream repositories. An upstream repository can be a standard, remote, or virtual repository.

Virtual repositories simplify client configuration for consumers of your artifacts. You can also mitigate dependency confusion attacks by configuring your upstream policy to prioritize repositories with your private artifacts over remote repositories that cache public artifacts.

Repository usage example

The following diagram shows one of many possible ways you can use repositories in different modes together. The diagram shows a workflow across two Google Cloud projects. In a development project, developers build a Java application. In a separate a runtime project, another build creates a container image with the application for deployment to Google Kubernetes Engine.

Standard, virtual, and remote repositories used across two projects.

  1. In the development project, a Java development team uses Cloud Build to build a Java application.

    • The build can request public Java dependencies using the virtual repository. The virtual repository serves the dependencies from the remote repository, which is a caching proxy for Maven Central.
    • Cloud Build uploads the package to the standard Maven repository in the component project.
  2. In the runtime project, Cloud Build containerizes the Java application.

    The build uses the Maven virtual repository to download the application. The virtual repository serves the package from the standard repository in the development project. The build can also download public Java dependencies from the same virtual repository.

  3. In the runtime project, Cloud Build uploads the built container image to a standard Docker repository.

  4. GKE pulls images from the Docker virtual repository.

    • The upstream standard Docker repository provides private images, such as the containerized Java application.
    • The upstream remote repository provides images that GKE requests from Docker Hub.

In this example, all repositories, builds, and GKE clusters are in the same region. Using the same location for Google Cloud services has benefits which are described in Repository location.

gcr.io domain support

Artifact Registry supports hosting of images on the gcr.io domain. If you are transitioning from Container Registry to Artifact Registry, you can set up gcr.io repositories Artifact Registry to minimize changes to your existing automation and workflows. These repositories provide:

  • Redirection of requests to the gcr.io domain.
  • Creation of gcr.io repositories when the first image is pushed to a gcr.io hostname for compatibility with Container Registry behavior.

For more information, see Transition to repositories with gcr.io domain support

Repository location

You can create one or more repositories in a supported region or multi-region. A good repository location balances latency, availability, and bandwidth costs for data consumers. Your organization might also have specific compliance requirements.

Location considerations

Creating a repository in the same region as other Google Cloud services has a number of benefits:

  • Reduce latency and network egress costs by creating repositories in the same region where you run GKE, Cloud Run, Cloud Build, and other Google Cloud services that interact with the repository. There is no charge for egress from Artifact Registry to other Google Cloud services in the same region.

    Although there is no charge for egress from a multi-region to a Google Cloud service in a corresponding region, this pricing only applies to a limited set of regions.

    • For the us multi-region, egress to a region in the United States such as us-central is not charged, to any region in Canada or South America is charged.
    • For the asia multi-region, egress to regions in Asia such as asia-northeast1 are not charged, but egress to regions in Australia are charged.
  • You can only use image streaming in GKE and Dataproc Serverless if your container images are stored in Artifact Registry repositories in the same region as your workloads or a multi-region that corresponds to the region with your workloads. Image streaming can reduce workload initialization time significantly when you are using larger container images since workloads can start before the entire image is downloaded.

  • Consider the location of consumers outside of Google Cloud. For example, if you developers team in Australia need to download artifacts from Artifact Registry to their local workstations, a repository in an Australian region will reduce latency and incur lower egress charges than a repository located on another continent.

Restricting repository locations

If you need to comply with regulations or policies that require you to store data in specific regions, you can include a resource locations constraint in your Google Cloud organization policy that only allows repository creation in compliant regions. Artifact Registry only enforces the constraint after you include it in your organization policy. If you have existing repositories in non-compliant locations, you must move your artifacts to a repository in a compliant location yourself and then delete the non-compliant repository.

Project structure

Your resource hierarchy is the way that you organize your resources across Google Cloud projects. The structure that you choose depends on factors such as data governance requirements, trust boundaries, and team structure.

There are two general approaches for setting up your repositories in multi-project organizations.

Centralize repositories
Create all repositories in a single project and then grant access to principals from other projects at the repository level. This approach can be more effective when a single person or team handles repository administration and repository access across your organization. It can also simplify setup of virtual repositories or solutions like Software Delivery Shield since you only need to enable and manage a single instance of Artifact Registry.
Project-specific repositories
Create repositories in projects that store and download artifacts. This approach might be required when you have data governance policies or trust boundaries that require more project-level separation and control of resources.

Access control

Repositories are only accessible with appropriate permissions unless you configure the repository for public access. You can grant permissions at the project or repository level.

Some Google Cloud services such as Cloud Build, Cloud Run, and GKE use default service accounts with default permissions to repositories in the same Google Cloud project. However, these default might not be suitable for your software development process or might not comply with security or policy requirements in your organization. Your repository administrator must explicitly grant these services access to repositories if:

  • Artifact Registry is in a different project than the service that is interacting with it.
  • You are using custom IAM roles with the default service accounts instead of the predefined role.
  • You are not using the default service account for the Google Cloud service.
  • You are setting up virtual repositories. You must explicitly grant the Artifact Registry service account access to upstream repositories.

For other principals that require access to repositories, your repository administrator must grant access. Following the security principle of least privilege, grant the minimum required permissions. For example:

  • You deploy container images in Artifact Registry to GKE clusters in several different projects. The service account for nodes in these clusters only require read access to repositories.
  • You have a development repository for applications that are in development and production repository for applications that are released. Developers require read and write access to the development repository and read-only access to the production repository.
  • You have a demo repository with sample applications. Your sales team only requires read-only access to download the demos.

Data encryption

By default, Google Cloud automatically encrypts data when it is at rest using encryption keys managed by Google. If you have specific compliance or regulatory requirements related to the keys that protect your data, you can create repositories encrypted with customer-managed encryption keys (CMEK).

Artifact Registry also supports organization policy constraints that can require CMEK to protect resources.

Labels and tags

Labels provide a way to organize resources specific to a Google Cloud service. In Artifact Registry, you can add labels to repositories so that you can group them together or filter repository lists by label. For example, you can use labels to group repositories by development stage or by team for automation or billing purposes. For more information about creating and using repository labels, see Labelling repositories.

You can also apply tags to repositories. While labels are primarily for organizing and filtering service-specific resources, tags are for programmatic control of policies across a Google Cloud organization. For more information, see Tagging repositories.

What's Next