# Harbor — Cloud Native Trusted Container Registry

> Harbor is a CNCF-graduated open-source container registry that stores, signs, and scans container images. Vulnerability scanning, RBAC, replication, and OCI support.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Download installer
wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
tar xvf harbor-offline-installer-v2.11.0.tgz
cd harbor

# Configure
cp harbor.yml.tmpl harbor.yml
# Edit harbor.yml with your hostname

# Install
sudo ./install.sh
```

Open `http://your-hostname` — login with admin/Harbor12345 and push your first image.

## Intro

**Harbor** is an open-source, CNCF-graduated trusted cloud-native container registry that stores, signs, and scans content. It extends the open-source Docker Distribution by adding the functionality usually required by users such as security, identity, and management — making it the go-to choice for enterprises running private container registries.

With 28.2K+ GitHub stars and Apache-2.0 license, Harbor is used by thousands of organizations including financial institutions, telecommunications companies, and government agencies for secure, compliant container image management.

## What Harbor Does

- **Container Registry**: Store and distribute Docker and OCI images
- **Vulnerability Scanning**: Integrated Trivy/Clair for continuous image security scanning
- **Image Signing**: Notary and Cosign integration for trusted content verification
- **RBAC**: Role-based access control with projects and LDAP/AD/OIDC integration
- **Replication**: Sync images between Harbor instances and public registries
- **Webhooks**: Notify external systems on push, pull, scan, delete events
- **Helm Chart Repository**: Store Helm charts alongside container images
- **Image Signing**: Sign images with Cosign for supply chain security
- **Garbage Collection**: Automatic cleanup of untagged/unused blobs
- **Audit Logging**: Track all operations for compliance
- **Quotas**: Set storage quotas per project

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Docker CLI  │────▶│  Harbor      │────▶│  Storage     │
│  / kubectl   │     │  (Portal +   │     │  (Local/S3/  │
└──────────────┘     │   Core +     │     │   GCS/Swift) │
                     │   Registry)  │     └──────────────┘
                     └──────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
       ┌──────┴──┐   ┌─────┴───┐   ┌─────┴───┐
       │PostgreSQL│  │  Redis  │   │  Trivy  │
       │ (Metadata│  │ (Cache) │   │ (Scan)  │
       └──────────┘  └─────────┘   └─────────┘
```

## Installation

### Docker Compose (Recommended)

```bash
# Download
wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
tar xvf harbor-offline-installer-v2.11.0.tgz
cd harbor

# Configure harbor.yml
hostname: registry.yourdomain.com
http:
  port: 80
https:
  port: 443
  certificate: /etc/harbor/ssl/cert.pem
  private_key: /etc/harbor/ssl/key.pem

harbor_admin_password: YourSecurePassword
database:
  password: root123
data_volume: /data

trivy:
  ignore_unfixed: false
  skip_update: false
  insecure: false

# Install
sudo ./install.sh --with-trivy
```

### Helm Chart (Kubernetes)

```bash
helm repo add harbor https://helm.goharbor.io
helm install harbor harbor/harbor 
  --namespace harbor --create-namespace 
  --set expose.type=ingress 
  --set expose.tls.auto.commonName=registry.yourdomain.com 
  --set externalURL=https://registry.yourdomain.com 
  --set trivy.enabled=true
```

## Usage

### Push Images

```bash
# Login
docker login registry.yourdomain.com
Username: admin
Password: YourPassword

# Tag image
docker tag myapp:latest registry.yourdomain.com/myproject/myapp:latest

# Push
docker push registry.yourdomain.com/myproject/myapp:latest

# Pull
docker pull registry.yourdomain.com/myproject/myapp:latest
```

### With Kubernetes

```yaml
# Create image pull secret
apiVersion: v1
kind: Secret
metadata:
  name: harbor-creds
type: kubernetes.io/dockerconfigjson
stringData:
  .dockerconfigjson: |
    {"auths": {"registry.yourdomain.com": {"username":"user","password":"pass","auth":"base64-encoded"}}}

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      imagePullSecrets:
        - name: harbor-creds
      containers:
        - name: myapp
          image: registry.yourdomain.com/myproject/myapp:latest
```

## Key Features

### Vulnerability Scanning

```
Push image → Automatic Trivy scan
  → CVE report with severity levels
  → Fail deployment if CVSS > threshold
  → Dashboard showing scan history
```

Configure scan policies per project:
- Auto-scan on push
- Prevent pulling vulnerable images
- Schedule periodic re-scans

### Projects & RBAC

```
Projects (Namespace equivalent):
├── engineering
│   ├── Members: Alice (Admin), Bob (Developer), Charlie (Guest)
│   ├── Quota: 100GB
│   └── Policies: Require scan, block critical CVEs
├── staging
│   └── Members: Ops team
└── public
    └── Anyone can pull
```

Roles: Project Admin, Master, Developer, Guest, Limited Guest.

### Replication

```yaml
# Sync from Docker Hub to Harbor
Rule: Replicate Docker Hub nginx
  Source: docker.io/library/nginx
  Destination: registry.yourdomain.com/library/nginx
  Trigger: Scheduled (every 6 hours)
  Filters: tag = "1.*.*-alpine"

# Sync between Harbor instances
Rule: Backup to DR site
  Source: registry.primary.com
  Destination: registry.dr.com
  Trigger: On push
```

Supported remote registries:
- Docker Hub, GitHub Container Registry, GCR, ECR, ACR
- Quay, JFrog Artifactory
- Other Harbor instances
- Helm chart repositories

### Image Signing with Cosign

```bash
# Sign image
cosign sign --key cosign.key registry.yourdomain.com/myproject/myapp:v1.0

# Verify
cosign verify --key cosign.pub registry.yourdomain.com/myproject/myapp:v1.0

# Harbor shows signature status in UI
```

### Retention Policies

```yaml
Project: production
Retention Rules:
  - Retain latest 10 pulled images
  - Retain images tagged "release-*" for 1 year
  - Delete images older than 30 days untagged
  - Run cleanup every Sunday at 02:00
```

## Harbor vs Alternatives

| Feature | Harbor | Docker Registry | Nexus | JFrog Artifactory |
|---------|--------|-----------------|-------|-------------------|
| Open Source | Yes | Yes | Yes (OSS) | No (paid) |
| Vulnerability scan | Trivy/Clair | No | IQ (paid) | Xray (paid) |
| RBAC | Yes | No | Yes | Yes |
| Replication | Yes | No | Yes | Yes |
| Helm charts | Yes | No | Yes | Yes |
| OCI compliant | Yes | Yes | Yes | Yes |
| Web UI | Beautiful | None | Yes | Yes |
| Multi-registry | Yes | No | Yes | Yes |

## FAQ

**Q: What's the difference between Harbor and Docker Registry?**
A: Docker Registry is just a base component for storing and distributing images (no auth, no UI). Harbor layers on a Web UI, RBAC, vulnerability scanning, image signing, replication, and other enterprise features. Harbor is strongly recommended for production.

**Q: How much storage space is needed?**
A: It depends on the number and size of images. Harbor uses deduplication, so identical layers are stored only once. A typical enterprise deployment should start with 500GB and can scale to terabytes as needed.

**Q: Does it support multi-replica / HA deployments?**
A: Yes. The Helm chart supports HA architectures: multi-replica Harbor components, external PostgreSQL cluster, external Redis, and shared storage (S3/NFS). Large enterprise deployments handle millions of pull requests per day.

## Sources & Credits

- GitHub: [goharbor/harbor](https://github.com/goharbor/harbor) — 28.2K+ ⭐ | Apache-2.0
- Official site: [goharbor.io](https://goharbor.io)

---
Source: https://tokrepo.com/en/workflows/harbor-cloud-native-trusted-container-registry-c9f4655f
Author: Script Depot