Use the attached export_inventory.py script to turn your BinaryLane servers into an Ansible inventory file, so you can run Ansible against your fleet without maintaining a host list yourself.

The exporter makes read-only API requests and saves the inventory on your computer. The later connection check runs a small Ansible test on one server you choose; it does not change that server's configuration.

TABLE OF CONTENTS


Before you begin

You need:

  • A supported Python 3 release, version 3.9 or later, for the exporter. It uses no third-party packages.
  • Ansible installed on a Linux or macOS control machine, or inside WSL on Windows. See the Ansible installation guide. Ansible's Python requirements depend on its release and are separate from the exporter's minimum version.
  • A BinaryLane API token. See Getting Started with the BinaryLane API for how to create one.
  • Working SSH access and a compatible Python interpreter on a Linux server for the connection check. The exporter does not configure or test either.

The inventory includes all servers, including Windows and stopped servers. This guide's connection example is for Linux only. You can export from native Windows PowerShell, but run the Ansible commands on your control machine.

Download export_inventory.py from the attachments below and open a terminal in the folder where you saved it. The script needs no installation.

Treat the API token as full account access

BinaryLane does not currently support scoped API tokens, so a token that can list your servers can also do anything else the API allows on your account. See Does BinaryLane support scoped API tokens?

Because of that:

  • Pass the token through an environment variable. Do not put it in this script, a playbook, the inventory or an Ansible variable file.
  • Do not commit it to version control, and do not put it in the inventory the script generates. The script never writes it there.
  • If a token may have been exposed, replace it in mPanel.

Step 1: Set your token in the environment

The script reads your token from BINARYLANE_API_TOKEN and from nowhere else.

On Linux or macOS, using Bash:

read -r -s -p 'BinaryLane API token: ' BINARYLANE_API_TOKEN
printf '\n'
export BINARYLANE_API_TOKEN

On Windows PowerShell 7 or later (export only):

$env:BINARYLANE_API_TOKEN = Read-Host 'BinaryLane API token' -MaskInput

These prompts avoid putting the token in a command saved to shell history. The exporter sends it in an Authorization header over HTTPS and refuses redirects. It does not include the token in its output.

Step 2: Export the inventory

python3 export_inventory.py --output fleet.json

On Windows, use python instead of python3. The script requests your servers one page at a time and writes fleet.json. It reports what it did, and anything you should know, on standard error:

warning: hostname 'web1' is used by more than one server (bl-101, bl-102); the ID aliases keep them distinct
warning: 1 server(s) have no public IPv4 address and were left without ansible_host; see the bl_no_public_ipv4 group
wrote 4 server(s) to fleet.json

Keep the .json extension. Ansible's built-in YAML inventory plugin accepts .yaml, .yml, and .json, so the file works as a static inventory with no extra configuration.

If the export fails, for example because the token was rejected or the API could not be reached, the script prints one error: line, exits non-zero, and does not write the file. An inventory from an earlier successful run is left exactly as it was.

If the reported server total changes or the pages are incomplete, rerun the export before using the file. If no total is supplied, the script warns that completeness could not be checked; compare the inventory with your account.

After exporting, remove the token from this terminal: unset BINARYLANE_API_TOKEN in Bash, or Remove-Item Env:BINARYLANE_API_TOKEN in PowerShell. The inventory contains account infrastructure details, so keep it out of public repositories.

Step 3: Read the inventory before you connect to anything

The output is a plain text file, so you can open it. Ansible can also summarise it for you:

ansible-inventory -i fleet.json --graph

@all:
  |--@ungrouped:
  |--@binarylane:
  |  |--bl-101
  |  |--bl-102
  |  |--bl-103
  |  |--bl-104
  |--@bl_no_public_ipv4:
  |  |--bl-103
  |--@bl_region_syd:
  |  |--bl-101
  |  |--bl-102
  |  |--bl-103
  |  |--bl-104
  |--@bl_status_active:
  |  |--bl-101
  |  |--bl-102
  |  |--bl-103
  |--@bl_status_off:
  |  |--bl-104

To see everything recorded about one server:

ansible-inventory -i fleet.json --host bl-102

{
    "ansible_host": "203.0.113.9",
    "bl_duplicate_hostname": true,
    "bl_hostname": "web1",
    "bl_private_ipv4": [],
    "bl_public_ipv4": [
        "203.0.113.9",
        "203.0.113.100"
    ],
    "bl_public_ipv6": [],
    "bl_region": "syd",
    "bl_server_id": 102,
    "bl_size_slug": "std-min",
    "bl_status": "active",
    "bl_vpc_id": null
}

The output above comes from a four-server example fleet. The addresses are reserved for documentation, and syd stands in for whichever region your servers are in. Your own output will show your servers and regions.

Check that the servers you expect are listed, that each one you plan to target has an ansible_host, and that the addresses are the ones you meant to connect to. Do this before running anything against real servers.

What the inventory contains

Every server on the account appears once in the binarylane group, whatever its status, so the file describes your whole fleet rather than a filtered part of it.

Each host is named bl- followed by the server's ID, for example bl-101. The ID is used rather than the hostname because two servers can share a hostname, and because renaming a server does not change its ID. Your host names therefore stay the same across exports.

These groups are available:

GroupContains
binarylaneEvery server on the account.
bl_region_<region>Servers in one region.
bl_status_<status>Servers with one status: new, active, archive, or off. Status is not an OS or SSH-readiness check.
bl_no_public_ipv4Servers with no public IPv4 address, which have no ansible_host.

BinaryLane servers have no tags or groups of their own in the API, so these groups are built from the region and status the API reports. If you want groups of your own, such as one per application, define them in a separate inventory file alongside this one rather than editing fleet.json, which is overwritten on each export.

Alongside ansible_host, each host carries its server ID, hostname, region, status, size slug, VPC ID, and the full list of its public IPv4, private IPv4, and public IPv6 addresses.

Which address the inventory uses

ansible_host is set to the server's lowest public IPv4 address. Every public address is still listed in bl_public_ipv4, so you can choose a different one.

Private and VPC addresses are recorded in bl_private_ipv4 but never used for ansible_host, because they are only reachable from a machine already on that network. If your control machine is on the VPC, set ansible_host from bl_private_ipv4 in your own variables.

Public IPv6 addresses are recorded but not used either, because whether IPv6 works between your control machine and the server is something only you can confirm.

A server with no public IPv4 address is left without ansible_host and listed in the bl_no_public_ipv4 group. Ansible would otherwise try to connect to the host name, which is an ID alias rather than an address.

The API reports which addresses a server has. It does not report which of them your machine can actually reach, or that anything is listening on them. That is what Step 5 checks.

Step 4: Add SSH settings for a chosen Linux server

The inventory holds no login details. It has no username, no key path, and no password, and the script never guesses any of them.

Choose a running Linux server from the inventory. In this example it is bl-101; replace that alias with yours. Create a host_vars directory beside fleet.json, then create the matching host file.

host_vars/bl-101.yml:

ansible_user: your_user
ansible_ssh_private_key_file: ~/.ssh/id_ed25519

Replace your_user and the key path with the SSH settings you normally use for this server. Verify its SSH host key through your normal trusted process; do not disable host-key checking.

Never put your BinaryLane API token in host_vars or in any other Ansible variable. Ansible does not need it. Only the export script does, and only from the environment.

Step 5: Check the chosen Linux server

ansible bl-101 -i fleet.json -m ansible.builtin.ping

Replace bl-101 with the same alias used in Step 4. Success includes "ping": "pong". This checks SSH login and usable remote Python, not ICMP ping. On failure, check the selected address, credentials, host-key trust, network access and Python compatibility; inspecting the inventory alone does not prove these are correct.

Use the same inventory with your playbooks after reviewing their targets. Do not target the entire binarylane or bl_status_active group with Linux tasks unless every selected server is suitable.

Keep the inventory current

fleet.json describes your fleet at the moment you exported it. Run the export again after you create, destroy, rename, or re-address a server.

An out-of-date inventory is the most likely way this approach goes wrong. It can leave a decommissioned server in the file, or leave a new one out of a change you thought covered everything. Re-exporting takes one command, so run it at the start of any session where the fleet may have moved.

Terraform or Ansible

These solve different problems.

Using one does not rule out the other. If you already create your servers with Terraform, this export still gives Ansible a current view of what the API reports, without you having to keep a second host list in step.

Applies to

  • BinaryLane servers listed by the API endpoint GET /v2/servers
  • Python 3.9 or later on the machine running the export
  • Ansible's built-in YAML inventory plugin and Linux SSH/Python connection checking; Windows server configuration is outside this guide