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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/create-harbor-projects.md.txt).

### Required IAM roles

To pull images from Harbor registry instances, contact your IAM Project 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.

- **Limited Guest** : required to pull images from a Harbor repository. For more information on all available roles, see the Harbor documentation on User permissions by role: <https://goharbor.io/docs/2.8.0/administration/managing-users/user-permissions-by-role/>.

## 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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/configure-docker-authentication.md.txt) to the Harbor instance.
2. Pull the image from a Harbor project:

   ```bash
   docker pull INSTANCE_URL/HARBOR_PROJECT_NAME/IMAGE:TAG
   ```

   or

   ```bash
   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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/manage-harbor-instances.md.txt#view-harbor-registry-instances).
- `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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/manage-harbor-instances.md.txt#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:

- [Deploy a container app](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/deploy-container-workloads.md.txt)
- [Configure tag retention rules](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/configure-tag-retention-rules.md.txt)
- [Scan for vulnerabilities](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform-application/pa-ao-operations/scan-vulnerabilities.md.txt)