layout

package
v0.2.0-beta.20 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

README

Layout Module

Go Reference

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
Layout paths

A layout's directory is FullRepoPath(), which is Namespace joined with Name. Namespace is always the parent's directory: set a child's Namespace to its parent's FullRepoPath(), and use "." for the root of the tree. An empty Namespace means cluster. An AppFileSingle layout writes one file, <Namespace>/<Name>.yaml, into its Namespace, normally its parent's directory, and the parent's kustomization.yaml lists it. An AppFileSingle root writes that file and its kustomization.yaml into its Namespace, and lists its children there: build them with the root's Namespace, not its FullRepoPath().

The parent lists an AppFileSingle child's file by its path relative to the parent's directory, slash-separated (go-kure/kure#879): svc.yaml when the child's Namespace is the parent's directory, sub/svc.yaml when it is <parent directory>/sub. Before, the entry was always <Name>.yaml, which named no file for a child below the parent's directory, and named one file twice for two such children with one name. A listed child whose file lands outside the parent's directory (a sibling or an ancestor directory) is refused before anything is written: the entry would start with ../, and kustomize's default load restrictor rejects it. The parent's directory must match exactly: a child Namespace of P or P/sub under a parent directory p is refused too, since the two spellings name one directory only on a case-insensitive volume. Below the parent's directory the child's own spelling is kept, so p/Sub under p is listed as Sub/svc.yaml. A child the parent does not list (an umbrella child, one that renders bundles, one with no resources), or any child of a parent that writes no kustomization.yaml, may land anywhere. A FluxIntegratedPerLayout parent, or a parent of another package, lists an AppFileSingle child's file all the same. An AppFileSingle child's Name must be one file name: one that is rooted or holds a path separator (/svc, sub/svc, ../q/svc) is refused, listed or not. A rooted Namespace is joined onto the writer's base path, and WriteToTar resolves it under the archive root, so a child Namespace of /p/sub under a parent directory p is listed as sub/svc.yaml by all three writers.

When a parent's kustomization.yaml references a child by directory (- <Name>), the child's directory must be <parent directory>/<Name> for the reference to resolve; building every child with its parent's FullRepoPath() as Namespace gives exactly that. Layouts with the same name nest: a bundle web with an application web gives web/web. A caller may still place a child elsewhere on purpose, for example an OCI artifact whose root lists sibling layers that live under a group directory; nothing refuses that, but such a root's own kustomization.yaml is not a valid kustomize entry point.

Before go-kure/kure#771, FullRepoPath() dropped Name whenever Namespace ended with it as a string, and callers commonly set Namespace to the full path including the child's own name. That rule also collapsed layouts that merely shared a name or a name suffix onto one directory, losing resources from the kustomize graph. A caller still joining the child's Name into its Namespace would get that name twice (.../<name>/<name>), below the directory its parent's kustomization.yaml lists, which then holds no kustomization.yaml. Every writer refuses such a child before anything is written (go-kure/kure#979): a directory child that its parent lists and whose Namespace is <parent directory>/<Name>, the path the child itself should have. The error names both layouts, the directory written and the directory the parent lists; pass the parent's path instead. The two paths are compared without regard to case, as the writers compare directories: a Namespace that is the child's own path in another case (apps/web for a child named Web under apps) is the same mistake, and the error says the difference is one of case. Only that shape is refused. Layouts of one name built with the parent's path nest as above (web/web), a child placed elsewhere on purpose is written as described above, and so is a child no entry names: one its parent does not list (an umbrella child, one that renders bundles, a directory child of a FluxIntegratedPerLayout parent, and for WriteToDisk and WriteToTar a child of another package), or any child of a parent that writes no kustomization.yaml. The directories compared are the writer's own, so under an AppFileSingle root the parent directory is the root's Namespace.

Breaking change (go-kure/kure#979). A hand-built tree with such a child was written, with a parent entry that named a directory without a kustomization.yaml. It is now refused.

Every writer (WriteToDisk, WriteToTar, WriteManifest) checks the whole tree before writing anything, and refuses two layouts that resolve to the same directory (when one of them is a bundle's own directory, the error names the bundle by its path, so two bundles that take one directory name are told apart), or two AppFileSingle layouts that resolve to the same file, or an AppFileSingle child with children of its own or with ConfigMapGenerators, or any other layout it writes no kustomization.yaml for that has ConfigMapGenerators. It also refuses an AppFileSingle layout whose file, <Name>.yaml, or one of whose extra files would replace another file written into the same directory: the kustomization.yaml there, one of the resource or extra files of the layout that owns the directory, or another AppFileSingle layout's file (go-kure/kure#871). A child named kustomization, or named like one of its parent's generated files (default-configmap-a, or configmap under FileNamingKindName + FilePerKind), is refused, as is an AppFileSingle root named kustomization. A child with no resources writes no <Name>.yaml, so its name is never refused as replacing another file; its directory, which the writers still create, and its extra files are checked. Nor may such a file need a directory where another layout writes a file, or be a file where another layout needs a directory (go-kure/kure#878): an extra file default-configmap-a.yaml/v.yaml next to the parent's default-configmap-a.yaml, an extra file sub where a child layout's directory sub is (or a directory below it), or an extra file x of one AppFileSingle layout and x/y.yaml of another. Nor may a layout's directory, including the one the writers create for an AppFileSingle layout without resources, be or lie beneath a file another layout writes. Before this, WriteToDisk and WriteManifest failed partway with not a directory, and WriteToTar wrote an archive tar could not extract. Of the kustomize control files only kustomization.yaml is written, so a directory named kustomization, Kustomization or kustomization.yml clashes with nothing. An AppFileSingle layout's extra file inside a sibling layout's directory (sub/v.yaml next to its parent's directory child sub) is written; that directory's kustomization.yaml does not list it. A layout's own extra file inside its own child's directory is refused (see Extra Files and ConfigMap Generators). Directories and file names are compared case-insensitively, as on default macOS volumes: an AppFileSingle child named Kustomization, or Default-ConfigMap-A, is refused too, and so is a directory child Default-ConfigMap-A.yaml next to its parent's default-configmap-a.yaml.

The writers also refuse two layouts that hold an object with one kustomize identity when one kustomize build takes in both (go-kure/kure#880): kustomize refuses the second copy (may not add resource with an already registered id), so that build would fail. The identity is kustomize's own: group, version, kind, name and namespace, where an omitted namespace counts as default and a kind kustomize knows is cluster-scoped (such as Namespace) has none, even when the object sets one; so one layout holding such an object with and without a namespace field is refused too. Two versions of one object (autoscaling/v1 and autoscaling/v2) are two identities, and kustomize builds both. A build is every kustomization.yaml a writer writes, with the files and the AppFileSingle child files it lists and, recursively, the build of each child directory it lists; and the Flux build of a KustomizationRecursive directory marked with SetFluxBuild (see "Kustomization Generation"). The error names both layouts and the innermost build. A child its parent does not list (an umbrella child, one that renders bundles, a directory child of a FluxIntegratedPerLayout parent, or under WriteToDisk and WriteToTar a directory child of another package) is a build of its own, so it may hold an object its parent holds. An AppFileSingle child of such a parent is still listed, so its objects count in the parent's build.

The ConfigMap a configMapGenerator generates counts as an object of the layout whose kustomization.yaml holds the generator (go-kure/kure#894): v1 ConfigMap, the generator's name and no namespace, so default. kustomize compares the name before the content-hash suffix, so two generators of one name are one identity whatever their files hold. It refuses a generator whose ConfigMap its own kustomization already holds (id ... exists; ... behavior must be merge or replace; kure writes no behavior), and one object reaching a kustomization twice from its resources, the generator's ConfigMap included (may not add resource with an already registered id). So a generator named x is refused next to a ConfigMap default/x, or one without a namespace, anywhere in the same kustomize build (its own layout, a listed child, the parent that lists it, or a sibling that parent lists), and so are two generators named x in one layout or in two layouts of one build. A ConfigMap x in another namespace, or a generator x in a child its parent does not list, is written.

In a tree Flux delivers, the writers refuse a directory that is written and that nothing applies (go-kure/kure#977). A tree is one Flux delivers when its root is marked with SetFluxBuild: the fluxcd integrator marks the root of every tree it generated a Kustomization for, and a caller that places Flux Kustomizations itself marks its tree the same way. In such a tree every child its parent's kustomization.yaml does not list (the children named above: an umbrella child, one that renders bundles, a directory child of a FluxIntegratedPerLayout parent, and under WriteToDisk and WriteToTar a directory child of another package) is applied only by a Flux Kustomization whose spec.path names its directory, so it must be marked as well. An unmarked one is refused, naming the layout and its parent. A child of another package is not exempt: those two writers write its directory into the tree and nothing in the tree lists it. An AppFileSingle child without resources writes no file and is not checked. A tree whose root is not marked, an Argo CD tree included, is not checked.

The writers also refuse two Flux Kustomizations with one namespace and name anywhere in a tree, marked or not (go-kure/kure#977). The checks above refuse one object held twice in what one kustomize build takes in; two Kustomizations in directories that are applied separately pass those, yet they are one object in the cluster, where each apply replaces what the other wrote. A Kustomization is matched by the group kustomize.toolkit.fluxcd.io and its kind, at any version, and an omitted namespace counts as default. The error names both layouts. A Kustomization inside a List counts, where a List is what kustomize opens as one: an object written with a kind ending in List and that has an items field, opened again when an item is itself such a List. A kind that does not end in List is one object, whatever fields it has, and so is a List kind without items; a List whose items is null holds nothing. An item a typed List holds as raw JSON (runtime.RawExtension) is read as the object it encodes, also when the item carries an object beside the raw JSON: the raw JSON is what is written. A Kustomization written with kustomize's config.kubernetes.io/local-config annotation at any value but false (the string "false" or the boolean false, as kustomize reads the written value) is left out of this check: a build drops it, so it never reaches the cluster (go-kure/kure#1059). The checks of one layout and of one build still count it, because kustomize refuses one identity twice in a build before it drops anything.

Every check above that compares objects reads a resource that way (go-kure/kure#1006): the check of one layout, the check of one build and the check of Kustomization names take a resource for the objects kustomize builds from it, so two objects of one identity are refused however many Lists deep one of them sits. For a typed object the kind and the items field are the ones in the written file, not what its Go value reports: a typed object written without a kind, as one whose TypeMeta is left out of what is written is unless another field writes a kind, is one object without a kind, whatever its Go type, and one that writes a kind ending in List is opened as a List. A typed List kind that leaves an empty items out is one object, and one that writes other items than its Go value holds is read for the ones it writes. An item of a typed List need not carry object metadata to be read: a List without any, such as the core v1 List as a Go value (metav1.List), is opened like any other, and an item held as raw JSON is the object it encodes. An item that is none of these and has no object metadata is refused: its namespace and name cannot be read. An item that is a nil pointer is written as null and holds nothing. A List that holds itself among its items is refused in two forms: an unstructured one, and a typed list as apimachinery takes one (a pointer to a struct with an Items field, metav1.List for one) that holds itself as the object of an item, directly or through such lists. No other value that reaches itself is looked for: building one is the calling program's error. The Flux integration reads a resource by the same rule, so it and the writers agree on which objects a tree holds.

Read the same way, every object a build takes in must be written with a kind and an apiVersion (go-kure/kure#1020): each resource, and each item of a List however many Lists deep, typed or unstructured, judged on what is written for it, not on its Go type. A typed object is written as it is, so one whose TypeMeta is unset becomes a document with neither; the writers refuse a layout that holds one before anything is written, naming the layout, the object and what it lacks. Set the TypeMeta, as this library's Create* constructors do, or the two fields of an unstructured object. The type is not filled in from a scheme, which would hide the mistake, and only an empty field is refused: whether the kind exists or the apiVersion is well formed is not looked at. A kustomize build fails on a document without a kind, and one without an apiVersion builds into an object of no version that nothing applies. A List's own apiVersion is exempt: kustomize drops the envelope without reading it, so a List without one whose items are complete builds and applies as its items do, and is written as before. So is the apiVersion of an object with kustomize's config.kubernetes.io/local-config annotation at any value but false (the string "false" or the boolean false): kustomize drops such an object from the build without requiring one, so it is written as before. Its kind is still required, since kustomize reads the kind before it drops anything.

2. LayoutRules Configuration
  • NodeGrouping: whether each child node gets a directory (GroupByName, default) or merges into its parent's (GroupFlat; the root keeps its directory)
  • BundleGrouping: whether each bundle gets a directory inside its node's (GroupByName) or renders in the node's directory (GroupFlat, default; the root node's bundles get one directory inside the root's, see The root node's bundles)
  • ApplicationGrouping: whether each application gets a directory inside its bundle's (GroupByName) or writes into the bundle's directory (GroupFlat, default)

The three axes are independent and apply the same way to the root node (also under a ClusterName), to umbrella children and in WalkClusterByPackage, with the one exception below. A level set to GroupFlat is rendered into the layout above it: its resources, its child layouts and its origins. Umbrella child bundles and augmenter applications always keep their own directory, because each carries its own Flux Kustomization or writer-owned files. FilePer is honoured on every layout. The writers refuse a merge that makes two layouts claim one directory, and a directory that would hold two objects with the same group, kind, namespace and name (kustomize cannot build it); objects that merely share a file name are written into one multi-document file, as FilePerKind intends.

A name that becomes a directory must be one path segment (stack.ValidateDirectoryName): not empty, not . or .., and without /, \ or a NUL byte. Bundle and node names are checked by stack.ValidateCluster, which every walk runs first. That check does not look at the rules: a node that NodeGrouping: GroupFlat absorbs into its parent's directory is checked too, because its name is a segment of the node's path in the model. An application name is checked by the walk itself, and only where the rules give the application a directory: under GroupByName, or for an augmenter application that takes its own layout under either grouping. An application written into its bundle's directory keeps any name. The check runs on the tree the walk returns, which holds every application directory: FlattenSingleTier collapses none. The error names the application and the directory it would have been created in.

Wherever a bundle's name becomes a directory, the directory is named by Bundle.DirName, or by Bundle.Name when that is empty: an umbrella child's directory, a node's bundle's under BundleGrouping: GroupByName, and the one the root node's bundles get inside the root node's under GroupFlat (see The root node's bundles). The name of the bundle's Flux Kustomization or ArgoCD Application is not affected, and its path follows the directory: a child with Name: "shop-infra" and DirName: "00-infra" is written to <umbrella>/00-infra and applied by the Kustomization shop-infra. Under BundleGrouping: GroupFlat below the root a node's bundle is rendered in its node's directory and its DirName has no effect. A DirName is checked like a name that becomes a directory, by stack.ValidateCluster before the walk, whether or not the rules give the bundle a directory; it is no object name, so nothing else is asked of it. The directory is named on the bundle: IndexOrigins refuses a bundle's own layout that was renamed after the walk.

  • FilePer: How resources are written (FilePerResource vs FilePerKind)
  • FluxPlacement: Where/at what granularity Flux Kustomizations go — FluxSeparate, FluxIntegratedPerLayout (a CR per layout node), or FluxIntegratedPerBundle (CRs at bundle boundaries; application children included as directories)
  • FileNaming: Resource file naming pattern (see File Naming Modes)
  • ClusterName: Optional cluster name prefix for cluster-aware directory paths

The rules carry no application file mode: no walk sets one on the layouts it builds. Whether an application is written as one file is the layout's own ApplicationFileMode (every writer), or Config.ApplicationFileMode as the default for application layouts in WriteManifest.

WalkCluster and WalkClusterByPackage validate the rules they are given before they build anything (LayoutRules.Validate), so no caller has to and no entry point that walks checks on its own. The rules are validated as given, then unset values take their defaults: an unset value is valid. Two things are refused, each with an error naming the field and the value:

  • an unknown value of NodeGrouping, BundleGrouping, ApplicationGrouping, FilePer, FluxPlacement or FileNaming. It is not walked as if it were another value;
  • a ClusterName with a .. path segment (../prod, clusters/../prod). The cluster directory is the top layout's Namespace, which the writers refuse with such a segment, so the walk refuses it first. This is stricter than the writers in one case, by design: x/../platform over a root node platform would be cleaned to platform and written, and is refused all the same. Every other spelling is accepted and written: ., a nested or rooted path, a trailing slash, dots inside a segment (a..b).

The rules are checked whatever the cluster is: a nil cluster with invalid rules returns the rules error, not a nil layout.

The root node's bundles

The root node's directory renders no bundle (go-kure/kure#979). A directory that renders bundles is applied by its own Flux Kustomization, which its parent directory hosts; the root node's directory can be the top of the tree, which has no parent, so its Kustomization would be part of the build it applies.

With BundleGrouping: GroupFlat the bundles that would render in the root node's directory (the root node's own, and under NodeGrouping: GroupFlat those of every node it absorbs) are therefore rendered into one directory inside it, named after the first of them:

Root node Bundle BundleGrouping Bundle directory
platform platform GroupFlat platform/platform
platform core GroupFlat platform/core
platform, child node web absorbed (NodeGrouping: GroupFlat) core, web GroupFlat platform/core for both
unnamed, ClusterName: "." core GroupFlat core
platform core GroupByName platform/core, as for every node

They stay one unit: one directory and one Flux Kustomization or ArgoCD Application, named after the first bundle. The directory takes that bundle's DirName, or its Name without one (a DirName on a bundle merged into it later has no effect); its KustomizationName, when it sets one, names the Kustomization or Application alone. ManifestLayout.OriginUnit() on the root node's layout returns that directory's layout. Every other node is unchanged: its bundle renders in the node's directory. Both walkers do this, WalkClusterByPackage in the tree of the package the root node is in. The unnamed wrapper WalkClusterByPackage builds for a package the root node is not in is not the root node's directory and is unchanged: under NodeGrouping: GroupFlat it renders the bundles merged into it, and the Flux integration refuses such a tree (its top renders a bundle).

A child node of the root that carries the name of that directory is refused by the walk, since both would be written to one place; the error names the node, the bundle and the directory. The two directories are compared as the writers compare them (ManifestLayout.SameDirectory: the path resolved under the output directory and cleaned, without regard to case; it compares directories, says nothing about an AppFileSingle layout, which is a file, and does not describe WriteToDisk(""), which writes a rooted path as an absolute one), so a node name that differs only in case (WEB beside the bundle web) is refused too. Rename one of them, or give the bundle's directory another name with DirName: the check compares the directory the bundle gets, so it follows a DirName, and names the bundle by its Name. A name that is not one path segment does not reach the walk: stack.ValidateCluster refuses a node named /web or ./web, and a bundle named ., / or web/api, before it. The bundle's directory is therefore always one inside the root node's. A layout below a child node can still be rendered to it, when an application's LayoutAugmenter adds one with that name and place; the walk refuses the tree, and the error names the bundle, the directory and what takes it. BundleGrouping: GroupByName is no way around either: the bundle's directory is the same there, the walk does not check it, and the writers refuse the tree.

The workflow engines add a directory of their own to the top of the tree: flux-system (Flux, FluxSeparate) and argocd (ArgoCD). When the top is the root node's directory, a root node's bundle whose directory has that name (its DirName, or its Name without one) or a child node with that name would share it, and the engine refuses the tree, naming the bundle or node and the directory. A bundle named flux-system whose DirName is another name is accepted. In the path patterns below, <bundle> is that directory name too: the bundle's DirName, or its Name without one.

An unnamed root node under a ClusterName is rendered into the ClusterName directory, and its bundle into <ClusterName>/<bundle>. Every writer writes the ClusterName directory its kustomization.yaml, also when the directory holds no resource of its own. Without it, a Flux Kustomization that builds the directory would take in every file below it, each bundle's included.

Breaking change (go-kure/kure#979). WriteManifest used to make one exception: it wrote no kustomization.yaml for a layout with no Name and a one-segment Namespace that held no resource file and no AppFileSingle child's file and rendered no bundle, neither itself nor in a directory inside it (OriginUnit()). A walk gives that shape as a one-segment ClusterName directory (prod, not clusters/prod); a caller or an application's AugmentLayout can set it anywhere in a tree. WriteToDisk and WriteToTar never made that exception. It is gone: WriteManifest writes such a layout's kustomization.yaml under the same rules as any other layout's (none for a KustomizationRecursive layout; for an AppFileSingle one only at the root of the written tree, when it has resources or children). A tree written with WriteManifest can so have one more file, at its top when the layout is the ClusterName directory. That file is created like every other one the writer writes: a file of that name already in the directory is replaced, and a caller that writes its own there afterwards replaces kure's. The file lists the directory's children, so WriteManifest now holds the build it starts to every check a directory with a kustomization.yaml gets, as the other two writers do, and refuses a tree it used to write when that directory fails one of them. Two examples, not a complete list: a child directory named kustomization.yaml, the path of the file now written (a walk gives it for a root node of that name below a ClusterName), and listed children that hold one object twice, which kustomize refuses in a build.

Breaking change (go-kure/kure#979). Before, the root node's bundles rendered in the root node's directory. Their files, the Flux Kustomization's spec.path and the ArgoCD Application's source.path move one directory down, from <root> to <root>/<first bundle name> (that bundle's DirName when it sets one, go-kure/kure#972). On a deployed tree with prune on, the objects can be deleted by the outer owner and re-created by the inner Kustomization.

3. Two Main Walker Functions
  • WalkCluster(): Standard hierarchical layout (Node → Bundle → App structure)
  • WalkClusterByPackage(): Groups by PackageRef for multi-source scenarios

Both skip an entry of an application's Generate result that is nil or holds no object (a nil client.Object interface, or a nil pointer of an object type such as (*corev1.ConfigMap)(nil)): it holds nothing to write, so it gets no file and no kustomization.yaml entry.

4. Writing System
  • WriteManifest(): Config-driven writing — uses Config to resolve file naming, kustomization mode, and directory structure
  • WriteToDisk(): Self-contained method on ManifestLayout — uses the layout's own FileNaming and FluxPlacement fields
  • WriteToTar(): Same as WriteToDisk but writes to a tar archive for OCI artifact consumers
  • WritePackagesToDisk(): Package-based writing with sanitized directory names
  • All writers auto-generate 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/
  web/
    app-manifests.yaml
git-packages/
  monitoring/
    app-manifests.yaml
Flat Layout (GroupFlat rules)
clusters/
  cluster-name/
    root-node/
      kustomization.yaml
      first-bundle/
        all-manifests-together.yaml
        kustomization.yaml

The root node's directory renders no bundle, so the merged bundles share one directory inside it (see The root node's bundles).

GitOps Tool Compatibility

Flux Integration
  • Every Kustomization spec.path is the directory of the layout that renders the bundle, e.g. cluster-name/node (see Layout origins)
  • Auto-generates kustomization.yaml files
  • Handles FluxSeparate, FluxIntegratedPerLayout and FluxIntegratedPerBundle placement modes
ArgoCD Integration
  • spec.source.path is the same layout directory, e.g. cluster-name/node
  • 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
File Naming Modes

Controls how resource YAML files are named:

Mode Format Example
FileNamingDefault {namespace}-{kind}-{name}.yaml default-service-web.yaml
FileNamingKindName {kind}-{name}.yaml service-web.yaml

FileNamingKindName drops the namespace prefix, which is useful when each application already has its own directory (e.g., Pattern A / CentralizedControlPlane). The naming mode is propagated through all writers: WriteManifest, WriteToDisk, and WriteToTar.

WriteManifest names every layout's files from its Config. WriteToDisk and WriteToTar name each layout's files from that layout's own FileNaming, which LayoutRules.FileNaming sets across the tree:

  • every layout a walker creates carries the rules' FileNaming;
  • a layout an augmenter adds and leaves unset takes its parent's, at any depth;
  • the flux-system/ directory of FluxSeparate takes the rules' (the root layout's when the rules passed to IntegrateWithLayout leave it unset);
  • a layout that sets its own FileNaming keeps it, and the layouts below it inherit that one.

A layout added to a tree by hand, outside a walker, is not touched: set its FileNaming yourself. A layout FlattenSingleTier absorbs into the root has no directory of its own any more: its files take the root's FileNaming, and its own only when the root's is unset.

Breaking change (go-kure/kure#976). Before, the flux-system/ directory and the layouts an augmenter added always used the default pattern unless the augmenter set FileNaming itself. With FileNamingKindName (the CentralizedControlPlane preset included) those files are renamed: flux-system/flux-system-kustomization-<name>.yaml becomes flux-system/kustomization-<name>.yaml, and an augmenter layout's <namespace>-<kind>-<name>.yaml becomes <kind>-<name>.yaml. Each directory's kustomization.yaml lists the new names. Update anything outside kure that reads those files by name. An augmenter that needs the old names sets FileNamingDefault on the layouts it adds.

Kustomization Generation
  • KustomizationExplicit: Lists all manifest files explicitly

  • KustomizationRecursive: Writes no kustomization.yaml into the layout's directory; every other file is written as in Explicit mode. The directory is meant for a Flux Kustomization, which generates the kustomization.yaml from every .yaml and .yml file below it, adding a subdirectory that has its own kustomization file as a whole (go-kure/kure#868). Every writer refuses, before writing anything:

    • ConfigMapGenerators on a Recursive layout: they exist only inside a kustomization.yaml;
    • a parent's kustomization.yaml that lists a Recursive layout's directory, which kustomize cannot build without one.

    A Flux Kustomization kure generated builds a directory when SetFluxBuild marks it: the fluxcd integrator marks each generated spec.path layout, and the root, which the Flux bootstrap applies. Nothing else marks: a caller placing Flux Kustomizations from GenerateFromLayout or its own code calls SetFluxBuild on the root and on their spec.path layouts to get these checks. The integrator also records, on every layout, the Flux Kustomizations it placed or kept there (SetFluxKustomizations, read back with FluxKustomizations): each one's identity, spec.path as path.Clean leaves it, Source and whether it sets spec.kubeConfig, as FluxKustomizationRecord values, compared as kure reads identities (Path cleaned, an omitted Namespace default, an omitted SourceNamespace the record's Namespace). It is written only by an integration that succeeds, as its last step: a refused one leaves every record as it was. Like the build marker the record is in memory only; fluxcd.UmbrellaTerminals reads it, and a caller that places Flux Kustomizations itself records them there to have them read. Once the root is marked, every directory its parent does not list must be marked too (see "Layout paths" above): an unmarked one is a directory nothing applies.

    A marked Recursive directory that holds no file is refused (go-kure/kure#904): no resource file, extra file, AppFileSingle child file, file of a layout below it or kustomization.yaml a directory below it gets lands at or below it. A marked AppFileSingle root with no resource is refused the same way, since it writes no file either. The writers write it no kustomization.yaml, so every writer would leave an empty directory, which a Git tree drops: the Kustomization would name a path the committed output does not contain. This happens to a bundle with no applications yet, one whose applications were all removed, or one whose applications render nothing, when the whole tree is Recursive. Give the layout a resource, or write it KustomizationExplicit, which writes it resources: [].

    For a marked Recursive directory, the writers also refuse what would make its build differ from the Explicit mode's (its build is its own directory and every directory below it that no kustomization.yaml shields):

    • another marked layout below it with no kustomization.yaml in any directory in between (its own does not count): its objects would be applied twice;
    • an extra file named *.yaml or *.yml in its build: Flux would apply it, or fail the whole build on one it cannot decode, and Explicit mode never lists extra files;
    • an extra or resource file named like a kustomization file (kustomization.yaml, kustomization.yml, Kustomization) in its build: Flux would build the directory holding it as a kustomization;
    • a resource file whose name does not end in .yaml or .yml (only a Config.ManifestFileName can produce one): Flux would skip it, where Explicit mode lists it;
    • the file of an AppFileSingle umbrella child, or of one that renders bundles, in its build: Flux would apply it, where Explicit mode does not list it;
    • the file of an AppFileSingle child in its build that a kustomization.yaml at or above the Recursive directory lists (the child's parent lists it by its path below the parent's directory, see "Layout paths"): both builds would apply it;
    • a child directory its parent's kustomization.yaml would not list, in its build: under WriteToDisk and WriteToTar, a child of another package (its PackageRef and its parent's are both set, with different values). Flux would apply it, where Explicit mode leaves it out. WriteManifest lists such a child, so it is accepted there.

    Two layouts in a marked Recursive directory's build that hold one object are refused as well, as in any other build (see "Layout paths"): that fails the Flux build and the Explicit one alike.

    So Recursive fits a generated target with no other target below it: a leaf bundle directory, or a GroupByName bundle directory over the application directories it lists, plus any unmarked Recursive layout inside one. A Recursive layout with children under FluxIntegratedPerLayout is refused (each child is a target), and so is a Recursive root over any target no kustomization.yaml shields. How Argo CD or a caller's own Kustomization treats a Recursive directory is not checked: Argo CD Applications do not set directory.recurse (go-kure/kure#144), and an unmarked Recursive directory holding no file is accepted, although Git does not keep an empty directory.

  • A FluxIntegratedPerLayout layout references no child directory: each child is applied by the Flux Kustomization the integrator placed in the parent's Resources, listed as one of its own files. No reference is derived from a child's name.

  • No layout references a child that renders bundles, in any placement: that child is a reconciliation unit, applied by its own Flux Kustomization or ArgoCD Application and by nothing else, so every object has one owner. Building a parent directory therefore does not include its child units; a tree written without Flux or ArgoCD integration has no CR applying them.

  • GroupByName bundle layouts are written KustomizationExplicit, so the CRs hosted there (umbrella children, PerLayout applications) are listed

  • A layout that renders a bundle, and every child of a FluxIntegratedPerLayout layout, always gets a kustomization.yaml unless it is KustomizationRecursive, even when it holds nothing else (a bundle with no applications, an empty node, an empty augmenter layout): a Flux Kustomization or ArgoCD Application names that directory, and an empty directory does not survive a Git tree. A kustomization that lists nothing is written resources: [] (kustomize rejects a bare resources: as empty). A Recursive one that holds nothing and that a generated Flux Kustomization names is refused, as described above.

  • A resources entry, a configMapGenerator name and a generator's files entry are written plain when kustomize reads them back as the same string, and double-quoted otherwise (go-kure/kure#896). kustomize reads a kustomization.yaml as YAML 1.1, so a child directory or generator named y, on, null or 1e3 would otherwise be read as a bool, null or number and fail the build.

  • An AppFileSingle child writes one file, <Name>.yaml, into its Namespace, normally its parent's directory, and never a kustomization.yaml of its own (before go-kure/kure#860 it replaced the parent's, dropping the parent's files), and its file may not take the name of a file the parent writes there (see "Layout paths"). The parent's kustomization.yaml lists that file next to its own, by its path relative to the parent's directory (sub/<Name>.yaml for a child below it), and the writers refuse a listed file outside that directory or in a spelling of it that differs only in case; in WriteManifest the child's mode is its effective one, so a child with no mode of its own under ArgoProfile's AppFileSingle is listed as <Name>.yaml, not as a directory, also by the unnamed cluster root. A child with no resources writes no file, so nothing lists it; a cluster root that holds only such a child still gets its kustomization.yaml, which lists nothing. An AppFileSingle root, with no parent to list its file, still writes a kustomization.yaml next to it, which lists its children in that same directory (see "Layout paths").

  • Every writer refuses an AppFileSingle child that has children of its own before writing anything: it writes no kustomization.yaml, so nothing would list them and they would drop out of the build. The walkers never build one themselves; the root is not checked, since the synthetic cluster wrapper a walker builds takes ArgoProfile's AppFileSingle in WriteManifest.

  • Every writer likewise refuses an AppFileSingle child, with or without resources, that carries ConfigMapGenerators (go-kure/kure#891): a configMapGenerator exists only inside a kustomization.yaml, the child writes none, and before this its generators were silently dropped. They are not moved into the parent's kustomization.yaml. In WriteManifest this includes any application layout written as one file through Config (ArgoProfile, or ApplicationFileMode: AppFileSingle set explicitly) that an augmenter gives generators: under WalkCluster with every Flux placement but FluxIntegratedPerLayout, and under WalkClusterByPackage with every placement, since it clears the placement. An augmenter that also sets its layout's ApplicationFileMode to AppFilePerResource keeps its generators: the layout gets its own directory and kustomization.yaml.

  • The same holds for any other layout the writer writes no kustomization.yaml for (go-kure/kure#899). That is an AppFileSingle root with no resources and no children, in every writer, including one made AppFileSingle through Config in WriteManifest. A layout shaped like the synthetic cluster root (Name "", a single-segment Namespace) with nothing to list was one too in WriteManifest; since go-kure/kure#979 it gets its kustomization.yaml there as in the other writers, and its generators are written into it. A KustomizationRecursive root, AppFileSingle or not, is refused as Recursive. Each is refused before anything is written when it carries ConfigMapGenerators, which were silently dropped before. FlattenSingleTier no longer builds such a root: it moved a lone augmenter application and its generators onto the root, and since go-kure/kure#979 it collapses no directory that renders a bundle. Give such a root a resource, or put the generators on a layout that writes a kustomization.yaml.

Layout origins

Every layout the walkers build records what it renders: OriginNodes(), OriginBundles() and OriginApplication(). A node layout renders its node (plus its bundle when BundleGrouping is GroupFlat); a GroupByName bundle layout and an umbrella-child layout render their bundle; a per-app layout its application. The root node's layout renders its node and no bundle: with BundleGrouping: GroupFlat its bundles are rendered by the directory OriginUnit() returns (see The root node's bundles); on every other layout OriginUnit() is nil. A level merged by a GroupFlat axis moves the absorbed nodes and bundles into the absorbing layout's origins, and a FlattenSingleTier collapse the absorbed node; a merged application has no origin of its own. Hand-built layouts have none. OriginBundleObjects(b) returns the objects bundle b's applications render in that directory or its per-app directories (plus a stand-in for each ConfigMap a configMapGenerator makes in an augmenter application's layout or a layout below it: its kind and name, and the annotations the entry sets at the time of the call): the Flux generator uses it to refuse a patch that would reach another bundle sharing the directory. OriginApplicationObjects() returns, per application rendered in a layout, the application, its objects and its own layout: the objects are what the application emitted plus, for an application with its own directory, what a LayoutAugmenter added there or below; the layout is nil for an application written into its bundle's directory. The records are on the layout that renders the application's bundle, under every grouping, and a FlattenSingleTier collapse leaves them there: it collapses no directory that renders a bundle (go-kure/kure#979). A workflow uses them to apply an application's Delivery intent to exactly its objects.

IndexOrigins(root, cluster) resolves a cluster's bundles and nodes to those layouts (BundleLayout, NodeLayout, Parent, Bundles in layout pre-order) and KustomizationPath(b) is the directory of the layout that renders b — the one path every Flux Kustomization and ArgoCD Application kure emits for a bundle uses. It refuses a tree it cannot resolve: an object rendered twice, a rendered set that differs from what the cluster reaches (hand-built, partial or other-cluster trees), two bundles with one name, two bundles whose Kustomization or Application would get one name (Bundle.UnitName), a node or bundle layout set to AppFileSingle mode, a layout that is a bundle's own directory (an umbrella child's, a node's bundle's under GroupByName, or the root node's bundle's under GroupFlat when no other bundle is merged with it) and is not named by the bundle's DirName or else its Name, two bundles whose own directories are one (compared as the writers compare them, so two DirNames that differ in case only are one; named by their paths, as the writers name them), and a dependency cycle between units. WriteManifest refuses a node or bundle layout whose own ApplicationFileMode is AppFileSingle too: its files would go into its Namespace, so no directory would exist at its path. Config.ApplicationFileMode is only the default for application (and hand-built) layouts, so ArgoProfile's AppFileSingle writes one file per application while nodes and bundles keep their directories.

Units() returns the layouts that render bundles: each is one reconciliation unit, the directory a Flux Kustomization or ArgoCD Application applies. UnitName(b) is the unit that applies b: the name in effect (Bundle.UnitName: KustomizationName, or Name without it) of the first bundle its directory renders. UnitOfName(name) maps a Kustomization name to its unit, and returns a name no rendered bundle has in effect unchanged. UnitDependencies(l) / UnitNamedDependencies(l) map the bundles' DependsOn / NamedDependsOn to units, dropping dependencies inside l's own unit. IndexOrigins refuses a cycle in those dependencies; waits a workflow adds on top (Flux health checks, creation order) are checked by that workflow. Bundles are resolved by Name, which is unique, so a copy of a bundle resolves like the original. A DependsOn copy that leaves KustomizationName empty or sets the rendered bundle's name in effect (UnitName()) is that bundle. IndexOrigins refuses one that sets another name, naming both, and one that stands for a bundle whose Kustomization name is also in the dependant's NamedDependsOn (one dependency in both lists), in the words stack.ValidateCluster uses.

NodeGrouping: GroupFlat (as in the CentralizedControlPlane preset) moves a merged node's umbrella children and augmenter layouts under the absorbing node, where they keep their own directories, files and Flux CRs.

Extra Files and ConfigMap Generators

ManifestLayout.ExtraFiles lets callers attach arbitrary files (e.g. a values.yaml) into a layout's directory alongside the resource YAMLs. ManifestLayout.ConfigMapGenerators adds entries to a configMapGenerator: section in the generated kustomization.yaml. kustomize appends a content-hash suffix to the generated ConfigMap name and rewrites references (e.g. HelmRelease.spec.valuesFrom) on build, so any change to the source file forces re-reconciliation — the canonical FluxCD pattern for tracking Helm values changes.

A generator needs a kustomization.yaml the writer writes, so the writers refuse one on a KustomizationRecursive layout, an AppFileSingle child, or a root that writes no kustomization.yaml, and they refuse a generated ConfigMap whose identity its build already holds (see "Layout paths").

ConfigMapGeneratorSpec.Annotations is written as the entry's options.annotations, in key order, so the ConfigMap kustomize builds carries them. An entry without annotations is written as before, with no options block.

An ExtraFile.Name is a relative path of /-separated segments made of letters, digits, ., _ and -, with no . or .. segment; a name in a subdirectory (assets/dashboard.json) creates that directory. Every writer (WriteToDisk, WriteManifest, WriteToTar) refuses, before writing any file of the tree, an extra file that would take a path it owns in that directory: a generated resource file, a kustomize control file (kustomization.yaml, kustomization.yml, Kustomization), a child layout's output directory where it lies inside this layout's (umbrella children included; anything under it, or a file on the way to it) or the <name>.yaml of an AppFileSingle child with resources, or another extra file (listed twice); nor may it use any of those files as a directory (kustomization.yaml/x), or be a file where one of them needs a directory. A child's output directory is the one its writer uses (for WriteManifest, after applying the Config defaults). All names are compared case-insensitively, as on default macOS volumes. A .. segment in the Namespace or Name of any layout of the tree refuses it before any file is written, whether or not the layout has extra files (go-kure/kure#977): an augmenter can rename its layout after the walk, and the final value is what the writers join into a path. When a layout has extra files, a .. segment in a generated file name refuses the tree as well. A rooted name (/x) is not refused, since every writer joins it under its base. Previously such an extra file silently replaced the generated one on disk, or shadowed it as a later tar entry, while kustomization.yaml still listed the path.

LayoutAugmenter is an optional interface on stack.ApplicationConfig:

type LayoutAugmenter interface {
    AugmentLayout(layout *ManifestLayout) error
}

When app.Config implements it, the walker invokes AugmentLayout on the per-app ManifestLayout after resource generation, giving the config a chance to attach ExtraFiles, ConfigMapGenerators, and sub-ManifestLayout children. It runs on every per-app layout a walker creates, in both walkers and inside umbrella children — with ApplicationGrouping: GroupFlat an augmenter app still gets its own per-app sub-layout instead of merging into its bundle's directory.

LayoutIntentAugmenter is an optional companion to LayoutAugmenter, for a config whose desire for its own layout varies per instance rather than being fixed for the whole type:

type LayoutIntentAugmenter interface {
    LayoutAugmenter
    WantsOwnLayout() bool
}

WantsOwnLayout() gates placement only, and only where ApplicationGrouping is GroupFlat (in WalkCluster and WalkClusterByPackage alike, umbrella children included):

ApplicationGrouping WantsOwnLayout() absent or true WantsOwnLayout() == false
GroupByName own layout + AugmentLayout own layout + AugmentLayout
GroupFlat own child layout + AugmentLayout resources merged into the bundle's directory, AugmentLayout not called (no layout exists to pass it)

A config that implements only LayoutAugmenter keeps today's presence-only behaviour unchanged.

A walk calls AugmentLayout once, right after the Generate call it belongs to. The layout it passes holds, in Resources, the very objects that call returned. Read them there, never from state Generate saved. Application.Generate and Bundle.Generate never augment. Each walk augments a new layout: for an unchanged config an augmenter adds the same things every time and keeps no state the next call depends on. WantsOwnLayout() answers from the config alone. A wrapper config that embeds the stack.ApplicationConfig interface hides both interfaces: it gets no AugmentLayout under any grouping and, under GroupFlat, no layout of its own; one that forwards AugmentLayout without WantsOwnLayout gets its own layout whatever the wrapped config answers. Forward both (see Stack § Generation contract).

After AugmentLayout returns, every layout below the per-app layout that leaves FileNaming unset takes its parent's (see File Naming Modes).

Sub-Layout Children and Flux Integration

Augmenters may attach sub-layouts as Children of a per-app ManifestLayout. In FluxIntegratedPerLayout mode each such child that is eligible (see below) receives a Flux Kustomization CR automatically placed in the parent layout's Resources.

Eligibility for CR generation. A child layout receives a Flux Kustomization CR when ALL of the following hold:

  • Integration runs with FluxIntegratedPerLayout.
  • !child.UmbrellaChild
  • child.ApplicationFileMode != AppFileSingle
  • The child renders no bundle (a child that does already has that bundle's CR in the parent).
  • A source can be resolved: the SourceRef of the nearest layout at or above the parent that renders bundles (with BundleGrouping: GroupFlat the root node's layout renders none and counts with the SourceRef of its own bundle, see The root node's bundles; with GroupByName no node's layout counts), else the one SourceRef the URL-less bundles below the child share, else (no SourceRef without a URL below the child, or two that differ) the SourceRef of the bundle of the nearest node, at or above the child's own, that has one (the fluxcd README, "Per-layout name rule"). The Kustomization of the root node's layout, which exists below a ClusterName wrapper, takes no Source the integration generates, since it applies the directory that hosts them: such a SourceRef is passed over, and with no other left the integration is refused (go-kure/kure#979; the fluxcd README, "Layout Integration"). A missing or incomplete SourceRef (nil, empty, or without Kind or Name) causes IntegrateWithLayout to return a hard error — a Kustomization without spec.sourceRef is rejected by Flux.

The parent's kustomization.yaml lists that CR file as one of its own resources, so every child the writers do not reference as a directory has a backing CR. The integrator applies this rule at any depth.

Naming Constraint

In FluxIntegratedPerLayout mode a child layout's Flux Kustomization CR is named <unit name>-<child Name>, the unit name being the name of the Kustomization that applies the bundle the application belongs to (web-nginx-00-pre-install for the child nginx-00-pre-install below the bundle web). Set ManifestLayout.KustomizationName on the child to give the CR another name. The name in effect must be a Flux Kustomization name, a DNS-1123 subdomain of at most 63 characters. The default is longer than the child's own name by the unit name, so the integrator shortens a default over the limit to <unit prefix>-<hash>-<child Name>, keeping the child's name (fluxcd package README, "Per-layout name rule"); a default that fits is unchanged. A child name over 54 characters leaves no room for the hash beside it, so its default over the limit is <first 54 bytes of the child Name>-<hash>, without the hyphens and dots that end those bytes, or the hash alone where nothing is left of them (go-kure/kure#1036; it was refused before). A set name is never shortened: one over the limit is refused, and is fixed by changing the field (the error names the layout and the field). Flux Kustomization CRs live in the flux-system namespace, so names must be globally unique across all apps in the cluster — two CRs with the same metadata.name collide, and the integrator refuses such a tree rather than skipping one of them, naming both owners.

Augmenters are responsible for ensuring uniqueness within their bundle. The recommended convention is to prefix each child name with the app name: {appName}-{hookGroupDir} (e.g. nginx-00-pre-install).

DependsOn

Set ManifestLayout.DependsOn to a list of sibling layout names. In FluxIntegratedPerLayout mode the layout integrator translates these into spec.dependsOn entries on the child's Kustomization CR, enabling ordered reconciliation between hook groups (e.g. pre-install → hooks → post-install). Each entry is written as the CR name of the layout it names, which is not the layout's own name (see above). An entry may also name another layout below the same bundle's directory, the parent application layout for instance; when two such layouts share the name and neither is a sibling, the entry is refused. An entry that names no such layout is written as given, as the name of a Kustomization. The CR of a node layout that renders no bundle is one such name: <path with "/" replaced by "-">-node, or the node's KustomizationName. The field applies only to a child layout that gets a CR of its own (not an umbrella child, not AppFileSingle, rendering no bundle). In every other case, and under the other placements, the layout integrator and ResourceGenerator.GenerateFromLayout refuse it, naming the layout, every such field it sets, and FluxIntegratedPerLayout as the placement that carries them. An augmenter that orders its layouts is therefore refused under FluxSeparate (the default) and FluxIntegratedPerBundle: integrate its application with FluxIntegratedPerLayout. A value the walker copied from a node (below) is refused on the node instead, by the node's path, and not again on its layout.

Wait, Timeout, RetryInterval, Labels, Annotations

Five fields of ManifestLayout are settings of the layout's Flux Kustomization CR in FluxIntegratedPerLayout mode: Wait (*bool), Timeout, RetryInterval (Go durations), Labels and Annotations. No object in the layout's directory gets them. Unset, the CR of an application's layout and of every layout below it takes the value of the bundle that holds the application; a set Wait, Timeout or RetryInterval replaces the bundle's (a Wait pointing at false turns an inherited wait off), and labels and annotations are merged with the bundle's key by key, the layout's value winning, so an inherited key cannot be dropped. Any other layout inherits nothing. The layout integrator refuses a duration that does not parse or that the Flux API does not take (a negative one, or a positive one under a millisecond) and a label or annotation the Kubernetes API would not accept, naming the layout. Like DependsOn, the fields apply only to a layout that gets a CR of its own, and are refused in every other case and under the other placements. See the Flux engine's "Per-layout settings" for where the values come from and what readiness through a chain of such CRs means.

Interval, Prune, Force, Suspend

Four more fields are settings of the same CR, under the same conditions: Interval (a Go duration), Prune, Force and Suspend (*bool). A set field replaces the value of the bundle that holds the layout's application, and a pointer to false turns an inherited Prune, Force or Suspend off. Unset, the CR takes the bundle's. Where neither sets one, Interval and Prune are the Flux generator's (ResourceGenerator.DefaultInterval and Prune), and Force and Suspend are left out of the CR. The layout integrator refuses an interval that does not parse or that the Flux API does not take, naming the layout. A layout has no field for patches or for a post-build substitution: those are the bundle's, and the Flux engine's "Per-layout settings" says which CR takes them.

Node fields

On a node's own layout the walker fills KustomizationName from stack.Node.KustomizationName and DependsOn from stack.Node.NamedDependsOn; those entries are Kustomization names and are written as given, whatever their value. A node that a grouping axis renders into another node's directory has no layout of its own, so nothing is copied for it. The copy is taken at the walk: a name or an entry the node gets afterwards is not on the layout, and the layout integrator refuses that node until the cluster is walked again or the layout carries the value. The layout integrator decides which nodes may set the fields: see the Flux engine's "Node Kustomizations". The walker fills none of the nine settings above on a node's layout, since stack.Node has no field for them: set them on the walked layout.

ClusterName-Aware Layouts

Setting LayoutRules.ClusterName prepends the cluster name as a root directory, producing paths like {clusterName}/{nodeName}/... instead of {nodeName}/.... This is useful when a single repository manages multiple clusters. When the last segment of ClusterName is the root node's name (for example ClusterName platform with a root node platform), the root node is the cluster directory itself: the output is platform/..., not platform/platform/....

Without a ClusterName the root node sits at {rootName} and every child node nests under it ({rootName}/{childName}/...). An unnamed root node has no directory of its own and stays at cluster, with its children at cluster/{childName} as before; deeper descendants now nest under them (cluster/{childName}/{grandchildName}), where they used to be written outside cluster/, unreferenced. WalkClusterByPackage places each package's root the same way, below the package directory; a package whose root node belongs to another package has no root directory of its own either, so its unnamed wrapper stays at cluster. A node outside the package adds no directory of its own: its in-package descendants attach to the nearest in-package ancestor (or the package root), including where the tree leaves a package and re-enters it lower down.

TopDirectory(rootNode, rules) returns the directory at the top of the tree WalkCluster builds: the one that holds the tree's first kustomization.yaml, and so the one to point Flux at. With a ClusterName it is the cluster directory; without one it is the root node's name, cluster for an unnamed root node, and . when the root node is nil (no tree is walked, and the caller applies the directory it writes to). It is relative to the directory the tree is written into and has no leading slash (. is that directory itself). The walk takes its top from the same place, so the two name the same directory, and the Flux bootstrap asks it for the directory it applies. Only the spelling differs, and only for a rooted ClusterName (/prod): the walk's own FullRepoPath keeps the slash and the writers resolve it under the directory they write to, which is the directory returned (prod). The rules are validated first, as WalkCluster validates them. Where the root node's name is the directory, a name that is no directory name (../prod, a/b, .) is an error, as it is to WalkCluster; under a ClusterName the name is no part of the directory and is not checked. Two limits: it does not describe a WalkClusterByPackage tree, which is placed without the ClusterName, one tree per package; and it does not know the directory a writer is given, so a tree written below a sub-path of the repository is at that sub-path joined with this directory.

Flatten Single Tier (opt-in)

LayoutRules.FlattenSingleTier collapses one vestigial intermediate directory layer at the top of the tree when it adds no semantic value.

Conservative collapse preconditions — ALL must hold:

  • LayoutRules.FlattenSingleTier is true.
  • The parent layout is top-level (Namespace has no path separator).
  • Parent has exactly one Children entry.
  • Parent has no own Resources.
  • The single child is not an UmbrellaChild.
  • The single child has no Children of its own (terminal layer).
  • The single child renders no bundle (go-kure/kure#979).

A directory that renders a bundle is applied by its own Flux Kustomization, which its parent hosts. Collapsing it into the top of the tree, which has no parent, would make that Kustomization part of the build it applies, so it is left where it is.

What it still collapses in a walked tree is a single child directory that renders no bundle and has no directory below it: a node that has neither a bundle nor child nodes, or, under NodeGrouping: GroupFlat, a node with the bundle-less nodes below it merged into its directory. That is a ClusterName directory over such a root node, or a root node over one such child. The absorbing layout takes over the collapsed layout's origin nodes (see Layout origins). A hand-built tree, which carries no origins, collapses as before. Nothing is rewritten after generation: a Flux CR a caller adds to the walked tree keeps the spec.path it was given.

Breaking change (go-kure/kure#979). Before, a single child that rendered a bundle was collapsed too: a root node apps with one bundle under ClusterName: cluster-name was written to cluster-name/. It is now written to cluster-name/apps/<bundle>/ (the bundle's DirName, or its Name without one) with or without the flag (see The root node's bundles).

Scoped to WalkCluster. WalkClusterByPackage is unaffected — its synthetic unnamed wrappers express package boundaries that the flatten helper would otherwise erroneously collapse.

Default: false — no behaviour change for existing callers.

Layout Presets

Three named presets provide pre-configured LayoutRules for common deployment patterns. Use LayoutRulesForPreset() to get rules, or ConfigForPreset() to get a matching Config.

Preset Pattern FluxPlacement NodeGrouping FileNaming
CentralizedControlPlane A FluxSeparate GroupFlat FileNamingKindName
SiblingControlPlane B FluxSeparate GroupByName FileNamingDefault
ParentDeployedControl C FluxIntegratedPerLayout GroupByName FileNamingDefault

This block and the one under Example Usage are the bodies of Example functions in example_test.go, which go test runs; the two interface blocks above are declarations, shown as excerpts. The examples import this package as layout, os, path/filepath, and fmt for the lines that print what they built. Two helpers are declared in the same file: exampleCluster() builds cluster prod, whose root node apps holds one bundle web with applications api and ui, each emitting a ConfigMap; printFiles(dir) prints every file below dir.

rules, err := layout.LayoutRulesForPreset(layout.PresetCentralizedControlPlane)
if err != nil {
    panic(err)
}
cfg, err := layout.ConfigForPreset(layout.PresetCentralizedControlPlane)
if err != nil {
    panic(err)
}
fmt.Println(rules.FluxPlacement, rules.NodeGrouping, rules.FileNaming, cfg.KustomizationFileName("web"))

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

cluster := exampleCluster()
out, err := os.MkdirTemp("", "kure-layout-example")
if err != nil {
    panic(err)
}
defer func() { _ = os.RemoveAll(out) }()

// 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 {
    panic(err)
}

// Write to disk
cfg := layout.DefaultLayoutConfig()
err = layout.WriteManifest(filepath.Join(out, "out/manifests"), cfg, ml)
if err != nil {
    panic(err)
}
printFiles(out)

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.

Example (AgentsLayout)
cluster := exampleCluster()

rules := layout.LayoutRules{
	BundleGrouping:      layout.GroupFlat,
	ApplicationGrouping: layout.GroupFlat,
}
ml, err := layout.WalkCluster(cluster, rules)
if err != nil {
	panic(err)
}
// The root node's layout renders no bundle: bundle "web" has the directory
// inside it.
unit := ml.OriginUnit()
fmt.Println(ml.FullRepoPath(), len(ml.Resources))
fmt.Println(unit.FullRepoPath(), len(unit.Resources))
Output:
apps 0
apps/web 2

Index

Examples

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 KindNameManifestFileName

func KindNameManifestFileName(_, kind, name string, mode FileExportMode) string

KindNameManifestFileName returns file names using {kind}-{name}.yaml format, without the namespace prefix. This is the default for Pattern A (CentralizedControlPlane) where per-app artifact directories make the namespace prefix redundant.

func TopDirectory

func TopDirectory(root *stack.Node, rules LayoutRules) (string, error)

TopDirectory returns the directory at the top of the tree WalkCluster builds with rules for a cluster whose root node is root: the directory that holds the tree's first kustomization.yaml, and so the one to point Flux at. It is relative to the directory the tree is written into and has no leading slash; "." is that directory itself. The walk takes its top from the same place (topLayout), so the two name the same directory. The rules are validated first, as WalkCluster validates them.

With a ClusterName it is the cluster directory. Without one it is the root node's name, "cluster" for an unnamed root node, and "." when root is nil: no tree is walked then, and the caller applies the directory it writes to.

Where the root node's name is the directory, a name that is no directory name ("../prod", "a/b", ".") is an error, as it is to WalkCluster (stack.ValidateCluster): no tree is walked for such a root. Under a ClusterName the name is no part of the directory and is not checked here.

Only the spelling differs, and only for a rooted ClusterName ("/prod"): the walk's own ManifestLayout.FullRepoPath keeps the slash, and the writers resolve it under the directory they write to. That is the directory returned here, "prod"; a ClusterName of "/" alone gives ".".

It does not describe a WalkClusterByPackage tree, which is placed without the ClusterName, one tree per package. Nor does it know the directory a writer is given: a tree written below a sub-path of the repository is at that sub-path joined with this directory.

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. The grouping axes apply as in WalkCluster; the package trees carry no Flux placement. The rules are validated first, as in WalkCluster, including the options this walk does not use.

func WriteManifest

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

WriteManifest writes a ManifestLayout to disk using the provided configuration, every directory under basePath/<cfg.ManifestsDir>: a Flux source for a walked layout must be rooted there, because every Flux Kustomization spec.path is a layout directory relative to that root. It refuses, before writing anything, a tree in which two layouts resolve to the same directory (see checkLayoutTree) and a layout that renders a node or bundle but sets AppFileSingle as its own mode: that layout's files go into its Namespace, so no directory exists at the path its Flux Kustomization or ArgoCD Application names. cfg's AppFileSingle never applies to such a layout (see manifestAppMode).

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 ApplicationObjects

type ApplicationObjects struct {
	// Application is the application.
	Application *stack.Application
	// Objects are the objects the application's directory builds for it, the
	// same values the layouts hold: those it emitted and, when it has a layout
	// of its own, those a LayoutAugmenter added to that layout or below it. A
	// ConfigMap that a configMapGenerator builds is not among them: it exists
	// only once kustomize has built the directory (see Layout).
	Objects []client.Object
	// Layout is the application's own layout, whose ConfigMapGenerators (and
	// those of the layouts below it) are the application's. Nil when the
	// application's objects were written into its bundle's directory.
	Layout *ManifestLayout
	// contains filtered or unexported fields
}

ApplicationObjects is what one application rendered in a walked layout.

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
	// FluxKustomizationMode overrides KustomizationMode based on FluxPlacement.
	// When a ManifestLayout's FluxPlacement matches a key in this map, the
	// corresponding KustomizationMode is used instead of the global
	// KustomizationMode. This allows different kustomization.yaml reference
	// styles per flux placement strategy.
	FluxKustomizationMode map[FluxPlacement]KustomizationMode
	// FileNaming controls the file naming pattern. When set, it determines
	// the ManifestFileNameFunc to use. If ManifestFileName is also set, it
	// takes precedence over FileNaming.
	FileNaming FileNamingMode
	// ManifestFileName formats the file name for a resource manifest.
	// Takes precedence over FileNaming when set.
	ManifestFileName ManifestFileNameFunc
	// KustomizationFileName formats the file name for a Flux Kustomization.
	KustomizationFileName KustomizationFileNameFunc
}

Config LayoutConfig defines rules for generating a cluster layout.

func ConfigForPreset

func ConfigForPreset(p LayoutPreset) (Config, error)

ConfigForPreset returns a Config configured for the given preset. Unknown presets return an error.

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.

func (Config) ResolveKustomizationMode

func (c Config) ResolveKustomizationMode(fp FluxPlacement) KustomizationMode

ResolveKustomizationMode returns the effective KustomizationMode for the given FluxPlacement. If FluxKustomizationMode contains an override for the placement, that value is used. Otherwise, the global KustomizationMode (or KustomizationExplicit when unset) is returned.

func (Config) ResolveManifestFileName

func (c Config) ResolveManifestFileName() ManifestFileNameFunc

ResolveManifestFileName returns the effective ManifestFileNameFunc for this Config. If ManifestFileName is set it is returned directly. Otherwise, FileNaming is used to select the function. If neither is set, DefaultManifestFileName is returned.

type ConfigMapGeneratorSpec

type ConfigMapGeneratorSpec struct {
	Name        string
	Files       []string
	Annotations map[string]string
}

ConfigMapGeneratorSpec describes a single kustomize configMapGenerator entry. Files are paths (relative to the layout directory) of files included in the generated ConfigMap. Annotations are written as the entry's options.annotations, which kustomize puts on the ConfigMap it generates: the only way to annotate an object that exists only after the build.

type ExtraFile

type ExtraFile struct {
	Name    string
	Content []byte
}

ExtraFile is an arbitrary file written into a ManifestLayout's directory alongside the resource YAMLs.

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 FileNamingMode

type FileNamingMode string

FileNamingMode controls the file naming pattern for manifest files.

const (
	// FileNamingDefault uses the standard {namespace}-{kind}-{name}.yaml format.
	FileNamingDefault FileNamingMode = "default"
	// FileNamingKindName uses the {kind}-{name}.yaml format, omitting the namespace prefix.
	FileNamingKindName FileNamingMode = "kind-name"
	// FileNamingUnset indicates no file naming preference.
	FileNamingUnset FileNamingMode = ""
)

type FluxKustomizationRecord

type FluxKustomizationRecord struct {
	Namespace, Name string
	Path            string
	SourceKind      string
	SourceNamespace string
	SourceName      string
	KubeConfig      bool
}

FluxKustomizationRecord is what a Flux Kustomization kure placed or kept in a layout read when the integration ended: its identity, its spec.path as path.Clean leaves it, the Source its spec.sourceRef names (an omitted namespace the Kustomization's own) and whether it sets spec.kubeConfig. fluxcd.UmbrellaTerminals compares records as kure reads identities: Path cleaned, an omitted Namespace "default", an omitted SourceNamespace the record's Namespace.

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"
	// FluxIntegratedPerLayout places a Flux Kustomization CR inline for every
	// layout node, including augmenter-added child layouts. Each child's CR is
	// hosted in its parent layout and listed there as a resource file; the
	// parent does not reference the child directory. Finest granularity; use
	// when each child should be reconciled by
	// its own Flux Kustomization (e.g. hook-group dependsOn).
	FluxIntegratedPerLayout FluxPlacement = "integrated"
	// FluxIntegratedPerBundle places Flux Kustomization CRs inline at bundle
	// boundaries only, each hosted in the parent of the directory it applies;
	// a bundle's interior (application and augmenter-added child layouts) is a
	// single kustomize build, with those children referenced as directories.
	// A child that renders bundles is never referenced: its own CR applies
	// it. Coarser than PerLayout: Flux reconciles per bundle, kustomize
	// handles the interior. Use when the unit of Flux reconciliation is the
	// bundle, not each layout node.
	FluxIntegratedPerBundle FluxPlacement = "integrated-per-bundle"
	// 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 writes no kustomization.yaml into the layout's
	// directory, and every other file as KustomizationExplicit does: a Flux
	// Kustomization builds the directory from every .yaml and .yml file below
	// it (go-kure/kure#868).
	KustomizationRecursive KustomizationMode = "recursive"
	// KustomizationUnset indicates no kustomization mode preference.
	KustomizationUnset KustomizationMode = ""
)

type LayoutAugmenter

type LayoutAugmenter interface {
	AugmentLayout(layout *ManifestLayout) error
}

LayoutAugmenter is an optional interface that ApplicationConfig implementations can implement to attach extra files or configMapGenerator entries to their per-app ManifestLayout after resource generation. The walker invokes AugmentLayout when app.Config satisfies this interface.

A walk calls AugmentLayout once, right after the Generate call it belongs to, on the application's own layout; that layout's Resources are the very objects the call returned. The augmenter reads them there, never from state Generate saved. It runs only where the walk gives the application a layout of its own (see LayoutIntentAugmenter for flat grouping), and never from Application.Generate or Bundle.Generate. Each walk augments a new layout, so for an unchanged config an augmenter adds the same things every time and keeps no state the next call depends on.

The interface lives in the layout package (rather than pkg/stack alongside Validator) because ApplicationConfig — defined in pkg/stack — cannot reference *ManifestLayout without creating an import cycle: the layout package already imports pkg/stack.

type LayoutIntentAugmenter

type LayoutIntentAugmenter interface {
	LayoutAugmenter
	WantsOwnLayout() bool
}

LayoutIntentAugmenter is an optional companion to LayoutAugmenter for a config whose desire for its own per-app layout varies per instance rather than being fixed for the whole type. Implementing LayoutAugmenter alone is a per-type, presence-only signal: the method either exists or it doesn't, so a config that only wants its own layout for some instance configurations has no way to express that without a separate wrapper type per case. LayoutIntentAugmenter lets such a config implement AugmentLayout unconditionally and answer "do I want the walker to carve me a directory" per instance instead.

WantsOwnLayout() gates placement only, and only where ApplicationGrouping is GroupFlat (in every walker, WalkClusterByPackage included): false is treated as-if-absent for that decision — the app's resources merge into the bundle's layout instead of getting a per-app child, and AugmentLayout is not invoked because no per-app layout exists to pass it. With ApplicationGrouping GroupByName every app already gets its own layout and AugmentLayout runs unconditionally, regardless of augmenter status.

A config that does not implement this interface keeps LayoutAugmenter's existing presence-only behaviour unchanged.

WantsOwnLayout answers from the config alone: the same config gives the same answer on every call.

The interface lives in the layout package for the same import-cycle reason as LayoutAugmenter above.

type LayoutPreset

type LayoutPreset string

LayoutPreset identifies a named layout pattern that configures all layout dimensions into a known-valid combination. Presets are based on the layout patterns defined in the multi-tier FluxCD layout research.

const (
	// PresetCentralizedControlPlane implements Pattern A: all Flux KS CRs in
	// dedicated aggregator directories, completely separate from payload. Best
	// suited for fleet management with many applications. Uses flat directory
	// grouping and {kind}-{name}.yaml file naming.
	PresetCentralizedControlPlane LayoutPreset = "CentralizedControlPlane"

	// PresetSiblingControlPlane implements Pattern B: Flux KS CRs in a
	// flux-system/ sibling directory within each artifact. Designed for
	// single-artifact or per-app artifact scenarios.
	PresetSiblingControlPlane LayoutPreset = "SiblingControlPlane"

	// PresetParentDeployedControl implements Pattern C: KS CRs live in the
	// payload of their parent Kustomization. Best suited for simple,
	// single-app deployments.
	PresetParentDeployedControl LayoutPreset = "ParentDeployedControl"
)

type LayoutRules

type LayoutRules struct {
	// NodeGrouping says whether each child node gets its own directory
	// (GroupByName) or is merged into its parent's (GroupFlat): its bundle,
	// child nodes and origins then render in the parent's directory. The root
	// node always keeps its directory. Defaults to GroupByName.
	NodeGrouping GroupingMode
	// BundleGrouping says whether each bundle gets its own directory inside
	// its node's (GroupByName) or is rendered in the node's directory
	// (GroupFlat). The root node's directory renders no bundle: with GroupFlat
	// the bundles that would render there share one directory inside it, named
	// after the first of them, and a child node of the root with that name is
	// refused. Defaults to GroupFlat.
	BundleGrouping GroupingMode
	// ApplicationGrouping says whether each application gets its own
	// directory inside its bundle's (GroupByName) or writes its resources into
	// the bundle's directory (GroupFlat). An augmenter application that wants
	// its own layout gets a directory either way, and so does every umbrella
	// child bundle. The three axes are independent. Defaults to GroupFlat.
	ApplicationGrouping GroupingMode
	// 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
	// FileNaming is the naming pattern of the manifest files WriteToDisk and
	// WriteToTar write, for every layout of the tree: those the walkers
	// create, the layouts an augmenter adds and leaves unset (each takes its
	// parent's) and the flux-system directory of FluxSeparate. A layout that
	// sets its own FileNaming keeps it. WriteManifest names files from its
	// Config instead. Defaults to FileNamingDefault
	// ({namespace}-{kind}-{name}.yaml).
	FileNaming FileNamingMode

	// FlattenSingleTier collapses a vestigial intermediate directory layer
	// produced by the walker when it adds no semantic value: a parent layout
	// with exactly one named child whose own children are empty, which is
	// not an UmbrellaChild and which renders no bundle, where the parent
	// itself is a top-level layout (Namespace has no path separator) with no
	// own Resources.
	//
	// A directory that renders a bundle is never collapsed: its Flux
	// Kustomization is hosted by its parent, and the top of the tree has
	// none. In a walked tree that leaves one case: a single child directory
	// that renders no bundle and has no directory below it. That is a node
	// with neither a bundle nor child nodes, or, under NodeGrouping flat, a
	// node with the bundle-less nodes below it merged into it.
	//
	// Only effective for WalkCluster (not WalkClusterByPackage, which uses
	// synthetic unnamed wrappers to express package boundaries).
	//
	// The absorbing layout takes over the collapsed layout's origin nodes.
	// Nothing is rewritten afterwards: a Flux CR a caller adds to the walked
	// tree keeps the spec.path it was given.
	FlattenSingleTier bool
}

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 LayoutRulesForPreset

func LayoutRulesForPreset(p LayoutPreset) (LayoutRules, error)

LayoutRulesForPreset returns LayoutRules configured for the given preset. Unknown presets return an error.

Example
package main

import (
	"fmt"

	"github.com/go-kure/kure/pkg/stack/layout"
)

func main() {
	rules, err := layout.LayoutRulesForPreset(layout.PresetCentralizedControlPlane)
	if err != nil {
		panic(err)
	}
	cfg, err := layout.ConfigForPreset(layout.PresetCentralizedControlPlane)
	if err != nil {
		panic(err)
	}
	fmt.Println(rules.FluxPlacement, rules.NodeGrouping, rules.FileNaming, cfg.KustomizationFileName("web"))
}
Output:
separate flat kind-name kustomization-web.yaml

func (LayoutRules) Validate

func (lr LayoutRules) Validate() error

Validate ensures the LayoutRules contain known option values and a ClusterName the writers can write: one without a ".." path segment. An unset value is valid; it takes its documented default. WalkCluster and WalkClusterByPackage validate the rules they are given before they build anything, so no caller has to (go-kure/kure#979).

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
	// FileNaming is the naming pattern of this layout's resource files under
	// WriteToDisk and WriteToTar. The writers read it from the layout itself,
	// never from its parent: the walkers set it from LayoutRules.FileNaming,
	// and give a layout an augmenter added and left unset its parent's.
	FileNaming FileNamingMode
	Resources  []client.Object
	Children   []*ManifestLayout
	// ExtraFiles are arbitrary files written alongside resource YAMLs in this
	// layout's directory. Typical use: a values.yaml referenced by a
	// configMapGenerator entry. Augmenters (LayoutAugmenter) attach these.
	ExtraFiles []ExtraFile
	// ConfigMapGenerators emit a kustomize configMapGenerator: section in
	// kustomization.yaml. kustomize appends a content-hash suffix to each
	// generated ConfigMap name; resources referencing it (e.g.
	// HelmRelease.spec.valuesFrom) are rewritten to the suffixed name on
	// build, so any change to the source file forces re-reconciliation.
	ConfigMapGenerators []ConfigMapGeneratorSpec
	// UmbrellaChild marks this layout as rendered from a Bundle.Children
	// entry. When true, the parent's kustomization.yaml does not list it: the
	// child is applied by its own Flux Kustomization, which the layout
	// integrator places at the parent layout node (integrated placement) or
	// in flux-system (separate placement), with spec.path = this layout's
	// directory.
	UmbrellaChild bool
	// DependsOn lists what this layout's Flux Kustomization CR waits for.
	// Augmenters (LayoutAugmenter) set this field; on a node's own layout the
	// walker fills it from Node.NamedDependsOn.
	//
	// On an application or augmenter layout an entry is read as a layout name
	// first: that of a sibling, or of another layout below the same bundle's
	// directory. The Flux layout integrator then writes the name of that
	// layout's CR, which is not the layout's ("<unit>-<layout name>", or its
	// KustomizationName). An entry that names no such layout is written as
	// given, as a Kustomization name: the CR of a node layout that renders no
	// bundle is named "<path with / replaced by ->-node" unless the node names
	// it, and that is the name to list. On a node's own layout every entry is
	// a Kustomization name and is written as given; an entry the node lists
	// in NamedDependsOn and this field lacks (the node got it after the walk)
	// is refused by the integrator.
	//
	// The integrator writes spec.dependsOn only on the Kustomization CR it
	// generates for this layout itself, which it does only under
	// FluxIntegratedPerLayout and only for a child layout that is not an
	// umbrella child, is not AppFileSingle and renders no bundle. In every
	// other case the integrator, and ResourceGenerator.GenerateFromLayout,
	// refuse the field (go-kure/kure#1032): under FluxIntegratedPerBundle and
	// FluxSeparate an augmenter that orders its layouts is refused, and only
	// FluxIntegratedPerLayout carries the ordering: integrate an augmenter
	// that orders its layouts with FluxIntegratedPerLayout. What a node sets is refused on the node's own fields, by the
	// node's path, and not again on the layout that carries it.
	DependsOn []string
	// KustomizationName names the Flux Kustomization the layout integrator
	// generates for this layout in FluxIntegratedPerLayout mode, instead of
	// the default: "<unit>-<layout name>" for an application or augmenter
	// layout, the "-node" name for a node's own layout. An augmenter sets it
	// on a layout it creates; the walker fills it from Node.KustomizationName
	// on a node's own layout. A name a caller sets on a walked node layout
	// wins over the node's; a node that has a name while its layout carries
	// none (the node got it after the walk) is refused by the integrator.
	// Like DependsOn it is read only where the
	// layout gets a Kustomization of its own, and refused anywhere else.
	// The name in effect, set or
	// default, must be one Flux can reconcile
	// (stack.ValidateKustomizationName): the integrator refuses any other
	// where it creates the Kustomization. It shortens a "<unit>-<Name>"
	// default over the limit, keeping the "-<Name>" tail where Name has at
	// most 54 characters, and keeping the first 54 bytes of a longer Name,
	// without the hyphens and dots that end them, before the hash (the hash
	// alone where nothing is left of them). A name set here is not
	// shortened, so one that is too long is refused.
	KustomizationName string
	// Wait, Timeout, RetryInterval, Labels and Annotations are settings of the
	// Flux Kustomization the layout integrator generates for this layout in
	// FluxIntegratedPerLayout mode: its spec.wait, spec.timeout and
	// spec.retryInterval, and the labels and annotations of the Kustomization
	// object itself. No object in the layout's directory gets them. Like
	// KustomizationName they are read only where the layout gets a
	// Kustomization of its own, and are refused anywhere else.
	//
	// An application's own layout, and every layout below it (the ones its
	// LayoutAugmenter added), inherits the five from the bundle that holds the
	// application. Wait, Timeout and RetryInterval left unset here are the
	// bundle's, and set here they replace it: a Wait that points at false
	// turns an inherited wait off, while an inherited Timeout or RetryInterval
	// can be replaced but not removed. Labels and Annotations are merged with
	// the bundle's per key and the value set here wins, so a key the bundle
	// sets can be given another value but not dropped. Any other layout (a
	// node's own, one a caller added to the tree) inherits nothing: its
	// Kustomization carries what is set here.
	//
	// Timeout and RetryInterval must parse as a Go duration ("5m"). Where the
	// integrator creates the Kustomization it refuses any other value, and a
	// label or annotation the Kubernetes API does not accept.
	Wait          *bool
	Timeout       string
	RetryInterval string
	Labels        map[string]string
	Annotations   map[string]string
	// Interval, Prune, Force and Suspend are four more settings of that
	// Kustomization (go-kure/kure#1021): its spec.interval, spec.prune,
	// spec.force and spec.suspend. They are read where the five above are and
	// refused anywhere else, and they follow the same rule:
	// set here, a value replaces the one of the bundle that holds the
	// application; left unset, it is that bundle's. A Prune, Force or Suspend
	// that points at false turns an inherited true off.
	//
	// Where neither the layout nor a holding bundle sets one, Interval and
	// Prune are the generator's (ResourceGenerator.DefaultInterval and
	// ResourceGenerator.Prune), and Force and Suspend are left out. Interval
	// must parse as a Go duration and be one Flux takes; the integrator
	// refuses any other value where it creates the Kustomization.
	//
	// The patches and the postBuild substitution of that Kustomization have
	// no field here: they are the holding bundle's (Bundle.Patches,
	// Bundle.PostBuild), and a layout without a holding bundle has none.
	Interval string
	Prune    *bool
	Force    *bool
	Suspend  *bool
	// contains filtered or unexported fields
}

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, bundle and application hierarchy. Each grouping axis of rules decides whether its level gets a directory (see grouping). The rules are validated first, as given (LayoutRules.Validate); unset values then take their defaults.

Example
package main

import (
	"fmt"
	"io/fs"
	"os"
	"path/filepath"

	"sigs.k8s.io/controller-runtime/pkg/client"

	"github.com/go-kure/kure/pkg/kubernetes"
	"github.com/go-kure/kure/pkg/stack"
	"github.com/go-kure/kure/pkg/stack/layout"
)

// exampleApp is a minimal stack.ApplicationConfig: one ConfigMap named after
// the application.
type exampleApp struct{}

func (exampleApp) Generate(app *stack.Application) ([]*client.Object, error) {
	var obj client.Object = kubernetes.CreateConfigMap(app.Name, app.Namespace)
	return []*client.Object{&obj}, nil
}

// exampleCluster is the cluster the examples walk: a root node "apps" whose
// bundle "web" holds the applications "api" and "ui".
func exampleCluster() *stack.Cluster {
	cluster, err := stack.NewClusterBuilder("prod").
		WithNode("apps").
		WithBundle("web").
		WithApplication("api", exampleApp{}).
		WithApplication("ui", exampleApp{}).
		End().
		End().
		Build()
	if err != nil {
		panic(err)
	}
	return cluster
}

// printFiles prints every file below dir, relative to it.
func printFiles(dir string) {
	err := filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
		if err == nil && !d.IsDir() {
			rel, _ := filepath.Rel(dir, path)
			fmt.Println(rel)
		}
		return err
	})
	if err != nil {
		panic(err)
	}
}

func main() {
	cluster := exampleCluster()
	out, err := os.MkdirTemp("", "kure-layout-example")
	if err != nil {
		panic(err)
	}
	defer func() { _ = os.RemoveAll(out) }()

	// 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 {
		panic(err)
	}

	// Write to disk
	cfg := layout.DefaultLayoutConfig()
	err = layout.WriteManifest(filepath.Join(out, "out/manifests"), cfg, ml)
	if err != nil {
		panic(err)
	}
	printFiles(out)
}
Output:
out/manifests/clusters/apps/kustomization.yaml
out/manifests/clusters/apps/web/cluster-configmap-api.yaml
out/manifests/clusters/apps/web/cluster-configmap-ui.yaml
out/manifests/clusters/apps/web/kustomization.yaml

func (*ManifestLayout) FluxBuild

func (ml *ManifestLayout) FluxBuild() bool

FluxBuild reports what SetFluxBuild last recorded.

func (*ManifestLayout) FluxKustomizations

func (ml *ManifestLayout) FluxKustomizations() []FluxKustomizationRecord

FluxKustomizations returns a copy of what SetFluxKustomizations last recorded: nil when nothing was.

func (*ManifestLayout) FullRepoPath

func (ml *ManifestLayout) FullRepoPath() string

FullRepoPath returns the layout's directory: Namespace joined with Name. Namespace is always the parent's path ("." for the tree root); an empty Namespace means "cluster". A child whose Namespace is already its own path nests one level deeper (go-kure/kure#771), and the writers refuse it where its parent lists it (go-kure/kure#979); set Namespace to the parent path.

func (*ManifestLayout) FullRepoPathWithPackage

func (ml *ManifestLayout) FullRepoPathWithPackage() string

FullRepoPathWithPackage returns the repository path including package-specific prefix

func (*ManifestLayout) OriginApplication

func (ml *ManifestLayout) OriginApplication() *stack.Application

OriginApplication returns the application a per-app layout renders, or nil.

func (*ManifestLayout) OriginApplicationObjects

func (ml *ManifestLayout) OriginApplicationObjects() []ApplicationObjects

OriginApplicationObjects returns, for a layout that renders bundles, what each application of those bundles rendered, in emission order: the record a workflow uses to act on one application's objects (a delivery intent, say). The layout package applies nothing to them. Nil for a hand-built layout and for a layout that renders no bundle.

func (*ManifestLayout) OriginBundleObjects

func (ml *ManifestLayout) OriginBundleObjects(b *stack.Bundle) []client.Object

OriginBundleObjects returns the objects bundle b's applications render in this layout's directory or its per-app directories. Nil when b is not one of OriginBundles. A ConfigMap a configMapGenerator builds is among them as a stand-in: its kind and name, and the annotations its entry sets at the time of the call.

func (*ManifestLayout) OriginBundles

func (ml *ManifestLayout) OriginBundles() []*stack.Bundle

OriginBundles returns the bundles whose resources this layout's directory holds. Nil for a hand-built layout.

func (*ManifestLayout) OriginNodes

func (ml *ManifestLayout) OriginNodes() []*stack.Node

OriginNodes returns the stack nodes whose directory this layout is. Nil for a hand-built layout and for bundle, application and augmenter layouts.

func (*ManifestLayout) OriginUnit

func (ml *ManifestLayout) OriginUnit() *ManifestLayout

OriginUnit returns the child layout that renders the bundles a flat BundleGrouping merges into this layout's node: the root node's layout renders no bundle, so they have one directory inside it (go-kure/kure#979). Nil for every other layout, and under BundleGrouping by name, where each bundle has a directory of its own.

func (*ManifestLayout) SameDirectory

func (ml *ManifestLayout) SameDirectory(other *ManifestLayout) bool

SameDirectory reports whether the directories of ml and other, each written as a directory, are one directory to the writers: the FullRepoPath resolved under the output directory (a leading slash dropped) and cleaned, compared without regard to case. A Name such as "/web" or "./web" resolves to the directory of "web", and the writers refuse a tree in which two layouts share a directory. It says nothing about a layout a writer writes as a single file (AppFileSingle), which has no directory of its own. WriteToDisk with an empty base path is the one writer call it does not describe: that call has no output directory to resolve a rooted path under, and writes it as an absolute path.

func (*ManifestLayout) SetFluxBuild

func (ml *ManifestLayout) SetFluxBuild(b bool)

SetFluxBuild records whether a Flux Kustomization kure generated builds this layout's directory: its spec.path names the directory, or it is the root of a tree whose integration generated one (the Flux bootstrap applies the root). Only fluxcd's LayoutIntegrator sets it; a caller that places Flux Kustomizations itself, from fluxcd's GenerateFromLayout or its own code, marks their spec.path layouts here. For a KustomizationRecursive layout so marked the writers refuse a directory that holds no file and a build that differs from what the Explicit mode would build (see checkRecursiveLayouts).

func (*ManifestLayout) SetFluxKustomizations

func (ml *ManifestLayout) SetFluxKustomizations(recs []FluxKustomizationRecord)

SetFluxKustomizations records the Flux Kustomizations kure placed or kept in this layout, replacing any earlier record; in memory only, never serialised. Only fluxcd's LayoutIntegrator sets it, on every layout of a tree it integrates, as the last step of an integration that succeeds (a refused one leaves every record as it was); a caller that places Flux Kustomizations itself records them here to have fluxcd.UmbrellaTerminals read them as the integration's. The slice is copied.

func (*ManifestLayout) WriteToDisk

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

WriteToDisk writes the layout tree under basePath. It refuses a tree in which two layouts resolve to the same directory (see checkLayoutTree) before writing anything.

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). It refuses a tree in which two layouts resolve to the same directory (see checkLayoutTree) before writing any entry.

type OriginIndex

type OriginIndex struct {
	// contains filtered or unexported fields
}

OriginIndex resolves the stack objects of one cluster to the layouts that render them. Build it with IndexOrigins.

func IndexOrigins

func IndexOrigins(root *ManifestLayout, c *stack.Cluster) (*OriginIndex, error)

IndexOrigins indexes a layout tree walked from cluster c (WalkCluster) by the origins its layouts record. It refuses:

  • a bundle or node rendered by two layouts;
  • a tree whose rendered set differs from the bundles and nodes reachable from c (node bundles plus their umbrella descendants), naming what is missing or foreign — so a hand-built, partial or other-cluster tree is refused;
  • two bundles with one Name: the name is the bundle's identity, by which a copy of it is resolved;
  • two bundles whose Flux Kustomization or ArgoCD Application would get one name (Bundle.UnitName: KustomizationName, or Name without it), naming both bundles by their paths;
  • a layout rendering a node or bundle in AppFileSingle mode: it is written into its Namespace, not into its own directory;
  • a DependsOn bundle that is a copy of a rendered bundle (another bundle with its Name, which UnitName resolves to it) and sets a KustomizationName other than the rendered bundle's name in effect, naming both. A copy that leaves the field empty is the rendered bundle;
  • such a copy of a bundle whose Kustomization name is also in the dependant's NamedDependsOn: one dependency in both lists, which Bundle.Validate cannot see through the copy. stack.ValidateCluster refuses both in the same words (see checkDependencyCopies);
  • a layout that is a bundle's own directory (an umbrella child, or a node's bundle under BundleGrouping GroupByName) whose Name is not the bundle's directory name, its DirName or else its Name: the directory is named on the bundle, not by renaming the layout after the walk. A node layout that renders a differently named bundle is not affected;
  • two bundles whose own directories are one, compared as the writers compare them (SameDirectory), so two DirNames that differ in case only are one: each would get a Kustomization or Application for that one directory. Both are named by their paths (the writers refuse the same tree in the same words, see checkLayoutTree);
  • a dependency cycle between reconciliation units (see Units).

func (*OriginIndex) BundleLayout

func (ix *OriginIndex) BundleLayout(b *stack.Bundle) *ManifestLayout

BundleLayout returns the layout whose directory holds b's resources, or nil.

func (*OriginIndex) Bundles

func (ix *OriginIndex) Bundles() []*stack.Bundle

Bundles returns every rendered bundle in layout pre-order (a layout's own bundles before its children's).

func (*OriginIndex) KustomizationPath

func (ix *OriginIndex) KustomizationPath(b *stack.Bundle) (string, error)

KustomizationPath returns the directory of the layout that renders b: the one path rule for a bundle's Flux Kustomization spec.path and ArgoCD Application source.path, relative to the writer's output root.

func (*OriginIndex) NodeLayout

func (ix *OriginIndex) NodeLayout(n *stack.Node) *ManifestLayout

NodeLayout returns the layout whose directory is n's, or nil.

func (*OriginIndex) Parent

func (ix *OriginIndex) Parent(ml *ManifestLayout) *ManifestLayout

Parent returns ml's parent layout in the indexed tree, or nil for the root.

func (*OriginIndex) UnitDependencies

func (ix *OriginIndex) UnitDependencies(l *ManifestLayout) []string

UnitDependencies returns the units the unit of layout l depends on through the DependsOn of the bundles it renders: each dependency mapped to the unit that applies it, in order and without repeats. A dependency applied by l's own unit is dropped: the bundles are applied together.

func (*OriginIndex) UnitName

func (ix *OriginIndex) UnitName(b *stack.Bundle) string

UnitName returns the name of the reconciliation unit that applies bundle b: the name in effect (Bundle.UnitName) of the first bundle the layout rendering b renders. b is resolved by its Name, which IndexOrigins proves unique, so a copy of a rendered bundle (the fluent builder copies bundles) resolves like the original, whatever KustomizationName the copy carries (IndexOrigins refuses a DependsOn copy that sets another one than the rendered bundle's name in effect). A bundle outside the index keeps its own name in effect.

func (*OriginIndex) UnitNamedDependencies

func (ix *OriginIndex) UnitNamedDependencies(l *ManifestLayout) []string

UnitNamedDependencies is UnitDependencies for the bundles' NamedDependsOn: a name that is a rendered bundle's Kustomization name is mapped to its unit (and dropped when that is l's own), any other name is kept as the external dependency it is.

func (*OriginIndex) UnitOfName

func (ix *OriginIndex) UnitOfName(name string) string

UnitOfName maps the name of a rendered bundle's Kustomization or Application (Bundle.UnitName) to the name of the unit that applies the bundle; a name no rendered bundle has in effect (an external Kustomization, say) is returned unchanged. A bundle's Name is not looked up: it resolves only where it is some bundle's name in effect. References to a bundle's Kustomization by name — health checks, dependencies — resolve through it.

func (*OriginIndex) Units

func (ix *OriginIndex) Units() []*ManifestLayout

Units returns the layouts that render bundles, in layout pre-order. Each is one reconciliation unit: the directory is what a Flux Kustomization or an ArgoCD Application applies, so the bundles a grouping axis merged into one directory share one, named after the first of them (UnitName).

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"
)

Jump to

Keyboard shortcuts

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