# 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.

> Added 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