docs: Add HCL2 code examples to shell-local provisioner and post-processor. (#9602)

* get start on shell-local postprocessor

* HCL2 tabs for shell-local pp

* shell local provisoner hcl examples
This commit is contained in:
Megan Marsh 2020-07-20 07:55:56 -07:00 committed by GitHub
parent 8964367eb5
commit 6439ebff22
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 566 additions and 78 deletions

View File

@ -17,15 +17,52 @@ some task with packer outputs and variables.
## Basic example
The example below is fully functional.
The example below is a fully functional self-contained build.
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"inline": ["echo foo"]
"builders": [
{
"type": "file",
"name": "example",
"target": "./test_artifact.txt",
"content": "example content"
}
],
"post-processors": [
{
"type": "shell-local",
"inline": ["echo foo"]
}
]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
source "file" "example" {
content = "example content"
}
build {
source "source.file.example" {
target = "./test_artifact.txt"
}
post-processor "shell-local" {
inline = ["echo foo"]
}
}
```
</Tab>
</Tabs>
## Configuration Reference
The reference of available configuration options is listed below. The only
@ -173,6 +210,10 @@ still in beta. There will be some limitations as a result. For example, it will
likely not work unless both Packer and the scripts you want to run are both on
the C drive.
<Tabs>
<Tab heading="JSON">
```json
{
"builders": [
@ -181,7 +222,7 @@ the C drive.
"communicator": "none"
}
],
"provisioners": [
"post-processors": [
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
@ -200,6 +241,37 @@ the C drive.
}
```
</Tab>
<Tab heading="HCL2">
```hcl
source "null" "example" {
communicator = "none"
}
build {
sources = [
"source.null.example"
]
post-processor "shell-local"{
environment_vars = ["PROVISIONERTEST=ProvisionerTest1"]
execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
use_linux_pathing = true
scripts = ["C:/Users/me/scripts/example_bash.sh"]
}
post-processor "shell-local"{
environment_vars = ["PROVISIONERTEST=ProvisionerTest2"]
execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
use_linux_pathing = true
script = "C:/Users/me/scripts/example_bash.sh"
}
}
```
</Tab>
</Tabs>
## Default Environmental Variables
In addition to being able to specify custom environmental variables using the
@ -238,6 +310,9 @@ of files produced by a `builder` to a json file after each `builder` is run.
For example, if you wanted to package a file from the file builder into a
tarball, you might write this:
<Tabs>
<Tab heading="JSON">
```json
{
"builders": [
@ -265,6 +340,34 @@ tarball, you might write this:
}
```
</Tab>
<Tab heading="HCL2">
```hcl
source "file" "example" {
content = "Lorem ipsum dolor sit amet"
target = "dummy_artifact.txt"
}
build {
sources = [
"source.file.example"
]
post-processor "manifest" {
output = "manifest.json"
strip_path = true
}
post-processor "shell-local" {
inline = [
"jq \".builds[].files[].name\" manifest.json | xargs tar cfz artifacts.tgz"
]
}
}
```
</Tab>
</Tabs>
This uses the [jq](https://stedolan.github.io/jq/) tool to extract all of the
file names from the manifest file and passes them to tar.
@ -282,6 +385,9 @@ _must_ be extra careful to `exit 0` when necessary.
Example of running a .cmd file on windows:
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
@ -290,6 +396,20 @@ Example of running a .cmd file on windows:
}
```
</Tab>
<Tab heading="HCL2">
```hcl
post-processor "shell-local" {
environment_vars = ["SHELLLOCALTEST=ShellTest1"]
scripts = ["./scripts/test_cmd.cmd"]
}
```
</Tab>
</Tabs>
Contents of "test_cmd.cmd":
echo %SHELLLOCALTEST%
@ -297,6 +417,10 @@ Contents of "test_cmd.cmd":
Example of running an inline command on windows: Required customization:
tempfile_extension
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
@ -306,9 +430,26 @@ tempfile_extension
}
```
</Tab>
<Tab heading="HCL2">
```hcl
post-processor "shell-local" {
environment_vars = ["SHELLLOCALTEST=ShellTest2"],
tempfile_extension = ".cmd",
inline = [echo %SHELLLOCALTEST%"]
}
```
</Tab>
</Tabs>
Example of running a bash command on windows using WSL: Required
customizations: use_linux_pathing and execute_command
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
@ -319,6 +460,21 @@ customizations: use_linux_pathing and execute_command
}
```
</Tab>
<Tab heading="HCL2">
```hcl
post-processor "shell-local" {
environment_vars = ["SHELLLOCALTEST=ShellTest3"],
execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
use_linux_pathing = true
script = "./scripts/example_bash.sh"
}
```
</Tab>
</Tabs>
Contents of "example_bash.sh":
#!/bin/bash
@ -327,6 +483,9 @@ Contents of "example_bash.sh":
Example of running a powershell script on windows: Required customizations:
env_var_format and execute_command
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
@ -337,9 +496,27 @@ env_var_format and execute_command
}
```
</Tab>
<Tab heading="HCL2">
```hcl
post-processor "shell-local" {
environment_vars = ["SHELLLOCALTEST=ShellTest4"]
execute_command = ["powershell.exe", "{{.Vars}} {{.Script}}"]
env_var_format = "$env:%s=\"%s\"; "
script = "./scripts/example_ps.ps1"
}
```
</Tab>
</Tabs>
Example of running a powershell script on windows as "inline": Required
customizations: env_var_format, tempfile_extension, and execute_command
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
@ -351,10 +528,29 @@ customizations: env_var_format, tempfile_extension, and execute_command
}
```
</Tab>
<Tab heading="HCL2">
```hcl
post-processor "shell-local" {
tempfile_extension = ".ps1"
environment_vars = ["SHELLLOCALTEST=ShellTest5"]
execute_command = ["powershell.exe", "{{.Vars}} {{.Script}}"]
env_var_format = "$env:%s=\"%s\"; "
inline = ["write-output $env:SHELLLOCALTEST"]
}
```
</Tab>
</Tabs>
### Unix Host
Example of running a bash script on unix:
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
@ -363,8 +559,24 @@ Example of running a bash script on unix:
}
```
</Tab>
<Tab heading="HCL2">
```hcl
post-processor "shell-local" {
environment_vars = ["PROVISIONERTEST=ProvisionerTest1"]
scripts = ["./scripts/example_bash.sh"]
}
```
</Tab>
</Tabs>
Example of running a bash "inline" on unix:
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
@ -373,8 +585,25 @@ Example of running a bash "inline" on unix:
}
```
</Tab>
<Tab heading="HCL2">
```hcl
post-processor "shell-local" {
environment_vars = ["PROVISIONERTEST=ProvisionerTest2"]
inline = ["echo hello", "echo $PROVISIONERTEST"]
}
```
</Tab>
</Tabs>
Example of running a python script on unix:
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
@ -388,6 +617,25 @@ Example of running a python script on unix:
}
```
</Tab>
<Tab heading="HCL2">
```hcl
post-processor "shell-local" {
script = "hello.py"
environment_vars = ["HELLO_USER=packeruser"]
execute_command = [
"/bin/sh",
"-c",
"{{.Vars}} /usr/local/bin/python {{.Script}}"
]
}
```
</Tab>
</Tabs>
Where "hello.py" contains:
import os

View File

@ -25,13 +25,51 @@ scripts on a remote machine.
The example below is fully functional.
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"command": "echo foo"
"builders": [
{
"type": "file",
"name": "example",
"target": "./test_artifact.txt",
"content": "example content"
}
],
"provisioners": [
{
"type": "shell-local",
"inline": ["echo foo"]
}
]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
source "file" "example" {
content = "example content"
}
build {
source "source.file.example" {
target = "./test_artifact.txt"
}
provisioner "shell-local" {
inline = ["echo foo"]
}
}
```
</Tab>
</Tabs>
## Configuration Reference
The reference of available configuration options is listed below. The only
@ -164,30 +202,66 @@ options instead.
Please note that the WSL is a beta feature, and this tool is not guaranteed to
work as you expect it to.
<Tabs>
<Tab heading="JSON">
```json
{
"builders": [
{
"builders": [
{
"type": "null",
"communicator": "none"
}
],
"provisioners": [
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
"execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
"use_linux_pathing": true,
"scripts": ["C:/Users/me/scripts/example_bash.sh"]
},
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest2"],
"execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
"use_linux_pathing": true,
"script": "C:/Users/me/scripts/example_bash.sh"
}
]
"type": "null",
"communicator": "none"
}
],
"provisioners": [
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
"execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
"use_linux_pathing": true,
"scripts": ["C:/Users/me/scripts/example_bash.sh"]
},
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest2"],
"execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
"use_linux_pathing": true,
"script": "C:/Users/me/scripts/example_bash.sh"
}
]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
source "null" "example" {
communicator = "none"
}
build {
sources = [
"source.null.example"
]
provisioner "shell-local"{
environment_vars = ["PROVISIONERTEST=ProvisionerTest1"]
execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
use_linux_pathing = true
scripts = ["C:/Users/me/scripts/example_bash.sh"]
}
provisioner "shell-local"{
environment_vars = ["PROVISIONERTEST=ProvisionerTest2"]
execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
use_linux_pathing = true
script = "C:/Users/me/scripts/example_bash.sh"
}
}
```
</Tab>
</Tabs>
## Default Environmental Variables
@ -234,15 +308,36 @@ _must_ be extra careful to `exit 0` when necessary.
## Usage Examples:
### Windows Host
Example of running a .cmd file on windows:
{
"type": "shell-local",
"environment_vars": ["SHELLLOCALTEST=ShellTest1"],
"scripts": ["./scripts/test_cmd.cmd"]
}
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"environment_vars": ["SHELLLOCALTEST=ShellTest1"],
"scripts": ["./scripts/test_cmd.cmd"]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "shell-local" {
environment_vars = ["SHELLLOCALTEST=ShellTest1"]
scripts = ["./scripts/test_cmd.cmd"]
}
```
</Tab>
</Tabs>
Contents of "test_cmd.cmd":
@ -251,23 +346,63 @@ Contents of "test_cmd.cmd":
Example of running an inline command on windows: Required customization:
tempfile_extension
{
"type": "shell-local",
"environment_vars": ["SHELLLOCALTEST=ShellTest2"],
"tempfile_extension": ".cmd",
"inline": ["echo %SHELLLOCALTEST%"]
}
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"environment_vars": ["SHELLLOCALTEST=ShellTest2"],
"tempfile_extension": ".cmd",
"inline": ["echo %SHELLLOCALTEST%"]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "shell-local" {
environment_vars = ["SHELLLOCALTEST=ShellTest2"],
tempfile_extension = ".cmd",
inline = [echo %SHELLLOCALTEST%"]
}
```
</Tab>
</Tabs>
Example of running a bash command on windows using WSL: Required
customizations: use_linux_pathing and execute_command
{
"type": "shell-local",
"environment_vars": ["SHELLLOCALTEST=ShellTest3"],
"execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
"use_linux_pathing": true,
"script": "./scripts/example_bash.sh"
}
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"environment_vars": ["SHELLLOCALTEST=ShellTest3"],
"execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"],
"use_linux_pathing": true,
"script": "./scripts/example_bash.sh"
}
```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "shell-local" {
environment_vars = ["SHELLLOCALTEST=ShellTest3"],
execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"]
use_linux_pathing = true
script = "./scripts/example_bash.sh"
}
```
</Tab>
</Tabs>
Contents of "example_bash.sh":
@ -277,53 +412,158 @@ Contents of "example_bash.sh":
Example of running a powershell script on windows: Required customizations:
env_var_format and execute_command
{
"type": "shell-local",
"environment_vars": ["SHELLLOCALTEST=ShellTest4"],
"execute_command": ["powershell.exe", "{{.Vars}} {{.Script}}"],
"env_var_format": "$env:%s=\"%s\"; ",
"script": "./scripts/example_ps.ps1"
}
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"environment_vars": ["SHELLLOCALTEST=ShellTest4"],
"execute_command": ["powershell.exe", "{{.Vars}} {{.Script}}"],
"env_var_format": "$env:%s=\"%s\"; ",
"script": "./scripts/example_ps.ps1"
}
```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "shell-local" {
environment_vars = ["SHELLLOCALTEST=ShellTest4"]
execute_command = ["powershell.exe", "{{.Vars}} {{.Script}}"]
env_var_format = "$env:%s=\"%s\"; "
script = "./scripts/example_ps.ps1"
}
```
</Tab>
</Tabs>
Example of running a powershell script on windows as "inline": Required
customizations: env_var_format, tempfile_extension, and execute_command
{
"type": "shell-local",
"tempfile_extension": ".ps1",
"environment_vars": ["SHELLLOCALTEST=ShellTest5"],
"execute_command": ["powershell.exe", "{{.Vars}} {{.Script}}"],
"env_var_format": "$env:%s=\"%s\"; ",
"inline": ["write-output $env:SHELLLOCALTEST"]
}
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"tempfile_extension": ".ps1",
"environment_vars": ["SHELLLOCALTEST=ShellTest5"],
"execute_command": ["powershell.exe", "{{.Vars}} {{.Script}}"],
"env_var_format": "$env:%s=\"%s\"; ",
"inline": ["write-output $env:SHELLLOCALTEST"]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "shell-local" {
tempfile_extension = ".ps1"
environment_vars = ["SHELLLOCALTEST=ShellTest5"]
execute_command = ["powershell.exe", "{{.Vars}} {{.Script}}"]
env_var_format = "$env:%s=\"%s\"; "
inline = ["write-output $env:SHELLLOCALTEST"]
}
```
</Tab>
</Tabs>
### Unix Host
Example of running a bash script on unix:
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
"scripts": ["./scripts/example_bash.sh"]
}
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest1"],
"scripts": ["./scripts/example_bash.sh"]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "shell-local" {
environment_vars = ["PROVISIONERTEST=ProvisionerTest1"]
scripts = ["./scripts/example_bash.sh"]
}
```
</Tab>
</Tabs>
Example of running a bash "inline" on unix:
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest2"],
"inline": ["echo hello",
"echo $PROVISIONERTEST"]
}
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"environment_vars": ["PROVISIONERTEST=ProvisionerTest2"],
"inline": ["echo hello", "echo $PROVISIONERTEST"]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "shell-local" {
environment_vars = ["PROVISIONERTEST=ProvisionerTest2"]
inline = ["echo hello", "echo $PROVISIONERTEST"]
}
```
</Tab>
</Tabs>
Example of running a python script on unix:
{
"type": "shell-local",
"script": "hello.py",
"environment_vars": ["HELLO_USER=packeruser"],
"execute_command": ["/bin/sh", "-c", "{{.Vars}} /usr/local/bin/python {{.Script}}"]
}
<Tabs>
<Tab heading="JSON">
```json
{
"type": "shell-local",
"script": "hello.py",
"environment_vars": ["HELLO_USER=packeruser"],
"execute_command": [
"/bin/sh",
"-c",
"{{.Vars}} /usr/local/bin/python {{.Script}}"
]
}
```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "shell-local" {
script = "hello.py"
environment_vars = ["HELLO_USER=packeruser"]
execute_command = [
"/bin/sh",
"-c",
"{{.Vars}} /usr/local/bin/python {{.Script}}"
]
}
```
</Tab>
</Tabs>
Where "hello.py" contains: