From Forklift Network Upgrade to Infrastructure as Code: Automating TP-Link Omada with an Ansible Collection

When a client asked me to forklift-replace their network — new gateway, new switch, new access points, a full VLAN redesign — I could have done what most consultants do: click through the Omada Controller's UI, configure everything by hand, hand over a network diagram, and move on. Instead, I decided the new network needed to be built as infrastructure as code from day one: every VLAN, every port assignment, every firmware policy defined in Ansible, version-controlled and reproducible, not a snapshot of whatever I happened to click one afternoon.

That decision turned into a much deeper project than I expected, and it's a good example of what's changed about what one engineer can realistically build under a real deadline when AI-assisted engineering tools are used well — not as a replacement for judgment, but as a force multiplier for it.

The gap

TP-Link's Omada SDN platform — the controller, gateway, switches, and APs a lot of small and mid-size networks run on — has no official Ansible support. There's a well-maintained community Python client, tplink-omada-client, used by Home Assistant's own integration, but it talks to Omada's legacy private controller API rather than the newer official OpenAPI, and critically, it had no way to read or create LAN networks/VLANs at all. That's not a minor gap for a project whose entire premise was "define the VLANs in code."

Before writing anything, I did what I'd normally call due diligence: cataloguing every Omada-adjacent Python and Ansible project that exists, and mapping exactly what tplink-omada-client's API surface actually supported — not what its docs claimed, but its real introspected method signatures, cross-referenced against its own CLI and its GitHub issue history. Nobody had built VLAN/network write support for this library, anywhere.

So I built it.

Reverse-engineering a private API safely

Omada's network-creation flow doesn't behave the way you'd guess from the API docs. Reading existing VLANs uses one endpoint; creating a new one uses a completely different one, TP-Link's newer official OpenAPI, wrapped in a multi-step wizard flow that only becomes clear once you watch what the Controller UI itself actually sends. I tried the sensible things first — introspecting the client library, guessing at a plausible request body, testing against a disposable VLAN. Every guess failed cleanly, which was useful information, but slow.

The turning point was capturing the real request: instrumenting a live browser session to intercept the network calls the Controller UI made while creating a test network by hand, extracting the exact payload shape, and building the real create_network() call against it. I also hit a second landmine: Omada exposes two completely unrelated API resources that are both called "tags" — one legacy and cosmetic, one the real thing switch ports and networks actually reference.

None of this is exotic engineering on its own. What was different was the pace at which I could work through it responsibly. This was a scaled down test lab with all components of the eventual production environment. Every step ran under a strict discipline: read-only until explicitly approved, narrow single-purpose writes, state verified before and after every change, no guessing at scope. Working with an AI coding partner made it possible to hold that discipline and still move fast — proposing hypotheses, writing verification scripts, building out a full test suite alongside every confirmed API discovery, and correcting course immediately the one time a step drifted outside the agreed scope.

What came out of it

I ended up shipping three things. First, a public fork of tplink-omada-client adding the missing VLAN/network and port-label read-write support, verified end-to-end against real hardware — an ER707-M2 gateway, an SG3452XP switch, an OC200 controller, EAP723 access points. Second, a from-scratch Ansible collection, published to Ansible Galaxy as japplewhite0.omada, with modules to read and configure sites, devices, firmware, switch ports, and now VLANs themselves — all idempotent and check-mode aware, with a real test suite behind them. Third, a documented capability matrix of exactly what the whole Omada Python ecosystem does and doesn't support today, which I've also raised directly with the upstream maintainer as a starting point for contributing this back.

The client's network is now something I can stand up, audit, and modify with a playbook instead of a mouse. And the tooling exists for the next person who needs the same thing, instead of living only in one consultant's head.

If you're evaluating engineers for infrastructure, network automation, or platform work: this is the kind of problem I like — one where the fastest path isn't obvious, the documentation doesn't help you, and the right answer requires both real systems engineering and the judgment to move quickly without being reckless about a client's production environment. TP-Link built genuinely solid hardware here; it just didn't have this automation layer yet.