hanzo-registry

Hanzo Registry is a private Docker container registry running Docker Distribution (registry:2) on hanzo-k8s, authenticated via Hanzo IAM token-based auth.

Hanzo Registry - Private Docker Container Registry

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-id.md, hanzo/hanzo-platform.md, hanzo/hanzo-universe.md

Overview

Hanzo Registry is a private Docker container registry running Docker Distribution (registry:2) on hanzo-k8s, authenticated via Hanzo IAM token-based auth. It carries container images and Helm charts, org-namespaced as <host>/<org>/<app>. Live at oci.hanzo.ai.

Why Hanzo Registry?

• IAM-integrated auth: Token-based auth via hanzo.id/v1/iam/registry/token
• S3-backed storage: object storage on hanzoai/s3, no PVC
• CORS-enabled: Supports browser-based registry operations
• Delete support: Image deletion enabled for cleanup workflows
• K8s-native: Runs as a Deployment in the hanzo namespace on hanzo-k8s

Tech Stack

• Image: registry:2 (Docker Distribution)
• Auth: JWT token-based via Hanzo IAM (Hanzo IAM)
• Storage: S3-backed (hanzoai/s3)
• Port: 5000 (ClusterIP service)
• CI: GitHub Actions deploy workflow with KMS-sourced credentials

OSS Base

Repo: hanzoai/registry (Apache 2.0).

When to use

• Pushing/pulling private Docker images for Hanzo services
• Hosting container images that should not be on public registries
• Integrating container workflows with Hanzo IAM authentication
• Self-hosting a Docker registry with OIDC-based access control

Hard requirements

1. Kubernetes cluster (hanzo-k8s) with the hanzo namespace
2. Hanzo IAM at hanzo.id for token-based authentication
3. Signing certificate (signing.crt / signing.key) as K8s secret registry-signing-key
4. S3 bucket on hanzoai/s3 with credentials in the s3-credentials secret

Quick reference

| Item | Value | |------|-------| | Endpoint | oci.hanzo.ai | | Repository path | oci.hanzo.ai/<org>/<app> | | Internal port | 5000 (ClusterIP) | | Auth realm | https://hanzo.id/v1/iam/registry/token | | Auth service | oci.hanzo.ai | | Token issuer | hanzo-iam | | Storage | S3 (hanzoai/s3) | | K8s namespace | hanzo | | Repo | github.com/hanzoai/registry | | License | Apache 2.0 |

One-file quickstart

Push and pull images

# Login (uses Hanzo IAM credentials)
docker login oci.hanzo.ai

# Push an image — repositories are org-namespaced
docker tag myapp:latest oci.hanzo.ai/hanzoai/myapp:latest
docker push oci.hanzo.ai/hanzoai/myapp:latest

# Pull an image
docker pull oci.hanzo.ai/hanzoai/myapp:latest

First-time setup

# Generate a self-signed signing certificate (10-year validity)
make generate-cert

# Create the K8s secret from local cert files
make create-secret

# Deploy to hanzo-k8s
make deploy

Operations

# Check deployment status
make status

# Tail logs
make logs

# Restart pods
make restart

Core Concepts

Architecture

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Docker Client │────>│ oci.hanzo.ai     │────>│ Hanzo IAM │
│ (push/pull) │ │ (registry:2) │ │ (token realm) │
└─────────────────┘ └────────┬─────────┘ └─────────────────┘
 │
 ┌──────┴─────────┐
 │ hanzoai/s3 │
 │ (object store) │
 └────────────────┘

Auth Flow

1. Docker client attempts to push/pull from oci.hanzo.ai
2. Registry returns 401 with token realm URL (hanzo.id/v1/iam/registry/token)
3. Client requests token from IAM, providing credentials
4. IAM validates credentials and returns a signed JWT (issuer: hanzo-iam)
5. Client retries with JWT in Authorization header
6. Registry validates JWT signature against signing.crt mounted from K8s secret

Registry Configuration

The auth and http stanzas of config.yml — the storage driver is S3, configured from the s3-credentials secret:

version: 0.1
http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
    Access-Control-Allow-Origin: ['https://oci.hanzo.ai']
    Access-Control-Allow-Methods: ['HEAD', 'GET', 'OPTIONS', 'DELETE']
auth:
  token:
    realm: https://hanzo.id/v1/iam/registry/token
    service: oci.hanzo.ai
    issuer: hanzo-iam
    rootcertbundle: /etc/registry-signing/signing.crt

K8s Resources

• Deployment: 1 replica, registry:2 image, 100m/128Mi request, 500m/512Mi limit
• Service: ClusterIP on port 5000
• Secret: registry-signing-key with signing.crt mounted to /etc/registry-signing/
• Secret: s3-credentials (KMS-synced) for the object store

CI/CD

The deploy.yml workflow triggers on push to main (when k8s/ or config.yml change) or manual dispatch:

1. Fetches DO_API_TOKEN from KMS via Universal Auth
2. Configures kubectl via doctl kubernetes cluster kubeconfig save hanzo-k8s
3. Applies K8s manifests (kubectl apply -f k8s/)
4. Restarts and waits for rollout

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | 401 on push/pull | Missing or expired IAM token | docker login oci.hanzo.ai | | Certificate error | signing.crt not mounted | Verify registry-signing-key secret exists | | Push denied to a bare name | Repositories are org-namespaced | Tag as oci.hanzo.ai/<org>/<app> | | CORS errors | Browser request blocked | Check Access-Control-Allow-Origin in config.yml |

Related Skills

• hanzo/hanzo-id.md - IAM and authentication (token realm)
• hanzo/hanzo-platform.md - PaaS deployment platform
• hanzo/hanzo-universe.md - Production K8s infrastructure
• hanzo/hanzo-kms.md - Secret management (deploy credentials)

---

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: registry, docker, containers, iam Prerequisites: Docker CLI, Kubernetes, Hanzo IAM credentials