From 451d4c2620fac65e1b19d0d48e0600522f94fae5 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Tue, 9 Jun 2020 12:42:01 +0200 Subject: [PATCH] hcl2 docs pass (#9375) * moved blocks and functions top the nav list for easier access ( I think those will be used a lot) * added a concrete fileset example * added more concrete examples in the blocks doc --- website/data/docs-navigation.js | 10 +-- .../docs/from-1.5/blocks/build/index.mdx | 65 +++++++++++++++++++ .../from-1.5/blocks/build/provisioner.mdx | 30 +++++++-- .../docs/from-1.5/blocks/build/source.mdx | 26 +++++++- website/pages/docs/from-1.5/blocks/index.mdx | 8 +++ .../docs/from-1.5/functions/file/fileset.mdx | 60 ++++++++++++----- website/pages/docs/from-1.5/index.mdx | 4 +- .../from-1.5/builds/example-block.mdx | 4 +- 8 files changed, 174 insertions(+), 33 deletions(-) diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index e0ceac5a7..038d56cce 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -9,11 +9,6 @@ export default [ { category: 'from-1.5', content: [ - 'variables', - 'locals', - 'syntax', - 'expressions', - 'syntax-json', { category: 'blocks', content: [ @@ -143,6 +138,11 @@ export default [ }, ], }, + 'variables', + 'locals', + 'syntax', + 'expressions', + 'syntax-json', ], }, '--------', diff --git a/website/pages/docs/from-1.5/blocks/build/index.mdx b/website/pages/docs/from-1.5/blocks/build/index.mdx index c05377e46..f8ce353af 100644 --- a/website/pages/docs/from-1.5/blocks/build/index.mdx +++ b/website/pages/docs/from-1.5/blocks/build/index.mdx @@ -27,6 +27,71 @@ Define [top-level `source` blocks](/docs/from-1.5/blocks/source) to configure your builders. The list of available builders can be found in the [builders](/docs/builders) section. +## Naming your builds + +The optional `name` field of the `build` block can be used to set the name of a +build. Named builds will prefix the log lines in a `packer build` with the name +of the build block. For example: + +```hcl +source "null" "first-example" { + communicator = "none" +} + +source "null" "second-example" { + communicator = "none" +} + +build { + name = "a" + + sources = [ + "sources.null.first-example", + "sources.null.second-example", + ] +} + + +build { + sources = ["sources.null.second-example"] +} +``` + +Will output: + +```shell-session +> packer build ./folder +Build 'a.null.first-example' finished. +Build 'a.null.second-example' finished. +Build 'null.second-example' finished. + +==> Builds finished. The artifacts of successful builds are: +--> a.null.first-example: Did not export anything. This is the null builder +--> a.null.second-example: Did not export anything. This is the null builder +--> null.second-example: Did not export anything. This is the null builder +``` + +### Running only specific builds + +The `-only`/`-except` flags will match a source's `type.name` and run 'only' +matching **builders** (source) or all referenced builders 'except' the matching +ones, for example with the same config file: + +```shell-session +> packer build -only "*.second" ./folder +Build 'null.second-example' finished. +Build 'a.null.second-example' finished. + +==> Builds finished. The artifacts of successful builds are: +--> a.null.second-example: Did not export anything. This is the null builder +--> null.second-example: Did not export anything. This is the null builder +``` + +Here `'a.null.first-example'` was skipped. + +-> Note: It is not yet possible to match a named `build` block to do this, but +this is soon going to be possible. So here "a.*" will match nothing. + ## Related diff --git a/website/pages/docs/from-1.5/blocks/build/provisioner.mdx b/website/pages/docs/from-1.5/blocks/build/provisioner.mdx index c455ae3e5..0c06e36f8 100644 --- a/website/pages/docs/from-1.5/blocks/build/provisioner.mdx +++ b/website/pages/docs/from-1.5/blocks/build/provisioner.mdx @@ -43,14 +43,34 @@ 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" { - inline = [ - "echo provisioning all the things", - "echo the value of 'foo' is '${var.foo}'", + # 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!" ] - only = ["source.amazon-ebs.example"] } } ``` diff --git a/website/pages/docs/from-1.5/blocks/build/source.mdx b/website/pages/docs/from-1.5/blocks/build/source.mdx index 73b8747a2..27000affe 100644 --- a/website/pages/docs/from-1.5/blocks/build/source.mdx +++ b/website/pages/docs/from-1.5/blocks/build/source.mdx @@ -16,14 +16,34 @@ source and to set specific fields. ```hcl # builds.pkr.hcl +source "lxd" "arch" { + image = "archlinux" +} + build { - source "amazon-ebs.example" { - output = "specific-value" + source "lxd.arch" { + output_image = "nomad" + } + + provisioner "shell" { + inline = [ "echo installing nomad" ] + } +} + +build { + source "lxd.arch" { + output_image = "consul" + } + + provisioner "shell" { + inline = [ "echo installing consul" ] } - # ... } ``` +This allows to have commonly defined source settings with specific parts of it +defined inside the specific build block. + -> **Note:** It is **not allowed** to set the same field in a top-level source block and in a used source block. For example, if in the above example, the top-level "amazon-ebs.example" source block also had an `output` field; diff --git a/website/pages/docs/from-1.5/blocks/index.mdx b/website/pages/docs/from-1.5/blocks/index.mdx index ea4fc2ed8..311e214c9 100644 --- a/website/pages/docs/from-1.5/blocks/index.mdx +++ b/website/pages/docs/from-1.5/blocks/index.mdx @@ -24,8 +24,16 @@ list of all of the available built-in HCL2 blocks. `@include 'from-1.5/variables/foo-block.mdx'` +* [Variable block documentation](/docs/from-1.5/blocks/variable). + `@include 'from-1.5/locals/example-block.mdx'` +* [Locals block documentation](/docs/from-1.5/blocks/locals). + `@include 'from-1.5/sources/example-block.mdx'` +* [source block documentation](/docs/from-1.5/blocks/source). + `@include 'from-1.5/builds/example-block.mdx'` + +* [build block documentation](/docs/from-1.5/blocks/build). diff --git a/website/pages/docs/from-1.5/functions/file/fileset.mdx b/website/pages/docs/from-1.5/functions/file/fileset.mdx index 4a2cf2a7b..4228d8491 100644 --- a/website/pages/docs/from-1.5/functions/file/fileset.mdx +++ b/website/pages/docs/from-1.5/functions/file/fileset.mdx @@ -37,39 +37,67 @@ before Packer takes any actions. ## Examples ```shell-session -> fileset(path.folder, "files/*.txt") +> tree pkr-consul +pkr-consul +├── build-linux.pkr.hcl +└── linux + ├── files + │ ├── hello.txt + │ └── world.txt + └── scripts + ├── script-1-install.sh + └── script-2-setup.sh + +3 directories, 5 files + +> fileset(".", "*") | packer console pkr-consul [ - "files/hello.txt", - "files/world.txt", + "build-linux.pkr.hcl", +] + +> echo 'fileset(".", "linux/scripts/*")' | packer console pkr-consul +[ + "linux/scripts/script-1-install.sh", + "linux/scripts/script-2-setup.sh", ] -> fileset(path.folder, "files/{hello,world}.txt") +> echo 'fileset("linux", "files/{hello,world}.txt")' | packer console pkr-consul [ "files/hello.txt", "files/world.txt", ] -> fileset("${path.folder}/files", "*") +> echo 'fileset("./linux/files", "*")' | packer console pkr-consul [ "hello.txt", "world.txt", ] -> fileset("${path.folder}/files", "**") +> echo 'fileset("./linux", "**")' | packer console pkr-consul [ - "hello.txt", - "world.txt", - "subdirectory/anotherfile.txt", + "files/hello.txt", + "files/world.txt", + "scripts/script-1-install.sh", + "scripts/script-2-setup.sh", ] ``` -A common use of `fileset` is to create one resource instance per matched file, using -[the `for_each` meta-argument](https://www.terraform.io/docs/configuration/resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings): +A common use of `fileset` is to set the `scripts` field of a `shell` +provisioner with a list of matching scripts to run. ```hcl -resource "example_thing" "example" { - for_each = fileset(path.folder, "files/*") - - # other configuration using each.value -} +build { + sources = [ + "source.amazon-ebs.linux", + ] + + provisioner "shell" { + scripts = fileset(".", "linux/scripts/*") + } ``` + +List of provisioners with a `scripts` field: +* [`shell`](/docs/provisioners/shell) +* [`powershell`](/docs/provisioners/powershell) +* [`shell-local`](/docs/provisioners/shell-local) +* [`windows-shell`](/docs/provisioners/windows-shell) diff --git a/website/pages/docs/from-1.5/index.mdx b/website/pages/docs/from-1.5/index.mdx index e5fb91b29..928d309d8 100644 --- a/website/pages/docs/from-1.5/index.mdx +++ b/website/pages/docs/from-1.5/index.mdx @@ -25,8 +25,8 @@ language features exist only to make the definition of builds more flexible and convenient. `packer build` takes one argument. When a directory is passed, all files in the -folder with a name ending with ".pkr.hcl" or ".pkr.json" will be parsed using -the HCL2 format. When a file ending with ".pkr.hcl" or ".pkr.json" is passed it +folder with a name ending with `.pkr.hcl` or `.pkr.json` will be parsed using +the HCL2 format. When a file ending with `.pkr.hcl` or `.pkr.json` is passed it will be parsed using the HCL2 schema. For every other case; the _JSON only_ old packer schema will be used. diff --git a/website/pages/partials/from-1.5/builds/example-block.mdx b/website/pages/partials/from-1.5/builds/example-block.mdx index 4ac0af5ef..52e44eb00 100644 --- a/website/pages/partials/from-1.5/builds/example-block.mdx +++ b/website/pages/partials/from-1.5/builds/example-block.mdx @@ -20,8 +20,8 @@ build { name = var.foo } - provisioner "shell-local" { - inline = ["echo Hello World"] + provisioner "shell" { + scripts = fileset(".", "scripts/{install,secure}.sh") } post-processor "shell-local" {