Skip to content

Ansible Playbooks

Ansible playbook assemblies run from the Linux Engine against remote devices over Borealis-managed WireGuard paths. Use them for infrastructure-style automation when Ansible modules fit better than endpoint scripts.

Borealis Ansible Playbook Recap
Ansible recaps expose Engine-side playbook execution output and per-target status.

Create Playbook Assembly

  1. Open Automation > Assemblies.
  2. Select New Ansible Playbook.
  3. Add playbook content and metadata.
  4. Save.

Schedule Playbook

  1. Create Scheduled Job.
  2. Add Ansible playbook assembly.
  3. Choose device or filter targets.
  4. Choose execution context:
  5. ssh_individual
  6. ssh
  7. winrm_individual
  8. winrm
  9. Select credential or service account path where applicable.
  10. Save.

New Ansible jobs default to individual execution so each target gets separate status, output, and timeout handling. The Site Worker Scheduled Tasks value is the visible throttle for scheduled Ansible execution. Engine.sh --network-mode public|local deploy tunes that value from the detected Engine sizing profile.

The Site Worker Scheduled Tasks value limits active scheduled work items, not raw devices. Shared Ansible mode uses one work-item slot for a site batch and lets Ansible process the hosts inside that batch. Individual mode uses one work-item slot per target while active.

Read Recap

Run history shows target status and StdOut/StdErr. Playbook recap data captures Ansible results per host or run component.

Credential Notes

SSH credentials may include password, private key, become method, and become password. Borealis chooses final SSH auth mode per target instead of blindly passing key and password together.

Detailed Codex Breakdown

API endpoints

  • Playbook execution is scheduled through Scheduled Jobs.
  • Assembly CRUD endpoints are listed in Assemblies.
  • GET /api/server/site-worker-settings - read profile-managed scheduled-lane worker capacity.

Source map

  • Ansible runner: Data/Engine/Containers/api-backend/data/services/ansible/runner.py
  • SSH credential rendering: Data/Engine/Containers/api-backend/data/services/ansible/ssh_auth.py
  • Scheduler dispatch: Data/Engine/Containers/api-backend/cmd/api-backend/scheduler_execution.go
  • Scheduled job UI: Data/Engine/Containers/webui-frontend/data/web-interface/src/Scheduling/Create_Job.jsx

Runtime behavior

  • Engine stages required Ansible collections into Engine/Services/api-backend/cache/Ansible/collections.
  • Shared contexts run one inventory per playbook component and consume one scheduled-lane worker slot for that site batch. The nodegraph can show Task (8 Devices) for one shared work item because the label reports target count, not slot count.
  • Individual contexts create one-host inventories and one run row per target/component pair. Each queued run consumes one scheduled-lane worker slot while active. The nodegraph can group several same-job, same-status runs into one Task (n Devices) card.
  • SSH/WinRM target admission depends on WireGuard readiness and credential/service-account resolution.
  • Legacy Ansible runner limit endpoints remain API-compatible but scheduler dispatch no longer uses them as active gates.
  • Site-worker scheduled-lane capacity is the active work-item claim limit. Profile values are 5, 8, 12, or 16 scheduled work items per site worker; onboarding and other lanes are not changed by this setting.
  • Borealis does not currently pass --forks to Ansible. Shared batches use Ansible's default internal host fan-out inside the single claimed work item.