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.

To provide flexibility, Google Distributed Cloud (GDC) air-gapped provides two methods to authenticate with Docker and Helm from your Harbor registry instance. The first method is using the Managed Harbor Service (MHS) credential helper and your GDC identity to sign in to the Docker or Helm CLI. After authenticating with GDC, you can sign in to the Docker client and perform Docker operations, without having to create or manage separate CLI secrets in Harbor.

The second method is using CLI secrets. After you authenticate using Identity-Aware Proxy (IAP) and sign in to the Harbor interface for the first time, use the Docker or Helm CLI to access Harbor. The Docker and Helm CLIs cannot handle redirection for IAP, so Harbor provides a CLI secret to use when signing in from Docker or Helm. This method is only available when Harbor uses IAP authentication.

Before you begin

To configure Docker and Helm authentication for Harbor registry instances, you must have the following:

• The MHS credential helper docker-credential-mhs installed in the environment. The credential helper is included by default in the gdcloud CLI bundle. For more information, see gdcloud CLI overview.
• The necessary identity and access role. Ask your Organization IAM Admin to grant you the Harbor Instance Viewer (harbor-instance-viewer) role.

Sign in to Docker with your GDC identity

Use the MHS credential helper with your GDC identity to sign into the Docker CLI. To authenticate with Docker, follow these steps:

1. Sign in to the Management API server with GDC 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:

   • PROJECT_NAME: the name of your tenant project. This is the same project name you provided when creating your Harbor instance.
   • HARBOR_INSTANCE_NAME: the name of the Harbor instance that is created in Create Harbor registry instances.

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 config file. For example, ~/.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 gdcloud:

   TENANT_PROJECT=PROJECT_NAME
   gdcloud config set project $TENANT_PROJECT
   

   The following output is shown:

   Updated property [core/project].
   

6. 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://##)
   
   # Push image
   docker pull nginx
   docker tag nginx ${REGISTRY}/library/nginx:latest
   docker push ${REGISTRY}/library/nginx:latest
   
   # Pull image
   docker pull ${REGISTRY}/library/nginx:latest
   

   A successful output is similar to the following:

   # Push image
   root@gpc-adhoc-70846130vm-bootstrapper-zone1:~# docker push ${REGISTRY}/library/nginx:latest
   The push refers to repository [myinstance-e2e-test-user.org-1.zone1.google.gdch.test/library/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/library/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 case, the GDC authentication session has expired and you must sign in to GDC again. For more information, see Sign in.

Sign into Helm with your GDC identity

Use the MHS credential helper with your GDC identity to sign into the Helm CLI.

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$[e-mail]","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$[e-mail]
   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 to Docker or Helm 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 the ellipses in your user profile.

   Note: A user can only have one CLI secret. When a new secret is generated or created, the old secret becomes invalid.

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

6. You can now 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.

Note: The CLI secret does not expire, unless you manually rotate it. The CLI secret is not associated with the user identity token. Signing out from Harbor or the GDC console does not revoke the CLI secret.