d8b67f8520
* Update and pin dependencies * Update NextJS Scripts * npm run lint * npm run format * docs generator: indent docs by two and make spacing better Co-authored-by: Adrien Delorme <azr@users.noreply.github.com>
166 lines
4.4 KiB
Plaintext
166 lines
4.4 KiB
Plaintext
---
|
|
description: >
|
|
The provisioner block defines how a provisioner is configured.
|
|
layout: docs
|
|
page_title: provisioner - build - Blocks
|
|
sidebar_title: <tt>provisioner</tt>
|
|
---
|
|
|
|
# The `provisioner` block
|
|
|
|
`@include 'from-1.5/beta-hcl2-note.mdx'`
|
|
|
|
The `provisioner` block defines how a provisioner is configured.
|
|
|
|
```hcl
|
|
# builds.pkr.hcl
|
|
build {
|
|
# ...
|
|
provisioner "shell" {
|
|
inline = [
|
|
"echo provisioning all the things",
|
|
"echo the value of 'foo' is '${var.foo}'",
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
Provisioners use builtin and third-party software to install and configure the
|
|
machine image after booting. Provisioners prepare the system for use.
|
|
|
|
The list of available provisioners can be found in the
|
|
[provisioners](/docs/provisioners) section.
|
|
|
|
# Run on Specific Builds
|
|
|
|
You can use the `only` or `except` configurations to run a provisioner only
|
|
with specific builds. These two configurations do what you expect: `only` will
|
|
only run the provisioner on the specified builds and `except` will run the
|
|
provisioner on anything other than the specified builds.
|
|
|
|
An example of `only` being used is shown below, but the usage of `except` is
|
|
effectively the same:
|
|
|
|
```hcl
|
|
# builds.pkr.hcl
|
|
|
|
source "amazon-ebs" "first-example" {
|
|
#...
|
|
}
|
|
|
|
source "amazon-ebs" "second-example" {
|
|
#...
|
|
}
|
|
|
|
build {
|
|
source = [
|
|
"source.amazon-ebs.first-example",
|
|
"source.amazon-ebs.second-example",
|
|
]
|
|
provisioner "shell" {
|
|
# This provisioner only runs for the 'first-example' source.
|
|
only = ["source.amazon-ebs.first-example"]
|
|
|
|
inline = [
|
|
"echo provisioning all the things",
|
|
"echo the value of 'foo' is '${var.foo}'",
|
|
]
|
|
}
|
|
provisioner "shell" {
|
|
# This runs with all sources.
|
|
inline = [
|
|
"echo Hi World!"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
The values within `only` or `except` are _build names_, not builder types.
|
|
|
|
## Pausing Before Running
|
|
|
|
With certain provisioners it is sometimes desirable to pause for some period of
|
|
time before running it. Specifically, in cases where a provisioner reboots the
|
|
machine, you may want to wait for some period of time before starting the next
|
|
provisioner.
|
|
|
|
Every provisioner definition in a Packer template can take a special
|
|
configuration `pause_before` that is the amount of time to pause before running
|
|
that provisioner. By default, there is no pause. An example is shown below:
|
|
|
|
```hcl
|
|
# builds.pkr.hcl
|
|
build {
|
|
# ...
|
|
provisioner "shell" {
|
|
inline = [
|
|
"echo provisioning all the things",
|
|
"echo the value of 'foo' is '${var.foo}'",
|
|
]
|
|
pause_before = "10s"
|
|
}
|
|
}
|
|
```
|
|
|
|
For the above provisioner, Packer will wait 10 seconds before uploading and
|
|
executing the shell script.
|
|
|
|
## Retry on error
|
|
|
|
With certain provisioners it is sometimes desirable to retry when it fails.
|
|
Specifically, in cases where the provisioner depends on external processes that are not done yet.
|
|
|
|
Every provisioner definition in a Packer template can take a special
|
|
configuration `max_retries` that is the maximum number of times a provisioner will retry on error.
|
|
By default, there `max_retries` is zero and there is no retry on error. An example is shown below:
|
|
|
|
```hcl
|
|
# builds.pkr.hcl
|
|
build {
|
|
# ...
|
|
provisioner "shell" {
|
|
inline = [
|
|
"echo provisioning all the things",
|
|
"echo the value of 'foo' is '${var.foo}'",
|
|
]
|
|
max_retries = 5
|
|
}
|
|
}
|
|
```
|
|
|
|
For the above provisioner, Packer will retry maximum five times until stops failing.
|
|
If after five retries the provisioner still fails, then the complete build will fail.
|
|
|
|
## Timeout
|
|
|
|
Sometimes a command can take much more time than expected
|
|
|
|
Every provisioner definition in a Packer template can take a special
|
|
configuration `timeout` that is the amount of time to wait before
|
|
considering that the provisioner failed. By default, there is no timeout. An
|
|
example is shown below:
|
|
|
|
```hcl
|
|
# builds.pkr.hcl
|
|
build {
|
|
# ...
|
|
provisioner "shell" {
|
|
inline = [
|
|
"echo provisioning all the things",
|
|
"echo the value of 'foo' is '${var.foo}'",
|
|
]
|
|
timeout = "5m"
|
|
}
|
|
}
|
|
```
|
|
|
|
For the above provisioner, Packer will cancel the script if it takes more than
|
|
5 minutes.
|
|
|
|
Timeout has no effect in debug mode.
|
|
|
|
## Build Contextual Variables
|
|
|
|
Packer allows to access connection information and basic instance state information from a provisioner. These information are stored in the `build` variable.
|
|
Check out the [Contextual Variables](/docs/from-1.5/contextual-variables) documentation to learn more about and see some examples of how to use them.
|