osapi-orchestrator

README

OSAPI Orchestrator

A Go package for orchestrating operations across OSAPI-managed hosts -- typed operations, chaining, conditions, and result decoding built on top of the osapi-sdk engine.

📦 Install

go install github.com/osapi-io/osapi-orchestrator@latest

As a library dependency:

go get github.com/osapi-io/osapi-orchestrator

🎯 Targeting

Most operations accept a target parameter to control which agents receive the request:

Target	Behavior
_any	Send to any available agent (load balanced)
_all	Broadcast to every agent
hostname	Send to a specific host
key:value	Send to agents matching a label

⚙️ Operations

101 typed constructors across 23 domains:

Domain	Docs	Example
Node	4 operations	node-info.go
Hostname	2 operations	hostname-update.go
Hardware	2 operations	node-info.go
Network	4 operations	dns-update.go
Interface	5 operations	interface.go
Route	5 operations	route.go
Command	2 operations	command.go
Docker	9 operations	docker.go
Cron	5 operations	cron.go
Sysctl	5 operations	sysctl.go
NTP	4 operations	ntp.go
Timezone	2 operations	timezone.go
Service	10 operations	service.go
Package	6 operations	package.go
User	9 operations	user.go
Group	5 operations	group.go
Certificate	4 operations	certificate.go
Process	3 operations	process.go
Power	2 operations	power.go
Log	3 operations	log.go
File	5 operations	file-deploy.go
Agent	4 operations	agent-drain.go
Health	1 operation	basic.go

✨ Features

The orchestrator provides a declarative DSL for composing operations into DAG-based plans with typed results, guards, retry, and discovery.

Feature	Description
Step Chaining	Sequential and parallel DAG execution
Guards	Conditional execution (When, OnlyIfChanged...)
Error Recovery	Continue strategy with OnlyIfFailed cleanup
Broadcast	Per-host results from _all/label targets
Host Status	Skipped and failed detection per host
Retry	Automatic retry with exponential backoff
Discovery	Find agents by OS, arch, labels, conditions
File Workflow	Upload, deploy, drift detection, undeploy
Result Decode	Typed struct decoding from step results
TaskFunc	Custom logic with access to prior results

See the DSL reference for guards, predicates, error strategies, and typed result tables.

📖 Documentation

See the package documentation on pkg.go.dev for API details.

📋 Examples

Runnable examples in examples/operations/ (per-domain workflows) and examples/features/ (DSL features). Run with:

OSAPI_TOKEN="<jwt>" go run examples/features/basic.go

🤝 Contributing

See the Development guide for prerequisites, setup, and conventions. See the Contributing guide before submitting a PR.

📄 License

The MIT License.