README
¶
Compose operations across OSAPI-managed hosts as one plan.
Describe the plan, not the order.
Declare what has to happen and what depends on what, and the orchestrator resolves the order, runs independent work in parallel, and gives you one result per host rather than one answer for the fleet.
Install
go install github.com/osapi-io/osapi-orchestrator@latest
As a library dependency:
go get github.com/osapi-io/osapi-orchestrator
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.
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
Documentation
- Package documentation on pkg.go.dev. API reference.
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 |
Contributing
See the Contributing guide for prerequisites, setup, conventions, and the PR workflow.
License
The MIT License.
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
engine
Package engine provides DAG-based task orchestration primitives.
|
Package engine provides DAG-based task orchestration primitives. |
|
pkg
|
|
|
orchestrator
Package orchestrator provides a declarative DSL for OSAPI infrastructure operations.
|
Package orchestrator provides a declarative DSL for OSAPI infrastructure operations. |