Transitioning from Container Registry

Artifact Registry is the evolution of Container Registry. As a fully-managed service with support for both container images and non-container artifacts, Artifact Registry extends the capabilities of Container Registry.

If you currently use Container Registry, use the information on this page to learn about transitioning to Artifact Registry.

Overview

Artifact Registry provides the same container management features as Container Registry. You can start transitioning your automation to use Artifact Registry for your containers.

Backwards compatibility and co-existence

You can use both Artifact Registry and Container Registry in the same project. When you view a list of repositories with gcloud or Cloud Console, Artifact Registry also lists Container Registry repositories in the same project.

Both services will continue to co-exist after Artifact Registry becomes generally available. To take advantage of the expanded capabilities in Artifact Registry, you can transition your containers and your automation to Artifact Registry.

After Artifact Registry becomes generally available, you will have an option to create backwards-compatible repositories. These repositories can help you perform a more gradual update to your automation for builds and deployments with support for:

• gcloud container images commands
• Referencing the repository with a *.pkg.dev or *.gcr.io hostname.

To provide compatibility, these repositories will have some feature limitations. In particular, each backwards-compatible repository must be located in the same multi-region as a corresponding Container Registry hostname in your project.

Setting up repositories

In Artifact Registry you must create repositories before you can push images to them. So a key part of moving to Artifact Registry is setting up Artifact Registry repositories and integrating them into your CI/CD automation.

To provide greater flexibility, there are some changes in how Artifact Registry represents repositories.

Container Registry

Each multi-regional location is associated with a single storage bucket. Organizing your images into repositories under a hostname is optional. Consider the following example that shows the image webapp in three locations:

us.gcr.io/my-project/webapp
us.gcr.io/my-project/team1/webapp
us.gcr.io/my-project/team2/webapp

Repositories are only an organizing mechanism and do not restrict access. Any user with access to the storage bucket for us.gcr.io in this project can access all versions of the webapp container image.

Artifact Registry

Each repository is a separate resource in your project. Since each repository is a unique resource, you can:

• Give each repository a name, description, and labels
• Create multiple repositories in the same location
• Configure repository-specific permissions

In addition, the location of a repository can be a region or a multi-region.

These changes give you more control over your repositories. For example, if you have teams in São Paulo and Sydney, you can create a repository for each team in a region that is geographically closer than the nearest multi-regional location.

southamerica-east1-docker.pkg.dev/my-project/team1/webapp
australia-southeast1-docker.pkg.dev/my-project/team2/webapp

You can then grant each team with permissions to their team repository only.

See the setup guide for instructions to transition to Artifact Registry.

Pushing and pulling images

To help you adapt existing configuration, commands, and documentation designed for Container Registry, the following information compares building, pushing, pulling, and deploying images.

• Changes to building and deploying with Cloud Build
• Changes to pushing and pulling with Docker

Feature comparison

This section summarizes changes and improvements to Container Registry features.

After Artifact Registry becomes generally available, Artifact Registry will provide an option to create backwards-compatible repositories that you can reference with either *-docker.pkg.dev and *.gcr.io hostnames.

Feature	Container Registry	Artifact Registry
Supported formats	Container images only	Multiple artifact formats, including container images, Java packages and Node.js modules. Note: Package repositories are in alpha. To apply for the alpha, complete the sign up form.
Repositories	Creation - Automatically creates a repository in a multi-region if you have not pushed an image there before. Location - Multi-regional repositories only. Organization - All repositories on the same multi-regional host in a Google Cloud project share a single storage bucket. Access control - Grant permissions across the project level or on the storage bucket for each multi-regional host.	Creation - You must create a repository before pushing images to it. Location - Multi-regional or regional repositories. For example, the closest multi-region for Australia is Asia. With regional support, you can create a repository in the Sydney data center. Organization - You can create multiple, discrete repositories in each region or multi-region. Apply labels to group them by team, development stage, or other categories. Access control - Grant permissions on the project or on individual repositories.
Hostnames	Hosts are on the gcr.io domain.	Hosts are on the pkg.dev domain. For details on the name format, see Repository and artifact names.
Permissions	Grant access using Cloud Storage permissions. You can restrict access to all images stored in a multi-region, but not individual repositories. For example, you can restrict access to us.gcr.io in the project my-project, but you cannot grant specific permissions for images under us.gcr.io/my-project/team1 and us.gcr.io/my-project/team2	Grant access using Artifact Registry permissions. You can restrict access to individual repositories. For example, you can separately control access to images in us-docker.pkg.dev/my-project/team1 and us-docker.pkg.dev/my-project/team2
Authentication	Provides several authentication methods for pushing and pulling images with a third-party client.	Artifact Registry supports the same authentication methods as Container Registry. See Setting up authentication for Docker for details. If you use the Docker credential helper: Version 2.0.0 or newer is required. Docker client versions prior to v18.03 are no longer supported. You must add the Artifact Registry locations that you will use to the credential helper configuration.
Customer-managed encryption keys (CMEK)	Use CMEK to encrypt the storage buckets that contain your images.	Use CMEK to encrypt individual repositories.
Using Google Cloud Console	View and manage Container Registry images from the Container Registry section of Cloud Console.	View a list of your Artifact Registry and Container Registry repositories in the Artifact Registry section of Cloud Console. Manage your Artifact Registry repositories and images from this page. If you click a Container Registry repository, you are directed to the list of images in the Container Registry section of the Cloud Console.
Using gcloud and API commands	Uses gcloud container images commands.	Uses gcloud artifacts docker commands. After Artifact Registry becomes generally available, Artifact Registry will provide an option to create backwards-compatible repositories that support gcloud container images commands. For a comparison of Container Registry and Artifact Registry gcloud commands, see the gcloud command comparison. Artifact Registry also includes an API for managing repositories and artifacts in all formats.
Pub/Sub notifications	Publishes changes to the gcr topic.	Publishes changes to the gcr topic. If you create repositories in the same project as your existing Container Registry service, your existing Pub/Sub configuration works automatically. To learn more, see Configuring Pub/Sub notifications.
Cached Docker Hub images	Caches the most frequently requested Docker Hub images on mirror.gcr.io.	mirror.gcr.io continues to cache frequently requested images from Docker Hub.
VPC Service Controls	You can add Container Registry to a service perimeter.	You can add Artifact Registry to a service perimeter.
Metadata storage and analysis	Container Analysis provides metadata storage, vulnerability scanning, and integration with services that use the metadata such as Binary Authorization. Cloud SDK commands for working with notes and occurrences are under the gcloud container images group.	Container Analysis supports metadata storage and vulnerability scanning for container images in both Artifact Registry and Container Registry. Both products use the same Container Analysis APIs. When you enable Container Analysis APIs in either Container Registry or Artifact Registry the APIs are turned on for both products. Both products use the same `gcr` topic for Pub/Sub notifications. This means that your existing subscriptions to the gcr topic will include notifications for both Artifact Registry and Container Registry. Cloud SDK commands for working with notes and occurrences are under the gcloud artifacts docker group.
Google-provided images	Google-provided images are hosted on gcr.io. Examples include: Cached images on mirror.gcr.io. Cloud Build builders Managed base images	Google-provided images continue to be available on gcr.io.
Pricing	Container Registry pricing is based on Cloud Storage usage, including storage and network egress.	Artifact Registry has its own pricing, based on storage and network egress.