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 Docker repository stores Docker images. You can create multiple repositories for each format in the same Google Cloud project.

Repository modes

There are multiple 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.

To create standard repositories, follow the steps in Create standard repositories.

Remote repository

Remote repositories are read-only repositories that act as proxies to store artifacts from the following upstream sources:

  • Standard Artifact Registry repositories.
  • External sources such as Docker Hub, Maven Central, the Python Package Index (PyPI), Debian or CentOS.

The first time you request an artifact version, the repository downloads it from the upstream source and caches a copy of it. The remote 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 cached packages for vulnerabilities and other metadata.

To learn more about remote repositories, read Remote repository overview. To create remote repositories, follow the steps in Create remote repositories.

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.

To learn more about virtual repositories, read Virtual repository overview. To create virtual repositories, follow the steps in Create virtual repositories.

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.

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.

Cleanup policies

An Artifact Registry cleanup policy defines criteria for automatically deleting artifact versions that you no longer need or keeping artifacts that you want to store indefinitely.

Cleanup policies are useful if you store many versions of your artifacts, but only need to keep specific versions that you release to production. You can define delete policies with criteria for deleting artifacts and keep policies with criteria for retaining artifacts.

If an artifact version matches criteria in both a delete policy and a keep policy, Artifact Registry applies the keep policy.

Delete policies

Delete policies delete artifacts matching the following required criteria:

  • Tag state: indicates if the policy should check for tagged artifacts or untagged artifacts. Artifacts are tagged when pushing or pulling an image to or from a repository. For more on Docker tags, see Container concepts.

    • Any tag state: ignores tag state and applies to both tagged and untagged artifacts.
    • Tagged: only applies to tagged artifacts.
    • Untagged: only applies to untagged artifacts.

    Formats that don't support tags are treated as untagged. Tagged artifacts in repositories with immutable tags enabled cannot be deleted.

    For more information on tag state as it applies to cleanup policies, see the TagState reference.

The following are optional ways to define your delete policy:

  • Tag prefixes: is a comma-separated list of tag prefixes. For example, the prefixes test, and staging would match images with tags testenv and staging-1.5. tagState must be set to TAGGED to use tag prefixes.
    • Version prefixes: - is a comma-separated list of artifact version prefixes. For example v1, v2 would match versions v1.5, v2.0alpha, and v10.2.
  • Package prefixes: is a list of artifact name prefixes. You can enter multiple prefixes by pressing Enter or , between the prefixes. For example red, blue would create two prefixes, red and blue and would match artifact names red-team, redis, and bluebird.
  • Older than: is a minimum time since an artifact version was uploaded to the repository, specified as a duration. For example, 30d is 30 days. You can specify durations of seconds, minutes, hours, or days by appending s, m, h, or d respectively.
  • Newer than: is a maximum time since an artifact version was uploaded to the repository, specified as a duration. For example, 30d is 30 days.

Keep policies

Keep policies keep artifacts matching the same conditions as delete policies, or a set number of most recent versions.

For example, given a repository containing the following artifacts:

IMAGE: us-west1-docker.pkg.dev/my-project/release-xyz-v1
DIGEST: sha256:1b0a26bd07a3d17473d8d8468bea84015e27f87124b2831234581bce13f61370
TAGS:
CREATE_TIME: 2023-06-19T18:59:09
UPDATE_TIME: 2023-06-19T18:59:10

IMAGE: us-west1-docker.pkg.dev/my-project/release-xyz-v2
DIGEST: sha256:6e494387c901caf429c1bf77bd92fb82b33a68c0e19f123456a3ac8d27a7049d
TAGS: latest
CREATE_TIME: 2023-06-19T18:59:09
UPDATE_TIME: 2023-06-19T18:59:09

IMAGE: us-west1-docker.pkg.dev/my-project/release-v2
DIGEST: sha256:6e494387c901caf429c1bf77bd92fb82b33a68c0e19f123456a3ac8d27a7049d
TAGS: latest
CREATE_TIME: 2023-06-19T18:59:09
UPDATE_TIME: 2023-06-19T18:59:09

If your Keep most recent versions policy is set to keep 3 versions of packages matching the Package prefixes: {release-xyz}, only release-xyz-v1, and release-xyz-v2 are kept.

Deletions triggered by delete policies count against your Artifact Registry per project delete request quota.

To create and apply cleanup policies to your repository, see Configure cleanup policies.

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

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

Restrict artifact downloads

You can restrict artifact downloads with download rules. Download rules let you allow or deny artifact downloads from your repositories and packages. You can also set conditions so the rule applies to specific tags or versions.

For details on how downloads rules work, see the Restrict artifact downloads section of the Control access and protect artifacts overview.

Data encryption

By default, Google Cloud automatically encrypts data when it is at rest using Google-owned and Google-managed keys. 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