Pushing and pulling images

Beta

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA products and features may have limited support, and changes to pre-GA products and features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

This page describes how to push and pull container images.

For instructions on listing, tagging, and deleting images, see Managing images.

Before you begin

1. If the target repository does not exist, create a new repository.
2. You must have at least Artifact Registry Writer access to the repository.
3. Install Docker if it is not already installed.
4. Configure authentication for Docker.

Pushing an image

To push a local image to a Artifact Registry repository, you tag it with the repository name and then push the image.

Tagging the local image

Note: You must be authenticated to Artifact Registry before tagging an image to successfully push the image to the repository.

1. Determine the name of the image. The format of a full image name is:

   LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   where:

   • LOCATION is the regional or multi-regional location of the repository where the image is stored.

   • PROJECT is your Google Cloud Console project ID. If your project ID contains a colon (:), see Domain-scoped projects.

   • REPOSITORY is the name of the repository where the image is stored.

   • IMAGE is the image's name. It can be different than the image's local name.

   For example, consider an image with the following characteristics:

   • Repository location: us
   • Repository name: my-repo
   • Project ID: my-project
   • Local image name: my-image
   • Target image name: test-image

   This image name for this example is:

   us-docker.pkg.dev/my-project/my-repo/test-image
   

   Note: The name for the image that you will store in the repository can be different from the image name on your local machine.

   For details about the image name format, including handling domain-scoped projects, see Repository and image names.

2. Tag the local image with the repository name with the command:

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   where SOURCE-IMAGE is the local image name or image ID.

   This command names the image with the repository name and applies the tag latest.

   For the example image from the previous step, you would use the following command if the local image my-image is in the current directory:

   docker tag my-image us-docker.pkg.dev/my-project/my-repo/test-image
   

   If you want to apply a specific tag, use the command:

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   To use the tag staging with the example image, you add :staging to the command:

   docker tag my-image us-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Push the tagged image to Artifact Registry

Note: Artifact Registry does not support Docker chunked uploads. Some container image tools support uploading large container images with either chunked uploads or a single monolithic upload. You must use monolithic uploads when you push container images to Artifact Registry.

Push the tagged image with the command:

docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

This command pushes the image that has the tag latest. If you want to push an image that has a different tag, use the command:

docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

When you push an image, it is stored in the specified repository.

After pushing your image, you can:

• Go to the Cloud Console to view the image.

• Run the gcloud command to view the image's tags and automatically-generated digest:

  gcloud beta artifacts docker images list \
  LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
  

  The following example output shows truncated image digests, but the command always returns the full image digest.

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
    ```
  

Pulling images

To pull from a repository, use the command:

docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

or

docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

where:

• LOCATION is the regional or multi-regional location of the repository where the image is stored.

• PROJECT is your Google Cloud Console project ID. If your project ID contains a colon (:), see Domain-scoped projects.

• REPOSITORY is the name of the repository where the image is stored.

• IMAGE is the image's name in the repository.

• TAG is the tag for the image version that you want to pull.

• IMAGE-DIGEST is the sha256 hash value of the image contents. Each version of an image has a unique image digest. In Google Cloud Console, click on the specific image to see its metadata. The digest is listed as the Image digest.

For example, consider an image with the following characteristics:

• Repository location: us
• Repository name: my-repo
• Project ID: my-project
• Image name: test-image
• Tag: staging

This command to pull the image is:

docker pull us-docker.pkg.dev/my-project/my-repo/test-image:staging

What's next

• Learn about managing tags and deleting images.
• If you want to run containers on Compute Engine, learn about containers on Compute Engine.