Getting started

instamix lets you develop Ansible playbooks from a single Python script. Instead of editing a directory full of small YAML files, you edit one script, and either dump the playbook repo or run it outright.

Install#

instamix needs Python 3.9 or newer, click and glom.

$ pip install -e .
$ imix init site.py     # a starter script
$ imix import ./old-playbooks -o site.py   # or absorb what you have

Ansible itself comes from your PATH, or from an environment that instamix builds for the script: see Requirements and environments.

A first script#

# site.py
from instamix import file

file("site.yml", """
- hosts: localhost
  become: true
  tasks:
    - debug:
        msg: "Helloworld!"
""")

$ python site.py run
PLAY [localhost] ***************************************************************
TASK [debug] *******************************************************************
ok: [localhost] => {
    "msg": "Helloworld!"
}

Unless you declare your own, an inventory (localhost ansible_connection=local) and a minimal ansible.cfg are added, so the result runs as it is.

Every script is its own CLI#

python site.py run ran the playbook. The same script lists its files, prints them, writes them out, and says what would change:

$ python site.py show            # the files the script declares (the default)
$ python site.py cat site.yml    # their contents
$ python site.py generate out    # write the playbook directory
$ python site.py diff out        # what generate would change

imix SCRIPT ... does the same for a script that imports nothing: scripts run through the imix command are executed in a namespace instamix controls, and need no imports at all.

All of them are in the reference: the commands of a script and the imix command.

Where to go from here#

• Declaring files: what file() does, and how a tree is written out or absorbed.
• Structure helpers: roles, collections, inventory and variables without the directories.
• Describing a script: groups, variables with a shape, tags, and stages that run alone.
• Examples: scripts to read, from a hello world to a k3s cluster with applications on it.