orchestrator

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package orchestrator provides a declarative DSL for OSAPI infrastructure operations. Users declare what operations to run, where, in what order, and under what conditions. The orchestrator handles DAG execution, parallelism, retries, and reporting.

Index

Constants

View Source 
const (
	// HostStatusOk indicates the operation completed successfully on the host.
	HostStatusOk = "ok"
	// HostStatusSkipped indicates the operation is not supported on the host
	// (e.g., a Darwin host in a Linux fleet). This is NOT an error.
	HostStatusSkipped = "skipped"
	// HostStatusFailed indicates the operation failed on the host.
	HostStatusFailed = "failed"
)

Host-level status constants returned by the API for per-host results. These represent agent-side outcomes, distinct from task-level statuses (TaskStatusChanged, TaskStatusSkipped, etc.) which are DAG-level.

Variables

View Source 
var StructToMap = engine.StructToMap

StructToMap converts a struct to map[string]any using its JSON tags. Useful in TaskFunc callbacks to populate Result.Data from SDK types.

Functions

func MatchAll 

func MatchAll(
	agent osapi.Agent,
	predicates ...Predicate,
) bool

MatchAll returns true if the agent matches all given predicates. Returns true if no predicates are provided.

Types

type ErrorStrategy 

type ErrorStrategy int

ErrorStrategy controls what happens when a step fails. 

const (
	// StopAll halts the entire plan on failure.
	StopAll ErrorStrategy = iota
	// Continue skips dependent steps and continues with the rest.
	Continue
)

type HostResult 

type HostResult struct {
	Hostname string
	Status   string
	Changed  bool
	Error    string
	Data     map[string]any
}

HostResult represents a single host's response within a broadcast operation.

func (HostResult) Decode 

func (h HostResult) Decode(
	v any,
) error

Decode unmarshals host-specific data into a typed result struct.

type Option 

type Option func(*config)

Option configures the Orchestrator.

func WithVerbose 

func WithVerbose() Option

WithVerbose enables verbose output showing stdout, stderr, and full response data for all tasks.

type Orchestrator 

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

Orchestrator is the top-level entry point for building and running infrastructure plans.

func New 

func New(
	url string,
	token string,
	opts ...Option,
) *Orchestrator

New creates an Orchestrator connected to the given OSAPI server.

func (*Orchestrator) AgentDrain 

func (o *Orchestrator) AgentDrain(
	hostname string,
) *Step

AgentDrain creates a step that drains an agent, preventing it from accepting new jobs.

func (*Orchestrator) AgentGet 

func (o *Orchestrator) AgentGet(
	hostname string,
) *Step

AgentGet creates a step that retrieves detailed info about a specific agent.

func (*Orchestrator) AgentList 

func (o *Orchestrator) AgentList() *Step

AgentList creates a step that lists all active agents with their facts.

func (*Orchestrator) AgentUndrain 

func (o *Orchestrator) AgentUndrain(
	hostname string,
) *Step

AgentUndrain creates a step that undrains an agent, allowing it to accept new jobs again.

func (*Orchestrator) CertificateCreate 

func (o *Orchestrator) CertificateCreate(
	target string,
	opts osapi.CertificateCreateOpts,
) *Step

CertificateCreate creates a step that creates a CA certificate.

func (*Orchestrator) CertificateDelete 

func (o *Orchestrator) CertificateDelete(
	target string,
	certName string,
) *Step

CertificateDelete creates a step that deletes a CA certificate.

func (*Orchestrator) CertificateList 

func (o *Orchestrator) CertificateList(
	target string,
) *Step

CertificateList creates a step that lists CA certificates.

func (*Orchestrator) CertificateUpdate 

func (o *Orchestrator) CertificateUpdate(
	target string,
	certName string,
	opts osapi.CertificateUpdateOpts,
) *Step

CertificateUpdate creates a step that updates a CA certificate.

func (*Orchestrator) CommandExec 

func (o *Orchestrator) CommandExec(
	target string,
	command string,
	args ...string,
) *Step

CommandExec creates a step that executes a command.

func (*Orchestrator) CommandShell 

func (o *Orchestrator) CommandShell(
	target string,
	command string,
) *Step

CommandShell creates a step that executes a shell command string.

func (*Orchestrator) CronCreate 

func (o *Orchestrator) CronCreate(
	target string,
	opts osapi.CronCreateOpts,
) *Step

CronCreate creates a step that creates a new cron entry on the target host.

func (*Orchestrator) CronDelete 

func (o *Orchestrator) CronDelete(
	target string,
	entryName string,
) *Step

CronDelete creates a step that deletes a cron entry on the target host.

func (*Orchestrator) CronGet 

func (o *Orchestrator) CronGet(
	target string,
	entryName string,
) *Step

CronGet creates a step that retrieves a specific cron entry on the target host.

func (*Orchestrator) CronList 

func (o *Orchestrator) CronList(
	target string,
) *Step

CronList creates a step that lists cron entries on the target host.

func (*Orchestrator) CronUpdate 

func (o *Orchestrator) CronUpdate(
	target string,
	entryName string,
	opts osapi.CronUpdateOpts,
) *Step

CronUpdate creates a step that updates an existing cron entry on the target host.

func (*Orchestrator) Discover 

func (o *Orchestrator) Discover(
	ctx context.Context,
	predicates ...Predicate,
) ([]osapi.Agent, error)

Discover queries active agents and returns those matching all predicates. Runs synchronously at plan-build time. With no predicates, returns all agents.

func (*Orchestrator) DockerCreate 

func (o *Orchestrator) DockerCreate(
	target string,
	opts osapi.DockerCreateOpts,
) *Step

DockerCreate creates a step that creates a new container on the target host.

func (*Orchestrator) DockerExec 

func (o *Orchestrator) DockerExec(
	target string,
	id string,
	opts osapi.DockerExecOpts,
) *Step

DockerExec creates a step that executes a command inside a running container.

func (*Orchestrator) DockerImageRemove 

func (o *Orchestrator) DockerImageRemove(
	target string,
	imageName string,
	params *osapi.DockerRemoveImageParams,
) *Step

DockerImageRemove creates a step that removes a container image from the target host.

func (*Orchestrator) DockerInspect 

func (o *Orchestrator) DockerInspect(
	target string,
	id string,
) *Step

DockerInspect creates a step that retrieves detailed info about a container.

func (*Orchestrator) DockerList 

func (o *Orchestrator) DockerList(
	target string,
	params *osapi.DockerListParams,
) *Step

DockerList creates a step that lists containers on the target host.

func (*Orchestrator) DockerPull 

func (o *Orchestrator) DockerPull(
	target string,
	opts osapi.DockerPullOpts,
) *Step

DockerPull creates a step that pulls a Docker image on the target host.

func (*Orchestrator) DockerRemove 

func (o *Orchestrator) DockerRemove(
	target string,
	id string,
	params *osapi.DockerRemoveParams,
) *Step

DockerRemove creates a step that removes a container from the target host.

func (*Orchestrator) DockerStart 

func (o *Orchestrator) DockerStart(
	target string,
	id string,
) *Step

DockerStart creates a step that starts a stopped container on the target host.

func (*Orchestrator) DockerStop 

func (o *Orchestrator) DockerStop(
	target string,
	id string,
	opts osapi.DockerStopOpts,
) *Step

DockerStop creates a step that stops a running container on the target host.

func (*Orchestrator) FileChanged 

func (o *Orchestrator) FileChanged(
	name string,
	data []byte,
) *Step

FileChanged creates a step that checks whether local content differs from the version stored in the Object Store. Computes SHA-256 locally and compares against the stored hash. Pairs with OnlyIfChanged to skip uploads when content is unchanged.

func (*Orchestrator) FileDeploy 

func (o *Orchestrator) FileDeploy(
	target string,
	opts osapi.FileDeployOpts,
) *Step

FileDeploy creates a step that deploys a file from the Object Store to the target agent's filesystem. The objectName must reference a file previously uploaded to the Object Store. ContentType should be "raw" for literal content or "template" for Go-template rendering with vars and agent facts.

func (*Orchestrator) FileStatusGet 

func (o *Orchestrator) FileStatusGet(
	target string,
	path string,
) *Step

FileStatusGet creates a step that checks the status of a deployed file on the target agent. Returns whether the file is in-sync, drifted, or missing compared to the expected state.

func (*Orchestrator) FileUndeploy 

func (o *Orchestrator) FileUndeploy(
	target string,
	path string,
) *Step

FileUndeploy creates a step that removes a previously deployed file from the target agent's filesystem.

func (*Orchestrator) FileUpload 

func (o *Orchestrator) FileUpload(
	name string,
	contentType string,
	data []byte,
	opts ...UploadOption,
) *Step

FileUpload creates a step that uploads file content to the Object Store via the OSAPI REST API. Returns the object name that can be used in subsequent FileDeploy steps. This is a convenience wrapper that uses TaskFunc to call the file upload API directly. By default the upload is idempotent — the SDK compares SHA-256 digests and skips the upload when content is unchanged. Pass WithForce to always upload regardless of content changes.

func (*Orchestrator) GroupByFact 

func (o *Orchestrator) GroupByFact(
	ctx context.Context,
	key string,
	predicates ...Predicate,
) (map[string][]osapi.Agent, error)

GroupByFact queries agents, optionally filters by predicates, and groups results by the string value at the given key.

func (*Orchestrator) GroupCreate 

func (o *Orchestrator) GroupCreate(
	target string,
	opts osapi.GroupCreateOpts,
) *Step

GroupCreate creates a step that creates a group.

func (*Orchestrator) GroupDelete 

func (o *Orchestrator) GroupDelete(
	target string,
	groupName string,
) *Step

GroupDelete creates a step that deletes a group.

func (*Orchestrator) GroupGet 

func (o *Orchestrator) GroupGet(
	target string,
	groupName string,
) *Step

GroupGet creates a step that retrieves a specific group.

func (*Orchestrator) GroupList 

func (o *Orchestrator) GroupList(
	target string,
) *Step

GroupList creates a step that lists groups.

func (*Orchestrator) GroupUpdate 

func (o *Orchestrator) GroupUpdate(
	target string,
	groupName string,
	opts osapi.GroupUpdateOpts,
) *Step

GroupUpdate creates a step that updates a group.

func (*Orchestrator) HealthCheck 

func (o *Orchestrator) HealthCheck() *Step

HealthCheck creates a health check step.

func (*Orchestrator) InterfaceCreate 

func (o *Orchestrator) InterfaceCreate(
	target string,
	ifaceName string,
	opts osapi.InterfaceConfigOpts,
) *Step

InterfaceCreate creates a step that creates a network interface configuration.

func (*Orchestrator) InterfaceDelete 

func (o *Orchestrator) InterfaceDelete(
	target string,
	ifaceName string,
) *Step

InterfaceDelete creates a step that deletes a network interface configuration.

func (*Orchestrator) InterfaceGet 

func (o *Orchestrator) InterfaceGet(
	target string,
	ifaceName string,
) *Step

InterfaceGet creates a step that retrieves a specific network interface.

func (*Orchestrator) InterfaceList 

func (o *Orchestrator) InterfaceList(
	target string,
) *Step

InterfaceList creates a step that lists network interfaces.

func (*Orchestrator) InterfaceUpdate 

func (o *Orchestrator) InterfaceUpdate(
	target string,
	ifaceName string,
	opts osapi.InterfaceConfigOpts,
) *Step

InterfaceUpdate creates a step that updates a network interface configuration.

func (*Orchestrator) LogQuery 

func (o *Orchestrator) LogQuery(
	target string,
	opts osapi.LogQueryOpts,
) *Step

LogQuery creates a step that queries journal log entries.

func (*Orchestrator) LogQueryUnit 

func (o *Orchestrator) LogQueryUnit(
	target string,
	unit string,
	opts osapi.LogQueryOpts,
) *Step

LogQueryUnit creates a step that queries log entries for a systemd unit.

func (*Orchestrator) LogSources 

func (o *Orchestrator) LogSources(
	target string,
) *Step

LogSources creates a step that lists available log sources.

func (*Orchestrator) NTPCreate 

func (o *Orchestrator) NTPCreate(
	target string,
	opts osapi.NtpCreateOpts,
) *Step

NTPCreate creates a step that creates NTP configuration.

func (*Orchestrator) NTPDelete 

func (o *Orchestrator) NTPDelete(
	target string,
) *Step

NTPDelete creates a step that deletes NTP configuration.

func (*Orchestrator) NTPGet 

func (o *Orchestrator) NTPGet(
	target string,
) *Step

NTPGet creates a step that retrieves NTP status.

func (*Orchestrator) NTPUpdate 

func (o *Orchestrator) NTPUpdate(
	target string,
	opts osapi.NtpUpdateOpts,
) *Step

NTPUpdate creates a step that updates NTP configuration.

func (*Orchestrator) NetworkDNSDelete 

func (o *Orchestrator) NetworkDNSDelete(
	target string,
	interfaceName string,
) *Step

NetworkDNSDelete creates a step that deletes DNS configuration.

func (*Orchestrator) NetworkDNSGet 

func (o *Orchestrator) NetworkDNSGet(
	target string,
	interfaceName string,
) *Step

NetworkDNSGet creates a step that retrieves DNS configuration.

func (*Orchestrator) NetworkDNSUpdate 

func (o *Orchestrator) NetworkDNSUpdate(
	target string,
	interfaceName string,
	servers []string,
	searchDomains []string,
) *Step

NetworkDNSUpdate creates a step that updates DNS configuration.

func (*Orchestrator) NetworkPingDo 

func (o *Orchestrator) NetworkPingDo(
	target string,
	address string,
) *Step

NetworkPingDo creates a step that pings an address.

func (*Orchestrator) NodeDiskGet 

func (o *Orchestrator) NodeDiskGet(
	target string,
) *Step

NodeDiskGet creates a step that retrieves disk usage.

func (*Orchestrator) NodeHostnameGet 

func (o *Orchestrator) NodeHostnameGet(
	target string,
) *Step

NodeHostnameGet creates a step that retrieves the hostname.

func (*Orchestrator) NodeHostnameUpdate 

func (o *Orchestrator) NodeHostnameUpdate(
	target string,
	hostname string,
) *Step

NodeHostnameUpdate creates a step that sets the system hostname.

func (*Orchestrator) NodeLoadGet 

func (o *Orchestrator) NodeLoadGet(
	target string,
) *Step

NodeLoadGet creates a step that retrieves load averages.

func (*Orchestrator) NodeMemoryGet 

func (o *Orchestrator) NodeMemoryGet(
	target string,
) *Step

NodeMemoryGet creates a step that retrieves memory stats.

func (*Orchestrator) NodeOSGet 

func (o *Orchestrator) NodeOSGet(
	target string,
) *Step

NodeOSGet creates a step that retrieves OS information.

func (*Orchestrator) NodeStatusGet 

func (o *Orchestrator) NodeStatusGet(
	target string,
) *Step

NodeStatusGet creates a step that retrieves node status.

func (*Orchestrator) NodeUptimeGet 

func (o *Orchestrator) NodeUptimeGet(
	target string,
) *Step

NodeUptimeGet creates a step that retrieves system uptime.

func (*Orchestrator) PackageGet 

func (o *Orchestrator) PackageGet(
	target string,
	pkgName string,
) *Step

PackageGet creates a step that retrieves a specific package.

func (*Orchestrator) PackageInstall 

func (o *Orchestrator) PackageInstall(
	target string,
	pkgName string,
) *Step

PackageInstall creates a step that installs a package.

func (*Orchestrator) PackageList 

func (o *Orchestrator) PackageList(
	target string,
) *Step

PackageList creates a step that lists installed packages.

func (*Orchestrator) PackageListUpdates 

func (o *Orchestrator) PackageListUpdates(
	target string,
) *Step

PackageListUpdates creates a step that lists available package updates.

func (*Orchestrator) PackageRemove 

func (o *Orchestrator) PackageRemove(
	target string,
	pkgName string,
) *Step

PackageRemove creates a step that removes a package.

func (*Orchestrator) PackageUpdate 

func (o *Orchestrator) PackageUpdate(
	target string,
) *Step

PackageUpdate creates a step that updates all packages.

func (*Orchestrator) PowerReboot 

func (o *Orchestrator) PowerReboot(
	target string,
	opts osapi.PowerOpts,
) *Step

PowerReboot creates a step that initiates a reboot.

func (*Orchestrator) PowerShutdown 

func (o *Orchestrator) PowerShutdown(
	target string,
	opts osapi.PowerOpts,
) *Step

PowerShutdown creates a step that initiates a shutdown.

func (*Orchestrator) ProcessGet 

func (o *Orchestrator) ProcessGet(
	target string,
	pid int,
) *Step

ProcessGet creates a step that retrieves a specific process by PID.

func (*Orchestrator) ProcessList 

func (o *Orchestrator) ProcessList(
	target string,
) *Step

ProcessList creates a step that lists running processes.

func (*Orchestrator) ProcessSignal 

func (o *Orchestrator) ProcessSignal(
	target string,
	pid int,
	opts osapi.ProcessSignalOpts,
) *Step

ProcessSignal creates a step that sends a signal to a process.

func (*Orchestrator) RouteCreate 

func (o *Orchestrator) RouteCreate(
	target string,
	interfaceName string,
	opts osapi.RouteConfigOpts,
) *Step

RouteCreate creates a step that creates route configuration.

func (*Orchestrator) RouteDelete 

func (o *Orchestrator) RouteDelete(
	target string,
	interfaceName string,
) *Step

RouteDelete creates a step that deletes route configuration.

func (*Orchestrator) RouteGet 

func (o *Orchestrator) RouteGet(
	target string,
	interfaceName string,
) *Step

RouteGet creates a step that retrieves routes for a specific interface.

func (*Orchestrator) RouteList 

func (o *Orchestrator) RouteList(
	target string,
) *Step

RouteList creates a step that lists network routes.

func (*Orchestrator) RouteUpdate 

func (o *Orchestrator) RouteUpdate(
	target string,
	interfaceName string,
	opts osapi.RouteConfigOpts,
) *Step

RouteUpdate creates a step that updates route configuration.

func (*Orchestrator) Run 

func (o *Orchestrator) Run(
	ctx context.Context,
) (*Report, error)

Run executes the plan and returns a report.

func (*Orchestrator) ServiceCreate 

func (o *Orchestrator) ServiceCreate(
	target string,
	opts osapi.ServiceCreateOpts,
) *Step

ServiceCreate creates a step that creates a service unit file.

func (*Orchestrator) ServiceDelete 

func (o *Orchestrator) ServiceDelete(
	target string,
	serviceName string,
) *Step

ServiceDelete creates a step that deletes a service unit file.

func (*Orchestrator) ServiceDisable 

func (o *Orchestrator) ServiceDisable(
	target string,
	serviceName string,
) *Step

ServiceDisable creates a step that disables a service from starting on boot.

func (*Orchestrator) ServiceEnable 

func (o *Orchestrator) ServiceEnable(
	target string,
	serviceName string,
) *Step

ServiceEnable creates a step that enables a service to start on boot.

func (*Orchestrator) ServiceGet 

func (o *Orchestrator) ServiceGet(
	target string,
	serviceName string,
) *Step

ServiceGet creates a step that retrieves a specific service.

func (*Orchestrator) ServiceList 

func (o *Orchestrator) ServiceList(
	target string,
) *Step

ServiceList creates a step that lists services on the target host.

func (*Orchestrator) ServiceRestart 

func (o *Orchestrator) ServiceRestart(
	target string,
	serviceName string,
) *Step

ServiceRestart creates a step that restarts a service.

func (*Orchestrator) ServiceStart 

func (o *Orchestrator) ServiceStart(
	target string,
	serviceName string,
) *Step

ServiceStart creates a step that starts a service.

func (*Orchestrator) ServiceStop 

func (o *Orchestrator) ServiceStop(
	target string,
	serviceName string,
) *Step

ServiceStop creates a step that stops a service.

func (*Orchestrator) ServiceUpdate 

func (o *Orchestrator) ServiceUpdate(
	target string,
	serviceName string,
	opts osapi.ServiceUpdateOpts,
) *Step

ServiceUpdate creates a step that updates a service unit file.

func (*Orchestrator) SysctlCreate 

func (o *Orchestrator) SysctlCreate(
	target string,
	opts osapi.SysctlCreateOpts,
) *Step

SysctlCreate creates a step that creates a sysctl parameter.

func (*Orchestrator) SysctlDelete 

func (o *Orchestrator) SysctlDelete(
	target string,
	key string,
) *Step

SysctlDelete creates a step that deletes a sysctl parameter.

func (*Orchestrator) SysctlGet 

func (o *Orchestrator) SysctlGet(
	target string,
	key string,
) *Step

SysctlGet creates a step that retrieves a sysctl parameter by key.

func (*Orchestrator) SysctlList 

func (o *Orchestrator) SysctlList(
	target string,
) *Step

SysctlList creates a step that lists managed sysctl parameters.

func (*Orchestrator) SysctlUpdate 

func (o *Orchestrator) SysctlUpdate(
	target string,
	key string,
	opts osapi.SysctlUpdateOpts,
) *Step

SysctlUpdate creates a step that updates a sysctl parameter.

func (*Orchestrator) TaskFunc 

func (o *Orchestrator) TaskFunc(
	name string,
	fn func(ctx context.Context, c *osapi.Client, r Results) (*engine.Result, error),
) *Step

TaskFunc creates a custom step that receives the OSAPI client and completed results from prior steps. Use this for operations not covered by the typed constructors — the client provides full access to the SDK for calling any API endpoint.

func (*Orchestrator) TimezoneGet 

func (o *Orchestrator) TimezoneGet(
	target string,
) *Step

TimezoneGet creates a step that retrieves the system timezone.

func (*Orchestrator) TimezoneUpdate 

func (o *Orchestrator) TimezoneUpdate(
	target string,
	opts osapi.TimezoneUpdateOpts,
) *Step

TimezoneUpdate creates a step that sets the system timezone.

func (*Orchestrator) UserAddKey 

func (o *Orchestrator) UserAddKey(
	target string,
	username string,
	opts osapi.SSHKeyAddOpts,
) *Step

UserAddKey creates a step that adds an SSH authorized key for a user.

func (*Orchestrator) UserChangePassword 

func (o *Orchestrator) UserChangePassword(
	target string,
	username string,
	password string,
) *Step

UserChangePassword creates a step that changes a user's password.

func (*Orchestrator) UserCreate 

func (o *Orchestrator) UserCreate(
	target string,
	opts osapi.UserCreateOpts,
) *Step

UserCreate creates a step that creates a user account.

func (*Orchestrator) UserDelete 

func (o *Orchestrator) UserDelete(
	target string,
	username string,
) *Step

UserDelete creates a step that deletes a user account.

func (*Orchestrator) UserGet 

func (o *Orchestrator) UserGet(
	target string,
	username string,
) *Step

UserGet creates a step that retrieves a specific user account.

func (*Orchestrator) UserList 

func (o *Orchestrator) UserList(
	target string,
) *Step

UserList creates a step that lists user accounts.

func (*Orchestrator) UserListKeys 

func (o *Orchestrator) UserListKeys(
	target string,
	username string,
) *Step

UserListKeys creates a step that lists SSH authorized keys for a user.

func (*Orchestrator) UserRemoveKey 

func (o *Orchestrator) UserRemoveKey(
	target string,
	username string,
	fingerprint string,
) *Step

UserRemoveKey creates a step that removes an SSH authorized key for a user.

func (*Orchestrator) UserUpdate 

func (o *Orchestrator) UserUpdate(
	target string,
	username string,
	opts osapi.UserUpdateOpts,
) *Step

UserUpdate creates a step that updates a user account.

type Predicate 

type Predicate func(osapi.Agent) bool

Predicate filters agents by their facts and properties.

func Arch 

func Arch(
	architecture string,
) Predicate

Arch returns a predicate that matches agents with the given architecture (case-insensitive).

func FactEquals 

func FactEquals(
	key string,
	value any,
) Predicate

FactEquals returns a predicate that matches agents where the given fact key equals the expected value.

func HasCondition 

func HasCondition(
	conditionType string,
) Predicate

HasCondition returns a predicate that matches agents with an active condition (Status=true) of the given type.

func HasLabel 

func HasLabel(
	key string,
	value string,
) Predicate

HasLabel returns a predicate that matches agents with the given label key-value pair.

func Healthy 

func Healthy() Predicate

Healthy returns a predicate that matches agents with no active conditions (all conditions are false or the list is empty).

func MinCPU 

func MinCPU(
	count int,
) Predicate

MinCPU returns a predicate that matches agents with at least the given number of CPUs.

func MinMemory 

func MinMemory(
	total int,
) Predicate

MinMemory returns a predicate that matches agents with at least the given total memory (in the same unit as Memory.Total).

func NoCondition 

func NoCondition(
	conditionType string,
) Predicate

NoCondition returns a predicate that matches agents that do NOT have an active condition of the given type.

func OS 

func OS(
	distribution string,
) Predicate

OS returns a predicate that matches agents running the given distribution (case-insensitive).

type Report 

type Report struct {
	Tasks    []engine.TaskResult
	Duration time.Duration
}

Report summarizes plan execution.

func (*Report) Decode 

func (r *Report) Decode(
	name string,
	v any,
) error

Decode retrieves the result of a named task from the report and decodes it into the given typed struct.

For collection-based operations that have host results, Decode unwraps the first host's data automatically. For non-collection operations, it decodes from the task's top-level data.

func (*Report) Summary 

func (r *Report) Summary() string

Summary returns a human-readable summary of the plan execution.

type Result 

type Result = engine.Result

Result is the outcome of a single task execution. Users return this from TaskFunc callbacks.

type Results 

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

Results provides access to completed step results inside When guards.

func NewResults 

func NewResults(
	sdkResults engine.Results,
) Results

NewResults creates a Results from SDK results. Intended for testing.

func (Results) Changed 

func (r Results) Changed(
	name string,
) bool

Changed returns whether the named step reported changes. Returns false if the step is not found or did not report changes.

func (Results) Decode 

func (r Results) Decode(
	name string,
	v any,
) error

Decode retrieves the result of a named step and decodes it into the given typed struct.

For collection-based operations (CommandExec, NodeHostnameGet, etc.) that have host results, Decode unwraps the first host's data automatically. For non-collection operations (TaskFunc, FileChanged, etc.), it decodes from the step's top-level data.

func (Results) HostResults 

func (r Results) HostResults(
	name string,
) []HostResult

HostResults returns per-host results for a broadcast operation. Returns nil for unicast operations or unknown step names.

func (Results) Status 

func (r Results) Status(
	name string,
) TaskStatus

Status returns the terminal status of a completed dependency step.

type RetryOption 

type RetryOption func(*retryConfig)

RetryOption configures the Retry behavior.

func WithBackoff 

func WithBackoff(
	initial time.Duration,
	maxInterval time.Duration,
) RetryOption

WithBackoff sets custom initial and max intervals for exponential backoff between retry attempts. The delay doubles on each attempt, clamped to maxInterval.

func WithExponentialBackoff 

func WithExponentialBackoff() RetryOption

WithExponentialBackoff enables exponential backoff between retry attempts with sensible defaults (1s initial, 30s max).

type Step 

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

Step represents a single operation in the plan. Users chain methods to declare ordering, conditions, and error handling.

func (*Step) After 

func (s *Step) After(
	deps ...*Step,
) *Step

After declares that this step runs after the given steps complete.

func (*Step) ContinueOnError 

func (s *Step) ContinueOnError() *Step

ContinueOnError is a convenience for OnError(Continue). Independent tasks keep running when this step fails; only direct dependents are skipped.

func (*Step) Named 

func (s *Step) Named(
	name string,
) *Step

Named overrides the auto-generated step name.

func (*Step) OnError 

func (s *Step) OnError(
	strategy ErrorStrategy,
) *Step

OnError sets the error strategy for this step.

func (*Step) OnlyIfAllChanged 

func (s *Step) OnlyIfAllChanged() *Step

OnlyIfAllChanged skips this step unless all dependencies reported changes.

func (*Step) OnlyIfAllHostsChanged 

func (s *Step) OnlyIfAllHostsChanged() *Step

OnlyIfAllHostsChanged skips this step unless every host in every dependency reported changes. Only meaningful for broadcast operations.

func (*Step) OnlyIfAllHostsFailed 

func (s *Step) OnlyIfAllHostsFailed() *Step

OnlyIfAllHostsFailed skips this step unless every host in every dependency has an error. Only meaningful for broadcast operations.

func (*Step) OnlyIfAnyHostChanged 

func (s *Step) OnlyIfAnyHostChanged() *Step

OnlyIfAnyHostChanged skips this step unless any host in any dependency reported changes. Only meaningful for broadcast operations.

func (*Step) OnlyIfAnyHostFailed 

func (s *Step) OnlyIfAnyHostFailed() *Step

OnlyIfAnyHostFailed skips this step unless any host in any dependency has an error. Only meaningful for broadcast operations.

func (*Step) OnlyIfAnyHostSkipped 

func (s *Step) OnlyIfAnyHostSkipped() *Step

OnlyIfAnyHostSkipped skips this step unless any host in any dependency was skipped (unsupported operation). Only meaningful for broadcast operations. Skipped hosts are NOT errors — they indicate the operation is not available on that OS family.

func (*Step) OnlyIfChanged 

func (s *Step) OnlyIfChanged() *Step

OnlyIfChanged skips this step unless a dependency reported changes.

func (*Step) OnlyIfFailed 

func (s *Step) OnlyIfFailed() *Step

OnlyIfFailed skips this step unless at least one dependency failed.

func (*Step) Retry 

func (s *Step) Retry(
	n int,
	opts ...RetryOption,
) *Step

Retry sets the number of retry attempts on failure. Options configure exponential backoff between attempts.

func (*Step) When 

func (s *Step) When(
	fn func(Results) bool,
) *Step

When adds a guard condition — the step only runs if the predicate returns true.

func (*Step) WhenFact 

func (s *Step) WhenFact(
	agentListStep string,
	fn Predicate,
) *Step

WhenFact adds a fact-based guard. The step runs only if the predicate returns true for at least one agent. Requires a prior AgentList step referenced by name. The skip reason distinguishes between a missing/mistyped step name and no matching agents.

type TaskResult 

type TaskResult = engine.TaskResult

TaskResult records the full execution details of a task. Exposed via Report.Tasks.

type TaskStatus 

type TaskStatus int

TaskStatus represents the outcome of a step for guard inspection. 

const (
	// TaskStatusUnknown indicates the step was not found or has not run.
	TaskStatusUnknown TaskStatus = iota
	// TaskStatusChanged indicates the step ran and reported changes.
	TaskStatusChanged
	// TaskStatusUnchanged indicates the step ran with no changes.
	TaskStatusUnchanged
	// TaskStatusSkipped indicates the step was skipped.
	TaskStatusSkipped
	// TaskStatusFailed indicates the step failed.
	TaskStatusFailed
)

type UploadOption 

type UploadOption func(*uploadConfig)

UploadOption configures the FileUpload operation.

func WithForce 

func WithForce() UploadOption

WithForce makes FileUpload bypass the SHA-256 pre-check and always upload regardless of whether the content has changed. Without this option FileUpload is idempotent — the SDK compares digests and skips the upload when content is unchanged.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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