Harbor: Cloud‑Native Docker Registry Authentication, Installation, and Image Push Guide

Harbor Overview

Harbor is an open‑source CNCF‑hosted cloud‑native Docker registry that adds security, identity, and management features such as user management, access control, activity audit, and Helm chart repository support.

Authentication Principle

Harbor relies on Docker Registry v2’s token authentication. When a client runs docker login https://registry.example.com , the client calls the RegistryLogin API, which triggers a token request to the configured auth service. The auth service validates credentials (e.g., against a database or LDAP) and returns a JWT token, which the client then uses for subsequent registry operations.

Key Configuration

The registry’s auth section in its configuration file specifies the token realm, service, issuer, and certificate bundle. Setting the realm points the registry to the external auth server.

Installation Prerequisites

Kubernetes 1.10+

Helm 2.8.0+

Ingress controller

External PostgreSQL 9.6+

External Redis

ReadWriteMany PVC or external object storage

Helm Installation

Add the Harbor chart repository, pull version 1.9.2, and customize values-prod.yaml to configure external URL, database, Redis, storage class, and replica counts. Then run:

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

After deployment, verify pods are running and access the portal at https://harbor.k8s.local with the default admin credentials.

Image Push / Pull with containerd

Configure /etc/containerd/config.toml to add the Harbor endpoint, set insecure_skip_verify=true , and provide username/password. Restart containerd, then use nerdctl login (or --insecure-registry ) to authenticate, tag a local image, and push it:

nerdctl tag busybox:1.35.0 harbor.k8s.local/library/busybox:1.35.0
nerdctl push --insecure-registry harbor.k8s.local/library/busybox:1.35.0

Pulling the image back works similarly, and the image appears in the Harbor UI.

Kubernetes Usage

Create a Docker registry secret:

kubectl create secret docker-registry harbor-auth --docker-server=https://harbor.k8s.local --docker-username=admin --docker-password=Harbor12345 [email protected] -n default

Reference the secret in a pod spec to pull images from Harbor.

Conclusion

The guide demonstrates how to set up a highly available Harbor instance, configure authentication, and use it with containerd and Kubernetes for secure image storage and distribution.