From 6439ebff22c764c32cb980828d693511198a2803 Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Mon, 20 Jul 2020 07:55:56 -0700 Subject: [PATCH] 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 --- .../docs/post-processors/shell-local.mdx | 256 +++++++++++- .../pages/docs/provisioners/shell-local.mdx | 388 ++++++++++++++---- 2 files changed, 566 insertions(+), 78 deletions(-) diff --git a/website/pages/docs/post-processors/shell-local.mdx b/website/pages/docs/post-processors/shell-local.mdx index 60e888b25..1e98a3f2b 100644 --- a/website/pages/docs/post-processors/shell-local.mdx +++ b/website/pages/docs/post-processors/shell-local.mdx @@ -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. + + + ```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"] + } + ] } ``` + + + +```hcl +source "file" "example" { + content = "example content" +} + +build { + source "source.file.example" { + target = "./test_artifact.txt" + } + + post-processor "shell-local" { + inline = ["echo foo"] + } +} +``` + + + + ## 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. + + + + ```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. } ``` + + + +```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" + } +} +``` + + + + ## 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: + + + ```json { "builders": [ @@ -265,6 +340,34 @@ tarball, you might write this: } ``` + + + +```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" + ] + } +} +``` + + + + 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: + + + ```json { "type": "shell-local", @@ -290,6 +396,20 @@ Example of running a .cmd file on windows: } ``` + + + +```hcl +post-processor "shell-local" { + environment_vars = ["SHELLLOCALTEST=ShellTest1"] + scripts = ["./scripts/test_cmd.cmd"] +} +``` + + + + + 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 + + + + ```json { "type": "shell-local", @@ -306,9 +430,26 @@ tempfile_extension } ``` + + + +```hcl +post-processor "shell-local" { + environment_vars = ["SHELLLOCALTEST=ShellTest2"], + tempfile_extension = ".cmd", + inline = [echo %SHELLLOCALTEST%"] +} +``` + + + + Example of running a bash command on windows using WSL: Required customizations: use_linux_pathing and execute_command + + + ```json { "type": "shell-local", @@ -319,6 +460,21 @@ customizations: use_linux_pathing and execute_command } ``` + + + +```hcl +post-processor "shell-local" { + environment_vars = ["SHELLLOCALTEST=ShellTest3"], + execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"] + use_linux_pathing = true + script = "./scripts/example_bash.sh" +} +``` + + + + 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 + + + ```json { "type": "shell-local", @@ -337,9 +496,27 @@ env_var_format and execute_command } ``` + + + +```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" +} +``` + + + + Example of running a powershell script on windows as "inline": Required customizations: env_var_format, tempfile_extension, and execute_command + + + ```json { "type": "shell-local", @@ -351,10 +528,29 @@ customizations: env_var_format, tempfile_extension, and execute_command } ``` + + + +```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"] +} +``` + + + + ### Unix Host Example of running a bash script on unix: + + + ```json { "type": "shell-local", @@ -363,8 +559,24 @@ Example of running a bash script on unix: } ``` + + + +```hcl +post-processor "shell-local" { + environment_vars = ["PROVISIONERTEST=ProvisionerTest1"] + scripts = ["./scripts/example_bash.sh"] +} +``` + + + + Example of running a bash "inline" on unix: + + + ```json { "type": "shell-local", @@ -373,8 +585,25 @@ Example of running a bash "inline" on unix: } ``` + + + +```hcl +post-processor "shell-local" { + environment_vars = ["PROVISIONERTEST=ProvisionerTest2"] + inline = ["echo hello", "echo $PROVISIONERTEST"] +} + +``` + + + + Example of running a python script on unix: + + + ```json { "type": "shell-local", @@ -388,6 +617,25 @@ Example of running a python script on unix: } ``` + + + +```hcl +post-processor "shell-local" { + script = "hello.py" + environment_vars = ["HELLO_USER=packeruser"] + execute_command = [ + "/bin/sh", + "-c", + "{{.Vars}} /usr/local/bin/python {{.Script}}" + ] +} + +``` + + + + Where "hello.py" contains: import os diff --git a/website/pages/docs/provisioners/shell-local.mdx b/website/pages/docs/provisioners/shell-local.mdx index 36858c482..8260a9de6 100644 --- a/website/pages/docs/provisioners/shell-local.mdx +++ b/website/pages/docs/provisioners/shell-local.mdx @@ -25,13 +25,51 @@ scripts on a remote machine. The example below is fully functional. + + + ```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"] + } + ] } ``` + + + +```hcl +source "file" "example" { + content = "example content" +} + +build { + source "source.file.example" { + target = "./test_artifact.txt" + } + + provisioner "shell-local" { + inline = ["echo foo"] + } +} +``` + + + + + ## 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. + + + +```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" + } + ] +} +``` + + + + +```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" + } +} +``` + + + ## 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"] - } + + + +```json +{ + "type": "shell-local", + "environment_vars": ["SHELLLOCALTEST=ShellTest1"], + "scripts": ["./scripts/test_cmd.cmd"] +} +``` + + + + +```hcl +provisioner "shell-local" { + environment_vars = ["SHELLLOCALTEST=ShellTest1"] + scripts = ["./scripts/test_cmd.cmd"] +} +``` + + + + 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%"] - } + + + + +```json +{ + "type": "shell-local", + "environment_vars": ["SHELLLOCALTEST=ShellTest2"], + "tempfile_extension": ".cmd", + "inline": ["echo %SHELLLOCALTEST%"] +} +``` + + + + +```hcl +provisioner "shell-local" { + environment_vars = ["SHELLLOCALTEST=ShellTest2"], + tempfile_extension = ".cmd", + inline = [echo %SHELLLOCALTEST%"] +} +``` + + + 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" - } + + + +```json +{ + "type": "shell-local", + "environment_vars": ["SHELLLOCALTEST=ShellTest3"], + "execute_command": ["bash", "-c", "{{.Vars}} {{.Script}}"], + "use_linux_pathing": true, + "script": "./scripts/example_bash.sh" +} +``` + + + + +```hcl +provisioner "shell-local" { + environment_vars = ["SHELLLOCALTEST=ShellTest3"], + execute_command = ["bash", "-c", "{{.Vars}} {{.Script}}"] + use_linux_pathing = true + script = "./scripts/example_bash.sh" +} +``` + + + 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" - } + + + +```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" +} +``` + + + + +```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" +} +``` + + + 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"] - } + + + +```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"] +} +``` + + + + +```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"] +} +``` + + + ### Unix Host Example of running a bash script on unix: - { - "type": "shell-local", - "environment_vars": ["PROVISIONERTEST=ProvisionerTest1"], - "scripts": ["./scripts/example_bash.sh"] - } + + + +```json +{ + "type": "shell-local", + "environment_vars": ["PROVISIONERTEST=ProvisionerTest1"], + "scripts": ["./scripts/example_bash.sh"] +} +``` + + + + +```hcl +provisioner "shell-local" { + environment_vars = ["PROVISIONERTEST=ProvisionerTest1"] + scripts = ["./scripts/example_bash.sh"] +} +``` + + + Example of running a bash "inline" on unix: - { - "type": "shell-local", - "environment_vars": ["PROVISIONERTEST=ProvisionerTest2"], - "inline": ["echo hello", - "echo $PROVISIONERTEST"] - } + + + +```json +{ + "type": "shell-local", + "environment_vars": ["PROVISIONERTEST=ProvisionerTest2"], + "inline": ["echo hello", "echo $PROVISIONERTEST"] +} +``` + + + + +```hcl +provisioner "shell-local" { + environment_vars = ["PROVISIONERTEST=ProvisionerTest2"] + inline = ["echo hello", "echo $PROVISIONERTEST"] +} + +``` + + + 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}}"] - } + + + +```json +{ + "type": "shell-local", + "script": "hello.py", + "environment_vars": ["HELLO_USER=packeruser"], + "execute_command": [ + "/bin/sh", + "-c", + "{{.Vars}} /usr/local/bin/python {{.Script}}" + ] +} +``` + + + + +```hcl +provisioner "shell-local" { + script = "hello.py" + environment_vars = ["HELLO_USER=packeruser"] + execute_command = [ + "/bin/sh", + "-c", + "{{.Vars}} /usr/local/bin/python {{.Script}}" + ] +} + +``` + + + Where "hello.py" contains: