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.
Run a playbook on this machine
Section titled “Run a playbook on this machine”-
Create an inventory with one host, reached without SSH:
inventory.ini localhost ansible_connection=local -
Write a playbook:
site.yml - hosts: localhostgather_facts: falsetasks:- name: Who am I?command: id -unregister: me- name: Say hellodebug:msg: "Hello from {{ me.stdout }}" -
Run it.
volant playbooktakes the same arguments asansible-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=0Run 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, 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.
[web]web1 ansible_host=192.0.2.10 ansible_user=deploy- 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"volant playbook -i inventory.ini site.ymlYour ~/.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.
Your existing project
Section titled “Your existing project”Volant reads an Ansible project as it is. Run it from the project directory, or point -i at the inventory:
ansible.cfgis read from the same places as under Ansible, andANSIBLE_*variables apply. See Configuration.- Inventories in INI, YAML or script form, with
group_vars/andhost_vars/beside them, work without changes. See Inventories and Precedence and facts. - Vault-encrypted files and variables are decrypted when you pass
--ask-vault-passor a vault password file. See Vault. - Roles are found in
roles/and inroles_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.
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”- Will my playbook run? checks an existing project.
- What Volant leaves on your machines lists what it writes on the controller and the hosts.
- Running plays explains what happens between the first line and the recap.
- Command line lists every option.