Update provisioners and post-processor hcl2 docs

This commit is contained in:
Moss 2020-06-05 15:49:09 +02:00
parent 26e099023b
commit 110b1411d7
2 changed files with 135 additions and 1 deletions

View File

@ -26,4 +26,28 @@ build {
Post-processors run after the image is built by the builder and provisioned by
the provisioner(s). Post-processors are optional, and they can be used to
upload artifacts, re-package, or more. The list of available post-processors
can be found in the [post-processors](/docs/post-processors) section.
can be found in the [post-processors](/docs/post-processors) section.
# Run on Specific Builds
You can use the `only` or `except` configurations to run a post-provessor only
with specific builds. These two configurations do what you expect: `only` will
only run the post-provessor on the specified builds and `except` will run the
post-provessor 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
build {
# ...
post-processor "checksum" {
checksum_types = [ "md5", "sha512" ]
keep_input_artifact = true
only = ["source.amazon-ebs.example"]
}
}
```
The values within `only` or `except` are _build names_, not builder types.

View File

@ -30,3 +30,113 @@ 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
build {
# ...
provisioner "shell" {
inline = [
"echo provisioning all the things",
"echo the value of 'foo' is '${var.foo}'",
]
only = ["source.amazon-ebs.example"]
}
}
```
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.