Sign in to Docker and Helm

This page describes how to sign in to Docker or Helm using the Managed Harbor Service (MHS) credential helper or CLI secrets.

Harbor registry instances in Google Distributed Cloud (GDC) air-gapped use Identity-Aware Proxy (IAP) for authentication. You can sign in to your Harbor registry instance from the Docker or Helm CLI using either of the following methods:

  • MHS credential helper (docker-credential-mhs): uses your authenticated GDC identity to handle IAP authentication automatically. After you sign in with the gdcloud CLI, docker-credential-mhs fetches your authenticated user identity and verifies your access with Harbor. After verification, Harbor provides a short-lived token to Docker or Helm so you can perform registry operations without creating or managing separate CLI secrets.
  • CLI secrets: uses a static CLI secret from your Harbor user profile. After you sign in to the Harbor web interface using IAP for the first time, you can retrieve your CLI secret and use it as your password when signing in from the Docker or Helm CLI. This method is only available with the Harbor UI.

Before you begin

To configure Docker and Helm authentication for Harbor registry instances, you must have the MHS credential helper (docker-credential-mhs) installed in your environment. The credential helper is included by default in the gdcloud CLI bundle. For more information, see gdcloud CLI overview.

Required IAM roles

To configure authentication for 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 for authentication.

Sign in with the MHS credential helper

How you authenticate with docker-credential-mhs depends on your CLI client: you can configure Docker to fetch credentials automatically, or retrieve temporary credentials directly to sign in to Docker.

Sign in to Docker

To authenticate with Docker, follow these steps:

  1. Sign in to the Management API server with the gdcloud CLI by following the instructions in Sign in.

  2. Configure Docker to use the MHS credential helper docker-credential-mhs:

    TENANT_PROJECT=PROJECT_NAME
HARBOR_INSTANCE_NAME=HARBOR_INSTANCE_NAME
REGISTRY=$(kubectl get harborinstance $HARBOR_INSTANCE_NAME -n $TENANT_PROJECT -o jsonpath='{.status.url}' | sed s#https://##)

docker-credential-mhs configure-docker --registries=${REGISTRY}

    Replace the following:

  3. Follow the instructions in Configure Docker to trust the Harbor root CA.

  4. Optional: Verify that the credential helper is successfully configured by verifying the mhs entry is added to ~/.docker/config.json:

    cat DOCKER_CONFIG_PATH

    Replace DOCKER_CONFIG_PATH with the path to your Docker configuration file, such as ~/.docker/config.json.

    The output is similar to the following:

    {
    "auths": {
        "10.200.0.1": {
            "auth": "YWRtaW46YWRtaW4="
        },
        "10.200.16.5:10443": {
            "auth": "YWRtaW46ZEROVVJCVWE1a1FBcE4xQQ=="
        }
    },
    "credHelpers": {
        "asia.gcr.io": "gcloud",
        "eu.gcr.io": "gcloud",
        "gcr.io": "gcloud",
        "marketplace.gcr.io": "gcloud",
        "myinstance-e2e-test-user.org-1.zone1.google.gdch.test": "mhs",
        "staging-k8s.gcr.io": "gcloud",
        "us-central1-docker.pkg.dev": "gcloud",
        "us.gcr.io": "gcloud"
    }
}

    This example shows a successful output of "myinstance-e2e-test-user.org-1.zone1.google.gdch.test": "mhs".

  5. Configure the tenant project in the gdcloud CLI:

    TENANT_PROJECT=PROJECT_NAME
gdcloud config set project $TENANT_PROJECT

    The following output is shown:

    Updated property [core/project].

  6. Identify a Harbor project that you have management access to. If one doesn't exist, create a Harbor project.

  7. Perform Docker operations, such as an image push or pull:

    TENANT_PROJECT=PROJECT_NAME
HARBOR_INSTANCE_NAME=HARBOR_INSTANCE_NAME
REGISTRY=$(kubectl get harborinstance $HARBOR_INSTANCE_NAME -n $TENANT_PROJECT -o jsonpath='{.status.url}' | sed s#https://##)
HARBOR_PROJECT=HARBOR_PROJECT_NAME

# Push image
docker pull nginx
docker tag nginx ${REGISTRY}/${HARBOR_PROJECT}/nginx:latest
docker push ${REGISTRY}/${HARBOR_PROJECT}/nginx:latest

# Pull image
docker pull ${REGISTRY}/${HARBOR_PROJECT}/nginx:latest

    A successful output is similar to the following:

    # Push image
root@gpc-adhoc-70846130vm-bootstrapper-zone1:~# docker push ${REGISTRY}/harbor-project/nginx:latest
The push refers to repository [myinstance-e2e-test-user.org-1.zone1.google.gdch.test/harbor-project/nginx]
e4e9e9ad93c2: Pushed
6ac729401225: Pushed
8ce189049cb5: Pushed
296af1bd2844: Pushed
63d7ce983cd5: Pushed
b33db0c3c3a8: Pushed
98b5f35ea9d3: Pushed
latest: digest: sha256:7ba542bde95e6523a4b126f610553e3657b8108bc3175596ee7e911ae1219bfc size: 1778

# Pull image
root@gpc-adhoc-70846130vm-bootstrapper-zone1:~# docker pull ${REGISTRY}/library/nginx:latest
latest: Pulling from library/nginx
Digest: sha256:7ba542bde95e6523a4b126f610553e3657b8108bc3175596ee7e911ae1219bfc
Status: Image is up to date for myinstance-e2e-test-user.org-1.zone1.google.gdch.test/harbor-project/nginx:latest

    If the operation is unsuccessful, you might see the following output:

    E1025 19:21:39.322290 1273587 get.go:24] failed to get user name: user is not logged in or login expired, please login again

    In this example, the GDC authentication session has expired, and you must sign in to GDC again. For more information, see Sign in.

Sign in to Helm

To authenticate with Helm, follow these steps:

  1. After authenticating with GDC, retrieve your user credentials from the credential helper:

    echo $REGISTRY | docker-credential-mhs get

    The output is similar to the following:

    {"Username":"tokenreview$fop-infrastructure-operator@example.com","Secret":"STS-Bearer-3q2o6mBKk44Gzi4105vyiSnXMuixtnm-RnyxSgJtnYkNbGV7drpwgIuftinAXVlo0Im9kgoGmc2WcZTSjE-vh2a71Su7YjB6qIAjAQ5ABkY03AHNfkHhRZzxthumDIVAd08wm2weit3_NpMPgOnf9qMblds_Q0PAWk2OhpodBpCfyl3LWZpIZBaNVgtg-TB_7fjpEDOm-_Q5VYABScOgZFP_bw"}

  2. Sign in to the Helm CLI with the credentials. When prompted to enter the credentials, use the credentials returned by the credential helper.

    helm registry login $REGISTRY
Username: tokenreview$fop-infrastructure-operator@example.com
Password: STS-Bearer-3q2o6mBKk44Gzi4105vyiSnXMuixtnm-RnyxSgJtnYkNbGV7drpwgIuftinAXVlo0Im9kgoGmc2WcZTSjE-vh2a71Su7YjB6qIAjAQ5ABkY03AHNfkHhRZzxthumDIVAd08wm2weit3_NpMPgOnf9qMblds_Q0PAWk2OhpodBpCfyl3LWZpIZBaNVgtg-TB_7fjpEDOm-_Q5VYABScOgZFP_bw

    A successful output for this operation looks like the following:

    Login Succeeded

Sign in with CLI secrets

To sign in to Docker or Helm with CLI secrets, follow these steps:

  1. Sign in to Harbor with an IAP user account.
  2. Click your username and select User Profile.
  3. To copy the CLI secret associated with your account, click Copy.

  4. Optional: To display buttons for automatically generating or manually creating a new CLI secret, click More in your user profile.

  5. If you generated a new CLI secret, click Copy to copy it.

  6. Use your CLI secret as the password when signing in to Harbor from the Docker or Helm CLI:

    docker login -u USERNAME -p CLI_SECRET HARBOR_INSTANCE_URL

    Replace the following:

    • USERNAME: the Harbor account username.
    • CLI_SECRET: the generated CLI secret.
    • HARBOR_INSTANCE_URL: the URL of the Harbor instance.

What's next

After you sign in to Docker and Helm, your registry is connected and you can start using it: