Setup guide for Container Registry users

If you currently use Container Registry to manage your containers, this page explains how to set up an Artifact Registry repository and how using repositories differs from using Container Registry.

Overview

For simplicity, the instructions on this page assume that both Container Registry and Artifact Registry are in the same Google Cloud project. You can continue to both services as you transition to Artifact Registry so that you can gradually perform the setup steps and update your automation.

If required, you can set up Artifact Registry in a separate project and perform the same overall steps.

Transition steps

Transitioning to Artifact Registry includes the following steps:

  1. Learn about pricing for Artifact Registry before you begin the transition.
  2. Enable the Artifact Registry API.
  3. Update Cloud SDK and learn about the new gcloud commands. Optionally, set up defaults for gcloud commands.
  4. Create a Docker repository for your containers. You must create a repository before you can push images to it.
  5. Grant permissions to the repository.
  6. Configure authentication so that you can connect with your new repository.
  7. If needed, copy containers from Container Registry that you want to use in your new repository.
  8. Try pushing and pulling your containers.
  9. Try deploying your images to a runtime environment.
  10. Configure additional features.

Enabling service

To use Artifact Registry, enable the Artifact Registry API from the Cloud Console or with the command:

gcloud services enable artifactregistry.googleapis.com

What's next

Update and configure Cloud SDK or return to the list of steps.

Updating and configuring Cloud SDK

Container Registry uses gcloud container images commands.

Artifact Registry uses gcloud artifacts commands for images.

  1. Install Cloud SDK if it is not already installed.

  2. Update the gcloud components.

    gcloud components update

gcloud command comparison

The following table summarizes Container Registry commands and the equivalent Artifact Registry commands in the gcloud tool. Click a link in the table to view reference page for the command.

The table does not include all available Artifact Registry commands that have no equivalent in Container Registry. See the gcloud artifacts documentation for the full Artifact Registry command reference.

Operation Container Registry Artifact Registry
Create a repository Not applicable. gcloud artifacts repositories create
Delete a repository Not applicable. gcloud artifacts repositories delete
List images gcloud container images list gcloud artifacts docker images list
List tags gcloud container images list-tags gcloud artifacts docker tags list
Add a tag gcloud container images add-tag gcloud artifacts docker tags add
Delete a tag gcloud container images untag gcloud artifacts docker tags delete
Describe images gcloud container images describe gcloud artifacts docker image list --include-tags

What's next

Create repositories or return to the list of steps.

Creating repositories

Container Registry automatically creates a storage bucket in a multi-region if you have not pushed an image there before.

In Artifact Registry, you must create a repository before you can upload images. When you create a repository you must specify:

  • The repository format. Artifact Registry stores containers in Docker repositories.

  • A regional or multi-regional location for the repository.

    When choosing a location for your Artifact Registry repositories, consider the proximity of the repositories to your other infrastructure and your users. If you intend to copy images from Container Registry to Artifact Registry, differences in location can impact the cost of copying.

  • A Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption.

    In Container Registry, you configure the Container Registry storage bucket to use CMEK. In Artifact Registry, you configure repositories to use CMEK when you create them. For more information about using CMEK with Artifact Registry, see Enabling customer-managed encryption keys.

Container Registry hosts containers on the domain gcr.io. Artifact Registry hosts containers on the domain pkg.dev.

For information about creating repositories, including repositories that use CMEK for encryption, see Creating repositories.

What's next

Grant permissions or return to the list of steps.

Granting permissions

In Container Registry, access control is based on Cloud Storage roles and permissions. If you don't want to grant a project-wide role, you must grant permissions on the specific storage bucket that Container Registry uses.

Artifact Registry has its own IAM roles. You can grant roles at the project level,or you can set permissions on individual repositories. Use multiple Docker repositories in combination with repository-specific permissions to control access to different types of artifacts. For example, you can put tighter controls on a production repository or grant access to team-specific repositories based on team membership.

Service accounts for Google Cloud CI/CD services are preconfigured with access to repositories in the same project. If you use a Google Cloud service in a different project or a third-party tool to push or pull images, you must configure the appropriate permissions manually.

For instructions on granting permissions, see Granting permissions.

What's next

Configure authentication for third-party tools you use to access repositories, or return to the list of steps.

Authenticating to the repository

Artifact Registry supports the same authentication methods as Container Registry.

If you are using the Docker credential helper:

  • You must use version 2.0 or later to interact with Artifact Registry repositories. The standalone version is available in GitHub.
  • You must configure the credential helper with the Artifact Registry locations that you intend to use. By default the credential helper only configures access to Container Registry hosts.

For details about setting up authentication, see Setting up authentication for Docker.

What's next

Copy containers that you want to continue to store in Artifact Registry, or return to the list of steps.

Copying containers from Container Registry

If there are containers in Container Registry that you want to continue to use in Artifact Registry, there are several options for copying them. For instructions, see Copying images from Container Registry

What's next

Verify that you can push and pull containers, or return to the list of steps.

Pushing and pulling images

The Docker commands that you use to tag, push, and pull images in Artifact Registry are similar to the ones you use in Container Registry. There are two key differences:

  • The hostname for Artifact Registry Docker repositories include a location prefix, followed by -docker.pkg.dev. Examples include australia-southeast1-docker.pkg.dev, europe-north1-docker.pkg.dev, and europe-docker.pkg.dev.
  • Since Artifact Registry supports multiple Docker repositories in a single project, you must specify the repository name in commands.

For example, in Container Registry, this command pushes the image my-image to the registry eu.gcr.io in the project my-project.

docker push eu.gcr.io/my-project/my-image

In Artifact Registry, this command pushes the image my-image to the regional repository europe-north1-docker.pkg.dev in repository my-repo and the project my-project.

docker push europe-north1-docker.pkg.dev/my-project/my-repo/my-image

For details about pushing and pulling images in Artifact Registry, see Pushing and pulling images.

What's next

Verify that you can deploy images, or return to the list of steps.

Deploying images

Service accounts for common Google Cloud integrations are configured to work with Artifact Registry repositories by default.

Building images and pushing them to a repository with Cloud Build generally works the same way as it does for Container Registry. The key difference in Artifact Registry is that a target repository must exist before you push images to it, including the first image that you push.

Ensure that you create the repositories that you need before running commands that push images, including the Docker command docker push and the Cloud Build command gcloud builds submit.

Cloud Build builders are still hosted on gcr.io. For more information, see Integrating with Cloud Build.

What's next

Configure other features or return to the list of steps.

Managing metadata and scanning for vulnerabilities

Container Analysis supports both Container Registry and Artifact Registry. The Container Analysis documentation is updated to include both products.

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

Other features

This section describes configuration of other features that you might have set up in Container Registry.

Pub/Sub notifications

Artifact Registry publishes changes to the same gcr topic as Container Registry. No additional configuration is required if you already use Pub/Sub with Container Registry in the same project as Artifact Registry.

If you set up Artifact Registry in a separate project, the gcr topic might not exist. For setup instructions, see Configuring Pub/Sub notifications.

Securing repositories in a service perimeter

With VPC Service Controls, you can configure security perimeters around the resources of your Google-managed services and control the movement of data across the perimeter boundary.

See Securing repositories in a service perimeter for instructions.

What's next