This page describes how to push and pull container images.
For instructions on listing, tagging, and deleting images, see Managing images.
Before you begin
- If the target repository does not exist, create a new repository.
- You must have at least Artifact Registry Writer access to the repository.
- Install Docker if it is not already installed.
- 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.
If you are uploading large images, the following limits apply:
- Upload time
- If you authenticate to Artifact Registry using an access token, the token expires after 60 minutes. If you expect your upload time to exceed 60 minutes, use a different authentication method.
- Image size
- The maximum artifact size is 5 TB.
- Artifact Registry does not support Docker chunked uploads. Some tools support uploading large images with either chunked uploads or a single monolithic upload. You must use monolithic uploads to push images to Artifact Registry.
Tagging the local image
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.
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 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.