Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 36 ยท Provisioning

Ansible, Puppet, Chef and Docker Provisioners

Provision Vagrant machines with Ansible, ansible_local, Puppet, Chef and the Docker provisioner: configuration, inventories, idempotence and when to use each.

Shell scripts get unwieldy once a machine needs a dozen packages, templated configuration files, users, services and a database. Configuration management tools solve that by letting you describe the desired state ("package nginx is installed, this file has this content, service nginx is running") and by changing only what differs. Vagrant integrates the main ones as provisioners, so the same tool that configures your production servers can configure your development machine. Vagrant has built-in support for Ansible, Puppet, Chef and Salt, plus a Docker provisioner that installs Docker and starts containers.

Desired state: why it beats scripts

flowchart LR
    D["Desired state (playbook, manifest, recipe)"] --> T["Tool compares"]
    C["Current state of the guest"] --> T
    T --> A["Changes only what differs"]
    A --> R["Guest matches desired state"]

The tool reads the guest, compares it with the declaration and applies the difference. A second run changes nothing.

The stand-in below is a small Ruby model of this loop. It is not any real tool, but it shows why declarative provisioning is idempotent by construction: the tool computes the difference first.

Ruby Converging to a desired state (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.

Ansible

Ansible is the most popular choice with Vagrant because it needs no agent in the guest, only SSH and Python, and its playbooks are readable YAML. There are two variants.

ansible runs Ansible on the host. Vagrant generates an inventory with the machine's SSH details and calls ansible-playbook:

Ruby
config.vm.provision "ansible" do |ansible|
  ansible.playbook = "provisioning/site.yml"
  ansible.compatibility_mode = "2.0"
  ansible.extra_vars = { app_env: "development" }
  ansible.groups = { "web" => ["default"] }
end

ansible_local installs Ansible inside the guest and runs the playbook there. This is the right choice when the host cannot run Ansible, which means Windows without WSL:

Ruby
config.vm.provision "ansible_local" do |ansible|
  ansible.playbook = "provisioning/site.yml"
  ansible.install_mode = "default"       # install Ansible with the system package manager
end

A minimal playbook that matches both:

YAML
- hosts: all
  become: true
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true
    - name: Make sure nginx is running
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

Useful options are ansible.playbook, ansible.inventory_path, ansible.groups, ansible.extra_vars, ansible.tags, ansible.limit, ansible.verbose = "vv", ansible.galaxy_role_file and ansible.galaxy_roles_path. Use the same playbooks later against real servers; development then tests your automation. For the Ansible language itself, see the Ansible tutorial.

Puppet

Puppet describes resources in a manifest. Vagrant can run puppet apply (masterless) in the guest:

Ruby
config.vm.provision "puppet" do |puppet|
  puppet.manifests_path = "puppet/manifests"
  puppet.manifest_file = "default.pp"
  puppet.module_path = "puppet/modules"
  puppet.facter = { "environment" => "dev" }
end
PUPPET
package { 'nginx': ensure => installed }
service { 'nginx':
  ensure  => running,
  enable  => true,
  require => Package['nginx'],
}

The box must have Puppet installed, or you install it first with a shell provisioner. There is also puppet_server for talking to a Puppet master.

Chef

Chef uses Ruby recipes. Vagrant supports chef_solo, chef_zero, chef_client and chef_apply:

Ruby
config.vm.provision "chef_solo" do |chef|
  chef.cookbooks_path = "cookbooks"
  chef.add_recipe "shop::default"
  chef.arguments = "--chef-license accept"
  chef.json = { "shop" => { "env" => "development" } }
end

chef_zero starts an in-memory Chef server and is the usual choice for testing cookbooks. Because recipes are Ruby, Chef users find the Vagrantfile very natural.

Salt and others

Vagrant also ships a salt provisioner (masterless minion) and, through plugins, support for tools such as vagrant-hostmanager or Terraform-driven setups. If your company standardizes on another tool, a shell provisioner can bootstrap it.

The Docker provisioner

The docker provisioner installs Docker in the guest and can pull images and start containers, so you get a Docker host with no manual steps:

Ruby
config.vm.provision "docker" do |d|
  d.pull_images "redis:7"
  d.run "redis", image: "redis:7", args: "-p 6379:6379 --restart=always"
  d.run "web", image: "nginx:stable", args: "-p 8080:80 -v /vagrant/public:/usr/share/nginx/html:ro"
end

After vagrant up the containers run in the VM and the forwarded ports work as for any service. This is a good way to test a Compose or Docker setup on a full Linux host, or to give a Windows or macOS user a real Linux Docker daemon. See the Docker tutorial and Docker vs Virtual Machines for the container side.

Choosing a provisioner

Need Good choice
Few commands, quick prototype Shell
Production already uses Ansible ansible (or ansible_local on Windows)
Existing Puppet or Chef code base puppet or chef_*
An application in containers docker
Testing roles on many distributions Ansible with a multi-machine Vagrantfile

A common layered approach: shell for bootstrapping (install Python or Puppet), then the configuration tool for the real work, then triggers for housekeeping.

Common problems

  • Python not found in the guest (Ansible): install Python in a shell provisioner first, or use a box that has it.
  • Host Ansible on Windows: not supported natively; use ansible_local or run Vagrant in WSL.
  • SSH key permissions: Ansible refuses keys that are too open; Vagrant handles this, but synced /vagrant on Windows may expose files as 0777. Copy keys into the guest.
  • Slow runs: tune ansible.verbose, enable pipelining, and do not run apt update in every play.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main advantage of declarative provisioners such as Ansible or Puppet over shell scripts?

    Declarative tools compare the current state with the desired state, which makes them idempotent by design.
  2. 2. When should you use ansible_local instead of ansible?

    ansible_local installs Ansible in the guest and runs the playbook there.
  3. 3. What does the Docker provisioner do?

    It sets up Docker inside the VM, so you can start containers during provisioning.
  4. 4. Which tool uses Ruby recipes?

    Chef cookbooks and recipes are written in Ruby; Ansible uses YAML and Puppet its own language.

Summary

  • Configuration management describes the desired state, so reruns change nothing that is already right.
  • Vagrant supports Ansible (ansible and ansible_local), Puppet, Chef, Salt and a Docker provisioner.
  • Reuse the same playbooks or recipes for development and production to test your automation early.
  • Bootstrap prerequisites with a short shell provisioner, then hand over to the tool.

Next: Forwarded Ports