Documentation
¶
Overview ¶
Package kustomize wraps sigs.k8s.io/kustomize/api so the rest of flate never invokes the `kustomize` CLI. It provides:
- Render: return unstamped output from disk inputs through Flux's secure FS, or immutable source artifacts through their authoritative fs.FS. Generated files use one private overlay; artifact labels need not exist on disk.
- Prepare: the standard pre-render dance (Clone + expand postBuild.substituteFrom + authored inline values) for embedders rendering a single Kustomization. Symmetric to helm.Prepare for HelmReleases, minus a values cache; the substituteFrom path has no YAML parse to memoize; see Prepare's docstring.
- Substitute: envsubst-style "${VAR}" / "${VAR:=default}" used for Flux post-build substitutions.
Concurrency. Each Render call builds against its own private overlay, so no two renders share mutable state and there is no per-tree build lock. krusty's package-global state (the openapi schema registry, builtin plugin/transformer factories) is still not goroutine-safe, so the process-wide internal/kustomize.BuildMutex serializes EVERY krusty invocation flate runs, including the helm post-renderer's krusty.Run in pkg/helm. fluxcd/pkg/kustomize guards its own Build for the same reason; every flate-owned krusty entrypoint MUST hold that same mutex.
Render persists unstamped output with its input read-set snapshot and validates that snapshot against the source view before reusing a frame.
Index ¶
- func AdaptSelector(selector *fluxapis.Selector) *kustypes.Selector
- func Prepare(ks *manifest.Kustomization, provider values.Provider) (*manifest.Kustomization, error)
- func Render(ctx context.Context, cache *TreeCache, req RenderRequest, ...) ([]manifest.DocOccurrence, *manifest.RenderReceipt, error)
- func RenderInputs(receipt *manifest.RenderReceipt) map[string]bool
- func SourceInput(reads sourceReader, ks *manifest.Kustomization) (*store.SourceArtifact, bool, error)
- func Substitute(data []byte, vars map[string]string, strict bool) ([]byte, error)
- type EntryEvidence
- type EntryInput
- type GitBaseFetcher
- type GitBaseRequest
- type Preparation
- type RenderAcceptance
- type RenderRequest
- type ShapeOptions
- type Shaping
- type TreeCache
- func (c *TreeCache) ApplicationReceipt(ctx context.Context, request RenderRequest, evidence EntryEvidence, ...) (EntryEvidence, error)
- func (c *TreeCache) Close()
- func (*TreeCache) EntryValid(ctx context.Context, evidence EntryEvidence, st *store.Store) bool
- func (c *TreeCache) PreviousEntry(ctx context.Context, req RenderRequest) EntryEvidence
- func (c *TreeCache) PreviousRender(ctx context.Context, req RenderRequest) ([]manifest.DocOccurrence, *manifest.RenderReceipt, bool)
- func (c *TreeCache) RecordEntry(ctx context.Context, receipt *manifest.RenderReceipt, reads *store.ReadSet) error
- func (c *TreeCache) RecordRender(ctx context.Context, acceptance RenderAcceptance) error
- func (*TreeCache) RenderHistory(owner manifest.NamedResource, receipt *manifest.RenderReceipt, content any) (iter.Seq2[manifest.NamedResource, manifest.DiscoveryRecord], bool)
- func (c *TreeCache) SetGitBaseFetcher(fn GitBaseFetcher)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AdaptSelector ¶ added in v0.7.3
AdaptSelector converts a Flux selector into a kustomize selector. Mirrors flux's generator adaptSelector (nil in, nil out).
func Prepare ¶
func Prepare(ks *manifest.Kustomization, provider values.Provider) (*manifest.Kustomization, error)
Prepare clones ks and resolves referenced and inline substitutions.
func Render ¶ added in v0.7.3
func Render( ctx context.Context, cache *TreeCache, req RenderRequest, retry sourcecache.RetryConfig, ) ([]manifest.DocOccurrence, *manifest.RenderReceipt, error)
Render returns unstamped renderer documents from an admitted source and a private overlay. Generated files never mutate the source. Cancellation is checked around the upstream build, which does not accept a context.
func RenderInputs ¶ added in v0.7.3
func RenderInputs(receipt *manifest.RenderReceipt) map[string]bool
RenderInputs returns source-relative observed paths and whether each read excludes descendants.
func SourceInput ¶ added in v0.7.3
func SourceInput(reads sourceReader, ks *manifest.Kustomization) (*store.SourceArtifact, bool, error)
SourceInput resolves the ordinary Kustomization source and local ignore policy.
Types ¶
type EntryEvidence ¶ added in v0.7.3
type EntryEvidence struct {
Producer manifest.NamedResource `json:"Producer"`
Application map[string]any `json:"Application"`
Root manifest.NamedResource `json:"Root"`
Owner manifest.NamedResource `json:"Owner"`
Records iter.Seq2[manifest.NamedResource, manifest.DiscoveryRecord] `json:"Records"`
Receipt *manifest.RenderReceipt `json:"Receipt"`
Inputs []EntryInput `json:"Inputs"`
Renders []*manifest.RenderReceipt `json:"Renders"`
}
EntryEvidence retains the accepted producer inventory that qualified an entry application.
type EntryInput ¶ added in v0.7.3
type EntryInput struct {
Resource manifest.NamedResource `json:"Resource"`
Content string `json:"Content"`
Binding store.ArtifactInput `json:"Binding"`
Artifact *store.SourceArtifact `json:"-"`
Data manifest.Data `json:"-"`
}
EntryInput binds one resolved qualification input to owner-derived content.
type GitBaseFetcher ¶ added in v0.3.4
type GitBaseFetcher func(context.Context, GitBaseRequest, cache.RetryConfig) (*store.SourceArtifact, error)
GitBaseFetcher acquires an immutable repository view for private render mounts.
type GitBaseRequest ¶ added in v0.7.3
type GitBaseRequest struct {
Work manifest.WorkScope `json:"-"`
URL string `json:"URL"`
Ref string `json:"Ref"`
MaxAge time.Duration `json:"MaxAge"`
Timeout time.Duration `json:"Timeout"`
Submodules bool `json:"Submodules"`
}
GitBaseRequest carries effective Git policy and the referencing Flux interval.
type Preparation ¶ added in v0.7.3
type Preparation struct {
// contains filtered or unexported fields
}
Preparation MUST remain owned by one logical render consumer until transfer or retirement.
func (*Preparation) Retire ¶ added in v0.7.3
func (p *Preparation) Retire()
Retire MUST follow the final consumer and clears retained input references.
func (*Preparation) Take ¶ added in v0.7.3
func (p *Preparation) Take(previous *Preparation, cache *TreeCache, request *RenderRequest) bool
Take MUST NOT move a live capture or grant publication authority.
type RenderAcceptance ¶ added in v0.7.3
type RenderAcceptance struct {
Work *manifest.RenderWork `json:"-"`
// Source identifies the admitted filesystem used by the receipt.
Source manifest.SourceIdentity `json:"Source"`
Sources []manifest.SourceEvidence `json:"Sources"`
Owner manifest.NamedResource `json:"Owner"`
Receipt *manifest.RenderReceipt `json:"Receipt"`
// Records MUST describe accepted output under Owner.
Records iter.Seq2[manifest.NamedResource, manifest.DiscoveryRecord] `json:"Records"`
DependencySubstitutions values.DependencySubstitutions `json:"DependencySubstitutions"`
Content any `json:"Content"`
Reads *store.ReadSet `json:"Reads"`
OutputReads *store.ReadSet `json:"OutputReads"`
}
RenderAcceptance MUST retain the inventory and reads from the accepted emission.
type RenderRequest ¶ added in v0.7.3
type RenderRequest struct {
Preparation *Preparation `json:"-"`
// Work borrows stage counters from this render execution.
Work *manifest.RenderWork `json:"-"`
// HeldSlot is TreeCache's borrowed service when this render holds its slot.
// Standalone callers leave it nil.
HeldSlot *task.Service `json:"HeldSlot"`
// Source.FS supplies content; nil Source or FS is unavailable.
// Empty Source.Content denotes mutable content validated on every cache hit.
Source *store.SourceArtifact `json:"Source"`
// ApplyIgnore selects source-controller exclusions for admitted local aliases.
ApplyIgnore bool `json:"ApplyIgnore"`
// Label mounts source content in kyaml; empty uses Source.LocalPath.
Label string `json:"Label"`
// SubPath selects the source directory to build.
SubPath string `json:"SubPath"`
// Spec is the prepared Flux Kustomization; nil builds without a Flux owner.
Spec *manifest.Kustomization `json:"Spec"`
// StrictSubstitutions binds undefined-variable handling to accepted history.
StrictSubstitutions bool `json:"StrictSubstitutions"`
// SkipKinds binds the effective emitted-kind policy to accepted history.
SkipKinds []string `json:"SkipKinds"`
// DependencySubstitutions binds emitted dependency projection to accepted history.
DependencySubstitutions values.DependencySubstitutions `json:"DependencySubstitutions"`
}
RenderRequest carries the authoritative source and its mount label. Label is metadata and need not name an existing host path.
type ShapeOptions ¶ added in v0.7.3
type ShapeOptions struct {
Strict bool
Work *manifest.WorkRecord
}
ShapeOptions supplies substitution policy and its physical work counter.
type Shaping ¶ added in v0.7.3
type Shaping struct {
// contains filtered or unexported fields
}
Shaping owns private documents and temporary YAML for one render attempt.
func PrepareShape ¶ added in v0.7.3
func PrepareShape(request *RenderRequest, docs []manifest.DocOccurrence) *Shaping
PrepareShape MUST retain raw identity separately from sanitized application content.
func (*Shaping) Apply ¶ added in v0.7.3
func (p *Shaping) Apply(_ context.Context, options ShapeOptions) error
Apply consumes the attempt's prepared YAML and releases it on every return.
type TreeCache ¶ added in v0.3.4
type TreeCache struct {
// contains filtered or unexported fields
}
TreeCache borrows backing storage and HTTP inputs for one run's render state. Callers MUST join renders and Close before releasing borrowed dependencies.
func NewTreeCache ¶ added in v0.3.4
func NewTreeCache(owner *cache.Cache, remoteInputs *source.HTTPInputs, tasks *task.Service) *TreeCache
NewTreeCache borrows the nonnil storage owner, HTTP inputs and task service.
func (*TreeCache) ApplicationReceipt ¶ added in v0.7.3
func (c *TreeCache) ApplicationReceipt( ctx context.Context, request RenderRequest, evidence EntryEvidence, files []string, ) (EntryEvidence, error)
ApplicationReceipt captures complete local and resolved entry qualification inputs.
func (*TreeCache) Close ¶ added in v0.7.3
func (c *TreeCache) Close()
Close clears render state after callers join renders; borrowed inputs stay open.
func (*TreeCache) EntryValid ¶ added in v0.7.3
EntryValid qualifies provisional evidence against current resolved input content.
func (*TreeCache) PreviousEntry ¶ added in v0.7.3
func (c *TreeCache) PreviousEntry(ctx context.Context, req RenderRequest) EntryEvidence
PreviousEntry MUST treat persisted evidence as provisional until current inputs qualify it.
func (*TreeCache) PreviousRender ¶ added in v0.7.3
func (c *TreeCache) PreviousRender( ctx context.Context, req RenderRequest, ) ([]manifest.DocOccurrence, *manifest.RenderReceipt, bool)
PreviousRender returns validated raw output without rendering or acquiring remote inputs.
func (*TreeCache) RecordEntry ¶ added in v0.7.3
func (c *TreeCache) RecordEntry(ctx context.Context, receipt *manifest.RenderReceipt, reads *store.ReadSet) error
RecordEntry MUST publish only complete evidence with current captured inputs.
func (*TreeCache) RecordRender ¶ added in v0.7.3
func (c *TreeCache) RecordRender(ctx context.Context, acceptance RenderAcceptance) error
RecordRender MUST publish history only after the emission accepts its captured inputs.
func (*TreeCache) RenderHistory ¶ added in v0.7.3
func (*TreeCache) RenderHistory( owner manifest.NamedResource, receipt *manifest.RenderReceipt, content any, ) (iter.Seq2[manifest.NamedResource, manifest.DiscoveryRecord], bool)
RenderHistory returns complete accepted inventory matching the current final inputs.
func (*TreeCache) SetGitBaseFetcher ¶ added in v0.3.4
func (c *TreeCache) SetGitBaseFetcher(fn GitBaseFetcher)
SetGitBaseFetcher wires the git-clone capability used to resolve remote git bases referenced from a kustomization's resources:. The orchestrator calls this once at construction; library/test embedders may leave it unset.