TigerBeetle Ansible Complete Deployment

This project deploys a scalable TigerBeetle cluster using Ansible.

It supports both installation modes:

• online: each server downloads the TigerBeetle binary from the official Linux URL.
• offline: Ansible copies a TigerBeetle binary from your local control machine to all servers.

Structure

tigerbeetle-ansible-complete/
├── ansible.cfg
├── requirements.yml
├── inventories/
│   └── prod/
│       ├── hosts.yml
│       └── group_vars/
│           └── tigerbeetle.yml
├── playbooks/
│   └── site.yml
└── roles/
    └── tigerbeetle/
        ├── defaults/main.yml
        ├── files/
        ├── handlers/main.yml
        ├── meta/main.yml
        ├── tasks/main.yml
        └── templates/tigerbeetle.service.j2

Important TigerBeetle rule

The replica count is fixed after formatting. Decide the final number of nodes before first deployment.

The role automatically calculates:

replica index = host position in inventory group `tigerbeetle`
replica count = number of hosts in group `tigerbeetle`
addresses     = ordered list of all `tigerbeetle_advertise_address:port`

So for a 3-node cluster:

srv-tb-01 -> replica 0
srv-tb-02 -> replica 1
srv-tb-03 -> replica 2

For a 6-node cluster, just add 6 hosts to the tigerbeetle group before first deploy.

1. Install Ansible collections

ansible-galaxy collection install -r requirements.yml

2. Edit inventory

Edit:

inventories/prod/hosts.yml

Example:

all:
  children:
    tigerbeetle:
      hosts:
        srv-tb-01:
          ansible_host: 10.10.10.11
          tigerbeetle_advertise_address: 10.10.10.11
        srv-tb-02:
          ansible_host: 10.10.10.12
          tigerbeetle_advertise_address: 10.10.10.12
        srv-tb-03:
          ansible_host: 10.10.10.13
          tigerbeetle_advertise_address: 10.10.10.13

The order matters. The first host becomes replica 0, second becomes replica 1, etc.

3. Configure variables

Edit:

inventories/prod/group_vars/tigerbeetle.yml

Online mode

tigerbeetle_install_mode: online
tigerbeetle_online_url: "https://linux.tigerbeetle.com"

Offline mode

Put your local binary here:

cp /path/to/tigerbeetle roles/tigerbeetle/files/tigerbeetle
chmod +x roles/tigerbeetle/files/tigerbeetle

Then set:

tigerbeetle_install_mode: offline
tigerbeetle_offline_binary_src: "tigerbeetle"

4. Deploy

ansible-playbook playbooks/site.yml

5. Verify

On each server:

systemctl status tigerbeetle
journalctl -u tigerbeetle -f
ss -lntp | grep 3001

6. Useful variables

tigerbeetle_cluster_id: "123456789"
tigerbeetle_port: 3001
tigerbeetle_cache_grid_size: "4GiB"
tigerbeetle_data_dir: /var/lib/tigerbeetle
tigerbeetle_binary_path: /usr/local/bin/tigerbeetle

7. Reformat warning

By default, this role does not overwrite existing replica data files.

tigerbeetle_force_format: false

Only set this to true in test environments when you intentionally want to destroy/recreate replica data files.

8. UFW firewall support

Disabled by default:

tigerbeetle_manage_ufw: false

Enable it if you use UFW:

tigerbeetle_manage_ufw: true
tigerbeetle_allowed_cidrs:
  - "10.10.10.0/24"