Hanzo Operator

Overview

Why Hanzo Operator?

Feedback
Declarative infrastructure: Define an entire Hanzo service, datastore, or network in one CR
Feedback
7 CRDs: HanzoService, HanzoDatastore, HanzoGateway, HanzoMPC, HanzoNetwork, HanzoIngress, HanzoPlatform
Feedback
Idempotent reconciliation: Uses ctrl.CreateOrUpdate with MutateFuncFor for safe convergence
Feedback
KMS integration: Automatically creates kms.hanzo.ai/v1alpha1 KMSSecret CRs for secret management
Feedback
Owner references: Full GC cascade -- deleting the parent CR cleans up all children
Feedback
Phase lifecycle: Pending, Creating, Running, Degraded, Deleting

Tech Stack

Feedback
Language: Go 1.26
Feedback
Framework: Kubebuilder v4, controller-runtime v0.23.1
Feedback
K8s API: k8s.io/* v0.35.0
Feedback
Image: ghcr.io/hanzoai/operator:latest
Feedback
Namespace: hanzo-operator-system
Feedback
Stats: 28 Go source files, ~7,400 lines, 13,022 lines CRD YAML

When to use

Feedback
Deploying Hanzo services to Kubernetes declaratively
Feedback
Managing API gateways (KrakenD-based) via HanzoGateway
Feedback
Provisioning datastores (PostgreSQL, Redis, MongoDB) via HanzoDatastore
Feedback
Running blockchain validator networks via HanzoNetwork
Feedback
Managing multi-party computation infrastructure via HanzoMPC
Feedback
Orchestrating a full Hanzo platform stack via HanzoPlatform

Hard requirements

Feedback
Kubernetes v1.11.3+ cluster with CRD support
Feedback
cert-manager for TLS (used by HanzoIngress)
Feedback
KMS operator (kms.hanzo.ai) for KMSSecret reconciliation
Feedback
RBAC permissions: core, apps, autoscaling, batch, networking, policy, hanzo.ai/, kms.hanzo.ai/

Quick reference

CRD Reference

Repository Structure

api/v1alpha1/
  common_types.go              # Shared types (ContainerSpec, IngressSpec, etc.)
  hanzoservice_types.go        # HanzoService CRD spec
  hanzodatastore_types.go      # HanzoDatastore CRD spec
  hanzogateway_types.go        # HanzoGateway CRD spec
  hanzompc_types.go            # HanzoMPC CRD spec
  hanzonetwork_types.go        # HanzoNetwork CRD spec
  hanzoingress_types.go        # HanzoIngress CRD spec
  hanzoplatform_types.go       # HanzoPlatform CRD spec
  types.go                     # Additional shared types
  zz_generated.deepcopy.go     # Generated DeepCopy methods
cmd/
  main.go                      # Manager entry point
internal/
  controller/
    hanzoservice_controller.go   # HanzoService reconciler
    hanzodatastore_controller.go # HanzoDatastore reconciler
    hanzogateway_controller.go   # HanzoGateway reconciler
    hanzompc_controller.go       # HanzoMPC reconciler
    hanzonetwork_controller.go   # HanzoNetwork reconciler
    hanzoingress_controller.go   # HanzoIngress reconciler
    hanzoplatform_controller.go  # HanzoPlatform reconciler
    predicates.go                # Event filters (createOrUpdatePred, etc.)
    helpers.go                   # Shared controller utilities
  manifests/                     # K8s object builders (builder, labels, mutate)
  status/                        # Condition management
  metrics/                       # Prometheus metrics
  config/                        # Feature gates
config/
  crd/bases/                     # Generated CRD YAML (13k lines)
  rbac/                          # ClusterRole, bindings
  manager/                       # Deployment template
  samples/                       # Sample CRs for all 7 CRDs
Dockerfile                       # Multi-stage Go build (Alpine)
Makefile                         # Build, test, deploy targets

Build and Deploy

# Regenerate CRDs and DeepCopy
make manifests generate

# Build local binary
make build

# Run tests
make test

# Build Docker image
make docker-build IMG=ghcr.io/hanzoai/operator:latest

# Build and push (multi-platform)
docker buildx build --platform linux/amd64 --push -t ghcr.io/hanzoai/operator:latest .

# Install CRDs into cluster
make install

# Deploy operator
make deploy IMG=ghcr.io/hanzoai/operator:latest

# Apply sample CRs
kubectl apply -k config/samples/

Production Deployment

kubectl apply -k universe/infra/k8s/hanzo-operator/

Key Patterns

Feedback
Predicate filtering: createOrUpdatePred, updateOrDeletePred, statusChangePred control which events trigger reconciliation
Feedback
CreateOrUpdate with MutateFuncFor: Idempotent object reconciliation -- creates if missing, patches if changed
Feedback
Owner references: All child objects have owner refs for automatic garbage collection
Feedback
Phase lifecycle: Resources transition through Pending, Creating, Running, Degraded, Deleting
Feedback
KMSSecret delegation: Operator creates kms.hanzo.ai/v1alpha1 KMSSecret CRs; the existing KMS operator handles actual secret sync from kms.hanzo.ai

Troubleshooting

Related Skills

Feedback
hanzo/hanzo-charts.md - Helm charts (alternative to operator CRDs)
Feedback
hanzo/hanzo-universe.md - Universe manifests (where operator is deployed)
Feedback
hanzo/hanzo-kms.md - KMS for secret management (KMSSecret CRs)
Feedback
hanzo/hanzo-platform.md - PaaS platform (managed by HanzoPlatform CRD)