layout

package
v0.1.0-beta.1 Latest Latest
Warning

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

 Go to latest Published: Feb 17, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

README

Layout Module

The layout module is a sophisticated system for organizing and writing Kubernetes manifests to disk in directory structures that work with GitOps tools like Flux and ArgoCD.

Core Purpose

The layout module transforms Kure's in-memory stack representation (Clusters → Nodes → Bundles → Applications) into organized directory structures with proper kustomization.yaml files that GitOps tools can consume.

Key Components

1. ManifestLayout Structure
  • Central data structure representing a directory with its resources and children
  • Contains: Name, Namespace, Resources (K8s objects), Children (subdirectories)
  • Supports package-aware layouts for multi-OCI/Git scenarios
2. LayoutRules Configuration
  • NodeGrouping: How nodes are organized (GroupByName creates dirs, GroupFlat flattens)
  • BundleGrouping: How bundles within nodes are organized
  • ApplicationGrouping: How applications within bundles are organized
  • FilePer: How resources are written (FilePerResource vs FilePerKind)
  • FluxPlacement: Where Flux Kustomizations go (FluxSeparate vs FluxIntegrated)
3. Two Main Walker Functions
  • WalkCluster(): Standard hierarchical layout (Node → Bundle → App structure)
  • WalkClusterByPackage(): Groups by PackageRef for multi-source scenarios
4. Writing System
  • WriteManifest(): Standard hierarchical writing
  • WritePackagesToDisk(): Package-based writing with sanitized directory names
  • Auto-generates kustomization.yaml files with proper resource references

Directory Structure Patterns

Standard Layout (WalkCluster)
clusters/
  cluster-name/
    node1/
      bundle1/
        app1/
          manifest-files.yaml
          kustomization.yaml
        app2/...
      bundle2/...
    node2/...
Package-Based Layout (WalkClusterByPackage)
oci-packages/
  cluster/
    web/
      app-manifests.yaml
git-packages/
  cluster/
    monitoring/
      app-manifests.yaml
Flat Layout (GroupFlat rules)
clusters/
  cluster-name/
    all-manifests-together.yaml
    kustomization.yaml

GitOps Tool Compatibility

Flux Integration
  • Uses spec.path: ./clusters/cluster-name/node format
  • Auto-generates kustomization.yaml files
  • Supports recursive discovery of manifests
  • Handles FluxSeparate vs FluxIntegrated placement modes
ArgoCD Integration
  • Uses spec.source.path: clusters/cluster-name/node format
  • Requires explicit kustomization.yaml files (no auto-discovery)
  • Each target directory needs its own Application

Advanced Features

Package Reference Support
  • Tracks different source types (OCIRepository, GitRepository, Bucket)
  • Enables multi-source deployments with proper isolation
  • Sanitizes package keys into valid directory names
Flexible File Organization
  • FilePerResource: Each K8s object gets its own file
  • FilePerKind: Group objects by Kind (all Services together, etc.)
  • AppFileSingle: All app resources in one file
Kustomization Generation
  • KustomizationExplicit: Lists all manifest files explicitly
  • KustomizationRecursive: References subdirectories only
  • Smart handling of cross-references and child relationships

Real-World Use Cases

  1. Simple Cluster: Single source, hierarchical structure
  2. Multi-OCI Deployment: Different services from different OCI registries
  3. Monorepo: Everything flattened into minimal directory structure
  4. Bootstrap Scenarios: Special handling for Flux/ArgoCD system components

Example Usage

// Create layout rules
rules := layout.DefaultLayoutRules()
rules.BundleGrouping = layout.GroupFlat
rules.ApplicationGrouping = layout.GroupFlat

// Walk cluster to create layout
ml, err := layout.WalkCluster(cluster, rules)
if err != nil {
    return err
}

// Write to disk
cfg := layout.DefaultLayoutConfig()
err = layout.WriteManifest("out/manifests", cfg, ml)

Key Files

  • types.go: Core types and configuration options
  • walker.go: Tree traversal algorithms (WalkCluster, WalkClusterByPackage)
  • manifest.go: ManifestLayout structure and package-based writing
  • write.go: Standard manifest writing with kustomization generation
  • config.go: Configuration and file naming conventions

The layout module essentially bridges the gap between Kure's programmatic resource construction and the file-based expectations of GitOps workflows, with extensive configurability for different organizational preferences and tool requirements.

Documentation

Overview

Package layout provides utilities for generating cluster directory layouts and for writing Kubernetes and Flux manifests to disk.

Flux Kustomizations and ArgoCD Applications reference directories in a Git repository using different fields. Flux uses `spec.path`, which must start with `./` and is always interpreted relative to the repository root. ArgoCD uses `spec.source.path` without the `./` prefix but with the same relative semantics.

When nodes or bundles live in nested subfolders, the path must point directly to the folder containing the manifests unless the directory tree only contains files for a single node or bundle. Flux will recursively auto-generate a `kustomization.yaml` when one is missing and include every manifest under the specified path. ArgoCD does not auto-generate a `kustomization.yaml` and therefore ignores nested directories unless they are referenced from a `kustomization.yaml` at the target path.

For example, consider the layout: 

repo/
  clusters/
    prod/
      nodes/
        cp/
          kustomization.yaml
      bundles/
        monitoring/
          kustomization.yaml

The Flux Kustomization for the control-plane node uses: 

spec.path: ./clusters/prod/nodes/cp

The equivalent ArgoCD Application uses: 

spec.source.path: clusters/prod/nodes/cp

With this layout, each node or bundle is targeted individually. Pointing a Flux Kustomization at `./clusters/prod` would combine the `cp` and `monitoring` manifests into a single deployment because it would auto-generate a `kustomization.yaml` for the entire tree. ArgoCD will only process the manifests under `clusters/prod` itself unless a `kustomization.yaml` aggregates the subdirectories, so each subfolder must be referenced separately.

Package api defines configuration structures used to generate Kubernetes manifests and Flux resources.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultKustomizationFileName 

func DefaultKustomizationFileName(name string) string

DefaultKustomizationFileName returns the standard Flux Kustomization file name.

func DefaultManifestFileName 

func DefaultManifestFileName(namespace, kind, name string, mode FileExportMode) string

DefaultManifestFileName implements the standard file naming convention used by Kure. It writes either one file per resource or groups by kind depending on the FileExportMode.

func WalkClusterByPackage 

func WalkClusterByPackage(c *stack.Cluster, rules LayoutRules) (map[string]*ManifestLayout, error)

WalkClusterByPackage traverses a stack.Cluster and builds separate ManifestLayout trees for each unique PackageRef (OCI artifact). Returns a map where keys are PackageRef GVKs and values are the corresponding ManifestLayout trees. Nodes without PackageRef inherit from their parent, with nil representing the default package.

func WriteManifest 

func WriteManifest(basePath string, cfg Config, ml *ManifestLayout) error

WriteManifest writes a ManifestLayout to disk using the provided configuration.

func WritePackagesToDisk 

func WritePackagesToDisk(packages map[string]*ManifestLayout, basePath string) error

WritePackagesToDisk writes multiple package layouts to separate directory structures

Types

type ApplicationFileMode 

type ApplicationFileMode string

ApplicationFileMode specifies how resources within an application are written.

The default is AppFilePerResource which mirrors the behaviour of FilePerResource and writes each generated resource to its own file. AppFileSingle groups all resources belonging to an application into a single manifest file. 

const (
	// AppFilePerResource writes each application resource to its own file.
	AppFilePerResource ApplicationFileMode = "resource"
	// AppFileSingle writes all resources for an application into one file.
	AppFileSingle ApplicationFileMode = "single"
	// AppFileUnset indicates that no application file mode was specified.
	AppFileUnset ApplicationFileMode = ""
)

type Config 

type Config struct {
	// ManifestsDir is the directory under which Kubernetes manifests are written.
	ManifestsDir string
	// FluxDir is the directory under which Flux manifests are written.
	FluxDir string
	// FilePer determines how resources are grouped into files when writing manifests.
	FilePer FileExportMode
	// ApplicationFileMode controls whether application resources are written
	// to a single file or split per resource. Defaults to AppFilePerResource.
	ApplicationFileMode ApplicationFileMode
	// KustomizationMode controls how kustomization.yaml files are generated.
	// Defaults to KustomizationExplicit.
	KustomizationMode KustomizationMode
	// ManifestFileName formats the file name for a resource manifest.
	ManifestFileName ManifestFileNameFunc
	// KustomizationFileName formats the file name for a Flux Kustomization.
	KustomizationFileName KustomizationFileNameFunc
}

Config LayoutConfig defines rules for generating a cluster layout.

func DefaultConfigForProfile 

func DefaultConfigForProfile(p Profile) Config

DefaultConfigForProfile returns a Config initialised with defaults for the given profile. Unknown profiles fall back to FluxProfile.

func DefaultLayoutConfig 

func DefaultLayoutConfig() Config

DefaultLayoutConfig returns a configuration that matches the directory layout expected by FluxCD when writing manifests and Kustomizations.

type FileExportMode 

type FileExportMode string

FileExportMode determines how resources are written to disk. 

const (
	// FilePerResource writes each resource to its own file.
	FilePerResource FileExportMode = "resource"
	// FilePerKind groups resources by kind into a single file.
	FilePerKind FileExportMode = "kind"
	// FilePerUnset indicates that no export mode is specified.
	FilePerUnset FileExportMode = ""
)

type FluxPlacement 

type FluxPlacement string

FluxPlacement determines how Flux Kustomizations are placed in the layout. 

const (
	// FluxSeparate places all Flux Kustomizations in a separate directory.
	FluxSeparate FluxPlacement = "separate"
	// FluxIntegrated distributes Flux Kustomizations across their target nodes.
	FluxIntegrated FluxPlacement = "integrated"
	// FluxUnset indicates no flux placement preference.
	FluxUnset FluxPlacement = ""
)

type GroupingMode 

type GroupingMode string

GroupingMode controls how nodes, bundles and applications are laid out on disk.

The default for all grouping modes is GroupByName which creates a directory per entity. GroupFlat places all entities in the same directory. 

const (
	// GroupByName creates a directory for each item in the hierarchy.
	GroupByName GroupingMode = "name"
	// GroupFlat flattens the hierarchy placing all items in the same directory.
	GroupFlat GroupingMode = "flat"
	// GroupUnset indicates that no grouping preference was specified.
	GroupUnset GroupingMode = ""
)

type KustomizationFileNameFunc 

type KustomizationFileNameFunc func(name string) string

KustomizationFileNameFunc returns the file name for a Flux Kustomization manifest.

type KustomizationMode 

type KustomizationMode string

KustomizationMode determines how kustomization.yaml files reference manifests. 

const (
	// KustomizationExplicit lists each manifest file in kustomization.yaml.
	KustomizationExplicit KustomizationMode = "explicit"
	// KustomizationRecursive references only subdirectories in kustomization.yaml.
	KustomizationRecursive KustomizationMode = "recursive"
	// KustomizationUnset indicates no kustomization mode preference.
	KustomizationUnset KustomizationMode = ""
)

type LayoutRules 

type LayoutRules struct {
	// NodeGrouping controls how nodes are written to disk. Defaults to
	// GroupByName.
	NodeGrouping GroupingMode
	// BundleGrouping controls how bundles are written to disk. Defaults to
	// GroupByName.
	BundleGrouping GroupingMode
	// ApplicationGrouping controls how applications are written to disk.
	// Defaults to GroupByName.
	ApplicationGrouping GroupingMode
	// ApplicationFileMode controls whether application resources are
	// combined into a single file or split per resource. Defaults to
	// AppFilePerResource.
	ApplicationFileMode ApplicationFileMode
	// FilePer sets the default file export mode for resources. Defaults to
	// FilePerResource.
	FilePer FileExportMode
	// ClusterName specifies a cluster name to prepend to all paths.
	// When set, creates clusters/{ClusterName}/... structure.
	ClusterName string
	// FluxPlacement determines how Flux Kustomizations are placed.
	// Defaults to FluxSeparate.
	FluxPlacement FluxPlacement
}

LayoutRules control how layouts are generated.

Zero values are interpreted as the defaults described in the field documentation.

func DefaultLayoutRules 

func DefaultLayoutRules() LayoutRules

DefaultLayoutRules returns a LayoutRules instance populated with the documented default values.

func (LayoutRules) Validate 

func (lr LayoutRules) Validate() error

Validate ensures the LayoutRules contain known option values.

type ManifestFileNameFunc 

type ManifestFileNameFunc func(namespace, kind, name string, mode FileExportMode) string

ManifestFileNameFunc returns a file name for the given namespace, kind and resource name.

type ManifestLayout 

type ManifestLayout struct {
	Name                string
	Namespace           string
	PackageRef          *schema.GroupVersionKind
	FilePer             FileExportMode
	ApplicationFileMode ApplicationFileMode
	Mode                KustomizationMode
	FluxPlacement       FluxPlacement // Track flux placement mode for kustomization generation
	Resources           []client.Object
	Children            []*ManifestLayout
}

func WalkCluster 

func WalkCluster(c *stack.Cluster, rules LayoutRules) (*ManifestLayout, error)

WalkCluster traverses a stack.Cluster and builds a ManifestLayout tree that mirrors the node and bundle hierarchy. Behaviour is controlled via LayoutRules. When BundleGrouping and ApplicationGrouping are set to GroupFlat, all application resources are written directly to their parent node's directory.

func (*ManifestLayout) FullRepoPath 

func (ml *ManifestLayout) FullRepoPath() string

func (*ManifestLayout) FullRepoPathWithPackage 

func (ml *ManifestLayout) FullRepoPathWithPackage() string

FullRepoPathWithPackage returns the repository path including package-specific prefix

func (*ManifestLayout) WriteToDisk 

func (ml *ManifestLayout) WriteToDisk(basePath string) error

func (*ManifestLayout) WriteToTar 

func (ml *ManifestLayout) WriteToTar(w io.Writer) error

WriteToTar writes the ManifestLayout to a tar archive, mirroring the directory structure that WriteToDisk would produce. File paths use forward slashes and output is deterministic (sorted file names).

type Profile 

type Profile string

Profile identifies a supported layout profile. 

const (
	// FluxProfile represents defaults matching FluxCD conventions.
	FluxProfile Profile = "flux"
	// ArgoProfile represents defaults matching Argo CD conventions.
	ArgoProfile Profile = "argocd"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.