⚠️ Work in Progress
You are viewing development documentation built from the latest commit on main. APIs and features are subject to change.

Using Kure as a Library

Using Kure as a Library

Kure is primarily a Go library. This guide covers the basics of importing it, creating resources, and generating YAML output.

Installation

go get github.com/go-kure/kure

Creating Resources

Kure provides typed builder functions for Kubernetes and FluxCD resources.

FluxCD Resources

import "github.com/go-kure/kure/pkg/kubernetes/fluxcd"

// Create a GitRepository source
repo := fluxcd.GitRepository(&fluxcd.GitRepositoryConfig{
    Name:      "my-repo",
    Namespace: "flux-system",
    URL:       "https://github.com/org/repo",
    Branch:    "main",
    Interval:  "5m",
})

// Create a Kustomization that references the source
ks := fluxcd.Kustomization(&fluxcd.KustomizationConfig{
    Name:      "my-app",
    Namespace: "flux-system",
    Path:      "./clusters/production",
    Interval:  "10m",
    Prune:     true,
    SourceRef: kustv1.CrossNamespaceSourceReference{
        Kind: "GitRepository",
        Name: "my-repo",
    },
})

See the FluxCD Builders reference for all available resource types.

Beyond FluxCD, the Kubernetes Builders package provides typed constructors for core resources (Deployment, Service, Ingress, CronJob, NetworkPolicy, HTTPRoute), PSA security context helpers, ResourceRequirements builders, and more. The Prometheus Builders sub-package covers ServiceMonitor, PodMonitor, and PrometheusRule CRDs.

Generating YAML

Use the io package to serialize resources:

import "github.com/go-kure/kure/pkg/io"

// Serialize a single object
data, err := io.Marshal(deployment)

// Write multiple objects to stdout as YAML
err := io.PrintObjectsAsYAML(objects, os.Stdout)

// Save to file
err := io.SaveFile("output.yaml", deployment)

Clean YAML encoding

When encoding resources exported from a cluster, server-managed metadata fields (managedFields, resourceVersion, uid, etc.) clutter the output. The default encoding strips all of these automatically:

// Default: strips all server-set fields and uses standard key order
data, err := io.EncodeObjectsToYAMLWithOptions(objects, io.EncodeOptions{
    KubernetesFieldOrder: true,
})

Use ServerFieldStripping to control the level of stripping:

// Preserve server fields (e.g. for debugging)
data, err := io.EncodeObjectsToYAMLWithOptions(objects, io.EncodeOptions{
    ServerFieldStripping: io.StripServerFieldsNone,
})

See the IO reference for all output formats and stripping options.

Working with the Domain Model

For more complex scenarios, use the Stack package to define cluster topologies:

import "github.com/go-kure/kure/pkg/stack"

cluster := stack.NewClusterBuilder("production").
    WithNode("apps").
        WithBundle("web").
            WithApplication("frontend", frontendConfig).
        End().
    End().
    Build()

Then use the Flux Engine and Layout Engine to generate a complete GitOps repository structure. See the Generating Flux Manifests guide for the full workflow.

Error Handling

All Kure packages use the errors package:

import "github.com/go-kure/kure/pkg/errors"

if err != nil {
    return errors.Wrap(err, "failed to generate manifests")
}

Next Steps