Artifact Registry is the recommended service for container image storage and management on Google Cloud. 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. Although Container Registry is still available and supported as a Google Enterprise API, new features will only be available in Artifact Registry. Container Registry will only receive critical security fixes.
Artifact Registry provides the same container management features as Container Registry and includes additional features and benefits:
- Additional artifact formats
You can create repositories for the following artifact formats:
- Regional repositories
Container Registry only provides multi-regional registry hosts. Artifact Registry provides both regional and multi-regional registry hosts.
- Multiple, separate repositories in a single location
In Container Registry, you can only create a single registry host in a multi-region and all repositories in the registry share the same storage bucket. In Artifact Registry, each repository is a separate resource. You can apply different labels and Identity and Access Management policies to each repository.
- Repository-level permissions
In Container Registry, you grant permissions for each multi-regional registry host. You cannot apply separate permissions at the repository level. Artifact Registry offers repository level access control.
- Artifact Registry IAM roles
In Container Registry you use Cloud Storage roles to control access and need to push an image to a registry host before you can configure permissions for the host. In Artifact Registry, you use Artifact Registry roles to grant access, and there is a clear separation between repository administrator and repository user roles.
- Google Kubernetes Engine image streaming
GKE can stream data from eligible images as requested by your applications, so that workloads can initialize without waiting for the entire image to download. Image streaming provides faster autoscaling, faster pod startup, and reduced latency when pulling large images.
- Cloud Run source deployment
Deploy new services and new revisions to Cloud Run directly from source code using a single Google Cloud CLI command. Source deployment builds a container image from your code, stores it in Artifact Registry, and deploys it to Cloud Run.
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
Google Cloud console, Artifact Registry also lists Container Registry
repositories in the same project.
To take advantage of the expanded capabilities in Artifact Registry, you can transition your containers and your automation to Artifact Registry.
You can transition to Artifact Registry using one of these options:
- Standard repositories (Recommended)
- Regular Artifact Registry repositories that support all features and are fully independent of any existing Container Registry hosts.
- Repositories with gcr.io domain support
Special repositories that are mapped to Container Registry
gcr.iohostnames. These repositories support:
gcloud container imagescommands
- Redirecting traffic from
gcr.iohostnames to the corresponding gcr.io repositories in your project.
These repositories have some feature limitations. However, if you have a lot of tool configuration, scripts, or code with
gcr.ioreferences, a more tactical approach might be necessary to transition to Artifact Registry.
Both types of repositories can co-exist so that you can gradually transition. For example:
- You can create gcr.io repositories in Artifact Registry to transition your existing Container Registry setup and create standard repositories for new work.
- You can take a multi-staged approach to your transition. Transition to gcr.io repositories in Artifact Registry, then gradually shift to using to standard repositories as you update your automation to fully support Artifact Registry repository and image paths.
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
webappin 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.ioin this project can access all versions of the
- 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.
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.
This section summarizes changes and improvements to Container Registry features.
|Feature||Container Registry||Artifact Registry|
|Supported formats||Container images only||Multiple artifact formats, including container images, language packages, and OS packages.|
|Hostnames||Hosts are on the
||Hosts are on the
You can use gcr.io domain support to
automatically redirect traffic from your
|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:
|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 Google Cloud console.||View a list of your Artifact Registry and Container Registry
repositories in the Artifact Registry
section of Google 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 Google Cloud console.
|Using gcloud and API commands||Uses gcloud container images commands. Commands support shortened digests. If you don't specify the full digest string, Container Registry attempts to locate the correct image based on the partial string.||Uses gcloud artifacts docker commands. Commands don't support shortened digests.
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
||Publishes changes to the
To learn more, see Configuring Pub/Sub notifications.
|Cached Docker Hub images||Caches
the most frequently requested Docker Hub images on
|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 with Container Analysis||Scans for OS and language package vulnerabiities with on-demand scanning
in images with a supported OS. Automatic scanning only returns OS
Learn more about types of
||Scans for OS and lanaguage package vulnerabiities with both on-demand and
Learn more about types of
|Google-provided images||Google-provided images are hosted on
||Google-provided images continue to be available on
|Image streaming||Unavailable||GKE can stream data from eligible images in Artifact Registry for faster autoscaling, faster pod startup, and reduced latency when pulling large images.|
|Cloud Run source deployment||Unavailable||Source deployment lets you use a single gcloud CLI command to build a container image from your source code, store the image in Artifact Registry, and deploy it to Cloud Run.|
|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.|