salt.states.vagrant

Manage Vagrant VMs

Manange execution of Vagrant virtual machines on Salt minions.

Vagrant is a tool for building and managing virtual machine environments. It can use various providers, such as VirtualBox, Docker, or VMware, to run its VMs. Vagrant provides some of the functionality of a light-weight hypervisor. The combination of Salt modules, Vagrant running on the host, and a virtual machine provider, gives hypervisor-like functionality for developers who use Vagrant to quickly define their virtual environments.

New in version 2018.3.0.

The configuration of each virtual machine is defined in a file named Vagrantfile which must exist on the VM host machine. The essential parameters which must be defined to start a Vagrant VM are the directory where the Vagrantfile is located (argument cwd:), and the username which will own the Vagrant box created for the VM ( argument vagrant_runas:).

A single Vagrantfile may define one or more virtual machines. Use the machine argument to chose among them. The default (blank) value will select the primary (or only) machine in the Vagrantfile.

[NOTE:] Each virtual machine host must have the following:

  • a working salt-minion
  • a Salt sdb database configured for vagrant_sdb_data.
  • Vagrant installed and the vagrant command working
  • a suitable VM provider
# EXAMPLE:
# file /etc/salt/minion.d/vagrant_sdb.conf on the host computer
#  -- this sdb database is required by the Vagrant module --
vagrant_sdb_data:  # The sdb database must have this name.
  driver: sqlite3  # Let's use SQLite to store the data ...
  database: /var/cache/salt/vagrant.sqlite  # ... in this file ...
  table: sdb  # ... using this table name.
  create_table: True  # if not present
salt.states.vagrant.destroyed(name)

Stops a VM (or VMs) and removes all references to it (them). (Runs vagrant destroy.)

Subsequent re-use of the same machine will requere another operation of vagrant.running or a call to the vagrant.init execution module.

Parameters:name -- May be a Salt_id node or a POSIX-style wildcard string.
node_name:
  vagrant.destroyed
salt.states.vagrant.initialized(name, **kwargs)

Defines a new VM with specified arguments, but does not start it.

Parameters:name -- the Salt_id node name you wish your VM to have.

Each machine must be initialized individually using this function or the "vagrant.running" function, or the vagrant.init execution module call.

This command will not change the state of a running or paused machine.

Possible keyword arguments:

  • cwd: The directory (path) containing the Vagrantfile
  • machine: ('') the name of the machine (in the Vagrantfile) if not default
  • vagrant_runas: ('root') the username who owns the vagrantbox file
  • vagrant_provider: the provider to run the VM (usually 'virtualbox')
  • vm: ({}) a dictionary containing these or other keyword arguments
node_name1:
  vagrant.initialized
    - cwd: /projects/my_project
    - vagrant_runas: my_username
    - machine: machine1

node_name2:
  vagrant.initialized
    - cwd: /projects/my_project
    - vagrant_runas: my_username
    - machine: machine2

start_nodes:
  vagrant.start:
    - name: node_name?
salt.states.vagrant.paused(name)

Stores the state of a VM (or VMs) for fast restart. (Runs vagrant suspend.)

Parameters:name -- May be a Salt_id node or a POSIX-style wildcard string.
node_name:
  vagrant.paused
salt.states.vagrant.powered_off(name)

Stops a VM (or VMs) by power off. (Runs vagrant halt.)

This method is provided for compatibility with other VM-control state modules. For Vagrant, the action is identical with stopped.

Parameters:name -- May be a Salt_id node or a POSIX-style wildcard string.
node_name:
  vagrant.unpowered
salt.states.vagrant.rebooted(name)

Reboots a running, paused, or stopped VM (or VMs). (Runs vagrant reload.)

The will re-run the provisioning

Parameters:name -- May be a Salt_id node or a POSIX-style wildcard string.
node_name:
  vagrant.reloaded
salt.states.vagrant.running(name, **kwargs)

Defines and starts a new VM with specified arguments, or restart a VM (or group of VMs). (Runs vagrant up.)

Parameters:name -- the Salt_id node name you wish your VM to have.

If name contains a "?" or "*" then it will re-start a group of VMs which have been paused or stopped.

Each machine must be initially started individually using this function or the vagrant.init execution module call.

[NOTE:] Keyword arguments are silently ignored when re-starting an existing VM.

Possible keyword arguments:

  • cwd: The directory (path) containing the Vagrantfile
  • machine: ('') the name of the machine (in the Vagrantfile) if not default
  • vagrant_runas: ('root') the username who owns the vagrantbox file
  • vagrant_provider: the provider to run the VM (usually 'virtualbox')
  • vm: ({}) a dictionary containing these or other keyword arguments
node_name:
  vagrant.running
node_name:
  vagrant.running:
    - cwd: /projects/my_project
    - vagrant_runas: my_username
    - machine: machine1
salt.states.vagrant.stopped(name)

Stops a VM (or VMs) by shutting it (them) down nicely. (Runs vagrant halt)

Parameters:name -- May be a Salt_id node, or a POSIX-style wildcard string.
node_name:
  vagrant.stopped