Cashu Mint Operator

A Kubernetes operator for running CDK mintd with a single CashuMint custom resource. The operator manages the mint Deployment, generated config, Services, optional PostgreSQL, backups, ingress/TLS, Orchard, metrics, and sidecars so users can operate a Cashu mint with standard Kubernetes workflows instead of hand-managed YAML.

Documentation

• Docs: docs/index.md (rendered with mkdocs, see mkdocs.yml)
• Getting started: docs/getting-started.md
• Deployment guide: docs/deployment-guide.md
• Payment processors: docs/payment-processors.md
• Sample catalog: docs/samples.md
• API reference: docs/api-reference.md
• Troubleshooting: docs/troubleshooting.md

What the operator manages

• Deployment, ConfigMap, and Service for every mint
• PVCs for SQLite and Orchard state
• Auto-provisioned PostgreSQL Secret, Service, and StatefulSet
• S3 backup CronJob and restore Job for auto-provisioned PostgreSQL
• Ingress and optional cert-manager Certificate
• Optional Orchard companion resources
• Optional management RPC TLS Secret generation
• Optional PodMonitor when Prometheus metrics are enabled
• Optional gRPC payment processor sidecars and LDK node sidecars

Quick start

Install the latest release from git.cashu.dev:

TAG=$(curl -fsSL https://git.cashu.dev/api/v1/repos/asmo/cashu-operator/releases/latest \
  | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
kubectl apply -f "https://git.cashu.dev/asmo/cashu-operator/releases/download/${TAG}/install.yaml"

Or pin a version:

kubectl apply -f https://git.cashu.dev/asmo/cashu-operator/releases/download/v0.3.2/install.yaml

Deploy the minimal sample:

kubectl create namespace cashu-mints
kubectl apply -n cashu-mints \
  -f https://git.cashu.dev/asmo/cashu-operator/raw/branch/main/config/samples/mint_v1alpha1_cashumint_minimal.yaml
kubectl get cashumints -n cashu-mints -w

Access the mint:

kubectl -n cashu-mints port-forward svc/cashumint-minimal 8085:8085
curl http://localhost:8085/v1/info

Sample manifests

Scenario	Manifest
Minimal quick start (fakeWallet + SQLite)	mint_v1alpha1_cashumint_minimal.yaml
Annotated starter template	mint_v1alpha1_cashumint.yaml
Auto-provisioned PostgreSQL	mint_v1alpha1_cashumint_postgres_auto.yaml
External PostgreSQL	mint_v1alpha1_cashumint_external_postgres.yaml
LND backend	mint_v1alpha1_cashumint_lnd.yaml
CLN backend	mint_v1alpha1_cashumint_cln.yaml
External gRPC payment processor	mint_v1alpha1_cashumint_grpc_processor_external.yaml
Arkade Lightning sidecar processor	mint_v1alpha1_cashumint_arkade_processor.yaml
Spark/Breez or Stripe sidecar processors	mint_v1alpha1_cashumint_spark_breez.yaml, mint_v1alpha1_cashumint_stripe_processor.yaml
Orchard	mint_v1alpha1_cashumint_orchard_sqlite.yaml, mint_v1alpha1_cashumint_orchard_postgres.yaml
Auth, Redis cache, limits, metrics	mint_v1alpha1_cashumint_auth_httpcache.yaml
LDK node sidecar	mint_v1alpha1_cashumint_ldk_node.yaml
Production-style reference	mint_v1alpha1_cashumint_production.yaml

Development

Local development with Tilt + k3d

The recommended local workflow uses the dedicated k3d cluster defined in ctlptl-config.yaml.

make tilt-up

That command creates or updates a dedicated cashu-operator-dev k3d cluster with a local registry, switches kubectl to k3d-cashu-operator-dev, and starts Tilt against that context.

Once Tilt is running:

1. codegen regenerates manifests and deepcopy code when the API changes.
2. unit-tests is available as a manual Tilt resource for make test.
3. demo-mint is available as a manual Tilt resource to apply a minimal CashuMint from config/dev/.
4. demo-arkade-mint builds /Users/asm/git/cashu-arkade-lightning-procesor, imports cashu-arkade-lightning-procesor:dev into k3d, and applies the Arkade processor demo from config/dev/arkade/.

The Arkade demo image build defaults can be overridden with ARKADE_PROCESSOR_DIR, ARKADE_PROCESSOR_IMAGE, ARKADE_PROCESSOR_DOCKERFILE, and ARKADE_PROCESSOR_PLATFORM.

To inspect the demo mint after triggering demo-mint:

kubectl -n cashu-mints port-forward svc/cashumint-minimal 8085:8085
curl http://localhost:8085/v1/info

To inspect the Arkade processor demo after triggering demo-arkade-mint:

kubectl -n cashu-arkade port-forward svc/cashumint-arkade 8085:8085
curl http://localhost:8085/v1/info

To stop the local loop:

make tilt-down
make dev-cluster-delete

make build            # Build controller binary
make run              # Run controller locally against active kubeconfig
make dev-cluster-up   # Create/update the dedicated local k3d dev cluster
make tilt-up          # Start Tilt against the local k3d dev cluster
make tilt-down        # Stop Tilt and remove Tilt-managed resources
make dev-reset        # Tear down Tilt-managed resources and delete the dev cluster
make test             # Run unit tests
make test-e2e         # Run end-to-end tests (provisions Kind cluster)
make lint             # Run golangci-lint
make manifests        # Regenerate CRDs, RBAC, webhook configs
make generate         # Regenerate DeepCopy methods
make build-installer  # Generate dist/install.yaml

License

Apache 2.0 -- see LICENSE.

Persistent payment processor data

A stateful gRPC processor sidecar can require local storage even when the mint ledger uses PostgreSQL. Opt in on the CashuMint resource:

metadata:
  annotations:
    mint.cashu.asmogo.github.io/persist-processor-data: "true"
spec:
  replicas: 1
  storage:
    size: 10Gi

With an enabled gRPC processor sidecar, this annotation creates and mounts the mint data PVC using the existing storage settings, selects the Recreate deployment strategy, and rejects replica counts above one. The processor retains its existing sidecar-processor subdirectory mount. Without the annotation, existing storage and rollout behavior is unchanged. No CRD schema update is needed.

For an existing installation, preserve the old emptyDir contents and restore them to the PVC before enabling the annotation. The operator does not migrate files or convert processor database formats. Enabling or removing the annotation changes the data volume and can replace the pod. Recreate prevents overlapping wallet processes during normal deployment updates; it does not protect against force deletion or independently started instances using the same wallet identity.