Harbor guide

What Harbor does in production

Harbor is a private alternative to Docker Hub for teams that need control over images: who can push, which CVEs block deploy, and how images replicate to DR sites. Kubernetes clusters, CI pipelines, and developers pull from Harbor instead of the public internet — faster, auditable, and policy-governed.

Harbor vs a plain registry

A minimal registry only stores blobs. Harbor adds a web UI, projects (namespaces), RBAC, integrated vulnerability scanning, replication to other registries, retention/garbage collection, and robot accounts for CI. It speaks the standard Docker Registry HTTP API — docker push and docker pull work as usual.

Core concepts

• Project — logical grouping of repositories (e.g. library, team-backend)
• Repository — image name under a project (myapp/api)
• Artifact — image manifest + tags + layers (OCI)
• Tag — label pointing to an artifact (e.g. v1.2.3, latest)
• Robot account — non-human account for CI push/pull with scoped token
• Replication rule — sync images to/from another registry

How push and pull work

1. Login — docker login harbor.example.com (user, robot, or OIDC)
2. Tag — docker tag myapp:1.0 harbor.example.com/project/myapp:1.0
3. Push — layers upload to Harbor; manifest stored under the project
4. Scan — Trivy scanner (if enabled) reports CVEs on the artifact
5. Pull — kubelet or docker pull fetches by digest or tag

Image path format: REGISTRY/PROJECT/REPOSITORY:TAG. See the Docker lab for container basics.

Web UI and administration

The Harbor portal (HTTPS, usually port 443) is the control plane: browse projects, inspect scan results, configure webhooks, and manage users. Default install creates an admin user — change the password immediately in production.

Security and policies

• RBAC — project roles: Guest, Developer, Maintainer, ProjectAdmin
• Vulnerability scanning — block pull or deploy if severity threshold exceeded
• Content trust / signing — Notary (legacy) or Cosign integration for signed images
• CVE allowlists — exceptions for accepted risks
• Proxy cache — pull-through cache of Docker Hub to save bandwidth

Replication and HA

Replication jobs push or pull images between Harbor instances or cloud registries (ECR, GCR, Docker Hub). Use for DR, edge mirrors, or promoting images from CI Harbor to production Harbor. Harbor itself can run HA with external database (Postgres), Redis, and object storage for blobs — see the Postgres lab for DB troubleshooting when Harbor's backend misbehaves.

Helm charts and OCI

Harbor stores Helm charts as OCI artifacts in addition to container images. Push with helm push chart.tgz oci://harbor.example.com/project. Kubernetes clusters pull charts the same way as images when configured for OCI — see the Helm lab.

Deployment layout

Common installs: Docker Compose for dev, Helm chart on Kubernetes for production. Components include core (API), registry (distribution), portal (UI), jobservice (async tasks), scanner, database. Config: /etc/harbor/harbor.yml (installer); logs under /var/log/harbor/ on compose deployments.

Garbage collection and disk

Deleting tags in the UI does not immediately free disk — run garbage collection to remove unreferenced blobs. Schedule GC during maintenance windows. Monitor registry storage and set retention policies to prune old tags automatically.

Learning resources

• Harbor documentation — goharbor.io/docs
• Installation — goharbor.io — install
• Administration — goharbor.io — administration
• Working with projects — goharbor.io — projects