Building a Private Container Registry with Harbor

Relying solely on public Docker Hub for container operations presents limitations in rate limiting, security, and compliance. Enterprise environments require a private container registry with full image control, automated vulnerability scanning, and access control.

Harbor is a CNCF graduated open-source container registry that meets precisely these requirements. At Kubo, we use Harbor as our private registry for container infrastructure. This article covers practical guidance from initial setup through production operations.

Why You Need a Private Registry: Harbor's Value Proposition

Docker Hub is convenient, but production environments expose several challenges:

• Rate limiting: Free accounts are restricted to 100 pulls per 6 hours
• Security: Verifying the trustworthiness of public images is difficult
• Compliance: Requirements for image storage location and access audit logs
• Network: Latency and costs from internet-based pulls

VMware's blog positions Harbor as "your enterprise-ready container registry for a modern private cloud."

Harbor's key features:

By integrating Captain.AI with Harbor, you can automate container image management for AI workers.

Harbor Installation Methods

Harbor can be deployed via VM-based installation or Kubernetes Helm deployment.

Method 1: VM-Based Installation

System Requirements

# 1. Download Harbor installer
wget https://github.com/goharbor/harbor/releases/download/v2.12.0/harbor-online-installer-v2.12.0.tgz
tar xzvf harbor-online-installer-v2.12.0.tgz
cd harbor

# 2. Edit configuration file
cp harbor.yml.tmpl harbor.yml

Key harbor.yml settings:

hostname: harbor.example.com

# HTTPS configuration (required for production)
https:
  port: 443
  certificate: /etc/ssl/certs/harbor.crt
  private_key: /etc/ssl/private/harbor.key

# Admin password
harbor_admin_password: StrongPassword123!

# Database configuration
database:
  password: db-password
  max_idle_conns: 100
  max_open_conns: 900

# Storage configuration
data_volume: /data/harbor

# 3. Install with Trivy
./install.sh --with-trivy

# 4. Verify installation
docker compose ps
curl -k https://harbor.example.com/api/v2.0/health

Detailed steps are available in the Harbor official installation documentation.

Method 2: Kubernetes Helm Deployment

This is the method recommended by the CNCF deployment guide, suitable for production environments requiring high availability.

# Add Helm repository
helm repo add harbor https://helm.goharbor.io
helm repo update

# Create values.yaml
cat <<EOF > harbor-values.yaml
expose:
  type: ingress
  ingress:
    hosts:
      core: harbor.example.com
    className: nginx
  tls:
    enabled: true
    certSource: secret
    secret:
      secretName: harbor-tls
externalURL: https://harbor.example.com
persistence:
  enabled: true
  persistentVolumeClaim:
    registry:
      size: 100Gi
    database:
      size: 10Gi
trivy:
  enabled: true
EOF

# Deploy Harbor
helm install harbor harbor/harbor \
  -f harbor-values.yaml \
  -n harbor --create-namespace

Helm deployment is recommended on Kubo's Kubernetes clusters.

RBAC and Project Management

Harbor's RBAC manages access permissions at the project level.

Role Hierarchy

Project Configuration Example

# Create project via Harbor API
curl -X POST "https://harbor.example.com/api/v2.0/projects" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "production",
    "metadata": {
      "public": "false",
      "auto_scan": "true",
      "prevent_vul": "true",
      "severity": "high"
    }
  }'

Setting prevent_vul: true with severity: high blocks pulls of images containing HIGH or above vulnerabilities. The HostMyCode security hardening guide provides detailed coverage.

Vulnerability Management with Trivy Integration

Harbor's built-in Trivy automatically runs vulnerability scans on image push.

Configuring Auto-Scan

1. In Project Settings > Configuration, enable "Automatically scan images on push"
2. Set the vulnerability severity threshold (e.g., block at HIGH and above)
3. Configure a scan schedule (e.g., rescan all images nightly)

Checking Scan Results

# Retrieve scan results via API
curl "https://harbor.example.com/api/v2.0/projects/production/repositories/myapp/artifacts/latest/additions/vulnerabilities" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)"

Scan results are viewable in the Harbor UI, displaying CVE IDs, severity levels, and fixable versions.

CVE Allowlists

False positives or accepted vulnerabilities can be allowlisted per project. The Aqua Security Harbor Scanner Trivy repository contains detailed configuration instructions.

Replication and Disaster Recovery

Harbor's replication feature automatically synchronizes images across multiple registry instances.

Replication Targets

Harbor supports bidirectional replication with:

• Harbor (other instances)
• Docker Hub
• AWS ECR
• Google Artifact Registry
• Azure ACR
• Any OCI-compliant registry

Replication Policy

{
  "name": "sync-to-dr",
  "src_registry": { "id": 0 },
  "dest_registry": { "id": 1 },
  "dest_namespace": "production",
  "trigger": {
    "type": "event_based"
  },
  "filters": [
    { "type": "name", "value": "production/**" },
    { "type": "tag", "value": "v*" }
  ],
  "enabled": true
}

Choose between event-based triggers (replicate immediately on push) and schedule-based triggers (periodic synchronization).

The Shipyard registry comparison evaluates Harbor's replication capabilities as a major differentiator for enterprise environments.

Summary: Enterprise-Grade Container Registry

Harbor delivers an enterprise-grade private container registry integrating:

• Built-in Trivy: Detect vulnerabilities instantly with auto-scan on push
• RBAC: Fine-grained access control at project and role levels
• Replication: Multi-registry image synchronization and DR capabilities
• Image Signing: Tamper prevention with Cosign / Notary
• Helm Chart Hosting: Unified management for Kubernetes deployments

At Kubo, Harbor forms the core of our image management pipeline for production container workloads. Integration with Captain.AI enables one-stop operations from vulnerability response to automated deployments.

To discuss Harbor adoption or container registry operations, please contact us.