Deploying and Configuring Harbor: A Cloud‑Native Docker Registry on Kubernetes

Harbor is an open‑source CNCF‑hosted cloud‑native Docker registry that adds security, identity, and access‑control features, supports image signing, scanning, replication, and Helm chart hosting.

The core function is to place an authorization layer in front of a Docker registry v2, intercepting docker login/pull/push commands and delegating authentication to an external service.

Harbor authentication principle

When a user runs docker login https://registry.example.com , the Docker client calls the registry’s auth endpoint, which forwards the request to the configured authentication service. The service validates credentials (e.g., against a database or LDAP), issues a JWT token, and the client retries the request with the token, receiving a 200 response.

Key configuration points include specifying the authentication service address in the registry’s auth section (realm, service, issuer, rootcertbundle) and ensuring the token format matches the registry’s expectations (JWT).

Installation

Harbor can be installed as a high‑availability Helm chart on a Kubernetes 1.10+ cluster. Prerequisites include Helm 2.8+, an ingress controller, external PostgreSQL and Redis, and a shared PVC or external object storage.

Typical Helm commands:

# add chart repo
helm repo add harbor https://helm.goharbor.io
helm repo update
helm pull harbor/harbor --untar --version 1.6.2

Configuration values (excerpt):

auth:
  token:
    realm: token-realm
    service: token-service
    issuer: registry-token-issuer
    rootcertbundle: /root/certs/bundle
...
externalURL: https://harbor.k8s.local
expose:
  type: ingress
  ingress:
    hosts:
      core: harbor.k8s.local
      notary: notary.k8s.local
...

database:
  type: external
  external:
    host: postgresql.kube-ops.svc.cluster.local
    port: "5432"
    username: "gitlab"
    password: "passw0rd"
...

After customizing values-prod.yaml , install with:

helm upgrade --install harbor . -f values-prod.yaml -n kube-ops

Verify pods are running and configure DNS to point the Harbor domain to the ingress controller.

Push and pull images

Login to Harbor with Docker, handling self‑signed certificates either by adding the CA to /etc/docker/certs.d/harbor.k8s.local/ca.crt or by using the --insecure-registry flag.

Tag and push an image:

docker tag busybox:1.28.4 harbor.k8s.local/library/busybox:1.28.4
docker push harbor.k8s.local/library/busybox:1.28.4

Pull the image back to verify:

docker pull harbor.k8s.local/library/busybox:1.28.4

After successful push/pull, the image appears in the Harbor dashboard, and additional features such as image replication and Helm chart hosting can be explored.