generators

README

Generators - Application Generator System

The generators package provides a type-safe system for creating Kubernetes application workloads from configuration. Generators implement the stack.ApplicationConfig interface, allowing them to be used as applications within the domain model.

Overview

Generators use the GroupVersionKind (GVK) type system to identify and instantiate application configurations. Each generator is registered in a global registry and can be referenced by its GVK identifier.

Available Generators

Generator	GVK	Description
AppWorkload	generators/AppWorkload	General-purpose application workload with Deployment, Service, ConfigMap
FluxHelm	generators/FluxHelm	HelmRelease-based application using Flux
KurelPackage	generators/KurelPackage	Kurel package reference for pre-built application packages

Usage

Creating a Generator from GVK

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

// Look up generator by GVK
factory, err := generators.GetGenerator("generators/AppWorkload")

// Create application config from YAML configuration
config, err := factory.FromConfig(yamlData)

// Use in domain model
app := stack.NewApplication("my-app", "default", config)

YAML Configuration Format

Generators are typically configured via YAML:

apiVersion: generators/v1
kind: AppWorkload
metadata:
  name: my-web-app
spec:
  image: nginx:1.25
  replicas: 3
  ports:
    - containerPort: 80
      servicePort: 80
  env:
    - name: LOG_LEVEL
      value: info

Registry

Register custom generators:

generators.Register("mycompany/CustomApp", &MyGeneratorFactory{})

Query available generators:

// List all registered generator GVKs
gvks := generators.ListRegistered()

Sub-packages

appworkload

General-purpose application generator that produces:

• Deployment with configurable replicas, image, resources
• Service with port mappings
• Optional ConfigMap for configuration data
• Optional ServiceAccount

fluxhelm

Generates Flux HelmRelease resources for Helm-based applications:

• HelmRelease with chart reference
• HelmRepository source (if needed)
• Values configuration

kurelpackage

References kurel packages as applications within the stack hierarchy, enabling package-based deployments in cluster definitions.

Related Packages

• stack - Core domain model and ApplicationConfig interface
• stack/fluxcd - Flux workflow engine

Documentation

Overview

Package generators provides a pluggable system for generating Kubernetes resources from different configuration formats. It implements a registry pattern with Group, Version, Kind (GVK) identification following Kubernetes conventions.

Documentation

For detailed documentation, see:

• DESIGN.md: High-level design and GVK system overview
• ARCHITECTURE.md: Implementation patterns and conventions
• STATUS.md: Current development status and roadmap

Architecture

The package uses a registry pattern where each generator type:

• Is identified by a GVK (Group, Version, Kind)
• Implements the ApplicationConfig interface
• Is organized in its own subpackage
• Supports multiple versions (v1alpha1, v1beta1, v1, etc.)

Generator Organization

Each generator type is organized as:

generators/
├── <type>/                 # Generator type package
│   ├── v1alpha1.go        # Version implementation
│   ├── v1beta1.go         # Future version
│   ├── internal/          # Internal implementation
│   │   └── <type>.go      # Core logic
│   └── doc.go             # Package documentation

Available Generators

• appworkload: Standard Kubernetes workloads (Deployments, StatefulSets, DaemonSets)
• fluxhelm: Flux HelmRelease with various source types

Registration

Generators self-register during package initialization:

func init() {
    generators.Register(generators.GVK{
        Group:   "generators.gokure.dev",
        Version: "v1alpha1",
        Kind:    "MyGenerator",
    }, func() interface{} {
        return &MyGeneratorV1Alpha1{}
    })
}

Usage

Generators are typically used through the ApplicationWrapper:

var wrapper stack.ApplicationWrapper
err := yaml.Unmarshal(yamlData, &wrapper)
if err != nil {
    // handle error
}

app := wrapper.ToApplication()
resources, err := app.Config.Generate(app)

Creating New Generators

To create a new generator:

1. Create a new package under generators/<type> 2. Implement the ApplicationConfig interface 3. Add version files (v1alpha1.go, etc.) 4. Register in init() function 5. Add documentation

Version Evolution

Generators support version evolution:

• v1alpha1: Initial implementation, API may change
• v1beta1: API stabilizing, backward compatibility within beta
• v1: Stable API, backward compatibility guaranteed

When adding new versions, implement conversion interfaces to support migration between versions.

Index

• Variables
• func Create(apiVersion, kind string) (stack.ApplicationConfig, error)
• func CreateFromGVK(gvkObj GVK) (stack.ApplicationConfig, error)
• func HasKind(apiVersion, kind string) bool
• func Register(gvk GVK, factory ApplicationConfigFactory)
• type ApplicationConfigFactory
• type BaseMetadata
• type Convertible
• type GVK
  • func ListKinds() []GVK
• type MetadataConfig
• type NamedConfig
• type NamespacedConfig
• type VersionedType

Variables

var (
	ParseAPIVersion = gvk.ParseAPIVersion
)

Re-export common functions for backward compatibility

Functions

func Create

func Create(apiVersion, kind string) (stack.ApplicationConfig, error)

Create creates a new ApplicationConfig instance for the given apiVersion and kind

func CreateFromGVK

func CreateFromGVK(gvkObj GVK) (stack.ApplicationConfig, error)

CreateFromGVK creates a new ApplicationConfig instance for the given GVK

func HasKind

func HasKind(apiVersion, kind string) bool

HasKind checks if a GVK is registered in the global registry

func Register

func Register(gvk GVK, factory ApplicationConfigFactory)

Register adds a new ApplicationConfig type to the global registry

Types

type ApplicationConfigFactory

type ApplicationConfigFactory = gvk.Factory[stack.ApplicationConfig]

ApplicationConfigFactory is a function that creates a new ApplicationConfig instance

type BaseMetadata

type BaseMetadata = gvk.BaseMetadata

BaseMetadata provides common metadata fields for generators

type Convertible

type Convertible = gvk.Convertible

type GVK

type GVK = gvk.GVK

Re-export GVK type for backward compatibility

func ListKinds

func ListKinds() []GVK

ListKinds returns all registered GVKs from the global registry

type MetadataConfig

type MetadataConfig = gvk.MetadataType

type NamedConfig

type NamedConfig = gvk.NamedType

type NamespacedConfig

type NamespacedConfig = gvk.NamespacedType

type VersionedType

type VersionedType = gvk.VersionedType

Re-export interfaces from internal/gvk for backward compatibility