369 lines
13 KiB
Markdown
369 lines
13 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Basic Usage - Provisioning"
|
|
sidebar_current: "provisioning-basic"
|
|
description: |-
|
|
While Vagrant offers multiple options for how you are able to provision
|
|
your machine, there is a standard usage pattern as well as some important
|
|
points common to all provisioners that are important to know.
|
|
---
|
|
|
|
# Basic Usage of Provisioners
|
|
|
|
While Vagrant offers multiple options for how you are able to provision
|
|
your machine, there is a standard usage pattern as well as some important
|
|
points common to all provisioners that are important to know.
|
|
|
|
## Options
|
|
|
|
Every Vagrant provisioner accepts a few base options. The only required
|
|
option is what type a provisioner is:
|
|
|
|
|
|
* `name` (string) - The name of the provisioner. Note: if no `type` option is given,
|
|
this option _must_ be the type of provisioner it is. If you wish to give it a
|
|
different name you must also set the `type` option to define the kind of provisioner.
|
|
* `type` (string) - The class of provisioner to configure. (i.e. `"shell"` or `"file"`)
|
|
* `before` (string or symbol) - The exact name of an already defined provisioner
|
|
that _this_ provisioner should run before. If defined as a symbol, its only valid
|
|
values are `:each` or `:all`, which makes the provisioner run before each and
|
|
every root provisioner, or before all provisioners respectively.
|
|
__Note__: This option is currently experimental, so it needs to be explicitly
|
|
enabled to work. More info can be found [here](/docs/experimental/index.html).
|
|
* `after` (string or symbol) - The exact name of an already defined provisioner
|
|
that _this_ provisioner should run after. If defined as a symbol, its only valid
|
|
values are `:each` or `:all`, which makes the provisioner run after each and
|
|
every root provisioner, or before all provisioners respectively.
|
|
__Note__: This option is currently experimental, so it needs to be explicitly
|
|
enabled to work. More info can be found [here](/docs/experimental/index.html).
|
|
|
|
More information about how to use `before` and `after` options can be read [below](#dependency-provisioners).
|
|
|
|
## Configuration
|
|
|
|
First, every provisioner is configured within your
|
|
[Vagrantfile](/docs/vagrantfile/)
|
|
using the `config.vm.provision` method call. For example, the Vagrantfile
|
|
below enables shell provisioning:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
# ... other configuration
|
|
|
|
config.vm.provision "shell", inline: "echo hello"
|
|
end
|
|
```
|
|
|
|
Every provisioner has a type, such as `"shell"`, used as the first
|
|
parameter to the provisioning configuration. Following that is basic key/value
|
|
for configuring that specific provisioner. Instead of basic key/value, you
|
|
can also use a Ruby block for a syntax that is more like variable assignment.
|
|
The following is effectively the same as the prior example:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
# ... other configuration
|
|
|
|
config.vm.provision "shell" do |s|
|
|
s.inline = "echo hello"
|
|
end
|
|
end
|
|
```
|
|
|
|
The benefit of the block-based syntax is that with more than a couple options
|
|
it can greatly improve readability. Additionally, some provisioners, like
|
|
the Chef provisioner, have special methods that can be called within that
|
|
block to ease configuration that cannot be done with the key/value approach,
|
|
or you can use this syntax to pass arguments to a shell script.
|
|
|
|
The attributes that can be set in a single-line are the attributes that
|
|
are set with the `=` style, such as `inline = "echo hello"` above. If the
|
|
style is instead more of a function call, such as `add_recipe "foo"`, then
|
|
this cannot be specified in a single line.
|
|
|
|
Provisioners can also be named (since 1.7.0). These names are used cosmetically for output
|
|
as well as overriding provisioner settings (covered further below). An example
|
|
of naming provisioners is shown below:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
# ... other configuration
|
|
|
|
config.vm.provision "bootstrap", type: "shell" do |s|
|
|
s.inline = "echo hello"
|
|
end
|
|
end
|
|
```
|
|
|
|
Naming provisioners is simple. The first argument to `config.vm.provision`
|
|
becomes the name, and then a `type` option is used to specify the provisioner
|
|
type, such as `type: "shell"` above.
|
|
|
|
## Running Provisioners
|
|
|
|
Provisioners are run in three cases: the initial `vagrant up`, `vagrant
|
|
provision`, and `vagrant reload --provision`.
|
|
|
|
A `--no-provision` flag can be passed to `up` and `reload` if you do not
|
|
want to run provisioners. Likewise, you can pass `--provision` to force
|
|
provisioning.
|
|
|
|
The `--provision-with` flag can be used if you only want to run a
|
|
specific provisioner if you have multiple provisioners specified. For
|
|
example, if you have a shell and Puppet provisioner and only want to
|
|
run the shell one, you can do `vagrant provision --provision-with shell`.
|
|
The arguments to `--provision-with` can be the provisioner type (such as
|
|
"shell") or the provisioner name (such as "bootstrap" from above).
|
|
|
|
## Run Once, Always or Never
|
|
|
|
By default, provisioners are only run once, during the first `vagrant up`
|
|
since the last `vagrant destroy`, unless the `--provision` flag is set,
|
|
as noted above.
|
|
|
|
Optionally, you can configure provisioners to run on every `up` or
|
|
`reload`. They will only be not run if the `--no-provision` flag is
|
|
explicitly specified. To do this set the `run` option to "always",
|
|
as shown below:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
config.vm.provision "shell", inline: "echo hello",
|
|
run: "always"
|
|
end
|
|
```
|
|
|
|
You can also set `run:` to `"never"` if you have an optional provisioner
|
|
that you want to mention to the user in a "post up message" or that
|
|
requires some other configuration before it is possible, then call this
|
|
with `vagrant provision --provision-with bootstrap`.
|
|
|
|
If you are using the block format, you must specify it outside
|
|
of the block, as shown below:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
config.vm.provision "bootstrap", type: "shell", run: "never" do |s|
|
|
s.inline = "echo hello"
|
|
end
|
|
end
|
|
```
|
|
|
|
## Multiple Provisioners
|
|
|
|
Multiple `config.vm.provision` methods can be used to define multiple
|
|
provisioners. These provisioners will be run in the order they're defined.
|
|
This is useful for a variety of reasons, but most commonly it is used so
|
|
that a shell script can bootstrap some of the system so that another provisioner
|
|
can take over later.
|
|
|
|
If you define provisioners at multiple "scope" levels (such as globally
|
|
in the configuration block, then in a
|
|
[multi-machine](/docs/multi-machine/) definition, then maybe
|
|
in a [provider-specific override](/docs/providers/configuration.html)),
|
|
then the outer scopes will always run _before_ any inner scopes. For
|
|
example, in the Vagrantfile below:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
config.vm.provision "shell", inline: "echo foo"
|
|
|
|
config.vm.define "web" do |web|
|
|
web.vm.provision "shell", inline: "echo bar"
|
|
end
|
|
|
|
config.vm.provision "shell", inline: "echo baz"
|
|
end
|
|
```
|
|
|
|
The ordering of the provisioners will be to echo "foo", "baz", then
|
|
"bar" (note the second one might not be what you expect!). Remember:
|
|
ordering is _outside in_.
|
|
|
|
With multiple provisioners, use the `--provision-with` setting along
|
|
with names to get more fine grained control over what is run and when.
|
|
|
|
## Overriding Provisioner Settings
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning: Advanced Topic!</strong> Provisioner overriding is
|
|
an advanced topic that really only becomes useful if you are already
|
|
using multi-machine and/or provider overrides. If you are just getting
|
|
started with Vagrant, you can safely skip this.
|
|
</div>
|
|
|
|
When using features such as [multi-machine](/docs/multi-machine/)
|
|
or [provider-specific overrides](/docs/providers/configuration.html),
|
|
you may want to define common provisioners in the global configuration
|
|
scope of a Vagrantfile, but override certain aspects of them internally.
|
|
Vagrant allows you to do this, but has some details to consider.
|
|
|
|
To override settings, you must assign a name to your provisioner.
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
config.vm.provision "foo", type: "shell",
|
|
inline: "echo foo"
|
|
|
|
config.vm.define "web" do |web|
|
|
web.vm.provision "foo", type: "shell",
|
|
inline: "echo bar"
|
|
end
|
|
end
|
|
```
|
|
|
|
In the above, only "bar" will be echoed, because the inline setting
|
|
overloaded the outer provisioner. This overload is only effective
|
|
within that scope: the "web" VM. If there were another VM defined,
|
|
it would still echo "foo" unless it itself also overloaded the
|
|
provisioner.
|
|
|
|
**Be careful with ordering.** When overriding a provisioner in
|
|
a sub-scope, the provisioner will run at _that point_. In the example
|
|
below, the output would be "foo" then "bar":
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
config.vm.provision "foo", type: "shell",
|
|
inline: "echo ORIGINAL!"
|
|
|
|
config.vm.define "web" do |web|
|
|
web.vm.provision "shell",
|
|
inline: "echo foo"
|
|
web.vm.provision "foo", type: "shell",
|
|
inline: "echo bar"
|
|
end
|
|
end
|
|
```
|
|
|
|
If you want to preserve the original ordering, you can specify
|
|
the `preserve_order: true` flag:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
config.vm.provision "do-this",
|
|
type: "shell",
|
|
preserve_order: true,
|
|
inline: "echo FIRST!"
|
|
config.vm.provision "then-this",
|
|
type: "shell",
|
|
preserve_order: true,
|
|
inline: "echo SECOND!"
|
|
end
|
|
```
|
|
|
|
## Dependency Provisioners
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning: Advanced Topic!</strong> Dependency provisioners are
|
|
an advanced topic. If you are just getting started with Vagrant, you can
|
|
safely skip this.
|
|
</div>
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning!</strong> This feature is still experimental and may break or
|
|
change in between releases. Use at your own risk.
|
|
|
|
This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to:
|
|
|
|
```
|
|
VAGRANT_EXPERIMENTAL="dependency_provisioners"
|
|
```
|
|
|
|
Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more
|
|
information about this flag visit the [Experimental docs page](/docs/experimental/)
|
|
for more info. Without this flag enabled, provisioners with the `before` and
|
|
`after` option will be ignored.
|
|
</div>
|
|
|
|
If a provisioner has been configured using the `before` or `after` options, it
|
|
is considered a _Dependency Provisioner_. This means it has been configured to
|
|
run before or after a _Root Provisioner_, which does not have the `before` or
|
|
`after` options configured.
|
|
|
|
Dependency provisioners also have two valid shortcuts:
|
|
`:each` and `:all`.
|
|
|
|
**Note**: As of 2.2.6, dependency provisioners cannot rely on other dependency
|
|
provisioners and is considered a configuration state error in Vagrant. If you must
|
|
order dependency provisioners, you can still order them by the order they are defined
|
|
inside your Vagrantfile.
|
|
|
|
An example of these dependency provisioners can be seen below:
|
|
|
|
```ruby
|
|
Vagrant.configure("2") do |config|
|
|
config.vm.provision "C", after: "B", type: "shell", inline:<<-SHELL
|
|
echo 'C'
|
|
SHELL
|
|
config.vm.provision "B", type: "shell", inline:<<-SHELL
|
|
echo 'B'
|
|
SHELL
|
|
config.vm.provision "D", type: "shell", inline:<<-SHELL
|
|
echo 'D'
|
|
SHELL
|
|
config.vm.provision "A", before: "B", type: "shell", inline:<<-SHELL
|
|
echo 'A'
|
|
SHELL
|
|
config.vm.provision "Separate After", after: :each, type: "shell", inline:<<-SHELL
|
|
echo '=============================='
|
|
SHELL
|
|
config.vm.provision "Separate Before", before: :each, type: "shell", inline:<<-SHELL
|
|
echo '++++++++++++++++++++++++++++++'
|
|
SHELL
|
|
config.vm.provision "Hello", before: :all, type: "shell", inline:<<-SHELL
|
|
echo 'HERE WE GO!!'
|
|
SHELL
|
|
config.vm.provision "Goodbye", after: :all, type: "shell", inline:<<-SHELL
|
|
echo 'The end'
|
|
SHELL
|
|
end
|
|
```
|
|
|
|
The result of running `vagrant provision` with a guest configured above:
|
|
|
|
```
|
|
==> default: Running provisioner: Hello (shell)...
|
|
default: Running: inline script
|
|
default: HERE WE GO!!
|
|
==> default: Running provisioner: Separate Before (shell)...
|
|
default: Running: inline script
|
|
default: ++++++++++++++++++++++++++++++
|
|
==> default: Running provisioner: A (shell)...
|
|
default: Running: inline script
|
|
default: A
|
|
==> default: Running provisioner: Separate After (shell)...
|
|
default: Running: inline script
|
|
default: ==============================
|
|
==> default: Running provisioner: Separate Before (shell)...
|
|
default: Running: inline script
|
|
default: ++++++++++++++++++++++++++++++
|
|
==> default: Running provisioner: B (shell)...
|
|
default: Running: inline script
|
|
default: B
|
|
==> default: Running provisioner: Separate After (shell)...
|
|
default: Running: inline script
|
|
default: ==============================
|
|
==> default: Running provisioner: Separate Before (shell)...
|
|
default: Running: inline script
|
|
default: ++++++++++++++++++++++++++++++
|
|
==> default: Running provisioner: C (shell)...
|
|
default: Running: inline script
|
|
default: C
|
|
==> default: Running provisioner: Separate After (shell)...
|
|
default: Running: inline script
|
|
default: ==============================
|
|
==> default: Running provisioner: Separate Before (shell)...
|
|
default: Running: inline script
|
|
default: ++++++++++++++++++++++++++++++
|
|
==> default: Running provisioner: D (shell)...
|
|
default: Running: inline script
|
|
default: D
|
|
==> default: Running provisioner: Separate After (shell)...
|
|
default: Running: inline script
|
|
default: ==============================
|
|
==> default: Running provisioner: Goodbye (shell)...
|
|
default: Running: inline script
|
|
default: The end
|
|
```
|