From 8c219166068cfa8de3af5ec6c88dfd21270ececb Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:01:48 +0100 Subject: [PATCH 01/22] add guide on how to make ones component HCL2 enabled --- .../component-object-spec/index.html.mr.erb | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 website/source/guides/hcl/component-object-spec/index.html.mr.erb diff --git a/website/source/guides/hcl/component-object-spec/index.html.mr.erb b/website/source/guides/hcl/component-object-spec/index.html.mr.erb new file mode 100644 index 000000000..68ebe0178 --- /dev/null +++ b/website/source/guides/hcl/component-object-spec/index.html.mr.erb @@ -0,0 +1,37 @@ +--- +layout: guides +page_title: Generating code for congig spec. +sidebar_current: hcl +description: |- + Learn how to generate the HCL2 configuration of your component easily. +--- + +# Packer 1.5.0 can be + +From version 1.5.0 Packer can be configured using HCL2. Because Packer has so +many builders, provisioner & post-proessors, we relied on code generation to +iterate more easily. The good new is that you can benefit from this code +generator to get the HCL2 spec of your component simply. Is it a Go binary +package and is located in `cmd/mapstructure-to-hcl2`. Here are some simple +steps you can follow to have most of the code required : + +Say you want to configure the Config struct of a Builder in a package located +in `my/example-plugin/config.go`. + +* run `go install github.com/hashicorp/packer/cmd/mapstructure-to-hcl2` + +* Add `//go:generate mapstructure-to-hcl2 -type Config` at the top of +`config.go` + +* run `go generate my/example-plugin` + +This will generate a `my/example-plugin/config.hcl2spec.go` file containing the +configuration fields of Config. Now we only need to make Builder implement the +interface by adding the following snippet: + +```go +func (b *Builder) ConfigSpec() hcldec.ObjectSpec { return b.config.FlatMapstructure().HCL2Spec() } +``` + +From now one every time you add or change a field of Config you will need to +run he `go generate` command again. From 1ada06b2d75228a9f1080989358a4c57913c8d59 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:22:48 +0100 Subject: [PATCH 02/22] fix sidebar_current of guide/hcl/from-json-v1 --- website/source/guides/hcl/from-json-v1/index.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/hcl/from-json-v1/index.html.md.erb b/website/source/guides/hcl/from-json-v1/index.html.md.erb index 07ccdbf2b..e3917c52d 100644 --- a/website/source/guides/hcl/from-json-v1/index.html.md.erb +++ b/website/source/guides/hcl/from-json-v1/index.html.md.erb @@ -1,7 +1,7 @@ --- layout: guides page_title: Transforming Packer v1 files for Packer v1.5.0 -sidebar_current: hcl +sidebar_current: hcl-from-json-v1 description: |- Learn how to manually move from a Packer v1 working JSON build file to a working v1.5.0 HCL file. From da90c22c35f0bdd47f4a929bfbca3f8cda457620 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:51:13 +0100 Subject: [PATCH 03/22] Update index.html.md.erb better title --- website/source/guides/hcl/from-json-v1/index.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/hcl/from-json-v1/index.html.md.erb b/website/source/guides/hcl/from-json-v1/index.html.md.erb index e3917c52d..4c62edf47 100644 --- a/website/source/guides/hcl/from-json-v1/index.html.md.erb +++ b/website/source/guides/hcl/from-json-v1/index.html.md.erb @@ -7,7 +7,7 @@ description: |- working v1.5.0 HCL file. --- -# Transforming Packer v1 files for Packer v1.5 +# Transforming Packer v1 config files for Packer v1.5 -> **Note:** Starting from version **1.5.0** Packer can read HCL2 files. From 93b9f3cb80ff719842bba46a077394d864de3e41 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:51:32 +0100 Subject: [PATCH 04/22] rename --- .../component-object-spec/index.html.md.erb | 41 +++++++++++++++++++ .../component-object-spec/index.html.mr.erb | 37 ----------------- 2 files changed, 41 insertions(+), 37 deletions(-) create mode 100644 website/source/guides/hcl/component-object-spec/index.html.md.erb delete mode 100644 website/source/guides/hcl/component-object-spec/index.html.mr.erb diff --git a/website/source/guides/hcl/component-object-spec/index.html.md.erb b/website/source/guides/hcl/component-object-spec/index.html.md.erb new file mode 100644 index 000000000..e1acbcbe6 --- /dev/null +++ b/website/source/guides/hcl/component-object-spec/index.html.md.erb @@ -0,0 +1,41 @@ +--- +layout: guides +page_title: Generating code for congig spec. +sidebar_current: hcl +description: |- + Learn how to generate the HCL2 configuration of your component easily. +--- + +# Auto Generate the HCL2 code of a plugin + +From version 1.5.0 Packer can be configured using HCL2. Because Packer has so +many builders, provisioner & post-proessors, we relied on code generation to +iterate more easily. The good new is that you can benefit from this code +generator to get the HCL2 spec code of your component simply. Is it a Go binary +package and is located in `cmd/mapstructure-to-hcl2`. + +Say you want to configure the Config struct of a Builder in a package located +in `my/example-plugin/config.go`. Here are some simple steps you can follow to +have most of the code generated: + +* run `go install github.com/hashicorp/packer/cmd/mapstructure-to-hcl2` + +* Add `//go:generate mapstructure-to-hcl2 -type Config` at the top of +`config.go` + +* run `go generate my/example-plugin` + + This will generate a `my/example-plugin/config.hcl2spec.go` file containing + the configuration fields of Config. + +* Make sure that all the nested fields of Config are auto generated the same way. + +* Now we only need to make Builder implement the interface by adding the +following snippet: + + ```go + func (b *Builder) ConfigSpec() hcldec.ObjectSpec { return b.config.FlatMapstructure().HCL2Spec() } + ``` + + From now one every time you add or change a field of Config you will need to + run he `go generate` command again. diff --git a/website/source/guides/hcl/component-object-spec/index.html.mr.erb b/website/source/guides/hcl/component-object-spec/index.html.mr.erb deleted file mode 100644 index 68ebe0178..000000000 --- a/website/source/guides/hcl/component-object-spec/index.html.mr.erb +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: guides -page_title: Generating code for congig spec. -sidebar_current: hcl -description: |- - Learn how to generate the HCL2 configuration of your component easily. ---- - -# Packer 1.5.0 can be - -From version 1.5.0 Packer can be configured using HCL2. Because Packer has so -many builders, provisioner & post-proessors, we relied on code generation to -iterate more easily. The good new is that you can benefit from this code -generator to get the HCL2 spec of your component simply. Is it a Go binary -package and is located in `cmd/mapstructure-to-hcl2`. Here are some simple -steps you can follow to have most of the code required : - -Say you want to configure the Config struct of a Builder in a package located -in `my/example-plugin/config.go`. - -* run `go install github.com/hashicorp/packer/cmd/mapstructure-to-hcl2` - -* Add `//go:generate mapstructure-to-hcl2 -type Config` at the top of -`config.go` - -* run `go generate my/example-plugin` - -This will generate a `my/example-plugin/config.hcl2spec.go` file containing the -configuration fields of Config. Now we only need to make Builder implement the -interface by adding the following snippet: - -```go -func (b *Builder) ConfigSpec() hcldec.ObjectSpec { return b.config.FlatMapstructure().HCL2Spec() } -``` - -From now one every time you add or change a field of Config you will need to -run he `go generate` command again. From 8dc587967ecd1ae75b42906b96da0dd466e337e1 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:51:38 +0100 Subject: [PATCH 05/22] Update guides.erb --- website/source/layouts/guides.erb | 3 +++ 1 file changed, 3 insertions(+) diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb index 7d9859a39..32c081f82 100644 --- a/website/source/layouts/guides.erb +++ b/website/source/layouts/guides.erb @@ -7,6 +7,9 @@ > from JSON v1 + > + Making a plugin HCL2 enabled + > From f3629dbaf78057d2e0df3b3d06fde0c7ae944d46 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:57:01 +0100 Subject: [PATCH 06/22] Update index.html.md.erb fix sidebar_current --- .../source/guides/hcl/component-object-spec/index.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/hcl/component-object-spec/index.html.md.erb b/website/source/guides/hcl/component-object-spec/index.html.md.erb index e1acbcbe6..7be4178b0 100644 --- a/website/source/guides/hcl/component-object-spec/index.html.md.erb +++ b/website/source/guides/hcl/component-object-spec/index.html.md.erb @@ -1,7 +1,7 @@ --- layout: guides page_title: Generating code for congig spec. -sidebar_current: hcl +sidebar_current: hcl-component-object-spec description: |- Learn how to generate the HCL2 configuration of your component easily. --- From 9219a606a320f04b7c40b452209cd0d039424e36 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:57:28 +0100 Subject: [PATCH 07/22] move "Installing Packer" a little lower in the nav bar --- website/source/layouts/docs.erb | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index c6f13a3e3..657ed4867 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -1,9 +1,7 @@ <% wrap_layout :inner do %> <% content_for :sidebar do %>
    - > - Installing Packer - +
  • Terminology
    • > @@ -384,6 +382,12 @@
    + > + Installing Packer + + +
    + > Extending Packer
      From 971eac1701725f1b6f280dd0813e9d0aaa66965f Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:59:16 +0100 Subject: [PATCH 08/22] Update website/source/guides/hcl/component-object-spec/index.html.md.erb Co-Authored-By: Wilken Rivera --- .../source/guides/hcl/component-object-spec/index.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/hcl/component-object-spec/index.html.md.erb b/website/source/guides/hcl/component-object-spec/index.html.md.erb index 7be4178b0..6ec632a81 100644 --- a/website/source/guides/hcl/component-object-spec/index.html.md.erb +++ b/website/source/guides/hcl/component-object-spec/index.html.md.erb @@ -1,6 +1,6 @@ --- layout: guides -page_title: Generating code for congig spec. +page_title: Generating code for config spec. sidebar_current: hcl-component-object-spec description: |- Learn how to generate the HCL2 configuration of your component easily. From da12c7372649594dcdd301519427e2bdff514cbb Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:59:26 +0100 Subject: [PATCH 09/22] Update website/source/guides/hcl/component-object-spec/index.html.md.erb Co-Authored-By: Wilken Rivera --- .../source/guides/hcl/component-object-spec/index.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/hcl/component-object-spec/index.html.md.erb b/website/source/guides/hcl/component-object-spec/index.html.md.erb index 6ec632a81..3218b112d 100644 --- a/website/source/guides/hcl/component-object-spec/index.html.md.erb +++ b/website/source/guides/hcl/component-object-spec/index.html.md.erb @@ -37,5 +37,5 @@ following snippet: func (b *Builder) ConfigSpec() hcldec.ObjectSpec { return b.config.FlatMapstructure().HCL2Spec() } ``` - From now one every time you add or change a field of Config you will need to + From now on every time you add or change a field of Config you will need to run he `go generate` command again. From 978af9188fc79e0eaedf11ff9d73e53d24321487 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:59:33 +0100 Subject: [PATCH 10/22] Update website/source/guides/hcl/component-object-spec/index.html.md.erb Co-Authored-By: Wilken Rivera --- .../source/guides/hcl/component-object-spec/index.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/hcl/component-object-spec/index.html.md.erb b/website/source/guides/hcl/component-object-spec/index.html.md.erb index 3218b112d..4d75fc4e4 100644 --- a/website/source/guides/hcl/component-object-spec/index.html.md.erb +++ b/website/source/guides/hcl/component-object-spec/index.html.md.erb @@ -38,4 +38,4 @@ following snippet: ``` From now on every time you add or change a field of Config you will need to - run he `go generate` command again. + run the `go generate` command again. From 04a875881127d309471e11d6eeca4dd253065e05 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 15:59:53 +0100 Subject: [PATCH 11/22] Update website/source/guides/hcl/from-json-v1/index.html.md.erb Co-Authored-By: Wilken Rivera --- website/source/guides/hcl/from-json-v1/index.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/hcl/from-json-v1/index.html.md.erb b/website/source/guides/hcl/from-json-v1/index.html.md.erb index 4c62edf47..cee1b0ac9 100644 --- a/website/source/guides/hcl/from-json-v1/index.html.md.erb +++ b/website/source/guides/hcl/from-json-v1/index.html.md.erb @@ -7,7 +7,7 @@ description: |- working v1.5.0 HCL file. --- -# Transforming Packer v1 config files for Packer v1.5 +# Transforming Packer v1 config files to HCL2 for Packer v1.5 -> **Note:** Starting from version **1.5.0** Packer can read HCL2 files. From 26ceea0c36ff1afb56d1d5de57242d603dd2f7a6 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 16:13:52 +0100 Subject: [PATCH 12/22] update custon provider docs --- website/source/docs/extending/custom-builders.html.md | 3 ++- website/source/docs/extending/custom-post-processors.html.md | 1 + website/source/docs/extending/custom-provisioners.html.md | 3 ++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/website/source/docs/extending/custom-builders.html.md b/website/source/docs/extending/custom-builders.html.md index 63cfdb40b..1cd2b6094 100644 --- a/website/source/docs/extending/custom-builders.html.md +++ b/website/source/docs/extending/custom-builders.html.md @@ -31,7 +31,8 @@ method should do. ``` go type Builder interface { - Prepare(...interface{}) error + ConfigSpec() hcldec.ObjectSpec + Prepare(...interface{}) ([]string, []string, error) Run(context.Context, ui Ui, hook Hook) (Artifact, error) } ``` diff --git a/website/source/docs/extending/custom-post-processors.html.md b/website/source/docs/extending/custom-post-processors.html.md index e940047b3..7f717346a 100644 --- a/website/source/docs/extending/custom-post-processors.html.md +++ b/website/source/docs/extending/custom-post-processors.html.md @@ -36,6 +36,7 @@ explaining what each method should do. ``` go type PostProcessor interface { + ConfigSpec() hcldec.ObjectSpec Configure(interface{}) error PostProcess(context.Context, Ui, Artifact) (a Artifact, keep, mustKeep bool, err error) } diff --git a/website/source/docs/extending/custom-provisioners.html.md b/website/source/docs/extending/custom-provisioners.html.md index 7cfd55939..0d6d7f15b 100644 --- a/website/source/docs/extending/custom-provisioners.html.md +++ b/website/source/docs/extending/custom-provisioners.html.md @@ -35,8 +35,9 @@ explaining what each method should do. ``` go type Provisioner interface { + ConfigSpec() hcldec.ObjectSpec Prepare(...interface{}) error - Provision(Ctx, Ui, Communicator, new(interface{})) error + Provision(context.Context, Ui, Communicator, map[string]interface{}) error } ``` From bb72a0c0cea80cdc24e80c57c4a375b84d1b7369 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 16:57:36 +0100 Subject: [PATCH 13/22] document hcl language & syntax --- .../docs/configuration/from-1.5/index.html.md | 74 +++++++++++ .../configuration/from-1.5/syntax.html.md | 119 ++++++++++++++++++ website/source/layouts/docs.erb | 11 ++ 3 files changed, 204 insertions(+) create mode 100644 website/source/docs/configuration/from-1.5/index.html.md create mode 100644 website/source/docs/configuration/from-1.5/syntax.html.md diff --git a/website/source/docs/configuration/from-1.5/index.html.md b/website/source/docs/configuration/from-1.5/index.html.md new file mode 100644 index 000000000..ff3953d70 --- /dev/null +++ b/website/source/docs/configuration/from-1.5/index.html.md @@ -0,0 +1,74 @@ +--- +layout: "docs" +page_title: "Configuration Language" +sidebar_current: "configuration" +description: |- + Packer uses text files to describe infrastructure and to set variables. + These text files are called Packer _configurations_ and are + written in the HCL language. +--- + +# HCL Configuration Language + +Packer uses the Hashicorp Configuration Language - HCL - designed to allow +concise descriptions of the required steps to get to a build file. + +## Builds + +The main purpose of the HCL language is defining builds and sources. All other +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 +will be parsed using the HCL2 schema. For every other case; the *JSON only* old +packer schema will be used. + +## Arguments, Blocks, and Expressions + +The syntax of the HCL language consists of only a few basic elements: + +```hcl +source "amazon-ebs" "main" { + ami_name = "main-ami" +} + + "" "" { + # Block body + = # Argument +} +``` + +- _Blocks_ are containers for other content and usually represent the + configuration of some kind of object, like a source. Blocks have a + _block type,_ can have zero or more _labels,_ and have a _body_ that contains + any number of arguments and nested blocks. Most of Packer's features are + controlled by top-level blocks in a configuration file. +- _Arguments_ assign a value to a name. They appear within blocks. +- _Expressions_ represent a value, either literally or by referencing and + combining other values. They appear as values for arguments, or within other + expressions. + +For full details about Packer's syntax, see: + +- [Configuration Syntax](./syntax.html) +- [Expressions](./expressions.html) + +## Code Organization + +The HCL language uses configuration files that are named with the `.pkr.hcl` +file extension. There is also [a JSON-based variant of the +language](./syntax-json.html) that is named with the `.pkr.json` file +extension. + +Configuration files must always use UTF-8 encoding, and by convention are +usually maintained with Unix-style line endings (LF) rather than Windows-style +line endings (CRLF), though both are accepted. + +## Configuration Ordering + +The ordering of root blocks is not significant. The order of `provisioner` or +`post-processor` blocks within a `build` is the only major feature where block +order matters. diff --git a/website/source/docs/configuration/from-1.5/syntax.html.md b/website/source/docs/configuration/from-1.5/syntax.html.md new file mode 100644 index 000000000..4bcbb4e91 --- /dev/null +++ b/website/source/docs/configuration/from-1.5/syntax.html.md @@ -0,0 +1,119 @@ +--- +layout: "docs" +page_title: "Syntax - Configuration Language" +sidebar_current: configuration-syntax +description: |- + HCL has its own syntax, intended to combine declarative + structure with expressions in a way that is easy for humans to read and + understand. +--- + +# HCL Configuration Syntax + +Other pages in this section have described various configuration constructs +that can appear in HCL. This page describes the lower-level syntax of the +language in more detail, revealing the building blocks that those constructs +are built from. + +This page describes the _native syntax_ of HCL, which is a rich language +designed to be easy for humans to read and write. The constructs in HCL can +also be expressed in [JSON syntax](/syntax-json.html), which is harder for +humans to read and edit but easier to generate and parse programmatically. + +This low-level syntax of HCL is defined in terms of a syntax called _HCL_, +which is also used by configuration languages in other applications, and in +particular other HashiCorp products. It is not necessary to know all of the +details of HCL in order to use Packer, and so this page summarizes the most +important details. If you are interested, you can find a full definition of HCL +syntax in [the HCL native syntax +specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md). + +## Arguments and Blocks + +HCL syntax is built around two key syntax constructs: +arguments and blocks. + +### Arguments + +An _argument_ assigns a value to a particular name: + +```hcl +image_id = "abc123" +``` + +The identifier before the equals sign is the _argument name_, and the expression +after the equals sign is the argument's value. + +The context where the argument appears determines what value types are valid +(for example, each source type has a schema that defines the types of its +arguments), but many arguments accept arbitrary +[expressions](/expressions.html), which allow the value to +either be specified literally or generated from other values programmatically. + +### Blocks + +A _block_ is a container for other content: + +```hcl +source "amazon-ebs" "example" { + ami_name = "abc123" + + tags { + # ... + } +} +``` + +A block has a _type_ (`source` in this example). Each block type defines +how many _labels_ must follow the type keyword. The `source` block type +expects two labels, which are `amazon-ebs` and `example` in the example above. +A particular block type may have any number of required labels, or it may +require none as with the nested `tags` block type. + +After the block type keyword and any labels, the block _body_ is delimited +by the `{` and `}` characters. Within the block body, further arguments +and blocks may be nested, creating a hierarchy of blocks and their associated +arguments. + +HCL uses a limited number of _top-level block types,_ which +are blocks that can appear outside of any other block in a configuration file. +Most of Packer's features (including resources, input variables, output +values, data sources, etc.) are implemented as top-level blocks. + +## Identifiers + +Argument names, block type names, and the names of most Packer-specific +constructs like resources, input variables, etc. are all _identifiers_. + +Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`). +The first character of an identifier must not be a digit, to avoid ambiguity +with literal numbers. + +For complete identifier rules, Packer implements +[the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to +include the ASCII hyphen character `-`. + +## Comments + +HCL supports three different syntaxes for comments: + +* `#` begins a single-line comment, ending at the end of the line. +* `//` also begins a single-line comment, as an alternative to `#`. +* `/*` and `*/` are start and end delimiters for a comment that might span + over multiple lines. + +The `#` single-line comment style is the default comment style and should be +used in most cases. Automatic configuration formatting tools may automatically +transform `//` comments into `#` comments, since the double-slash style is +not idiomatic. + +## Character Encoding and Line Endings + +Packer configuration files must always be UTF-8 encoded. While the +delimiters of the language are all ASCII characters, Packer accepts +non-ASCII characters in identifiers, comments, and string values. + +Packer accepts configuration files with either Unix-style line endings +(LF only) or Windows-style line endings (CR then LF), but the idiomatic style +is to use the Unix convention, and so automatic configuration formatting tools +may automatically transform CRLF endings to LF. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 657ed4867..2099e6be0 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -1,6 +1,17 @@ <% wrap_layout :inner do %> <% content_for :sidebar do %>
        + + > + HCL + + + +
      • Terminology
        • From 8cdf8ca442c0a760723e6da21e0aa7a4f13a0e39 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 17:10:59 +0100 Subject: [PATCH 14/22] add syntax-json for HCL --- .../from-1.5/syntax-json.html.md | 276 ++++++++++++++++++ website/source/layouts/docs.erb | 3 + 2 files changed, 279 insertions(+) create mode 100644 website/source/docs/configuration/from-1.5/syntax-json.html.md diff --git a/website/source/docs/configuration/from-1.5/syntax-json.html.md b/website/source/docs/configuration/from-1.5/syntax-json.html.md new file mode 100644 index 000000000..39bbc05e0 --- /dev/null +++ b/website/source/docs/configuration/from-1.5/syntax-json.html.md @@ -0,0 +1,276 @@ +--- +layout: "docs" +page_title: "JSON Configuration Syntax - Configuration Language" +sidebar_current: configuration-syntax-json +description: |- + In addition to the native syntax that is most commonly used with Packer, + the HCL language can also be expressed in a JSON-compatible syntax. +--- + +# JSON Configuration Syntax + + +Most Packer configurations are written in [the native HCL +syntax](./syntax.html), which is designed to be easy for humans to read and +update. + +Packer also supports an alternative syntax that is JSON-compatible. This +syntax is useful when generating portions of a configuration programmatically, +since existing JSON libraries can be used to prepare the generated +configuration files. + +The JSON syntax is defined in terms of the native syntax. Everything that can +be expressed in native syntax can also be expressed in JSON syntax, but some +constructs are more complex to represent in JSON due to limitations of the +JSON grammar. + +Packer expects native syntax for files named with a `.pkr.hcl` suffix, and JSON +syntax for files named with a `.pkr.json` suffix. + +The low-level JSON syntax, just as with the native syntax, is defined in terms +of a specification called _HCL_. It is not necessary to know all of the details +of HCL syntax or its JSON mapping in order to use Packer, and so this page +summarizes the most important differences between native and JSON syntax. If +you are interested, you can find a full definition of HCL's JSON syntax in [its +specification](https://github.com/hashicorp/hcl2/blob/master/hcl/spec.md). + +## JSON File Structure + +At the root of any JSON-based Packer configuration is a JSON object. The +properties of this object correspond to the top-level block types of the +Packer language. For example: + +```json +{ + "variables": { + "example": "value" + } +} +``` + +Each top-level object property must match the name of one of the expected +top-level block types. Block types that expect labels, such as `variable` shown +above, are represented by one nested object value for each level of label. +`source` blocks expect two labels, so two levels of nesting are required: + +```json +{ + "source": { + "amazon-ebs": { + "example": { + "instance_type": "t2.micro", + "ami_name": "ami-abc123" + } + } + } +} +``` + +After any nested objects representing the labels, finally one more nested +object represents the body of the block itself. In the above example the +`instance_type` and `ami_name` arguments for `source "amazon-ebs" "example"` +are specified. + +Taken together, the above two configuration files are equivalent to the +following blocks in the native syntax: + +```hcl +variables { + example = "value" +} + +source "amazon-ebs" "example" { + instance_type = "t2.micro" + ami_name = "ami-abc123" +} +``` + +Within each top-level block type the rules for mapping to JSON are slightly +different (see [Block-type-specific Exceptions][inpage-exceptions] below), but the following general rules apply in most cases: + +* The JSON object representing the block body contains properties that + correspond either to argument names or to nested block type names. + +* Where a property corresponds to an argument that accepts + [arbitrary expressions](./expressions.html) in the native syntax, the + property value is mapped to an expression as described under + [_Expression Mapping_](#expression-mapping) below. For arguments that + do _not_ accept arbitrary expressions, the interpretation of the property + value depends on the argument, as described in the + [block-type-specific exceptions](#block-type-specific-exceptions) + given later in this page. + +* Where a property name corresponds to an expected nested block type name, + the value is interpreted as described under + [_Nested Block Mapping_](#nested-block-mapping) below, unless otherwise + stated in [the block-type-specific exceptions](#block-type-specific-exceptions) + given later in this page. + +## Expression Mapping + +Since JSON grammar is not able to represent all of the Packer language +[expression syntax](./expressions.html), JSON values interpreted as expressions +are mapped as follows: + +| JSON | Packer Language Interpretation | +| ------- | ------------------------------------------------------------------------------------------------------------- | +| Boolean | A literal `bool` value. | +| Number | A literal `number` value. | +| String | Parsed as a [string template](./expressions.html#string-templates) and then evaluated as described below. | +| Object | Each property value is mapped per this table, producing an `object(...)` value with suitable attribute types. | +| Array | Each element is mapped per this table, producing a `tuple(...)` value with suitable element types. | +| Null | A literal `null`. | + +When a JSON string is encountered in a location where arbitrary expressions are +expected, its value is first parsed as a [string template](./expressions.html#string-templates) +and then it is evaluated to produce the final result. + +If the given template consists _only_ of a single interpolation sequence, +the result of its expression is taken directly, without first converting it +to a string. This allows non-string expressions to be used within the +JSON syntax. + +## Nested Block Mapping + +When a JSON object property is named after a nested block type, the value +of this property represents one or more blocks of that type. The value of +the property must be either a JSON object or a JSON array. + +The simplest situation is representing only a single block of the given type +when that type expects no labels, as with the `tags` nested block used +within `source` blocks: + +```json +{ + "source": { + "amazon-ebs": { + "example": { + "tags": { + "key": "value" + } + } + } + } +} +``` + +The above is equivalent to the following native syntax configuration: + +```hcl +source "amazon-ebs" "example" { + tags { + key = "value" + } +} +``` + +When the nested block type requires one or more labels, or when multiple +blocks of the same type can be given, the mapping gets a little more +complicated. For example, the `provisioner` nested block type used +within `source` blocks expects a label giving the provisioner to use, +and the ordering of provisioner blocks is significant to decide the order +of operations. + +The following native syntax example shows a `source` block with a number +of provisioners of different types: + +```hcl +source "amazon-ebs" "example" { + # (source configuration omitted for brevity) + + provisioner "shell-local" { + inline = ["echo 'Hello World' >example.txt"] + } + provisioner "file" { + source = "example.txt" + destination = "/tmp/example.txt" + } + provisioner "shell" { + inline = [ + "sudo install-something -f /tmp/example.txt", + ] + } +} +``` + +In order to preserve the order of these blocks, you must use a JSON array +as the direct value of the property representing this block type, as in +this JSON equivalent of the above: + +```json +{ + "source": { + "amazon-ebs": { + "example": { + "provisioner": [ + { + "shell-local": { + "inline": ["echo 'Hello World' >example.txt"] + } + }, + { + "file": { + "source": "example.txt", + "destination": "/tmp/example.txt" + } + }, + { + "shell": { + "inline": ["sudo install-something -f /tmp/example.txt"] + } + } + ] + } + } + } +} +``` + +Each element of the `provisioner` array is an object with a single property +whose name represents the label for each `provisioner` block. For block types +that expect multiple labels, this pattern of alternating array and object +nesting can be used for each additional level. + +If a nested block type requires labels but the order does _not_ matter, you +may omit the array and provide just a single object whose property names +correspond to unique block labels. This is allowed as a shorthand for the above +for simple cases, but the alternating array and object approach is the most +general. We recommend using the most general form if systematically converting +from native syntax to JSON, to ensure that the meaning of the configuration is +preserved exactly. + +### Comment Properties + +Although we do not recommend hand-editing of JSON syntax configuration files +-- this format is primarily intended for programmatic generation and consumption -- +a limited form of _comments_ are allowed inside JSON objects that represent +block bodies using a special property name: + +```json +{ + "source": { + "amazon-ebs": { + "example": { + "//": "This instance runs the scheduled tasks for backup", + + "instance_type": "t2.micro", + "ami_name": "ami-abc123" + } + } + } +} +``` + +In any object that represents a block body, properties named `"//"` are +ignored by Packer entirely. This exception does _not_ apply to objects +that are being [interpreted as expressions](#expression-mapping), where this +would be interpreted as an object type attribute named `"//"`. + +This special property name can also be used at the root of a JSON-based +configuration file. This can be useful to note which program created the file. + +```json +{ + "//": "This file is generated by generate-outputs.py. DO NOT HAND-EDIT!", +} +``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 2099e6be0..50fe5872d 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -8,6 +8,9 @@ > Syntax + > + JSON Syntax +
      From 0436457fd7644540242a6ab3730120911fa8f313 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 17:14:02 +0100 Subject: [PATCH 15/22] fix sidebar current --- .../source/docs/configuration/from-1.5/syntax-json.html.md | 2 +- website/source/layouts/docs.erb | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/source/docs/configuration/from-1.5/syntax-json.html.md b/website/source/docs/configuration/from-1.5/syntax-json.html.md index 39bbc05e0..741f20c09 100644 --- a/website/source/docs/configuration/from-1.5/syntax-json.html.md +++ b/website/source/docs/configuration/from-1.5/syntax-json.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "JSON Configuration Syntax - Configuration Language" -sidebar_current: configuration-syntax-json +sidebar_current: configuration-json-syntax description: |- In addition to the native syntax that is most commonly used with Packer, the HCL language can also be expressed in a JSON-compatible syntax. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 50fe5872d..56cec5264 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -3,12 +3,12 @@
        > - HCL + v1.5 Configuration Language From 7fe51022ca06db49f56b2475e05211c8d45dc803 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 18:16:10 +0100 Subject: [PATCH 16/22] add expression --- .../configuration/from-1.5/expression.html.md | 234 ++++++++++++++++++ website/source/layouts/docs.erb | 3 + 2 files changed, 237 insertions(+) create mode 100644 website/source/docs/configuration/from-1.5/expression.html.md diff --git a/website/source/docs/configuration/from-1.5/expression.html.md b/website/source/docs/configuration/from-1.5/expression.html.md new file mode 100644 index 000000000..1d32445f5 --- /dev/null +++ b/website/source/docs/configuration/from-1.5/expression.html.md @@ -0,0 +1,234 @@ +--- +layout: "docs" +page_title: "Expressions - Configuration Language" +sidebar_current: configuration-expressions +description: |- + HCL allows the use of expressions to access data exported + by resources and to transform and combine that data to produce other values. +--- + +# Expressions + +_Expressions_ are used to refer to or compute values within a configuration. +The simplest expressions are just literal values, like `"hello"` or `5`, but +HCL also allows more complex expressions such as references to data exported by +resources, arithmetic, conditional evaluation, and a number of built-in +functions. + +Expressions can be used in a number of places in HCL, but some contexts limit +which expression constructs are allowed, such as requiring a literal value of a +particular type or forbidding. Each language feature's documentation describes +any restrictions it places on expressions. + +The rest of this page describes all of the features of Packer's +expression syntax. + +## Types and Values + +The result of an expression is a _value_. All values have a _type_, which +dictates where that value can be used and what transformations can be +applied to it. + +HCL uses the following types for its values: + +* `string`: a sequence of Unicode characters representing some text, like + `"hello"`. +* `number`: a numeric value. The `number` type can represent both whole + numbers like `15` and fractional values like `6.283185`. +* `bool`: either `true` or `false`. `bool` values can be used in conditional + logic. +* `list` (or `tuple`): a sequence of values, like + `["us-west-1a", "us-west-1c"]`. Elements in a list or tuple are identified by + consecutive whole numbers, starting with zero. +* `map` (or `object`): a group of values identified by named labels, like + `{name = "Mabel", age = 52}`. + +Strings, numbers, and bools are sometimes called _primitive types._ +Lists/tuples and maps/objects are sometimes called _complex types,_ _structural +types,_ or _collection types._ + +Finally, there is one special value that has _no_ type: + +* `null`: a value that represents _absence_ or _omission._ If you set an + argument of a source or module to `null`, Packer behaves as though you + had completely omitted it — it will use the argument's default value if it has + one, or raise an error if the argument is mandatory. `null` is most useful in + conditional expressions, so you can dynamically omit an argument if a + condition isn't met. + +### Advanced Type Details + +In most situations, lists and tuples behave identically, as do maps and objects. +Whenever the distinction isn't relevant, the Packer documentation uses each +pair of terms interchangeably (with a historical preference for "list" and +"map"). + +However, module authors and provider developers should understand the +differences between these similar types (and the related `set` type), since they +offer different ways to restrict the allowed values for input variables and +source arguments. + +### Type Conversion + +Expressions are most often used to set values for the arguments of resources and +child modules. In these cases, the argument has an expected type and the given +expression must produce a value of that type. + +Where possible, Packer automatically converts values from one type to +another in order to produce the expected type. If this isn't possible, Packer +will produce a type mismatch error and you must update the configuration with a +more suitable expression. + +Packer automatically converts number and bool values to strings when needed. +It also converts strings to numbers or bools, as long as the string contains a +valid representation of a number or bool value. + +* `true` converts to `"true"`, and vice-versa +* `false` converts to `"false"`, and vice-versa +* `15` converts to `"15"`, and vice-versa + +## Literal Expressions + +A _literal expression_ is an expression that directly represents a particular +constant value. Packer has a literal expression syntax for each of the value +types described above: + +* Strings are usually represented by a double-quoted sequence of Unicode + characters, `"like this"`. There is also a "heredoc" syntax for more complex + strings. String literals are the most complex kind of literal expression in + Packer, and have additional documentation on this page: + * See [String Literals](#string-literals) below for information about escape + sequences and the heredoc syntax. + * See [String Templates](#string-templates) below for information about + interpolation and template directives. +* Numbers are represented by unquoted sequences of digits with or without a + decimal point, like `15` or `6.283185`. +* Bools are represented by the unquoted symbols `true` and `false`. +* The null value is represented by the unquoted symbol `null`. +* Lists/tuples are represented by a pair of square brackets containing a + comma-separated sequence of values, like `["a", 15, true]`. + + List literals can be split into multiple lines for readability, but always + require a comma between values. A comma after the final value is allowed, + but not required. Values in a list can be arbitrary expressions. +* Maps/objects are represented by a pair of curly braces containing a series of + ` = ` pairs: + + ```hcl + { + name = "John" + age = 52 + } + ``` + + Key/value pairs can be separated by either a comma or a line break. Values + can be arbitrary expressions. Keys are strings; they can be left unquoted if + they are a valid [identifier](./syntax.html#identifiers), but must be quoted + otherwise. You can use a non-literal expression as a key by wrapping it in + parentheses, like `(var.business_unit_tag_name) = "SRE"`. + +## References to Named Values + +Packer makes one named values available. + +The following named values are available: + +* `source..` is an object representing a + [source](./sources.html) of the given type + and name. The attributes of the source can be accessed using + [dot or square bracket notation][inpage-index]. + + Any named value that does not match another pattern listed below + will be interpreted by Packer as a reference to a managed source. + +### Named Values and Dependencies + +Constructs like resources and module calls often use references to named values +in their block bodies, and Packer analyzes these expressions to automatically +infer dependencies between objects. For example, an expression in a source +argument that refers to another managed source creates an implicit dependency +between the two resources. + +## String Literals + +HCL has two different syntaxes for string literals. The +most common is to delimit the string with quote characters (`"`), like +`"hello"`. In quoted strings, the backslash character serves as an escape +sequence, with the following characters selecting the escape behavior: + +| Sequence | Replacement | +| ------------ | ----------------------------------------------------------------------------- | +| `\n` | Newline | +| `\r` | Carriage Return | +| `\t` | Tab | +| `\"` | Literal quote (without terminating the string) | +| `\\` | Literal backslash | +| `\uNNNN` | Unicode character from the basic multilingual plane (NNNN is four hex digits) | +| `\UNNNNNNNN` | Unicode character from supplementary planes (NNNNNNNN is eight hex digits) | + +The alternative syntax for string literals is the so-called "heredoc" style, +inspired by Unix shell languages. This style allows multi-line strings to +be expressed more clearly by using a custom delimiter word on a line of its +own to close the string: + +```hcl +<> Syntax + > + Expressions + > JSON Syntax From 4c3fa0ef263bf11c9b8b8571b66a8c5de43caf50 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Thu, 19 Dec 2019 14:58:44 +0100 Subject: [PATCH 17/22] document split files & main building blocks in guide --- website/source/guides/hcl/index.html.md.erb | 34 +++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/website/source/guides/hcl/index.html.md.erb b/website/source/guides/hcl/index.html.md.erb index 5d66496bf..711cf6597 100644 --- a/website/source/guides/hcl/index.html.md.erb +++ b/website/source/guides/hcl/index.html.md.erb @@ -50,3 +50,37 @@ It could be super handy for a boot_command. EOF } ``` + +## Building blocks can be split in files + +Currently Packer offers the `source` and the `build` root blocks. These two +building blocks can be defined in any order an a `build` can import one or more +`source`. Usually a `source` defines what we currently call a builder and a +`build` can apply multiple provisioning steps to a source. For example: + +```hcl +# folder/sources.pkr.hcl +sources "amazon-ebs" "example-1" { + ami_name = "example-1-ami" +} + +sources "amazon-ebs" "example-2" { + ami_name = "example-2-ami" +} +``` + +```hcl +# folder/build.pkr.hcl +build { + sources = [ + "sources.amazon-ebs.example-1", + "sources.amazon-ebs.example-2" + ] + + provisioner "shell" { + inline = [ + "echo it's alive !" + ] + } +} +``` From 1d066082a5fa13ac30ac0b549bfd3a9750d0a319 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Thu, 19 Dec 2019 15:28:29 +0100 Subject: [PATCH 18/22] Update index.html.md.erb --- website/source/guides/hcl/index.html.md.erb | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/source/guides/hcl/index.html.md.erb b/website/source/guides/hcl/index.html.md.erb index 711cf6597..802954164 100644 --- a/website/source/guides/hcl/index.html.md.erb +++ b/website/source/guides/hcl/index.html.md.erb @@ -54,17 +54,17 @@ EOF ## Building blocks can be split in files Currently Packer offers the `source` and the `build` root blocks. These two -building blocks can be defined in any order an a `build` can import one or more +building blocks can be defined in any order and a `build` can import one or more `source`. Usually a `source` defines what we currently call a builder and a `build` can apply multiple provisioning steps to a source. For example: ```hcl # folder/sources.pkr.hcl -sources "amazon-ebs" "example-1" { +source "amazon-ebs" "example-1" { ami_name = "example-1-ami" } -sources "amazon-ebs" "example-2" { +source "amazon-ebs" "example-2" { ami_name = "example-2-ami" } ``` @@ -73,8 +73,8 @@ sources "amazon-ebs" "example-2" { # folder/build.pkr.hcl build { sources = [ - "sources.amazon-ebs.example-1", - "sources.amazon-ebs.example-2" + "source.amazon-ebs.example-1", + "source.amazon-ebs.example-2" ] provisioner "shell" { From 31cad234f28e94464a14f7b833b7ac8546426e2f Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Thu, 19 Dec 2019 15:34:26 +0100 Subject: [PATCH 19/22] Update index.html.md.erb --- website/source/guides/hcl/index.html.md.erb | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/website/source/guides/hcl/index.html.md.erb b/website/source/guides/hcl/index.html.md.erb index 802954164..555d06c94 100644 --- a/website/source/guides/hcl/index.html.md.erb +++ b/website/source/guides/hcl/index.html.md.erb @@ -64,8 +64,12 @@ source "amazon-ebs" "example-1" { ami_name = "example-1-ami" } -source "amazon-ebs" "example-2" { - ami_name = "example-2-ami" +source "virtualbox-iso" "example-2" { + boot_command = < +/install/vmlinuz noapic +... +EOF } ``` @@ -74,7 +78,7 @@ source "amazon-ebs" "example-2" { build { sources = [ "source.amazon-ebs.example-1", - "source.amazon-ebs.example-2" + "source.virtualbox-iso.example-2" ] provisioner "shell" { From fbd3796377581f18fcb93f58cdb2d5e9c8129d7c Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Thu, 19 Dec 2019 15:40:08 +0100 Subject: [PATCH 20/22] Update index.html.md.erb --- .../component-object-spec/index.html.md.erb | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/website/source/guides/hcl/component-object-spec/index.html.md.erb b/website/source/guides/hcl/component-object-spec/index.html.md.erb index 4d75fc4e4..f548abdc8 100644 --- a/website/source/guides/hcl/component-object-spec/index.html.md.erb +++ b/website/source/guides/hcl/component-object-spec/index.html.md.erb @@ -8,27 +8,28 @@ description: |- # Auto Generate the HCL2 code of a plugin -From version 1.5.0 Packer can be configured using HCL2. Because Packer has so -many builders, provisioner & post-proessors, we relied on code generation to +From v1.5, Packer can be configured using HCL2. Because Packer has so many +builders, provisioner & post-processors, we relied on code generation to iterate more easily. The good new is that you can benefit from this code -generator to get the HCL2 spec code of your component simply. Is it a Go binary -package and is located in `cmd/mapstructure-to-hcl2`. +generator to get the HCL2 spec code of your component simply. It's a Go binary +package and is located in [`cmd/mapstructure-to-hcl2`](https://github.com/hashicorp/packer/tree/master/cmd/mapstructure-to-hcl2). -Say you want to configure the Config struct of a Builder in a package located -in `my/example-plugin/config.go`. Here are some simple steps you can follow to -have most of the code generated: +Say you want to configure the `Config` struct of a `Builder` in a package +located in `my/example-plugin/config.go`. Here are some simple steps you can +follow to make it HCL2 enabled: * run `go install github.com/hashicorp/packer/cmd/mapstructure-to-hcl2` * Add `//go:generate mapstructure-to-hcl2 -type Config` at the top of `config.go` -* run `go generate my/example-plugin` +* run `go generate ./my/example-plugin/...` This will generate a `my/example-plugin/config.hcl2spec.go` file containing - the configuration fields of Config. + the configuration fields of `Config`. -* Make sure that all the nested fields of Config are auto generated the same way. +* Make sure that all the nested structs of `Config` are also auto generated the + same way. * Now we only need to make Builder implement the interface by adding the following snippet: @@ -39,3 +40,5 @@ following snippet: From now on every time you add or change a field of Config you will need to run the `go generate` command again. + +A good example of this is the [Config struct of the amazon-ebs builder](https://github.com/hashicorp/packer/blob/master/builder/amazon/ebs/builder.go) \ No newline at end of file From 46ce0529dda37981a674eb40e03cdd7ed10d42f1 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Thu, 19 Dec 2019 16:23:30 +0100 Subject: [PATCH 21/22] docs ++ --- ...expression.html.md => expressions.html.md} | 38 +++++++------------ .../from-1.5/syntax-json.html.md | 2 +- .../configuration/from-1.5/syntax.html.md | 4 +- website/source/layouts/docs.erb | 2 +- 4 files changed, 17 insertions(+), 29 deletions(-) rename website/source/docs/configuration/from-1.5/{expression.html.md => expressions.html.md} (89%) diff --git a/website/source/docs/configuration/from-1.5/expression.html.md b/website/source/docs/configuration/from-1.5/expressions.html.md similarity index 89% rename from website/source/docs/configuration/from-1.5/expression.html.md rename to website/source/docs/configuration/from-1.5/expressions.html.md index 1d32445f5..8c2069a26 100644 --- a/website/source/docs/configuration/from-1.5/expression.html.md +++ b/website/source/docs/configuration/from-1.5/expressions.html.md @@ -135,19 +135,7 @@ The following named values are available: * `source..` is an object representing a [source](./sources.html) of the given type - and name. The attributes of the source can be accessed using - [dot or square bracket notation][inpage-index]. - - Any named value that does not match another pattern listed below - will be interpreted by Packer as a reference to a managed source. - -### Named Values and Dependencies - -Constructs like resources and module calls often use references to named values -in their block bodies, and Packer analyzes these expressions to automatically -infer dependencies between objects. For example, an expression in a source -argument that refers to another managed source creates an implicit dependency -between the two resources. + and name. ## String Literals @@ -166,24 +154,24 @@ sequence, with the following characters selecting the escape behavior: | `\uNNNN` | Unicode character from the basic multilingual plane (NNNN is four hex digits) | | `\UNNNNNNNN` | Unicode character from supplementary planes (NNNNNNNN is eight hex digits) | -The alternative syntax for string literals is the so-called "heredoc" style, -inspired by Unix shell languages. This style allows multi-line strings to -be expressed more clearly by using a custom delimiter word on a line of its -own to close the string: +The alternative syntax for string literals is the so-called Here Documents or +"heredoc" style, inspired by Unix shell languages. This style allows multi-line +strings to be expressed more clearly by using a custom delimiter word on a line +of its own to close the string: ```hcl -<Syntax > - Expressions + Expressions > JSON Syntax From d0e9242b3d2272d7d65639c1ec2781e423f933bf Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Thu, 19 Dec 2019 17:31:07 +0100 Subject: [PATCH 22/22] trigger preview