Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Multi-machine Environments

Multi-machine Vagrantfiles

Define several virtual machines in one Vagrantfile with config.vm.define, target them by name, and control startup order, primary and autostart machines.

Real applications rarely live on one server. A web server talks to a database, a cache sits beside it, and a load balancer stands in front. Vagrant lets you describe all of these machines in a single Vagrantfile, so one vagrant up builds the whole environment on your laptop.

This lesson shows how to declare several machines, how to address each one from the command line, and how Vagrant decides which machines to start when you give it no name.

Declaring machines with config.vm.define

Inside Vagrant.configure, every call to config.vm.define creates one named machine. The block receives a machine-specific config object, which accepts the same settings as the top-level config.

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"

  config.vm.define "web" do |web|
    web.vm.hostname = "web"
    web.vm.network "private_network", ip: "192.168.56.10"
  end

  config.vm.define "db" do |db|
    db.vm.hostname = "db"
    db.vm.network "private_network", ip: "192.168.56.11"
    db.vm.box = "ubuntu/focal64"
  end
end

Settings placed outside a define block apply to every machine. Settings inside the block apply to that machine only and override the outer value. Here both machines start from ubuntu/jammy64, except db, which switches to a different box.

Name machines with simple identifiers such as web, db or cache. The name is what you type on the command line, and it also becomes the machine's directory under .vagrant/machines/.

Targeting machines from the command line

Almost every Vagrant command accepts an optional machine name. Without a name, the command applies to all machines (or, for ssh, to the only one).

TEXT
$ vagrant status
Current machine states:

web                       not created (virtualbox)
db                        not created (virtualbox)

$ vagrant up web          # start only the web machine
$ vagrant ssh db          # open a shell in db
$ vagrant halt            # stop every machine
$ vagrant destroy -f db   # delete only db

You can also pass a regular expression between slashes: vagrant up /web.*/ starts every machine whose name starts with web. This is handy once you have web1, web2 and web3.

If you run vagrant ssh in a multi-machine project without a name, Vagrant stops with an error that lists the machine names, unless you marked one machine as primary.

Primary and autostart machines

Two options on define change what plain commands do.

Ruby
config.vm.define "web", primary: true do |web|
  # vagrant ssh (no name) lands here
end

config.vm.define "worker", autostart: false do |worker|
  # vagrant up (no name) skips this machine
end
  • primary: true marks the machine that vagrant ssh, vagrant ssh-config and similar commands use when you give no name.
  • autostart: false keeps a machine out of a bare vagrant up. You start it explicitly with vagrant up worker. Use this for heavy or rarely needed machines, such as a staging database copy or a test client.

Machines are brought up in the order they are defined, one after another. Vagrant does not know that web needs db to be ready, so if order matters, define db first. The next lesson covers talking between machines.

A stand-in: how Vagrant resolves which machines to start

Vagrant is not available in your browser, so this Ruby stand-in imitates the part of the DSL that matters here. It is not Vagrant itself, only a small model of how define, primary and autostart behave.

Ruby Mini multi-machine DSL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Notice that worker inherits the global box because the nested config copies it at the moment define is called. That is also why you should set the shared config.vm.box before the first define.

Shared settings with a common section

Because outer settings flow into every machine, put anything common there: the box, memory, synced folders and provisioning that every machine needs.

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  config.vm.synced_folder ".", "/vagrant", disabled: true

  config.vm.provider "virtualbox" do |vb|
    vb.memory = 1024
    vb.cpus = 1
  end

  config.vm.define "web" do |web|
    web.vm.provider "virtualbox" do |vb|
      vb.memory = 2048          # only web gets more memory
    end
  end

  config.vm.define "db"
end

A define without a block is allowed: it creates a machine that uses only the shared settings.

Common mistakes

  • Forgetting -f in scripts. vagrant destroy asks for confirmation for each machine; add -f in automation.
  • Duplicate private IPs. Two machines with the same address on the same host-only network will fight. Give each a unique address.
  • Putting config.vm.box after the defines. The inner blocks have already copied the old value.
  • Relying on definition order for readiness. Order controls when machines are created, not when the services inside them are listening.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do settings go if every machine in a multi-machine Vagrantfile should use them?

    Settings on the top-level config apply to all machines. A define block can still override them for one machine.
  2. 2. What does autostart: false do?

    An autostart: false machine is only created when you name it, as in vagrant up worker.
  3. 3. You run vagrant ssh with no name in a project with web and db. No machine is primary. What happens?

    With several machines and no primary, Vagrant cannot guess, so it asks you to name one.
  4. 4. How do you start all machines whose names begin with web?

    A name between slashes is treated as a regular expression.

Summary

  • config.vm.define "name" creates one machine; settings outside it are shared, inside it are machine-specific.
  • Commands accept a machine name or a /regex/; with no name they act on all machines.
  • primary: true picks the default target for vagrant ssh; autostart: false removes a machine from bare vagrant up.
  • Machines are created in definition order, which does not guarantee service readiness.

Next: Networking between machines