Skip to content
Volant

Quickstart

This page assumes volant is on your PATH. If it is not, start with Installation.

Run a playbook on this machine

Section titled “Run a playbook on this machine”

  1. Create an inventory with one host, reached without SSH:

    inventory.ini
    localhost ansible_connection=local

  2. Write a playbook:

    site.yml
    - hosts: localhost
      gather_facts: false
      tasks:
        - name: Who am I?
          command: id -un
          register: me
    

        - name: Say hello
          debug:
            msg: "Hello from {{ me.stdout }}"

  3. Run it. volant playbook takes the same arguments as ansible-playbook:

    Terminal window
    volant playbook -i inventory.ini site.yml

The output is the one you know from Ansible:

PLAY [localhost] ***************************************************************


TASK [Who am I?] ***************************************************************
changed: [localhost]


TASK [Say hello] ***************************************************************
ok: [localhost] => {
    "msg": "Hello from alice"
}


PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Run it on a remote host

Section titled “Run it on a remote host”

The host needs an SSH server and an account you can log into with a key. It does not need Volant: the controller uploads its agent with the first task and keeps it there for the next run.

inventory.ini
[web]
web1 ansible_host=192.0.2.10 ansible_user=deploy
site.yml
- hosts: web
  tasks:
    - name: Show the distribution
      debug:
        msg: "{{ ansible_distribution }} {{ ansible_distribution_version }}"


    - name: Make sure the release directory exists
      become: true
      file:
        path: /srv/app
        state: directory
        mode: "0755"
Terminal window
volant playbook -i inventory.ini site.yml

Your ~/.ssh/config applies, because Volant runs the ssh you already have. Volant never prompts for an SSH password: use a key file or an ssh-agent.

Look before you run

Section titled “Look before you run”

The listing commands read the playbook and print what a run would do, without connecting to anything:

Terminal window
volant playbook -i inventory.ini site.yml --list-hosts
volant playbook -i inventory.ini site.yml --list-tasks
volant playbook -i inventory.ini site.yml --syntax-check

A project layout that works

Section titled “A project layout that works”

Volant finds roles, group_vars and host_vars where Ansible finds them:

  • ansible.cfg
  • inventory.ini
  • site.yml
  • Directorygroup_vars/
    • all.yml
    • web.yml
  • Directoryhost_vars/
    • web1.yml
  • Directoryroles/
    • Directorynginx/
      • defaults/main.yml
      • handlers/main.yml
      • tasks/main.yml

Next steps

Section titled “Next steps”