Skip to main content

130. Host-Specific Ansible Playbooks

Status: Accepted Date: 2025-07-06

Context​

Our Ansible project manages the configuration for several different types of servers, each with a unique purpose (e.g., hecate is a powerful GPU machine, devmate is a development desktop, kuu is a media server). While these servers share a common base configuration (OS packages, SSH setup), they have very different sets of required roles. For example, only hecate needs the NVIDIA GPU driver role, and only kuu needs the Jellyfin media server role.

We need a way to apply the correct set of roles to the correct server. One approach is to have a single, monolithic playbook with complex conditionals (when: inventory_hostname == 'hecate'). This can quickly become very messy and hard to read.

Decision​

We will use separate, host-specific playbooks.

Each distinct server type will have its own playbook file in the playbooks/ directory (e.g., playbooks/hecate.yml, playbooks/devmate.yml). A "main" playbook (e.g., all_hosts.yml) can be used to run all host-specific playbooks in sequence.

Each host-specific playbook will be responsible for defining the exact list and order of roles required for that particular host. For example, hecate.yml might look like:

- hosts: hecate
  roles:
    - 01_common
    - 02_ssh
    - 08_docker
    - 09_nvidia_gpu
    - ...

While kuu.yml might look like:

- hosts: kuu
  roles:
    - 01_common
    - 02_ssh
    - 08_docker
    - 37_jellyfin
    - ...

This makes the configuration for each host explicit and easy to understand.

Consequences​

Positive:

  • Clarity and Readability: It is immediately obvious which roles are being applied to which host just by looking at the corresponding playbook file. There are no complex when conditions to parse.
  • Simplicity: This approach is much simpler to manage than a single playbook with a large number of conditionals. It's easy to add a new server type by just creating a new playbook file.
  • Flexibility: Allows us to have completely different role lists and orderings for different hosts, without affecting other hosts.

Negative:

  • Some Duplication: There will be some duplication of the common roles (like 01_common and 02_ssh) across all the playbook files.

Mitigation:

  • Acceptable Duplication: This small amount of duplication is a reasonable trade-off for the massive gain in clarity and simplicity. The list of common roles is very stable. We can also use Ansible's import_playbook feature to import a common.yml playbook into each host-specific playbook if we want to reduce this duplication in the future, but the current explicit approach is preferred for its clarity.