Documentation
¶
Overview ¶
Package orchestrator plans repository entries and renders isolated cluster trees. RenderTrees is the SDK lifecycle boundary:
runs, err := orchestrator.RenderTrees(ctx, []orchestrator.Tree{{
ID: manifest.TreeID{Cluster: ".", Side: manifest.TreeHead},
Path: "/path/to/repository",
}}, orchestrator.Config{Concurrency: 4})
defer func() {
for _, run := range runs {
run.Result.Close()
}
}()
Call Result.Close after the final selection consumer. Result.Close releases reporting references and preserves returned output.
Results are sorted by cluster and side. Each completed tree has an independent Store, controller state and result; all trees share the invocation's task budget, cache, network and Helm client. Cancellation joins every launched tree before releasing owned resources. Failed trees retain diagnostics and successful trees retain readable stores and materialized output.
Caller-supplied Cache, Network and HelmClient remain caller-owned. Keep the supplied cache alive through any later lazy source reads, and join those reads before closing it. Internally created resources close before RenderTrees returns.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
RecordWork bool
// Selection narrows declarations before rendering; zero selection is universal.
Selection selection.Request
// HelmOptions tunes templating and kind filtering through SkipKinds.
HelmOptions helm.Options
// AllowMissingKinds tolerates missing source Secret material, Helm valuesFrom kinds, and CRDs.
// Required postBuild references and malformed data remain errors.
AllowMissingKinds []string
// Supply contains authoritative reference-only documents, snapshotted before tree preparation.
// Identity and payload come from Doc; later duplicates replace whole declarations.
Supply []store.Declaration
// StrictSubstitutions fails undefined postBuild variables without defaults.
StrictSubstitutions bool
// RestrictEgress is the untrusted-render switch. It (1) enables the SSRF
// egress guard for ALL source fetches (kustomize remote resources/bases +
// Git/OCI/Helm/Bucket sources) — outbound dials to loopback/RFC1918/link-
// local/cloud-metadata addresses are refused — and (2) rejects GitRepository
// URLs whose transport is not https/ssh (file://, git://, http://, bare
// paths), so a fork-PR file:// source can't disclose an arbitrary in-pod
// repo (#743). Off by default — flate normally renders TRUSTED repos that
// legitimately reach private/LAN hosts and use local file:// self-sources;
// a consumer rendering UNTRUSTED input (e.g. konflate fork mode) sets this.
// The egress half is process-level (see pkg/source/ssrfguard): go-git
// installs its HTTPS transport process-wide, so a per-render git egress
// policy is impossible.
RestrictEgress bool
// RegistryConfig is the docker config.json used for OCI auth.
RegistryConfig string
// CacheDir selects the source and render cache root. Empty selects memory
// backing.
CacheDir string
// Cache, when injected, remains caller-owned and can be shared across runs.
Cache *sourcecache.Cache
// Network shares compatible HTTP transports and connection-timeout facts for this invocation.
Network *source.Network
// HelmClient must borrow Cache; both remain caller-owned when supplied.
HelmClient *helm.Client
// StatusListener receives concurrent tree-qualified store events and must not block.
StatusListener func(manifest.TreeID, manifest.DiagnosticIdentity, store.StatusInfo)
// Concurrency caps the number of active reconcile bodies running
// in parallel. <= 0 means unbounded (every Kustomization / HR
// reconciles on its own goroutine). Background watch loops are
// unaffected. Sensible default for I/O-bound work is
// runtime.NumCPU() * 4.
Concurrency int
// HeadOnly prepares both sides and reconciles only the head.
HeadOnly bool
// SourceRetry tunes the bounded, classified retry applied to every
// source fetch (Git/OCI/Bucket) on transient network failures —
// connection resets, refused connections, dial/IO timeouts. Permanent
// errors (bad path, missing secret, not-found) fail fast. Attempts
// <= 1 disables retry; the CLI defaults it to 3. See
// cache.RetryConfig.
SourceRetry sourcecache.RetryConfig
// GitDepth caps the shallow-clone history depth for GitRepository
// sources. 0 clones full
// history; the CLI defaults it to 1 (opt-out via --git-depth=0).
// Commit-pinned refs always full-clone regardless. See
// git.Fetcher.Depth.
GitDepth int
// contains filtered or unexported fields
}
Config contains invocation policy and shared rendering resources.
type Orchestrator ¶
type Orchestrator struct {
// contains filtered or unexported fields
}
Orchestrator exposes a completed execution tree's store.
func (*Orchestrator) Store ¶
func (o *Orchestrator) Store() *store.Store
Store returns the underlying object store.
type Rendered ¶ added in v0.3.2
Rendered retains one tree's completed output, warnings and attributed error. Absent denotes a missing comparison side and never exposes an orchestrator.
func RenderTrees ¶ added in v0.3.2
RenderTrees plans and renders isolated cluster trees using one invocation budget. Borrowed Cache, Network and HelmClient remain caller-owned. Returned documents and completed stores remain readable; later lazy source reads require a borrowed cache.
type Result ¶
type Result struct {
Work manifest.WorkSummary
Manifests []manifest.DocumentBatch
Failed map[manifest.NamedResource]store.StatusInfo
Orphans map[manifest.NamedResource]string
// Blocked maps a failed resource to the immediate dependencies that blocked
// it — present only for failures that are purely derived (the resource's own
// reconcile never ran because a dependency failed or was missing), absent for
// primary failures (a real render/template/build error). A consumer groups
// derived failures under their root cause by walking these edges to a primary
// failure or a missing id, instead of surfacing every cascaded failure.
Blocked map[manifest.NamedResource][]manifest.NamedResource
// Warnings contains ordinary side-specific diagnostics in deterministic order.
Warnings []manifest.Warning
// ClusterWarnings contains finalized cluster advisories on one RenderTrees result:
// the non-absent head, otherwise the non-absent base, without snapshot attribution.
ClusterWarnings []manifest.Warning
// contains filtered or unexported fields
}
Result contains rendered document batches, failures and discovery diagnostics. All borrowed payloads MUST remain immutable.
type Tree ¶ added in v0.3.3
type Tree struct {
ID manifest.TreeID
RepoRoot string
Path string
SelfURLs []string
Input *store.SourceArtifact
BaseInput *store.SourceArtifact
ExternalChanges *change.Set
// contains filtered or unexported fields
}
Tree identifies an admitted repository side and its requested scan boundary.