fluxcd

package
v0.2.0-beta.12 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 22, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

README

Flux Engine - FluxCD Workflow Implementation

Go Reference

The fluxcd package implements the stack.Workflow interface for FluxCD, providing complete Flux resource generation from domain model definitions.

Overview

The Flux engine transforms Kure's hierarchical domain model (Cluster, Node, Bundle, Application) into FluxCD resources (Kustomizations, source references) organized in a GitOps-ready directory structure.

The engine is composed of three specialized components:

Component Responsibility
ResourceGenerator Generates Flux resources from domain objects
LayoutIntegrator Integrates resources into directory structures
BootstrapGenerator Creates Flux bootstrap manifests

Quick Start

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

// Create engine with defaults
engine := fluxcd.Engine()

// Generate all Flux resources for a cluster
objects, err := engine.GenerateFromCluster(cluster)

// Or with a specific kustomization mode
engine = fluxcd.EngineWithConfig(layout.KustomizationExplicit)

// Placement is set on the LayoutRules passed to the layout call,
// not on the engine — see Layout Integration below.

Engine Construction

// Default engine
engine := fluxcd.Engine()

// Engine with specific kustomization mode
engine := fluxcd.EngineWithMode(layout.KustomizationExplicit)

// Engine with a specific kustomization mode (alias)
engine := fluxcd.EngineWithConfig(mode)

// Engine with custom components
engine := fluxcd.NewWorkflowEngine()

Placement (FluxIntegratedPerLayout vs FluxSeparate) is configured per call on layout.LayoutRules.FluxPlacement. FluxUnset is normalized to FluxSeparate by LayoutIntegrator.CreateLayoutWithResources — matching layout.DefaultLayoutRules() and the walker. See Layout Integration.

Resource Generation

Generate Flux resources at different hierarchy levels:

// From entire cluster
objects, err := engine.GenerateFromCluster(cluster)

// From a single node
objects, err := engine.GenerateFromNode(node)

// From a single bundle
objects, err := engine.GenerateFromBundle(bundle)

Each bundle produces a Flux Kustomization resource with:

  • Path matching the layout directory structure
  • Source reference from the node's package ref
  • Dependency ordering from Bundle.DependsOn
  • Interval and pruning configuration

Defaults are declared, named and exported

This package is a workflow layer above pkg/kubernetes, so unlike the builders it may hold opinions — but only as declared inputs with names a consumer can read, compare against and override. Every fallback this package applies is one of the exported identifiers in defaults.go, or comes from layout.DefaultLayoutRules() where the value belongs to pkg/stack/layout; grep for the identifier to find every place its value can reach emitted YAML.

Identifier Value Applies when Override by
DefaultInterval 60m the caller names no interval, or names one that does not parse assigning .DefaultInterval on either generator
DefaultNamespace flux-system generated resources need a namespace assigning .DefaultNamespace on either generator
DefaultMode layout.KustomizationExplicit ResourceGenerator is constructed — its only site assigning ResourceGenerator.Mode
DefaultBootstrapName flux-system naming the bootstrap Kustomization and the FluxInstance assigning BootstrapGenerator.BootstrapName
DefaultSourceName flux-system the root node has no name naming the root stack.Node
DefaultFluxMode flux-operator BootstrapConfig.FluxMode is empty setting BootstrapConfig.FluxMode
DefaultSourceKind OCIRepository BootstrapConfig.SourceKind does not name GitRepository, the empty string included setting BootstrapConfig.SourceKind
DefaultBootstrapPathRoot manifests building the bootstrap Kustomization's spec.path not overrideable; the root node's name is joined onto it
DefaultFluxDirName flux-system a separate Flux layout needs a directory not overrideable
DefaultSourceRef latest an OCI source, or an OCI FluxInstance sync, has no SourceRef setting BootstrapConfig.SourceRef
DefaultSyncPath ./ the root node has no name not overrideable; it is the prefix a sync path is built from

Four of these — DefaultInterval, DefaultNamespace, DefaultMode and DefaultBootstrapName — are copied into exported generator fields by NewResourceGenerator / NewBootstrapGenerator, and a field assigned afterwards is never overridden. The rest are applied where they are used and are overridden by naming the corresponding input, as the last column says. Three have no override at all and say so, rather than being listed as though they had one.

An empty BootstrapGenerator.BootstrapName resolves back to DefaultBootstrapName at emission. A generator built as a struct literal rather than through NewBootstrapGenerator leaves the field zero, and a Kustomization or FluxInstance with no metadata.name is invalid — the field is an override, not a way to remove the name.

DefaultNamespace governs the whole gotk bundle, not just the objects this package constructs itself. The bootstrap bundle has three producers — the root Kustomization, the root source, and the toolkit components generated by install.Generate — and the third takes its namespace from an upstream option whose own default is also flux-system. That option is set from BootstrapGenerator.DefaultNamespace, so overriding the field moves the controllers' Deployments, ServiceAccounts, Services, NetworkPolicies and ResourceQuota along with everything else. The cluster-scoped objects follow without further work — install.Generate derives the emitted Namespace's name and the ClusterRoleBinding names and subjects from the same option, while CRDs and ClusterRoles carry no namespace to correct. Before this was wired up the field half-applied: a non-default value left the components in flux-system while the objects depending on them moved. That split still reconciles, because the components default to WatchAllNamespaces: true — so it surfaces only when someone narrows the controllers to their own namespace, at which point reconciliation stops with no error. WatchAllNamespaces is deliberately left at the upstream default and is not currently derived from any field here.

In flux-operator mode — the default — the field reaches only the FluxInstance. That bundle's other objects come from the vendored upstream install manifest, appended unmodified, so its Namespace, ServiceAccount, Service and Deployment stay at the upstream flux-system whatever this field says. Relocating the operator itself is not something this package offers.

The wiring is guarded on the field being non-empty, which matters only for a struct-literal generator. install.Generate uses the option as the emitted Namespace's name, so assigning it unconditionally would make a generator with a zero DefaultNamespace fail the whole bundle — missing metadata.name in object {{v1 Namespace}} — rather than fall back. Guarded, that generator keeps the upstream flux-system for the components.

That generator is nonetheless inconsistent, and the guard does not fix it: the root Kustomization and the root source read the same empty value and emit no namespace at all, so the components sit in flux-system while the objects referencing them are unnamespaced. This predates the namespace wiring and is a property of struct-literal construction across this package rather than of one option. Construct through NewBootstrapGenerator, which populates the field; a struct literal is not a supported way to get a coherent bundle.

defaults.go also declares ModeGotk = "gotk", which is not a default: nothing falls back to it. It is named so that the bootstrap mode set has one authority. DefaultFluxMode is both the fallback for an empty BootstrapConfig.FluxMode and the mode GenerateBootstrap dispatches on, and SupportedBootstrapModes() reports exactly those two — the validation error for an unrecognised mode reads its list from that method rather than restating the names.

DefaultFluxDirName shares DefaultNamespace's value and is deliberately a separate identifier: one is a path segment and the other a Kubernetes namespace, and renaming the namespace must not silently rename the directory.

Three defaults are not declared here because this package does not own them. The separate Flux layout's file granularity and the fallback for an unset FluxPlacement both come from layout.DefaultLayoutRules(), which is where pkg/stack/layout declares them and where its own walker reads them from. A constant here would be a second copy of a value that can change independently.

The third is that layout's own Mode, left unset rather than seeded from DefaultMode. The layout writer resolves an unset mode to KustomizationExplicit, and the separate Flux layout never has children, so the mode selects nothing there — seeding it would have implied an override via ResourceGenerator.Mode at a site that never reads that field.

One resolved source kind, not three

resolvedSourceKind is the only place the source kind is decided. Three sites need it — the source object itself, the bootstrap Kustomization's spec.sourceRef.Kind, and the FluxInstance sync block — and they used to decide it separately, with the sourceRef testing for OCIRepository while the other two tested for GitRepository. The three agreed only when SourceKind named a kind exactly; an empty or unrecognised SourceKind emitted an OCIRepository under a sourceRef naming a GitRepository that was never created.

One resolved source ref, on both bootstrap paths

For an OCI tag, an empty ref or a bare Git branch name, BootstrapConfig.SourceRef selects the same revision in both modes. The gotk source reads it as an OCI tag, falling back to DefaultSourceRef, or as a Git branch. flux-operator renders the FluxInstance's spec.sync.ref as the source's ref.tag for OCI and as ref.name for Git, and ref.name takes a full Git reference. resolvedSyncRef bridges the two: an empty OCI ref becomes DefaultSourceRef, a Git branch name becomes refs/heads/<name>, and an empty Git ref stays empty. A Git ref that already starts with refs/ — a tag, say — passes through unchanged in flux-operator mode only: the gotk source still puts any Git SourceRef into ref.branch, so there a full reference is not equivalent. Before this, spec.sync.ref was SourceRef verbatim: an empty OCI tag where the gotk source used latest, and a bare branch name where Flux needs a full reference.

prune and wait are inputs, not policy

Bundle.Prune and Bundle.Wait are *bool and are passed through untouched. BootstrapConfig.Prune does the same for the bootstrap Kustomization, and ResourceGenerator.Prune for Kustomizations generated from a layout.ManifestLayout, which carries no prune setting of its own.

The two fields resolve differently because their upstream tags differ:

  • KustomizationSpec.Prune is +required with no omitempty, so an unset input cannot leave the key out. Unset emits prune: false — garbage collection off. An unset tri-state previously collapsed onto prune: true, enabling destructive garbage collection for a caller who never asked for it.
  • KustomizationSpec.Wait is +optional with omitempty, so unset and false produce the same YAML: the key is absent and Flux's own default, false, applies.

Sources (GitRepository, OCIRepository) and the FluxInstance are built the way the builder contract prescribes: the pkg/kubernetes/fluxcd Create<Kind> constructor returns a typed object, and the generator assigns the plain fields directly.

gr := pubfluxcd.CreateGitRepository(ref.Name, namespace)
gr.Spec.URL = ref.URL
gr.Spec.Interval = metav1.Duration{Duration: g.DefaultInterval}

Only writes that the contract admits as sugar keep a helper — appending to a slice field, or assigning a pointer field through a constructed value, as with SetGitRepositoryReference. See Kubernetes Builders for the admission rules.

Layout Integration

Combine resource generation with directory structure:

// Create layout with Flux resources integrated
ml, err := engine.CreateLayoutWithResources(cluster, rules)

// Write to disk
err = layout.WriteManifest(ml, "./clusters")

Bootstrap Generation

Generate Flux system bootstrap manifests. Two modes are supported:

Mode Description
"flux-operator" Default. Emits a full Flux Operator install bundle (CRDs, Deployment, RBAC). Recommended for new clusters.
"gotk" Legacy mode. Emits the GitOps Toolkit component manifests directly.

When FluxMode is empty, it defaults to "flux-operator".

The "flux-operator" bundle is vendored from the upstream flux-operator release and pinned in lockstep with the github.com/controlplaneio-fluxcd/flux-operator Go module (FluxOperatorVersion, currently v0.58.1). Renovate re-vendors the bundle and updates the constant and this version when it bumps the module (scripts/sync-flux-operator-pin.sh); see flux_operator_install.go for the manual refresh procedure.

bootstrapConfig := &stack.BootstrapConfig{
    Enabled:     true,
    FluxMode:    "flux-operator", // or "gotk"; empty defaults to "flux-operator"
    FluxVersion: "v2.8.2",
    SourceRef:   sourceRef,
}

objects, err := engine.GenerateBootstrap(bootstrapConfig, rootNode)
Sync name

BootstrapConfig.SyncName becomes the FluxInstance's spec.sync.name: the name flux-operator gives the source and Kustomization it creates for the sync. When it is empty the operator names both after the FluxInstance's namespace (DefaultNamespace). That fallback is the operator's, not kure's, which is why the defaults table above has no row for it. Set SyncName when the Kustomizations you generate reference the sync source by another name; otherwise their sourceRef points at a source nothing creates.

bootstrapConfig := &stack.BootstrapConfig{
    Enabled:   true,
    SourceURL: "oci://registry.example.com/fleet",
    SourceRef: "latest",
    SyncName:  "fleet",
}
  • flux-operator mode only: gotk mode ignores it, as flux-operator mode ignores Prune.
  • It needs SourceURL: without one no sync block is emitted, so there is nothing to name.
  • kure passes it through unvalidated. The CRD caps it at 63 characters and makes it immutable once set, so renaming the sync of a live cluster means recreating the FluxInstance.
  • It is not BootstrapGenerator.BootstrapName, which names the FluxInstance itself.

Configuration

Kustomization Mode

Controls how kustomization.yaml files reference resources:

  • KustomizationExplicit - Lists all manifest files explicitly
  • KustomizationRecursive - References subdirectories only
Flux Placement

Controls where Flux Kustomization resources are placed:

  • FluxSeparate - Flux resources collected in a separate directory tree; children referenced as directories
  • FluxIntegratedPerLayout - a Flux Kustomization CR for every layout node (incl. augmenter-added child layouts), placed alongside its manifests; children referenced as kustomization-<child>.yaml CR files. Finest granularity.
  • FluxIntegratedPerBundle - Flux Kustomization CRs at bundle/node boundaries only; a bundle's interior (incl. augmenter-added child layouts) is a single kustomize build, with children referenced as directories. Coarser: Flux reconciles per bundle, kustomize handles the interior.

External augmenters may add child layouts that are not represented in the bundle model; integrated placement discovers those layouts and emits the required Flux resources.

Umbrella Bundles

A Bundle with a non-empty Children slice becomes an umbrella: a parent Flux Kustomization that aggregates the readiness of its children via auto-generated spec.healthChecks. This gives downstream consumers a single stable anchor regardless of how many internal tiers the umbrella contains.

Resource generation

ResourceGenerator.createKustomization detects umbrella bundles and:

  • prepends one HealthChecks entry per direct child (referencing the child's own Kustomization by name/namespace)
  • leaves user-supplied HealthChecks appended after the auto entries

spec.wait is not forced to true here; it is the caller's Bundle.Wait input like any other field. Forcing it was self-defeating: upstream documents that when wait is enabled "the HealthChecks are ignored", so the auto entries the generator had just built were inert. Leaving wait unset is what makes them take effect. A caller who does set Wait=true gets upstream's whole-of-resources health assessment instead, which also gates on the child Kustomizations.

GenerateFromBundle(b) is strictly self-only — it never recurses into b.Children. Callers that want the entire umbrella closure as a flat list use GenerateFromNode or GenerateFromCluster, which walk umbrella children via generateUmbrellaClosure internally.

Placement in layouts

LayoutIntegrator places umbrella child Flux CRs at the parent layout node:

  • FluxIntegratedPerLayout, non-nodeOnly: the walker creates a bundle sub-layout under the node layout. Umbrella child Kustomization CRs (and their Source CRs, if the child has a SourceRef.URL) are appended to the bundle sub-layout's Resources. Nested umbrella children are placed at their enclosing umbrella child's layout node.
  • FluxIntegratedPerLayout, nodeOnly (GroupFlat): there is no intermediate bundle layer, so umbrella children become direct sub-layouts of the node layout, and their Flux CRs sit at the node layout alongside the umbrella self CR.
  • FluxSeparate: GenerateFromCluster walks the full umbrella closure, so the flux-system layout directory receives every descendant's Kustomization CR as a flat list.
On-disk shape

When a parent layout has an umbrella child, the parent's kustomization.yaml references the child via flux-system-kustomization-{child}.yaml (the Kustomization CR file sitting in the parent directory) instead of the child subdirectory. The child subdirectory still exists and still contains its own kustomization.yaml plus workload YAML files — but no Flux CR files, so Flux does not double-apply the child's resources.

Non-Bundle Child Layout CRs

In FluxIntegratedPerLayout mode the layout integrator generates Kustomization CRs for all eligible children of each node layout, not only the node's own bundle. A child is eligible when !UmbrellaChild && ApplicationFileMode != AppFileSingle.

This covers two cases with the same code path:

  • Flat/nodeOnly layouts — app layouts are direct children of the node layout. Each eligible app layout gets a Kustomization CR placed in the node layout's Resources, with spec.path set to child.FullRepoPath().
  • Augmenter sub-layouts — hook-group child layouts added by a LayoutAugmenter are children of an app layout. Each eligible child gets a CR placed in the app layout's Resources. spec.dependsOn is populated from ManifestLayout.DependsOn, enabling ordered reconciliation between hook groups.

The integrator applies this rule recursively: it covers children at any depth, always placing the CR in the immediate parent's Resources.

If the ancestor bundle has a nil, empty, or incomplete SourceRef (missing Kind or Name) and eligible children without existing CRs are present, IntegrateWithLayout returns a hard error. A Kustomization without a valid spec.sourceRef is rejected by Flux and must not be emitted silently.

Validation

All cluster-level entry points (GenerateFromCluster, CreateLayoutWithResources) call stack.ValidateCluster before walking the tree. Invalid umbrella configurations — such as a bundle referenced both by a Node and by another bundle's Children, shared umbrella ownership, or multi-package umbrellas — fail fast with a validation error rather than producing malformed output.

CreateLayoutWithResources additionally calls validateSourceRefsForFluxIntegrated for both inline placements (FluxIntegratedPerLayout and FluxIntegratedPerBundle) — both emit bundle/node CRs that carry a spec.sourceRef. (After normalization FluxUnset becomes FluxSeparate, which skips this gate.) This checks that every bundle reachable from the cluster node tree — node bundles and umbrella child bundles recursively — has a complete SourceRef with both Kind and Name set. A nil, zero-value, or partially-populated SourceRef is rejected before layout walking begins. The integrator also enforces this at CR-creation time as defense in depth. FluxSeparate and non-Flux paths are unaffected.

Documentation

Index

Constants

View Source
const (
	// DefaultNamespace is the namespace generated Flux resources are placed in
	// when the caller names none.
	DefaultNamespace = "flux-system"

	// DefaultSourceName is the name given to a generated GitRepository or
	// OCIRepository when the root node has no name of its own.
	DefaultSourceName = "flux-system"

	// DefaultBootstrapName is the name given to the bootstrap Kustomization and
	// to the FluxInstance. Neither is derived from the root node. Override it by
	// assigning [BootstrapGenerator.BootstrapName].
	DefaultBootstrapName = "flux-system"

	// DefaultFluxDirName is the directory a separate Flux layout is placed in,
	// under FluxSeparate placement. It is a path segment, not a namespace: it
	// happens to share [DefaultNamespace]'s value and must not be derived from
	// it, because a caller who renames the namespace does not thereby rename
	// the directory. It has no override.
	DefaultFluxDirName = "flux-system"

	// DefaultBootstrapPathRoot is the first segment of the bootstrap
	// Kustomization's spec.path; the root node's name is joined onto it. It is a
	// fixed segment with no override — rename the root node to change the path.
	DefaultBootstrapPathRoot = "manifests"

	// DefaultFluxMode is the bootstrap mode used when BootstrapConfig.FluxMode
	// is empty. It is also the mode GenerateBootstrap dispatches on and the
	// first entry [BootstrapGenerator.SupportedBootstrapModes] reports, so
	// changing it here changes the default and the accepted spelling together
	// — the alternative left an empty FluxMode resolving to a mode the switch
	// no longer recognised.
	DefaultFluxMode = "flux-operator"

	// ModeGotk is the legacy bootstrap mode. It is not a default — nothing
	// falls back to it — but it is named here so the mode set has one
	// authority alongside [DefaultFluxMode] rather than a literal repeated in
	// the dispatch switch and the supported-mode list.
	ModeGotk = "gotk"

	// DefaultSourceKind is the kind of source object bootstrap emits, and
	// references, when BootstrapConfig.SourceKind does not name "GitRepository".
	// That includes the empty string: an unnamed kind yields an OCIRepository
	// for backward compatibility, which is generateSource's own behaviour.
	//
	// There is deliberately one identifier rather than one per emission site.
	// The bootstrap Kustomization's sourceRef, the source object itself and the
	// FluxInstance sync block previously each decided the kind for themselves,
	// and the first of the three used the opposite polarity to the other two —
	// so an empty SourceKind emitted an OCIRepository under a sourceRef naming a
	// GitRepository that was never created. [resolvedSourceKind] is now the only
	// place that decision is made.
	DefaultSourceKind = "OCIRepository"

	// DefaultSourceRef is the OCI tag used when BootstrapConfig.SourceRef is
	// empty, by both the gotk OCIRepository and the FluxInstance sync
	// ([resolvedSyncRef]). It has no GitRepository equivalent: an empty
	// SourceRef leaves the Git reference unset rather than guessing a branch.
	DefaultSourceRef = "latest"

	// DefaultSyncPath is the path a FluxInstance sync block uses when the root
	// node has no name, and the prefix its name is appended to when it has one.
	// It has no override: it is the prefix a sync path is built from, not a
	// value a caller replaces.
	DefaultSyncPath = "./"
)

The values a generator falls back to when the caller supplies nothing.

pkg/stack is a workflow layer above pkg/kubernetes and may hold opinions — but as declared inputs with names a consumer can read, compare against and override, never as literals buried in a constructor. Every fallback the generators apply is one of the identifiers below; grep for the identifier to find every place the value can reach emitted YAML.

These are defaults, not policy, and they are overridden in one of two ways. DefaultNamespace, DefaultInterval, DefaultMode and DefaultBootstrapName are copied into an exported field of ResourceGenerator or BootstrapGenerator by its constructor, and a caller that assigns the field afterwards is never overridden. The rest are applied where they are used, and are overridden by naming the corresponding input on stack.BootstrapConfig, stack.Bundle or the root stack.Node — the per-identifier comments below say which input each one yields to.

Three have no override at all: DefaultSyncPath, DefaultBootstrapPathRoot and DefaultFluxDirName. Each is a fixed structural segment of a path the package builds, not a value a caller replaces, and their comments say so. They are named here anyway so the value is greppable and reviewable rather than a literal inside the function that emits it.

Interval and namespace are the two that always reach output. KustomizationSpec.Interval is +required upstream with no omitempty (kustomize-controller api/v1/kustomization_types.go:68), so a Kustomization cannot be emitted without one; DefaultInterval is what a caller who names no interval gets.

View Source
const DefaultInterval = 60 * time.Minute

DefaultInterval is the reconciliation interval used when the caller names none, on both generators.

It also applies when Bundle.Interval is non-empty but does not parse: the parse error is swallowed and the default retained (see createKustomization in resource_generator.go). That is pre-existing behaviour, stated here rather than quietly implied by "names none", and tracked for a decision in issue go-kure/kure#762.

DefaultMode is the Kustomization path mode ResourceGenerator starts in. It has exactly one application site, NewResourceGenerator, and is overridden by assigning ResourceGenerator.Mode. The separate Flux layout deliberately leaves its own mode unset rather than seeding it from here — see addSeparateFluxToLayout for why that value could not take effect.

View Source
const FluxOperatorVersion = "v0.58.1"

FluxOperatorVersion is the upstream flux-operator release whose install manifest is vendored as fluxOperatorInstallYAML. It is pinned to match the github.com/controlplaneio-fluxcd/flux-operator Go module version in kure's go.mod so that the generated FluxInstance type and the install bundle stay in lockstep.

scripts/sync-flux-operator-pin.sh performs steps 2-4 below from go.mod's version, and Renovate runs it after a module bump. To refresh by hand instead:

  1. Bump github.com/controlplaneio-fluxcd/flux-operator in go.mod.
  2. Download the matching install.yaml from the flux-operator GitHub release page: https://github.com/controlplaneio-fluxcd/flux-operator/releases/download/{version}/install.yaml
  3. Replace pkg/stack/fluxcd/flux_operator_install.yaml with it.
  4. Update this constant, and the version named in pkg/stack/fluxcd/README.md ("currently **vX.Y.Z**"); no test checks it.
  5. Run the tests in this package and confirm the resource inventory in TestFluxOperatorInstallObjects still matches.

Variables

This section is empty.

Functions

func FluxOperatorInstallObjects

func FluxOperatorInstallObjects() ([]client.Object, error)

FluxOperatorInstallObjects returns the parsed Flux Operator install manifest: Namespace, CRDs, RBAC, ServiceAccount, Service, and controller Deployment. The bytes are embedded at build time from flux_operator_install.yaml (version FluxOperatorVersion).

The returned slice is cached on first parse; callers must treat it as read-only. To mutate any object, deep-copy first.

The order of objects matches the order in the upstream install.yaml (Namespace → CRDs → RBAC → ServiceAccount → Deployment → Service), which is also a valid apply order.

Types

type BootstrapGenerator

type BootstrapGenerator struct {
	// DefaultNamespace is the namespace where bootstrap resources are created
	DefaultNamespace string
	// DefaultInterval is the default reconciliation interval
	DefaultInterval time.Duration
	// BootstrapName is the name given to the bootstrap Kustomization and to the
	// FluxInstance. Neither is derived from the root node, and BootstrapConfig
	// carries no equivalent input, so this field is the only way to override
	// [DefaultBootstrapName]. Leaving it empty means the default, not a
	// nameless object — see [BootstrapGenerator.bootstrapName].
	BootstrapName string
}

BootstrapGenerator implements the workflow.BootstrapGenerator interface for Flux. It handles the generation of bootstrap resources for setting up Flux.

func NewBootstrapGenerator

func NewBootstrapGenerator() *BootstrapGenerator

NewBootstrapGenerator creates a FluxCD bootstrap generator seeded with the exported defaults (DefaultNamespace, DefaultInterval, DefaultBootstrapName). Assign the fields afterwards to override any of them.

func (*BootstrapGenerator) GenerateBootstrap

func (bg *BootstrapGenerator) GenerateBootstrap(config *stack.BootstrapConfig, rootNode *stack.Node) ([]client.Object, error)

GenerateBootstrap creates bootstrap resources for setting up Flux. When FluxMode is empty, flux-operator is used as the default.

func (*BootstrapGenerator) GenerateFluxInstance

func (bg *BootstrapGenerator) GenerateFluxInstance(config *stack.BootstrapConfig, rootNode *stack.Node) (*fluxv1.FluxInstance, error)

GenerateFluxInstance returns only the FluxInstance CR configured for the given bootstrap settings, without the full Flux Operator install bundle. Returns (nil, nil) when config is nil. Unlike GenerateBootstrap, this method does not check config.Enabled — the caller is responsible for that gate.

func (*BootstrapGenerator) SupportedBootstrapModes

func (bg *BootstrapGenerator) SupportedBootstrapModes() []string

SupportedBootstrapModes returns the bootstrap modes supported by this generator. DefaultFluxMode is the primary (recommended) mode; ModeGotk is the legacy one. This is the single list: GenerateBootstrap's validation error reports it rather than restating the modes.

type LayoutIntegrator

type LayoutIntegrator struct {
	// ResourceGenerator generates the Flux resources
	Generator *ResourceGenerator
}

LayoutIntegrator implements the workflow.LayoutIntegrator interface for Flux. It handles integration of Flux resources with manifest layouts.

Placement (FluxIntegratedPerLayout vs FluxSeparate) is configured via layout.LayoutRules.FluxPlacement on each call. CreateLayoutWithResources normalizes FluxUnset to FluxSeparate before invoking the SourceRef validation gate, WalkCluster, and IntegrateWithLayout, so all three observers agree on the effective placement.

func NewLayoutIntegrator

func NewLayoutIntegrator(generator *ResourceGenerator) *LayoutIntegrator

NewLayoutIntegrator creates a FluxCD layout integrator.

func (*LayoutIntegrator) CreateLayoutWithResources

func (li *LayoutIntegrator) CreateLayoutWithResources(c *stack.Cluster, rules layout.LayoutRules) (*layout.ManifestLayout, error)

CreateLayoutWithResources creates a new layout that includes Flux resources.

rules.FluxPlacement is normalized once at the top of this method (FluxUnset -> FluxSeparate) and the normalized rules are passed to the SourceRef validation gate, WalkCluster, and IntegrateWithLayout. This guarantees a single placement authority per call.

func (*LayoutIntegrator) IntegrateWithLayout

func (li *LayoutIntegrator) IntegrateWithLayout(ml *layout.ManifestLayout, c *stack.Cluster, rules layout.LayoutRules) error

IntegrateWithLayout adds Flux resources to an existing manifest layout.

Placement is driven by rules.FluxPlacement. FluxUnset is treated as FluxSeparate to match DefaultLayoutRules and the walker's normalization in pkg/stack/layout/walker.go:42-44.

If the layout was post-processed by FlattenSingleTier (recorded as flattenInfo on the absorbing layouts), this method consults nodeAliases during integrated placement (see findLayoutNode) and rewrites Flux Kustomization Spec.Path values via layout.ApplyFlattenPathRewrites before returning, regardless of placement mode.

type ResourceGenerator

type ResourceGenerator struct {
	// Mode controls how spec.path is generated in Kustomizations
	Mode layout.KustomizationMode
	// DefaultInterval is the default reconciliation interval for generated resources
	DefaultInterval time.Duration
	// DefaultNamespace is the default namespace for generated Flux resources
	DefaultNamespace string
	// Prune is the garbage-collection input for Kustomizations generated from a
	// layout.ManifestLayout (FluxIntegratedPerLayout mode), which carries no
	// prune setting of its own. Kustomizations generated from a stack.Bundle
	// use that bundle's own Prune and ignore this field. nil emits
	// prune: false — see pruneValue.
	Prune *bool
}

ResourceGenerator implements the workflow.ResourceGenerator interface for Flux. It focuses purely on generating Flux CRDs from stack components.

func NewResourceGenerator

func NewResourceGenerator() *ResourceGenerator

NewResourceGenerator creates a FluxCD resource generator seeded with the exported defaults (DefaultMode, DefaultInterval, DefaultNamespace). Assign the fields afterwards to override any of them; nothing else is injected into generated resources.

func (*ResourceGenerator) GenerateFromBundle

func (g *ResourceGenerator) GenerateFromBundle(b *stack.Bundle) ([]client.Object, error)

GenerateFromBundle creates Flux resources (Kustomization, and optionally a Source) for b itself only. Umbrella Children are NOT recursed — callers that need the closure should use GenerateFromNode, which walks the subtree, or iterate b.Children directly.

func (*ResourceGenerator) GenerateFromCluster

func (g *ResourceGenerator) GenerateFromCluster(c *stack.Cluster) ([]client.Object, error)

GenerateFromCluster creates Flux Kustomizations and Sources from a cluster definition. It runs stack.ValidateCluster first to fail fast on structural errors (umbrella cycles, disjointness violations, etc.).

func (*ResourceGenerator) GenerateFromNode

func (g *ResourceGenerator) GenerateFromNode(n *stack.Node) ([]client.Object, error)

GenerateFromNode creates Flux resources from a node and its children. When a node's bundle is an umbrella (len(Bundle.Children) > 0), the umbrella closure is walked and flattened into the returned slice so flat-list consumers (e.g. separate Flux placement) see every child Kustomization CR.

func (*ResourceGenerator) GetName

func (g *ResourceGenerator) GetName() string

GetName returns the name of this resource generator.

func (*ResourceGenerator) GetVersion

func (g *ResourceGenerator) GetVersion() string

GetVersion returns the version of this resource generator.

type WorkflowEngine

type WorkflowEngine struct {
	// ResourceGen handles core resource generation
	ResourceGen *ResourceGenerator
	// LayoutInteg handles layout integration
	LayoutInteg *LayoutIntegrator
	// BootstrapGen handles bootstrap resource generation
	BootstrapGen *BootstrapGenerator
}

WorkflowEngine implements the stack.Workflow interface by composing the specialized generator components. This provides a complete FluxCD workflow implementation with clear separation of concerns.

func Engine

func Engine() *WorkflowEngine

Engine returns a WorkflowEngine initialized with defaults. This is the primary entry point for FluxCD workflow functionality.

func EngineWithConfig

func EngineWithConfig(mode layout.KustomizationMode) *WorkflowEngine

EngineWithConfig returns a WorkflowEngine with a specific kustomization mode. Placement is no longer a constructor argument; set it on layout.LayoutRules.FluxPlacement at call time.

func EngineWithMode

func EngineWithMode(mode layout.KustomizationMode) *WorkflowEngine

EngineWithMode returns a WorkflowEngine with a specific kustomization mode.

func NewWorkflowEngine

func NewWorkflowEngine() *WorkflowEngine

NewWorkflowEngine creates a FluxCD workflow engine with default components.

func NewWorkflowEngineWithConfig

func NewWorkflowEngineWithConfig(mode layout.KustomizationMode) *WorkflowEngine

NewWorkflowEngineWithConfig creates a workflow engine with custom configuration.

Placement is no longer a constructor argument; set it on layout.LayoutRules.FluxPlacement at call time. See LayoutIntegrator for the normalization semantics.

func (*WorkflowEngine) CreateLayoutWithResources

func (we *WorkflowEngine) CreateLayoutWithResources(c *stack.Cluster, rules stack.LayoutRulesProvider) (stack.ManifestLayoutResult, error)

CreateLayoutWithResources creates a new layout that includes Flux resources.

func (*WorkflowEngine) GenerateBootstrap

func (we *WorkflowEngine) GenerateBootstrap(config *stack.BootstrapConfig, rootNode *stack.Node) ([]client.Object, error)

GenerateBootstrap creates bootstrap resources for setting up Flux.

func (*WorkflowEngine) GenerateFromBundle

func (we *WorkflowEngine) GenerateFromBundle(b *stack.Bundle) ([]client.Object, error)

GenerateFromBundle creates Flux resources from a bundle definition.

func (*WorkflowEngine) GenerateFromCluster

func (we *WorkflowEngine) GenerateFromCluster(c *stack.Cluster) ([]client.Object, error)

GenerateFromCluster creates Flux resources from a cluster definition.

func (*WorkflowEngine) GenerateFromNode

func (we *WorkflowEngine) GenerateFromNode(n *stack.Node) ([]client.Object, error)

GenerateFromNode creates Flux resources from a node definition.

func (*WorkflowEngine) GetBootstrapGenerator

func (we *WorkflowEngine) GetBootstrapGenerator() *BootstrapGenerator

GetBootstrapGenerator returns the underlying bootstrap generator for advanced configuration.

func (*WorkflowEngine) GetLayoutIntegrator

func (we *WorkflowEngine) GetLayoutIntegrator() *LayoutIntegrator

GetLayoutIntegrator returns the underlying layout integrator for advanced configuration.

func (*WorkflowEngine) GetName

func (we *WorkflowEngine) GetName() string

GetName returns a human-readable name for this workflow engine.

func (*WorkflowEngine) GetResourceGenerator

func (we *WorkflowEngine) GetResourceGenerator() *ResourceGenerator

GetResourceGenerator returns the underlying resource generator for advanced configuration.

func (*WorkflowEngine) GetVersion

func (we *WorkflowEngine) GetVersion() string

GetVersion returns the version of this workflow engine.

func (*WorkflowEngine) IntegrateWithLayout

func (we *WorkflowEngine) IntegrateWithLayout(ml *layout.ManifestLayout, c *stack.Cluster, rules layout.LayoutRules) error

IntegrateWithLayout adds Flux resources to an existing manifest layout.

func (*WorkflowEngine) SetKustomizationMode

func (we *WorkflowEngine) SetKustomizationMode(mode layout.KustomizationMode)

SetKustomizationMode configures how Kustomization paths are generated.

func (*WorkflowEngine) SupportedBootstrapModes

func (we *WorkflowEngine) SupportedBootstrapModes() []string

SupportedBootstrapModes returns the bootstrap modes supported by this engine.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL