Ansible
NetActuate provides Ansible modules for provisioning and managing infrastructure. You can use Ansible playbooks to deploy virtual servers, configure BGP sessions, and manage your NetActuate resources alongside your application deployment workflows.
Prerequisites
- Ansible 2.10 or later
- Python 3.8 or later
- A NetActuate API key (see Account → API Access in the portal)
Note: Ubuntu 24.04 LTS VMs reboot once after initial provisioning. The NetActuate playbooks handle this automatically with a login availability check before proceeding with configuration.
Installation
Install the NetActuate Ansible collection and the POSIX collection (required for sysctl and authorized_key modules):
ansible-galaxy collection install netactuate.compute
ansible-galaxy collection install ansible.posix
Authentication
Set your API key as an environment variable:
export NETACTUATE_API_KEY="your-api-key-here"
Or pass it directly in your playbook variables or group_vars/all:
auth_token: "YOUR_API_KEY"
Quick Start
NetActuate's open-source playbooks use a roles-based structure with group_vars/all for configuration and a per-node inventory file. See the BGP Worker Node page for a complete walkthrough, or jump to Compute Node for VM-only deployments without BGP.
Available Modules
| Module | Description |
|---|---|
netactuate.compute.node | Manage virtual server instances |
netactuate.compute.bgp | Provision servers with BGP sessions |
Control Node Setup
The machine you run Ansible from (your laptop or a bastion host) needs Python, Ansible, and the NetActuate collection installed.
macOS
brew install python3
pip3 install ansible
ansible-galaxy collection install netactuate.compute
ansible-galaxy collection install ansible.posix
Linux (Ubuntu/Debian)
sudo apt update && sudo apt install python3 python3-pip
pip3 install ansible
ansible-galaxy collection install netactuate.compute
ansible-galaxy collection install ansible.posix
Windows
Use WSL2 with Ubuntu, then follow the Linux instructions above.
wsl --install -d Ubuntu
AI-Assisted Provisioning
All NetActuate Ansible repos include an AGENTS.md file that gives AI coding assistants full context for provisioning infrastructure. See the AI-Assisted Provisioning guide.
Playbook Repositories
| Repository | Purpose |
|---|---|
| netactuate-ansible-compute | IaaS VMs, no BGP |
| netactuate-ansible-bgp-bird2 | Anycast BGP with BIRD2 |
| netactuate-ansible-bgp-frr | Anycast BGP with FRR |
| netactuate-ansible-nginx | NGINX on anycast nodes |
| netactuate-ansible-varnish | Varnish caching layer |
| netactuate-ansible-pdns | PowerDNS authoritative |
| netactuate-ansible-k3s | Self-managed k3s + anycast |
| netactuate-ansible-anycast-dns | KnotDNS anycast DNS |
Detailed Guides
- Compute Node (IaaS) -- Deploy VMs without BGP
- BGP Worker Node -- Deploy BGP-enabled anycast nodes
- NGINX Workers -- Deploy NGINX on anycast nodes
- PowerDNS Authoritative -- Deploy PowerDNS on anycast nodes
- Varnish Frontend -- Deploy Varnish caching on anycast nodes
- Add-On Playbooks -- Service layer overview
Need Help?
If you need assistance with Ansible automation, visit our support page.