README
¶
Kure
Kure is a Go library for describing a GitOps repository and writing it out as plain Kubernetes YAML. It is a domain model and a layout engine on a thin Kubernetes foundation:
- Domain model (
pkg/stack) — a Cluster → Node → Bundle → Application hierarchy that says what a cluster contains, independent of the GitOps tool that reconciles it. - Layout engine (
pkg/stack/layout,pkg/stack/fluxcd) — turns that hierarchy into a directory tree of manifests, with the Flux resources andkustomization.yamlfiles that make it reconcile. - Kubernetes foundation (
pkg/kubernetes) — the shared scheme, one generic constructor, the generated per-kind wrappers over it, and a small, admissible set of sugar helpers. The upstream Go struct is the construction API; kure adds identity and gets out of the way.
The foundation is deliberately thin. Constructors emit apiVersion, kind and identity and
nothing else, so an object kure builds is one you can reason about field by field against the
upstream type. The rules, and what they mean for a caller, are the
builder contract — the normative page for everything under
pkg/kubernetes/....
Features
- GitOps domain model: Cluster → Node → Bundle → Application (
pkg/stack) - Layout engine that writes a reconcilable directory tree,
kustomization.yamlfiles included - Flux workflow engine — the supported GitOps path; ArgoCD support exists but its bootstrap is not production-ready
- Generic
Create[T]plus a generated constructor for every registered kind — the count comes from the pinned upstream modules, so the kinds table states it and this page does not - CRD builders for cert-manager, Cilium, CloudNativePG, External Secrets, MetalLB, Prometheus Operator and VolSync
- Generated kinds, scope and field-maturity tables derived from the upstream modules this build pins, so "what does kure support" is answered from the pins rather than from prose
Installation
go get github.com/go-kure/kure
Documentation
- Website — guides, architecture, and tutorials
- Builder contract — normative: construction, sugar admission, purity, and where scope and maturity come from
- Supported kinds and field maturity — generated from the pinned modules
- Release-1 migration notes — every helper the builder contract removed, with the expression that replaces it
- API Reference — full Go package documentation
examples/— cluster configurations and patching samples
Development
- DEVELOPMENT.md — setup, build, test, and lint instructions
- CHANGELOG.md — release history
Quick commands:
make test # Run tests
make lint # Run linter
License
This project is licensed under the Apache License 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
getting-started
command
Package main demonstrates the complete Kure pipeline from Cluster definition to on-disk manifest directory.
|
Package main demonstrates the complete Kure pipeline from Cluster definition to on-disk manifest directory. |
|
internal
|
|
|
crds
Package crds reads the CustomResourceDefinition manifests a pinned module ships alongside its Go source: the scope a kind's definition declares, for the types whose own doc comment carries no +kubebuilder:resource marker, and the whole definition, for validating what kure emits against the schema the API server would hold it to.
|
Package crds reads the CustomResourceDefinition manifests a pinned module ships alongside its Go source: the scope a kind's definition declares, for the types whose own doc comment carries no +kubebuilder:resource marker, and the whole definition, for validating what kure emits against the schema the API server would hold it to. |
|
crdvalidate
Package crdvalidate validates custom resources the way the Kubernetes API server validates a create request, in process, against the CustomResourceDefinitions it is given and nothing else.
|
Package crdvalidate validates custom resources the way the Kubernetes API server validates a create request, in process, against the CustomResourceDefinitions it is given and nothing else. |
|
gotk
Package gotk carries the Flux toolkit install manifests kure vendors: the manifests.tar.gz asset of one flux2 release, embedded so that gotk-mode bootstrap generation, and the tests that read the toolkit's CustomResourceDefinitions out of it, need no network.
|
Package gotk carries the Flux toolkit install manifests kure vendors: the manifests.tar.gz asset of one flux2 release, embedded so that gotk-mode bootstrap generation, and the tests that read the toolkit's CustomResourceDefinitions out of it, need no network. |
|
kuretest
Package kuretest holds the test helpers that hold kure's output to what a cluster would accept: every object is validated, as the YAML a user would apply, against the CustomResourceDefinitions of the exact module versions the kinds registry pins, with the API server's own validation routines (crdvalidate).
|
Package kuretest holds the test helpers that hold kure's output to what a cluster would accept: every object is validated, as the YAML a user would apply, against the CustomResourceDefinitions of the exact module versions the kinds registry pins, with the API server's own validation routines (crdvalidate). |
|
pkg
|
|
|
errors
Package errors provides structured error types and handling utilities for the Kure library and kurel tool.
|
Package errors provides structured error types and handling utilities for the Kure library and kurel tool. |
|
gvk
Package gvk provides shared infrastructure for Group, Version, Kind (GVK) based type systems within Kure.
|
Package gvk provides shared infrastructure for Group, Version, Kind (GVK) based type systems within Kure. |
|
io
Package io provides utilities for reading, writing and parsing YAML representations of Kubernetes resources.
|
Package io provides utilities for reading, writing and parsing YAML representations of Kubernetes resources. |
|
kubernetes
Package kubernetes provides the scheme, the generic constructor and the admissible sugar helpers for building Kubernetes objects under the builder contract (ADR-038).
|
Package kubernetes provides the scheme, the generic constructor and the admissible sugar helpers for building Kubernetes objects under the builder contract (ADR-038). |
|
kubernetes/certmanager
Package certmanager exposes the generated constructors and the admissible sugar for cert-manager resources: Certificate, Issuer and ClusterIssuer.
|
Package certmanager exposes the generated constructors and the admissible sugar for cert-manager resources: Certificate, Issuer and ClusterIssuer. |
|
kubernetes/cilium
Package cilium exposes the generated constructors and the admissible sugar for Cilium resources: the network policies, CIDR groups, egress gateway and local redirect policies, load balancer IP pools, Envoy configs and the BGPv2 kinds.
|
Package cilium exposes the generated constructors and the admissible sugar for Cilium resources: the network policies, CIDR groups, egress gateway and local redirect policies, load balancer IP pools, Envoy configs and the BGPv2 kinds. |
|
kubernetes/cnpg
Package cnpg exposes the generated constructors and the admissible sugar for CloudNativePG (CNPG) and Barman Cloud plugin resources: Cluster, Database, Pooler, ScheduledBackup, ObjectStore and the image catalogs.
|
Package cnpg exposes the generated constructors and the admissible sugar for CloudNativePG (CNPG) and Barman Cloud plugin resources: Cluster, Database, Pooler, ScheduledBackup, ObjectStore and the image catalogs. |
|
kubernetes/externalsecrets
Package externalsecrets exposes the generated constructors and the admissible sugar for External Secrets Operator resources: ExternalSecret, SecretStore and ClusterSecretStore.
|
Package externalsecrets exposes the generated constructors and the admissible sugar for External Secrets Operator resources: ExternalSecret, SecretStore and ClusterSecretStore. |
|
kubernetes/fluxcd
Package fluxcd exposes helper functions for constructing resources used by the Flux family of controllers.
|
Package fluxcd exposes helper functions for constructing resources used by the Flux family of controllers. |
|
kubernetes/internal/admission
Package admission classifies the exported Set*/Add* sugar helpers under pkg/kubernetes by the builder contract's admission classes (ADR-038 §4).
|
Package admission classifies the exported Set*/Add* sugar helpers under pkg/kubernetes by the builder contract's admission classes (ADR-038 §4). |
|
kubernetes/internal/gen
command
Command gen emits the per-kind constructor wrappers under pkg/kubernetes and the kinds registry the identity test walks, from the registered scheme and the scope table in internal/kinds.
|
Command gen emits the per-kind constructor wrappers under pkg/kubernetes and the kinds registry the identity test walks, from the registered scheme and the scope table in internal/kinds. |
|
kubernetes/internal/kinds
Package kinds enumerates the object kinds registered in the pkg/kubernetes scheme and states each one's scope.
|
Package kinds enumerates the object kinds registered in the pkg/kubernetes scheme and states each one's scope. |
|
kubernetes/internal/markers
Package markers parses the controller-gen marker comments that upstream API types carry, so kure derives a kind's scope and a field's maturity from the pinned module sources instead of a hand-kept table.
|
Package markers parses the controller-gen marker comments that upstream API types carry, so kure derives a kind's scope and a field's maturity from the pinned module sources instead of a hand-kept table. |
|
kubernetes/internal/maturity
Package maturity reports which fields of the API types kure builds are gated, alpha, beta or deprecated upstream.
|
Package maturity reports which fields of the API types kure builds are gated, alpha, beta or deprecated upstream. |
|
kubernetes/internal/upstream
Package upstream loads the pinned API module sources that back the registered kinds, so scope and maturity are read from the modules kure actually builds against rather than from a table maintained by hand.
|
Package upstream loads the pinned API module sources that back the registered kinds, so scope and maturity are read from the modules kure actually builds against rather than from a table maintained by hand. |
|
kubernetes/metallb
Package metallb exposes helper functions for constructing MetalLB resources.
|
Package metallb exposes helper functions for constructing MetalLB resources. |
|
kubernetes/prometheus
Package prometheus exposes the generated constructors and the admissible sugar for Prometheus operator resources: ServiceMonitor, PodMonitor, PrometheusRule and the other monitoring.coreos.com kinds.
|
Package prometheus exposes the generated constructors and the admissible sugar for Prometheus operator resources: ServiceMonitor, PodMonitor, PrometheusRule and the other monitoring.coreos.com kinds. |
|
kubernetes/volsync
Package volsync exposes the generated constructors and the admissible sugar for VolSync (volsync.backube/v1alpha1) resources: ReplicationSource and ReplicationDestination.
|
Package volsync exposes the generated constructors and the admissible sugar for VolSync (volsync.backube/v1alpha1) resources: ReplicationSource and ReplicationDestination. |
|
logger
Package logger provides a structured logging interface for the Kure library.
|
Package logger provides a structured logging interface for the Kure library. |
|
manifest
Package manifest provides shared classification of Kubernetes manifests: recognizing CustomResourceDefinitions and determining the namespacing (scope) of an arbitrary object.
|
Package manifest provides shared classification of Kubernetes manifests: recognizing CustomResourceDefinitions and determining the namespacing (scope) of an arbitrary object. |
|
stack
Package stack provides the core domain model for defining and generating Kubernetes cluster configurations with GitOps tooling (Flux CD or ArgoCD).
|
Package stack provides the core domain model for defining and generating Kubernetes cluster configurations with GitOps tooling (Flux CD or ArgoCD). |
|
stack/helm
Package helm provides client-side Helm chart rendering from OCI registries and HTTP Helm repositories.
|
Package helm provides client-side Helm chart rendering from OCI registries and HTTP Helm repositories. |
|
stack/layout
Package layout provides utilities for generating cluster directory layouts and for writing Kubernetes and Flux manifests to disk.
|
Package layout provides utilities for generating cluster directory layouts and for writing Kubernetes and Flux manifests to disk. |
|
versions
Package versions exposes kure's supported-version metadata as a stable Go API, so consumers do not have to parse versions.yaml key paths by hand.
|
Package versions exposes kure's supported-version metadata as a stable Go API, so consumers do not have to parse versions.yaml key paths by hand. |
|
scripts
|
|
|
docapiindex
command
Command docapiindex builds the declaration index scripts/check-doc-api-refs.sh resolves documentation references against, by parsing the Go files it is given rather than matching their text.
|
Command docapiindex builds the declaration index scripts/check-doc-api-refs.sh resolves documentation references against, by parsing the Go files it is given rather than matching their text. |
|
docexamples
command
Command docexamples keeps the Go blocks of documentation pages in step with compiled Example functions, so a page cannot show code that no longer builds.
|
Command docexamples keeps the Go blocks of documentation pages in step with compiled Example functions, so a page cannot show code that no longer builds. |
Click to show internal directories.
Click to hide internal directories.