Skip to content

feat: Add Ansible component for playbooks and ad-hoc commands#5092

Open
dkozlov wants to merge 2 commits into
superplanehq:mainfrom
dkozlov:feat/ansible-component
Open

feat: Add Ansible component for playbooks and ad-hoc commands#5092
dkozlov wants to merge 2 commits into
superplanehq:mainfrom
dkozlov:feat/ansible-component

Conversation

@dkozlov
Copy link
Copy Markdown

@dkozlov dkozlov commented May 30, 2026

What

Adds a built-in ansible action component that runs Ansible playbooks and ad-hoc commands from a Canvas.

Why

SuperPlane ships execution components (ssh, runner, http) but nothing for configuration management / infrastructure automation. Ansible is a natural fit: a node that, given a playbook (or an ad-hoc module + host pattern) and an inventory, runs Ansible and routes the workflow on success / failed, surfacing the play recap (ok/changed/unreachable/failed) and stdout/stderr.

How

  • One component, two modes (Playbook / Ad-hoc) via conditional config fields, modeled on the existing ssh component.
  • The SuperPlane process acts as the Ansible control node; it reaches managed hosts through the provided inventory (SSH, or ansible_connection=local for a self-contained run).
  • Playbook mode runs with the JSON stdout callback so the per-host recap is captured; routes success (exit 0) / failed (non-zero). If Ansible can't run at all (missing binary, timeout), the run finishes in the error state.
  • Security: argv is built as a slice (no shell — no sh -c), module/var names and argv values are validated, and no secrets are logged or emitted.
  • Adds ansible to the dev-base image as a dedicated layer (DEBIAN_FRONTEND=noninteractive).
  • Unit tests cover validation, argv construction (playbook + ad-hoc, become/extra-vars/limit/verbosity), recap parsing, and success/failed channel routing.

Verified

Built and run end-to-end against a local dev instance: a Start → Ansible (playbook) → Smoke test (ad-hoc) → Display canvas executes, the playbook performs real file operations on localhost, the recap is captured (ok/changed/...), and routing follows success/failed.

Notes

  • The component shells out via os/exec on the node running the executor — appropriate for self-hosted/dev; flagged for reviewers.

Files

  • pkg/components/ansible/ansible.go, runner.go, example.go, example_output.json, ansible_test.go
  • pkg/registryimports/registryimports.go — register the component
  • Dockerfile — install ansible in the dev image

🤖 Generated with Claude Code

Add a built-in `ansible` action component that runs Ansible playbooks and
ad-hoc commands from a Canvas. The SuperPlane container acts as the Ansible
control node and reaches managed hosts via the provided inventory (SSH, or
ansible_connection=local for a self-contained run).

- One component, two modes (playbook / ad-hoc) via conditional config fields,
  modeled on the existing ssh component.
- Inline playbook + inventory written to a per-execution temp dir; playbook
  runs use the JSON stdout callback so the per-host recap is captured.
- Routes success / failed by Ansible exit status; inability to run Ansible
  (missing binary, timeout) surfaces as the error state.
- Security: argv is built as a slice (no shell), module/var names and argv
  values are validated, and no secrets are logged or emitted.
- Adds ansible to the dev-base image as a dedicated layer (DEBIAN_FRONTEND
  noninteractive) so it does not invalidate the cached toolchain layers.

Unit tests cover validation, argv construction, recap parsing, and channel
routing.

Signed-off-by: Dmitry Kozlov <dmitry.f.kozlov@gmail.com>
@superplanehq-integration
Copy link
Copy Markdown

👋 Commands for maintainers:

  • /sp start - Start an ephemeral machine (takes ~30s)
  • /sp stop - Stop a running machine (auto-executed on pr close)

Regenerated docs/components (scripts/generate_components_docs.go) so the
built-in Ansible component is documented in Core.mdx, matching how the other
core components (ssh, runner, http) are documented. Keeps the
check.components.docs CI gate green.

Signed-off-by: Dmitry Kozlov <dmitry.f.kozlov@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant