Ansible for firewalls — concepts, trade-offs, and blast-radius discipline · OPNsense

A single firewall can be driven by raw API scripts. A fleet of firewalls, or a single firewall that is touched repeatedly over months, benefits from a configuration-management tool that knows the state of the world, can apply changes idempotently, and can report on what it changed. Ansible is the most common such tool in production sysadmin work today, and OPNsense has a community collection that maps Ansible’s module model onto the OPNsense REST API.

This lesson covers why Ansible is preferred over raw scripts at fleet scale, the push-based execution model, idempotency and its operational meaning, the blast-radius discipline, and the trade-offs you weigh when picking one approach over the other.

Why Ansible for firewalls

Raw API scripts work for one firewall at a time. Three situations push teams toward Ansible:

Multi-firewall estates. A team running five firewalls across two data centres needs a single source of truth for rules, aliases, and backplane config. Ansible inventories give that; raw scripts do not.
Repeated change. A firewall that is touched monthly — new IPs, new ports, new rules — accumulates drift. Ansible’s idempotent modules re-apply the desired state on every run, so drift is corrected automatically.
Audit and change reporting. A regulated environment that asks “what changed on firewall X in the last 90 days” can answer from Ansible’s git-tracked playbooks + the changed flag. A bash + curl script that mutates the firewall leaves no such record.

The same firewall could be managed by either approach. The question is which one matches the team’s reality: a single engineer with three firewalls probably writes Ansible. A 30-engineer platform team certainly does.

Push-based execution (and how OPNsense is agentless)

Ansible normally connects to each managed node over SSH and runs the module there. OPNsense does not work that way: the modules never touch the firewall’s shell, and nothing is installed on the firewall at all. They execute on the controller and reach the firewall over its HTTPS API, which is why every play against OPNsense sets connection: local and passes the firewall’s address as a module parameter.

That is a genuine advantage rather than a workaround. The firewall needs no SSH access, no Python for Ansible, and no package installed for management purposes — only an API key/secret pair with the privileges the play needs. The management surface an operator has to secure is the one that already existed.

The community collection modules — ansibleguy.opnsense.rule, ansibleguy.opnsense.alias, and the rest — wrap that API. Each reads the current state with a search, compares it against the desired state, and applies the difference with the relevant add or set call. The module reports changed, ok or failed depending on whether there was a difference to apply.

Read-only / Safeansible --check --diff— A dry run on a single host. --check makes Ansible simulate the run without applying changes; --diff prints what would change. The output shows the new rule that the playbook would add (the + line) versus the absence of that rule in the current state. The changed count is 1 but nothing was actually applied yet — that is the report the operator reviews before re-running without --check. --limit fw-dc1-01 confines the dry run to a single firewall, the safe first step before running the play against a fleet.

$ ansible-playbook -i inventories/firewalls/hosts.yml playbooks/firewall-rules.yml --check --diff --limit fw-dc1-01

PLAY [firewall rules on dc1-01] ***************************************************

TASK [Ensure outbound allow for CI runners] **************************************
--- before
+++ after
@@ -1,1 +1,1 @@
-+        { action: pass, source: ci_runners_alias, destination: any, descr: CHG-2026-1314 }
changed: [fw-dc1-01]

PLAY RECAP ******************************************************************
fw-dc1-01                  : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Illustrative output

Idempotency: the operational meaning

An idempotent module is one where running the playbook twice produces the same end state as running it once. From the firewall’s perspective, that means the second run makes no write at all: the module reads the current state, finds it already matches, and sends nothing. A module that instead re-sent the same setRule every time would still leave the firewall correct, but it would write a new configuration revision on every run and bury real changes in a history of no-ops.

The operational meaning has three parts:

Drift correction. If someone hand-edits a rule through the GUI, the next Ansible run sees that the rule exists but does not match the playbook’s desired state, and reapplies the desired state. Without idempotency, this would require a separate “reconcile” workflow.
Re-running is safe. A playbook that timed out, or was interrupted by an on-call alert, can be re-run from the top. The second run is mostly no-ops, only the unfinished tasks apply.
Change reporting is honest. The changed flag is a precise signal: this run actually changed something on this host. A changed count of zero across a fleet means the firewall matches its desired state exactly.

Idempotency is not free. A module has to read state before writing. The cost: extra API calls (typically 1-3 per object per run). The benefit: the playbook is repeatable, predictable, and safe to re-run.

Serial batches and blast-radius discipline

A run against 30 firewalls is not safe to perform in parallel. One badly-formed module call could lock the operator out of every firewall simultaneously. The discipline is serial batches: --serial 1 or --serial 5 limits how many hosts the play runs against at the same time. A 30-firewall estate typically runs --serial 1 against a single maintenance window.

Three operational patterns:

Maintenance windows. All fleet changes happen during a scheduled change window. Out-of-window changes require manual override and a separate audit path.
Canary first. The play runs against one firewall (the canary) first. The operator verifies the change looks right, then extends to --limit all.
Auto-promotion. --serial 1 with a pause and a verification between batches. A failed batch halts the next from running (Ansible’s max_fail_percentage).

The blast-radius discipline turns a fleet-wide automation into a governed change. The same playbook, run naively in parallel, is an outage waiting to happen.

How Ansible's modules interact with the OPNsense API

The collection is a set of Python modules that follow Ansible’s module contract — they take parameters, make API calls, observe the result, and report changed, ok or failed. For “ensure this firewall rule exists”:

Get params. The task supplies the desired rule as fields: action, source, destination, description, and so on.
Read current state. The module calls /api/firewall/filter/searchRule and gets back every rule the firewall holds.
Identify. It compares each existing rule against the task, but only on the fields listed in match_fields. That parameter is how the module answers “is this the rule I am managing”, because the firewall itself has no idea which rules belong to which playbook.
Diff and apply. No match means addRule; a match that differs means setRule/{uuid}; a match that agrees means nothing is sent and the task reports ok.
Apply to the data plane. Unless the task disables it, the module follows a write with the controller’s apply, because a saved rule that has not been applied is not yet a rule the firewall enforces.

The module is structured code wrapping HTTP calls. What makes it worth more than the equivalent curl is that it carries a definition of object identity — match_fields — and a guarantee that the same task run twice produces one rule.

The trade-offs versus direct API scripts

Aspect	Direct API script	Ansible
Lines of code	Less	More (roles, tasks, vars, handlers)
Onboarding new team members	Faster for one script	Faster at scale (standard tools)
Drift correction	Manual	Automatic on next run
Multi-firewall inventory	Build your own	Built-in
Change reporting	Build your own	`changed` flag, callback plugins
Idempotency	Build your own	Module-provided
Pre-flight checks (per-firewall)	Manual	Built into the playbook
Required operator skill	Bash, curl, jq	Ansible playbook syntax, modules

For a single firewall and a one-off change, a script is faster to write and easier to understand. For a fleet or a regular-cadence change, Ansible earns its overhead. The wrong choice is to write a fleet of curl-based scripts that duplicate each other, each with its own drift, its own identifier for the same object, and its own audit story.

When not to use Ansible

Three situations where Ansible is the wrong tool:

Truly one-off changes. A change that will not be repeated (a one-time migration) does not need a playbook. A script with the change ticket ID in the comments is the right tool.
Discovery. Reading the firewall’s state to answer “what is the current rule for port 22?” is a curl call, not a playbook.
Bootstrapping the Ansible controller itself. Before there is an Ansible controller, there is no Ansible. The first run, on the first firewall, may be a curl call from a debug session — followed by an Ansible role that captures the same configuration for reuse.

Summary

Ansible is the right tool when the change is one of many, the firewall is one of many, or the audit story needs to be defended.
OPNsense is agentless; Ansible uses push mode over the API surface. Community modules wrap the OPNsense REST endpoints.
Idempotency means re-running is safe and drift is corrected automatically. The changed flag tells the operator what actually happened.
Serial batches and blast-radius discipline turn a fleet run into a governed change. The disciplined run is --limit fw-canary --check --diff first, then --limit all in a serial cadence.
An Ansible playbook is not magic; the discipline of pre-flight, anti-lockout invariants, and post-flight verification lives in the playbook’s structure.