k8s-manifests-lib

README

Kubernetes Manifests Library

Introduction

The Kubernetes Manifests Library is a Go-based toolkit designed to simplify the management, transformation, and rendering of Kubernetes manifests. It provides a robust set of utilities for working with Kubernetes resources programmatically, making it easier to generate, modify, and validate Kubernetes configurations.

Use Cases

This library is designed to be embedded in Go applications and libraries, not as a replacement for kubectl, Helm, or Kustomize CLIs.

When to Use This Library

Use k8s-manifests-lib when you need to programmatically work with Kubernetes manifests in your Go code:

• Kubernetes Operators/Controllers: Deploy and manage components using Helm charts, Kustomize, or YAML templates
• GitOps Tools: Process, transform, and validate manifests before applying them
• CI/CD Pipelines: Customize manifests based on environment, inject labels/annotations, filter resources
• Multi-tenant Platforms: Generate tenant-specific configurations from shared templates
• Custom Deployment Tools: Build application-specific deployment logic with manifest rendering

When NOT to Use This Library

• Ad-hoc manifest operations: Use kubectl, helm, or kustomize CLI directly
• Manual deployments: Standard CLI tools are more appropriate
• Simple scripting: Shell scripts with CLI tools may be simpler

Key Differentiator

Unlike CLI tools, this library provides a Go API for manifest operations, enabling:

• Type-safe configuration
• Programmatic filtering and transformation
• Integration into larger Go applications
• Testable manifest rendering logic
• Complex composition of multiple sources

Features

• Manifest rendering from multiple sources (Helm, Kustomize, Go templates, YAML)
• Resource transformation and filtering with JQ expressions
• Filter composition with boolean logic (Or, And, Not) and conditionals
• Transformer composition with chaining, conditionals, and multi-branch logic
• Built-in metadata filters (namespace, labels, annotations, name)
• Built-in metadata transformers (namespace, labels, annotations, name)
• Type-safe Kubernetes resource definitions
• Three-level filtering/transformation pipeline (renderer-specific, engine-level, render-time)
• Extensible engine for custom processing
• Built-in caching with TTL support and automatic deep cloning
• Parallel rendering for I/O-bound renderers
• Functional options pattern for flexible configuration

Installation

go get github.com/lburgazzoli/k8s-manifests-lib

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/lburgazzoli/k8s-manifests-lib/pkg/engine"
    "github.com/lburgazzoli/k8s-manifests-lib/pkg/filter/jq"
    "github.com/lburgazzoli/k8s-manifests-lib/pkg/renderer/helm"
    "github.com/lburgazzoli/k8s-manifests-lib/pkg/transformer/meta/labels"
)

func main() {
    // Create a Helm renderer with initial configuration values
    helmRenderer, err := helm.New([]helm.Source{
        {
            Chart:       "oci://registry-1.docker.io/bitnamicharts/nginx",
            ReleaseName: "my-release",
            Values: helm.Values(map[string]any{
                "replicaCount": 3,
                "image": map[string]any{
                    "repository": "nginx",
                    "tag":        "1.25.0",
                },
            }),
        },
    })
    if err != nil {
        log.Fatalf("Failed to create Helm renderer: %v", err)
    }

    // Create a JQ filter for resource selection
    deploymentFilter, err := jq.Filter(`.kind == "Deployment"`)
    if err != nil {
        log.Fatalf("Failed to create deployment filter: %v", err)
    }

    // Create the engine with initial configuration
    e := engine.New(
        // Add the Helm renderer
        engine.WithRenderer(helmRenderer),
        // Add a filter to only keep Deployments
        engine.WithFilter(deploymentFilter),
        // Add a transformer to add a common label
        engine.WithTransformer(labels.Set(map[string]string{
            "app.kubernetes.io/managed-by": "my-operator",
        })),
    )

    // Render with additional render-time options
    ctx := context.Background()
    objects, err := e.Render(ctx,
        // Add a render-time transformer to add an environment label
        engine.WithRenderTransformer(labels.Set(map[string]string{
            "environment": "production",
        })),
        // Override Helm values at render-time (deep merged with configured values)
        engine.WithValues(map[string]any{
            "replicaCount": 5, // Override configured replicaCount (3 -> 5)
            "image": map[string]any{
                "tag": "1.26.0", // Override tag, repository stays "nginx"
            },
        }),
    )
    if err != nil {
        log.Fatalf("Failed to render: %v", err)
    }

    // Print the results
    fmt.Printf("Rendered %d objects:\n", len(objects))
    for _, obj := range objects {
        fmt.Printf("- %s/%s (%s)\n", obj.GetKind(), obj.GetName(), obj.GetNamespace())
        fmt.Printf("  Labels: %v\n", obj.GetLabels())
    }
}

This example demonstrates:

• Rendering Helm charts from OCI registries
• Filtering objects with JQ expressions
• Transforming objects with label additions
• Three-level filtering/transformation pipeline (renderer → engine → render-time)
• Render-time values: Override Helm values at render-time with deep merging

Examples

For specific use cases and patterns, see the examples directory:

• 01-basic/ - Simple single-renderer examples (helm, kustomize, yaml, gotemplate)
• 02-filtering/ - Filtering by namespace, labels, GVK, JQ
• 03-transformation/ - Transforming labels, annotations, namespace, name
• 04-composition/ - Boolean logic, conditionals, chaining, switch
• 05-advanced/ - Three-level pipeline, multi-environment, conditional transformations, complex nested
• 06-renderers/ - Multiple sources, multiple renderers, dynamic values, render-time values
• 07-caching/ - Basic cache, performance benchmarks
• 08-parallel/ - Parallel rendering
• 09-metrics/ - Basic metrics
• 10-source-annotations/ - Source tracking

See the Examples README for a complete catalog with a recommended learning path.

Each example is runnable: go run examples/<category>/<name>/main.go

Project Structure

Directory	Description
pkg/	Main package directory containing all library code
pkg/types/	Core type definitions (Renderer, Filter, Transformer)
pkg/renderer/	Renderer implementations (helm, kustomize, gotemplate, yaml, mem)
pkg/transformer/	Resource transformation utilities (jq, labels, annotations)
pkg/filter/	Resource filtering utilities (jq, gvk)
pkg/engine/	Core processing engine
pkg/util/	Common utility functions and cache implementation

Documentation

For detailed architecture and design information, see the Design Document.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the terms of the included License file.

Support

• GitHub Issues: https://github.com/lburgazzoli/k8s-manifests-lib/issues
• Documentation: https://github.com/lburgazzoli/k8s-manifests-lib/docs