diff --git a/tech_docs/CUE.md b/tech_docs/CUE.md index 36407a4..435322f 100644 --- a/tech_docs/CUE.md +++ b/tech_docs/CUE.md @@ -169,4 +169,27 @@ Reply with the **number** you want to pursue (or say “new batch”) and I’ll 1. Minimal CUE schema 2. Exact `docker-compose.yml` generator snippet -3. One-liner to run it on a fresh Debian install \ No newline at end of file +3. One-liner to run it on a fresh Debian install + + +Yes — there are **very concrete reasons** to pair **Go + CUE** that do **not** apply (or apply only weakly) to other language stacks. +Below is a concise decision grid you can paste into an ADR or RFC. + +| Benefit | Why it matters | Go + CUE | Other stacks | +|---------|----------------|----------|--------------| +| **Single binary, zero runtime** | Shipping a CLI to ops/DevOps that “just works” | `go build` produces a static binary that embeds CUE via `cuelang.org/go` | Node, Python, etc. need a runtime and dependency tree | +| **Schema ↔ code round-trip** | Keep Go structs as the source-of-truth and still get CUE validation | `cue get go k8s.io/api/apps/v1` auto-generates CUE from Go types; `cue export` can spit JSON/YAML back out | Other languages have to hand-write schemas or use separate tools | +| **Cloud-native lingua franca** | Every major infra tool (K8s, Terraform, Helm, Docker, Dagger, Argo CD) is written in Go | You can import their Go packages and generate CUE constraints **without** re-implementing anything | Python/Node/Java must FFI or re-implement | +| **Rich Go API** | Load, unify, validate, diff, trim configs inside your program | Full lattice operations (unify, subsumption, export) via `cuecontext` and `cue/load` | Only shell-out or WASM today for non-Go | +| **Performance** | Parse & validate 1000s of YAML manifests in CI | Pure Go, no CGO; benchmarks show ~2× faster than Starlark/Jsonnet on large k8s repos | Python/Node bindings pay serialization cost | +| **Policy-as-code reuse** | Embed the same constraints in admission webhooks, CLIs, or controllers | Import CUE in Go controller code; compile once, run everywhere | Rego (OPA) needs separate runtime; Jsonnet is turing-complete & slower | +| **Community & tooling** | KubeVela, Dagger, Grafana, Holos, etc. all expose Go SDKs that expect CUE | Shared libraries and examples | Smaller, fragmented ecosystems outside Go | + +### When **not** to pick Go + CUE +- Your service is **purely browser/Node** → TypeScript + JSON Schema or Zod is lighter. +- You need **end-user scripting** (e.g., Terraform custom providers) → HCL/Starlark still wins on mind-share. +- You target **resource-constrained embedded** → CUE’s Go runtime is heavier than a hand-rolled C validator. + +### TL;DR +If you are already in the Go / cloud-native orbit, **Go + CUE is the only combination today that lets you keep your existing types, ship a single static CLI, and reuse the exact same constraints in controllers, CI, and documentation generators** . +