Pushing and pulling images

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

  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
    

    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

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