orchestrator

package
v0.7.3 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: AGPL-3.0 Imports: 41 Imported by: 0

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

func Select added in v0.7.3

func Select(
	runs []Rendered,
	runErr error,
	roots []manifest.NamedResource,
	labels map[string]string,
) ([]*selection.Result, selection.ProjectionErrors)

Select borrows completed results until their final consumer calls Close.

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

type Rendered struct {
	*Orchestrator

	ID     manifest.TreeID
	Absent bool
	Result *Result
	Err    error
}

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

func RenderTrees(
	ctx context.Context,
	trees []Tree,
	cfg Config,
) (results []Rendered, err error)

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.

func (*Result) Close added in v0.7.3

func (r *Result) Close()

Close MUST follow the final selection consumer of the completed result.

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.

Jump to

Keyboard shortcuts

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