Skip to content
Install

Quickstart

Run a first playbook on your own machine, then on a remote host over SSH.

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

  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

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, a small program of about 1.2 MB, with the first task and keeps it in ~/.ansible/tmp on the host 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. A key file or an ssh-agent is the simplest way to log in. To use a password, pass -k or set ansible_password.

Volant reads an Ansible project as it is. Run it from the project directory, or point -i at the inventory:

  • ansible.cfg is read from the same places as under Ansible, and ANSIBLE_* variables apply. See Configuration.
  • Inventories in INI, YAML or script form, with group_vars/ and host_vars/ beside them, work without changes. See Inventories and Precedence and facts.
  • Vault-encrypted files and variables are decrypted when you pass --ask-vault-pass or a vault password file. See Vault.
  • Roles are found in roles/ and in roles_path, with their defaults, handlers and dependencies. See Roles, includes and imports.
  • Collections work once they are installed with volant runtime install --collections.

Before the first real run, check what this release cannot do with Will my playbook run?. It reads the playbook and lists what a run would do without connecting to anything.

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