Pull an image with Docker

Pull an image from a Harbor project in the Docker client to download the specified container image from your Harbor registry to your local machine. This lets you run the containerized application locally or use it as a base image for building other images.

Before you begin

To pull an image with Docker, you must configure your environment with the necessary resources and permissions, including an existing Harbor project with the container image you want to pull. For more information, see Create Harbor projects.

Required IAM roles

To pull images from Harbor registry instances, contact your Project IAM Admin to request the Harbor Instance Viewer (harbor-instance-viewer) role, which lets you get, list, and watch Harbor instances in the project namespace. This role includes the required permissions to view the details of existing Harbor instances so you can retrieve the registry URLs required for pulling images.

Required Harbor RBAC roles

Unlike GDC IAM roles, pulling images requires specific permissions within Harbor's internal role-based access control (RBAC) system. Request the necessary permissions from your administrator. Enforce least privilege access by requesting only the roles required for your specific tasks.

Pull an image

Follow these steps to pull an image from a Harbor project in the Docker client:

  1. Make sure that you are authenticated to the Harbor instance.

  2. Pull the image from a Harbor project:

    docker pull INSTANCE_URL/HARBOR_PROJECT_NAME/IMAGE:TAG

    or

    docker pull INSTANCE_URL/HARBOR_PROJECT_NAME/IMAGE@IMAGE_DIGEST

Replace the following values:

  • INSTANCE_URL: the URL of the Harbor instance. For example, harbor-1.org-1.zone1.google.gdc.test. You can get the URL of the Harbor instance using the GDC console or gdcloud CLI.
  • HARBOR_PROJECT_NAME: the name of the Harbor project. For example, my-project.
  • IMAGE: the image's name. For example, nginx.
  • TAG: the tag for the image version that you want to pull. For example, staging.
  • IMAGE_DIGEST: the sha256 hash value of the image contents. Each version of an image has a unique image digest. In the Harbor instance UI, click the specific image to see its digest. For more information, see View Harbor registry instances.

What's next

After you've confirmed the connection by pulling an image, you can use your artifacts to launch the application in your environment: