RackPeek/Shared.Rcl/wwwroot/raw_docs/ansible-generator-guide.md

Ansible Inventory Generator User Guide

RackPeek can generate production-ready Ansible inventory directly from your modeled infrastructure.

---

1. Making a Resource Ansible-Ready

A resource becomes an Ansible host when it has an address label.

Required Label

At minimum, set:

labels:
  ansible_host: 192.168.1.10

Without this, the resource will not appear in inventory.

RackPeek will also accept these alternatives if ansible_host is not provided:

Label	Used As
ip	ansible_host
hostname	ansible_host

Example:

labels:
  ip: 192.168.1.10

---

2. Standard Ansible Labels

RackPeek automatically exports any label beginning with ansible_ as an Ansible host variable.

Example:

labels:
  ansible_host: 192.168.1.10
  ansible_user: ubuntu
  ansible_port: 22
  ansible_ssh_private_key_file: ~/.ssh/id_rsa

What these do

Label	Purpose
ansible_host	IP or DNS target
ansible_user	SSH user
ansible_port	SSH port
ansible_ssh_private_key_file	SSH key

These variables appear directly in the generated inventory.

---

3. Custom Host Variables (ansible_var_*)

RackPeek supports exposing custom variables to Ansible playbooks using the label prefix:

ansible_var_

The prefix is removed when generating inventory.

Example

labels:
  ansible_host: 10.0.0.10
  ansible_var_mac: 52:54:00:11:22:33
  ansible_var_rack: rack01

Generated inventory:

cerberus-0:
  ansible_host: 10.0.0.10
  mac: 52:54:00:11:22:33
  rack: rack01

This allows RackPeek to remain the source of truth for infrastructure metadata while making the data available to playbooks.

Example Playbook Usage

- hosts: all
  gather_facts: false

  tasks:
    - name: Copy ignition file
      ansible.builtin.copy:
        src: "output/{{ inventory_hostname }}.ign"
        dest: "/srv/ignition/{{ mac }}.ign"

---

4. Using Tags for Grouping

Tags are simple grouping mechanisms.

Example:

tags:
- prod
- web
- ansible

If you generate inventory with:

--group-tags prod,web

You will get:

[prod]
vm-web01 ...

[web]
vm-web01 ...

---

5. Using Labels for Structured Groups

Labels allow structured grouping.

Example:

labels:
  env: prod
  role: database

Generating with:

--group-labels env,role

Produces:

[env_prod]
vm-db01 ...

[role_database]
vm-db01 ...

This is cleaner and more scalable than raw tags.

---

6. Example Resource

- kind: System
  type: vm
  os: ubuntu-22.04
  cores: 4
  ram: 8
  name: vm-web01

  tags:
  - prod
  - web

  labels:
    ansible_host: 192.168.1.10
    ansible_user: ubuntu
    ansible_var_mac: 52:54:00:11:22:33
    env: prod
    role: web

---

7. Generating Inventory

CLI

rpk ansible inventory \
  --group-tags prod,web \
  --group-labels env,role \
  --global-var ansible_user=ansible \
  --global-var ansible_python_interpreter=/usr/bin/python3

Web UI

Navigate to:

/ansible/inventory

Set:

• Group By Tags
• Group By Labels
• Global Variables

Click Generate.

---

8. Example Generated Inventory

[all:vars]
ansible_python_interpreter=/usr/bin/python3
ansible_user=ansible

[env_prod]
vm-web01 ansible_host=192.168.1.10 ansible_user=ubuntu mac=52:54:00:11:22:33

[role_web]
vm-web01 ansible_host=192.168.1.10 ansible_user=ubuntu mac=52:54:00:11:22:33

[prod]
vm-web01 ansible_host=192.168.1.10 ansible_user=ubuntu mac=52:54:00:11:22:33

---

9. Writing Playbooks Against RackPeek Inventory

Example 1 – Ping Production

- name: Test production connectivity
  hosts: env_prod
  gather_facts: false

  tasks:
    - name: Ping hosts
      ansible.builtin.ping:

Run:

ansible-playbook -i inventory.ini ping.yml

---

Example 2 – Deploy Web Servers

- name: Configure web servers
  hosts: role_web
  become: true

  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true

    - name: Ensure nginx running
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

---

Example 3 – Database Setup

- name: Configure database servers
  hosts: role_database
  become: true

  tasks:
    - name: Install PostgreSQL
      ansible.builtin.apt:
        name: postgresql
        state: present
        update_cache: true

---

10. Best Practices

1. Use Labels for Structure

Prefer:

env: prod
role: web

Over raw tags when designing larger infrastructure.

---

2. Use ansible_var_* for Infrastructure Metadata

Examples:

ansible_var_mac
ansible_var_rack
ansible_var_datacenter
ansible_var_vlan

This allows playbooks to reference infrastructure information without duplicating configuration.

---

3. Keep Global Vars Minimal

Use:

[all:vars]
ansible_user=ansible
ansible_python_interpreter=/usr/bin/python3

Override per host only when needed.

---

4. Separate Infrastructure and Services

Model:

• Systems → Ansible hosts
• Services → Applications running on systems

Deploy against systems, not services.

---

5. Keep Inventory Deterministic

Avoid:

• Missing ansible_host
• Mixed case group names
• Unstructured tags

---

11. Advanced Pattern (Recommended)

Use both:

• env
• role

Then your structure becomes:

env_prod
env_staging
role_web
role_database

This allows extremely flexible play targeting:

ansible-playbook site.yml -l env_prod
ansible-playbook site.yml -l role_web
ansible-playbook site.yml -l env_prod:&role_web

---

12. Summary

To use RackPeek effectively with Ansible:

1. Add ansible_host label
2. Add env and role labels
3. Optionally add tags
4. Use ansible_var_* for custom host variables
5. Generate inventory
6. Write playbooks targeting groups