Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท Provisioning

Provisioning Overview

Understand Vagrant provisioners: what they are, when they run, the run options always and never, naming, ordering, idempotence and re-running them.

A bare box gives you an operating system. To get a working development environment you must also install packages, create users, copy configuration files, start services and load sample data. Doing that by hand defeats the purpose of Vagrant, so Vagrant has provisioners: configuration steps declared in the Vagrantfile and executed automatically inside the guest after it boots.

Vagrant includes provisioners for shell scripts, file copies, Ansible, Puppet, Chef, Salt, Docker, container hosts and more. In this lesson you learn the rules that apply to all of them: when they run, how to control that, how to name and order them, and how to write them so that running twice does no harm.

Declaring a provisioner

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

  config.vm.provision "shell", inline: "apt-get update"
  config.vm.provision "file", source: "app.conf", destination: "/tmp/app.conf"
  config.vm.provision "shell", path: "scripts/install-app.sh"
end

The first argument is the provisioner type (shell, file, ansible, puppet, docker...), followed by options. Provisioners run in the order they appear (and in load order across several Vagrantfiles, see load order). Each one runs inside the guest, usually over SSH, after the machine boots and shared folders are mounted.

flowchart LR
    A["vagrant up"] --> B["Boot VM"]
    B --> C["Mount synced folders"]
    C --> D["Provisioner 1"]
    D --> E["Provisioner 2"]
    E --> F["Provisioner 3"]
    F --> G["Machine ready"]

Provisioners run last, one after another, once the machine is reachable.

When do provisioners run?

This is the number one confusion. The default rules:

Situation Runs provisioners?
First vagrant up that creates the machine Yes
vagrant up on a halted existing machine No
vagrant reload No
vagrant up --provision or vagrant reload --provision Yes
vagrant provision on a running machine Yes
vagrant destroy then vagrant up Yes (new machine)

So if you edit your install script and just run vagrant up, nothing happens on an existing VM. Run vagrant provision (fast, no reboot) or vagrant reload --provision. Provisioning that never ran again is why "it works after destroy but not on my old machine".

Vagrant remembers whether a provisioner has already run in a file under .vagrant/machines/<name>/<provider>/action_provision; deleting it forces everything to run again, but --provision is the cleaner way.

Controlling when: run and name

Each provisioner can declare its own schedule:

Ruby
Vagrant.configure("2") do |config|
  config.vm.provision "install", type: "shell", inline: "apt-get install -y nginx"

  config.vm.provision "start-services", type: "shell", run: "always",
    inline: "systemctl start nginx"

  config.vm.provision "load-demo-data", type: "shell", run: "never",
    path: "scripts/demo-data.sh"
end
  • run: "once" (the default): first creation only (or with --provision).
  • run: "always": on every vagrant up, reload and provision. Good for starting services or mounting something that does not survive a reboot.
  • run: "never": only when asked explicitly.

Giving a provisioner a name (the first argument becomes the name when you also pass type:) lets you run it alone:

CONSOLE
$ vagrant provision --provision-with load-demo-data
$ vagrant up --provision-with install,start-services

Ordering across layers

Provisioners in the same Vagrantfile run in file order. With several layers (user file, project file, per-machine blocks) they are concatenated, which sometimes puts things in the wrong order. Use the before: and after: options (available in recent versions) to place a named provisioner relative to another:

Ruby
config.vm.provision "base-packages", type: "shell", inline: "apt-get update"
config.vm.provision "app", type: "shell", path: "scripts/app.sh"
config.vm.provision "hotfix", type: "shell", inline: "echo patch", before: "app"

Privilege, environment and failure

Shell-based provisioners run as root by default (through sudo). Set privileged: false to run as the vagrant user, which matters for tools that install into the home directory (version managers, user-level config). Provisioners that fail (non-zero exit status) stop the whole vagrant up:

CONSOLE
==> default: Running provisioner: install (shell)...
    default: E: Unable to locate package ngnix
The SSH command responded with a non-zero exit status.
Vagrant assumes that this means the command failed!

The machine is left running, so you can vagrant ssh, fix the problem, and run vagrant provision.

Write idempotent provisioners

Because provisioners may run more than once (--provision, run: "always"), each step should be idempotent: running it twice gives the same result as running it once. Compare:

Terminal
# Not idempotent: appends the line every time
echo "export PATH=\$PATH:/opt/app/bin" >> /etc/profile

# Idempotent: adds it only when missing
grep -q "/opt/app/bin" /etc/profile || echo "export PATH=\$PATH:/opt/app/bin" >> /etc/profile

Package installers (apt-get install -y), mkdir -p and ln -sf are naturally idempotent. Configuration management tools such as Ansible, Puppet and Chef, see Config management provisioners, are built around exactly this idea: you declare the desired state and the tool changes only what differs. For Ansible specifically, the Ansible tutorial goes deep.

Try the scheduling rules

The runnable stand-in below models the run: option and the --provision flag, so you can predict what each command would execute. It is Ruby, not Vagrant.

Ruby Which provisioners would run? (stand-in)

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.

(In real Vagrant, --provision also re-runs run: "never" provisioners only when named; the model follows that rule.)

Debugging provisioning

  • Read the output carefully: it prints the provisioner name before each step.
  • Run vagrant provision repeatedly while you develop a script; you do not need to reboot.
  • Use set -euxo pipefail at the top of shell scripts so that errors stop early and every command is echoed.
  • For long installs add config.vm.boot_timeout only for boot; provisioners themselves have no timeout.
  • vagrant up --no-provision skips provisioning on a first boot, useful when you only need the bare machine.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You edited your install script and ran vagrant up on an existing, halted machine. What happens to the script?

    By default provisioners run only on the first creation, or when you explicitly ask with --provision or vagrant provision.
  2. 2. Which option makes a provisioner run on every vagrant up?

    run: "always" is for steps such as starting services after each boot.
  3. 3. What does it mean for a provisioning step to be idempotent?

    Idempotent steps are safe to repeat, which is essential because provisioners may run again.
  4. 4. What happens when a shell provisioner exits with a non-zero status?

    Vagrant treats failure as fatal; the machine stays up so you can investigate and re-run provisioning.

Summary

  • Provisioners configure the guest after boot; they run in file and load order.
  • By default they run only at first creation or when you pass --provision / run vagrant provision.
  • run: "always", run: "never" and names (--provision-with) control scheduling.
  • Shell provisioners run as root unless privileged: false; a failing step stops vagrant up.
  • Write steps idempotently, or use a configuration management tool.

Next: The Shell Provisioner