Vagrant is able to define and control multiple guest machines per Vagrantfile. This is known as a "multi-machine" environment.
These machines are generally able to work together or are somehow associated with each other. Here are some use-cases people are using multi-machine environments for today:
- Accurately modeling a multi-server production topology, such as separating a web and database server.
- Modeling a distributed system and how they interact with each other.
- Testing an interface, such as an API to a service component.
- Disaster-case testing: machines dying, network partitions, slow networks, inconsistent world views, etc.
Historically, running complex environments such as these was done by flattening them onto a single machine. The problem with that is that it is an inaccurate model of the production setup, which can behave far differently.
Using the multi-machine feature of Vagrant, these environments can be modeled in the context of a single Vagrant environment without losing any of the benefits of Vagrant.
Defining Multiple Machines
Multiple machines are defined within the same project Vagrantfile using the
config.vm.define method call. This configuration directive is a little funny, because it creates a Vagrant configuration within a configuration. An example shows this best:
Vagrant.configure("2") do |config| config.vm.provision "shell", inline: "echo Hello" config.vm.define "web" do |web| web.vm.box = "apache" end config.vm.define "db" do |db| db.vm.box = "mysql" end end
As you can see,
config.vm.define takes a block with another variable. This variable, such as
web above, is the exact same as the
config variable, except any configuration of the inner variable applies only to the machine being defined. Therefore, any configuration on
web will only affect the
And importantly, you can continue to use the
config object as well. The configuration object is loaded and merged before the machine-specific configuration, just like other Vagrantfiles within the Vagrantfile load order.
If you're familiar with programming, this is similar to how languages have different variable scopes.
When using these scopes, order of execution for things such as provisioners becomes important. Vagrant enforces ordering outside-in, in the order listed in the Vagrnatfile. For example, with the Vagrantfile below:
Vagrant.configure("2") do |config| config.vm.provision :shell, inline: 'echo A' config.vm.define :testing do |test| test.vm.provision :shell, inline: 'echo B' end config.vm.provision :shell, inline: 'echo C' end
The provisioners in this case will output "A", then "C", then "B". Notice that "B" is last. That is because the ordering is outside-in, in the order of the file.
Controlling Multiple Machines
The moment more than one machine is defined within a Vagrantfile, the usage of the various
vagrant commands changes slightly. The change should be mostly intuitive.
Commands that only make sense to target a single machine, such as
vagrant ssh, now require the name of the machine to control. Using the example above, you would say
vagrant ssh web or
vagrant ssh db.
Other commands, such as
vagrant up, operate on every machine by default. So if you ran
vagrant up, Vagrant would bring up both the web and DB machine. You could also optionally be specific and say
vagrant up web or
vagrant up db.
Additionally, you can specify a regular expression for matching only certain machines. This is useful in some cases where you specify many similar machines, for example if you're testing a distributed service you may have a
leader machine as well as a
follower2, etc. If you want to bring up all the followers but not the leader, you can just do
vagrant up /follower[0-9]/. If Vagrant sees a machine name within forward slashes, it assumes you're using a regular expression.
Communication Between Machines
In order to facilitate communication within machines in a multi-machine setup, the various networking options should be used. In particular, the private network can be used to make a private network between multiple machines and the host.
Specifying a Primary Machine
You can also specify a primary machine. The primary machine will be the default machine used when a specific machine in a multi-machine environment is not specified.
To specify a default machine, just mark it primary when defining it. Only one primary machine may be specified.
config.vm.define "web", primary: true do |web| # ... end
By default in a multi-machine environment,
vagrant up will start all of the defined machines. The
autostart setting allows you to tell Vagrant to not start specific machines. Example:
config.vm.define "web" config.vm.define "db" config.vm.define "db_follower", autostart: false
vagrant up with the settings above, Vagrant will automatically start the "web" and "db" machines, but will not start the "db_follower" machine. You can manually force the "db_follower" machine to start by running
vagrant up db_follower.