salt.modules.vagrant

Work with virtual machines managed by Vagrant.

Mapping between a Salt node id and the Vagrant machine name (and the path to the Vagrantfile where it is defined) is stored in a Salt sdb database on the Vagrant host (minion) machine. In order to use this module, sdb must be configured. An SQLite database is the recommended storage method. The URI used for the sdb lookup is "sdb://vagrant_sdb_data".

requirements:

• the VM host machine must have salt-minion, Vagrant and a vm provider installed.

• the VM host must have a valid definition for sdb://vagrant_sdb_data

Configuration example:

# file /etc/salt/minion.d/vagrant_sdb.conf
vagrant_sdb_data:
  driver: sqlite3
  database: /var/cache/salt/vagrant.sqlite
  table: sdb
  create_table: True

salt.modules.vagrant.destroy(name)

Destroy and delete a virtual machine. (vagrant destroy -f)

This also removes the salt_id name defined by vagrant.init.

CLI Example:

salt <host> vagrant.destroy <salt_id>

salt.modules.vagrant.get_machine_id(machine, cwd)

returns the salt_id name of the Vagrant VM

Parameters

• machine -- the Vagrant machine name

• cwd -- the path to Vagrantfile

Returns

salt_id name

salt.modules.vagrant.get_ssh_config(name, network_mask='', get_private_key=False)

Retrieve hints of how you might connect to a Vagrant VM.

Parameters

• name -- the salt_id of the machine

• network_mask -- a CIDR mask to search for the VM's address

• get_private_key -- (default: False) return the key used for ssh login

Returns

a dict of ssh login information for the VM

CLI Example:

salt <host> vagrant.get_ssh_config <salt_id>
salt my_laptop vagrant.get_ssh_config quail1 network_mask=10.0.0.0/8 get_private_key=True

The returned dictionary contains:

• key_filename: the name of the private key file on the VM host computer

• ssh_username: the username to be used to log in to the VM

• ssh_host: the IP address used to log in to the VM. (This will usually be 127.0.0.1)

• ssh_port: the TCP port used to log in to the VM. (This will often be 2222)

• [ip_address:] (if network_mask is defined. see below)

• [private_key:] (if get_private_key is True) the private key for ssh_username

About network_mask:

Vagrant usually uses a redirected TCP port on its host computer to log in to a VM using ssh. This redirected port and its IP address are "ssh_port" and "ssh_host". The ssh_host is usually the localhost (127.0.0.1). This makes it impossible for a third machine (such as a salt-cloud master) to contact the VM unless the VM has another network interface defined. You will usually want a bridged network defined by having a config.vm.network "public_network" statement in your Vagrantfile.

The IP address of the bridged adapter will typically be assigned by DHCP and unknown to you, but you should be able to determine what IP network the address will be chosen from. If you enter a CIDR network mask, Salt will attempt to find the VM's address for you. The host machine will send an "ifconfig" command to the VM (using ssh to ssh_host:ssh_port) and return the IP address of the first interface it can find which matches your mask.

salt.modules.vagrant.get_vm_info(name)

get the information for a VM.

Parameters

name -- salt_id name

Returns

dictionary of {'machine': x, 'cwd': y, ...}.

salt.modules.vagrant.init(name, cwd=None, machine='', runas=None, start=False, vagrant_provider='', vm=None)

Initialize a new Vagrant VM.

This inputs all the information needed to start a Vagrant VM. These settings are stored in a Salt sdb database on the Vagrant host minion and used to start, control, and query the guest VMs. The salt_id assigned here is the key field for that database and must be unique.

Parameters

• name -- The salt_id name you will use to control this VM

• cwd -- The path to the directory where the Vagrantfile is located

• machine -- The machine name in the Vagrantfile. If blank, the primary machine will be used.

• runas -- The username on the host who owns the Vagrant work files.

• start -- (default: False) Start the virtual machine now.

• vagrant_provider -- The name of a Vagrant VM provider (if not the default).

• vm -- Optionally, all the above information may be supplied in this dictionary.

Returns

A string indicating success, or False.

CLI Example:

salt <host> vagrant.init <salt_id> /path/to/Vagrantfile
salt my_laptop vagrant.init x1 /projects/bevy_master machine=quail1

salt.modules.vagrant.list_active_vms(cwd=None)

Return a list of machine names for active virtual machine on the host, which are defined in the Vagrantfile at the indicated path.

CLI Example:

salt '*' vagrant.list_active_vms  cwd=/projects/project_1

salt.modules.vagrant.list_domains()

Return a list of the salt_id names of all available Vagrant VMs on this host without regard to the path where they are defined.

CLI Example:

salt '*' vagrant.list_domains --log-level=info

The log shows information about all known Vagrant environments on this machine. This data is cached and may not be completely up-to-date.

salt.modules.vagrant.list_inactive_vms(cwd=None)

Return a list of machine names for inactive virtual machine on the host, which are defined in the Vagrantfile at the indicated path.

CLI Example:

salt '*' virt.list_inactive_vms cwd=/projects/project_1

salt.modules.vagrant.pause(name)

Pause (vagrant suspend) the named VM.

CLI Example:

salt <host> vagrant.pause <salt_id>

salt.modules.vagrant.reboot(name, provision=False)

Reboot a VM. (vagrant reload)

CLI Example:

salt <host> vagrant.reboot <salt_id> provision=True

Parameters

• name -- The salt_id name you will use to control this VM

• provision -- (False) also re-run the Vagrant provisioning scripts.

salt.modules.vagrant.shutdown(name)

Send a soft shutdown (vagrant halt) signal to the named vm.

This does the same thing as vagrant.stop. Other-VM control modules use "stop" and "shutdown" to differentiate between hard and soft shutdowns.

CLI Example:

salt <host> vagrant.shutdown <salt_id>

salt.modules.vagrant.start(name)

Start (vagrant up) a virtual machine defined by salt_id name. The machine must have been previously defined using "vagrant.init".

CLI Example:

salt <host> vagrant.start <salt_id>

salt.modules.vagrant.stop(name)

Hard shutdown the virtual machine. (vagrant halt)

CLI Example:

salt <host> vagrant.stop <salt_id>

salt.modules.vagrant.version()

Return the version of Vagrant on the minion

CLI Example:

salt '*' vagrant.version

salt.modules.vagrant.vm_state(name='', cwd=None)

Return list of information for all the vms indicating their state.

If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs defined by the Vagrantfile in the cwd directory.

CLI Example:

salt '*' vagrant.vm_state <name>  cwd=/projects/project_1

returns a list of dictionaries with machine name, state, provider, and salt_id name.

datum = {'machine': _, # Vagrant machine name,
         'state': _, # string indicating machine state, like 'running'
         'provider': _, # the Vagrant VM provider
         'name': _} # salt_id name

Known bug: if there are multiple machines in your Vagrantfile, and you request the status of the primary machine, which you defined by leaving the machine parameter blank, then you may receive the status of all of them. Please specify the actual machine name for each VM if there are more than one.