From 54da4b047f1be8653aec41298c23b39091226ec6 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 28 Jan 2025 09:44:33 -0800 Subject: [PATCH] hcl templates content except functions --- .../hcl_templates/contextual-variables.mdx | 19 ++++++------ .../templates/hcl_templates/datasources.mdx | 21 +++++--------- .../templates/hcl_templates/expressions.mdx | 11 +++---- .../docs/templates/hcl_templates/index.mdx | 24 +++++++-------- .../docs/templates/hcl_templates/locals.mdx | 26 ++++++----------- .../templates/hcl_templates/onlyexcept.mdx | 19 ++++++------ .../hcl_templates/path-variables.mdx | 19 ++++++++---- .../templates/hcl_templates/syntax-json.mdx | 17 ++++------- .../docs/templates/hcl_templates/syntax.mdx | 25 +++++----------- .../templates/hcl_templates/variables.mdx | 29 ++++--------------- .../from-1.5/contextual-source-variables.mdx | 25 +++++++++------- .../content/partials/path/separator-note.mdx | 9 ++---- 12 files changed, 103 insertions(+), 141 deletions(-) diff --git a/website/content/docs/templates/hcl_templates/contextual-variables.mdx b/website/content/docs/templates/hcl_templates/contextual-variables.mdx index 03c04d82c86..50791222f6c 100644 --- a/website/content/docs/templates/hcl_templates/contextual-variables.mdx +++ b/website/content/docs/templates/hcl_templates/contextual-variables.mdx @@ -1,17 +1,16 @@ --- -page_title: Contextual Variables - HCL Configuration Language +page_title: Contextual variables reference description: >- - Special variables provide connection information and basic instance state - information. - - This page covers all existing special variables. + Source variabls, build variables, and other special variables are context dependent. Learn about contextual variables that provide connection and instance state information. --- -`@include 'from-1.5/beta-hcl2-note.mdx'` +# Contextual variables + +This topic provides reference information about special variables that return connection and basic instance state information based on the configuration context. `@include 'from-1.5/contextual-source-variables.mdx'` -# Build Variables +## Build Variables Build variables will allow you to access connection information and basic instance state information for a builder. All special build variables are stored in the `build` variable: @@ -86,7 +85,7 @@ For builder-specific builder variables, please also refer to the builder docs: The HCL2 Special Build Variables is in beta; please report any issues or requests on the Packer issue tracker on GitHub. -# Packer Version +## Packer Version This variable is set to the Packer version currently running. @@ -130,7 +129,7 @@ Make sure to wrap your variable in single quotes in order to escape the string that is returned; if you are running a dev version of packer the parenthesis may through off your shell escaping otherwise. -# HCP Packer Iteration ID +## HCP Packer Iteration ID ~> **Note**: The `packer.iterationID` variable is now deprecated and will be removed in a future version of Packer. HCP Packer Versions should be accessed with their fingerprint instead. The `packer.versionFingerprint` variable is now exposed to be used in its stead with the new HCP Packer data sources. @@ -176,7 +175,7 @@ build { mybuild.null.example: data is 01HN3KCRPVKR5PBQ28TS6B12W0 ``` -# HCP Packer Version Fingerprint +## HCP Packer Version Fingerprint If your build is pushing metadata to the HCP Packer registry, this variable is set to the value of the Version Fingerprint associated with this run. diff --git a/website/content/docs/templates/hcl_templates/datasources.mdx b/website/content/docs/templates/hcl_templates/datasources.mdx index 3a8878ff3f7..794841c3ef2 100644 --- a/website/content/docs/templates/hcl_templates/datasources.mdx +++ b/website/content/docs/templates/hcl_templates/datasources.mdx @@ -1,20 +1,15 @@ --- page_title: Data Sources description: >- - Data sources allow data to be fetched or computed for use elsewhere in local variables and - build sources configuration. Use of data sources - allows a Builder to make use of information defined outside of Packer. + A `data` block defines a data source that instructs Packer to query data defined outside of Packer for use in builds and sources. Learn how to configure `data` blocks to define data sources. --- -# Data Sources +# Data sources reference --> **Note:** Data Sources is a feature included in Packer 1.7 and later. +This topic describes how to use the `data` block to configure data sources in your HCL Packer templates. The `data` block instructs Packer to fetch or compute data for use in [`locals` blocks](/packer/docs/templates/hcl_templates/blocks/locals) and +[`source` blocks](/packer/docs/templates/hcl_templates/blocks/source) so that builders can use of information defined outside of Packer. -Data sources allow data to be fetched or computed for use elsewhere in [locals](/packer/docs/templates/hcl_templates/blocks/locals) and -[sources](/packer/docs/templates/hcl_templates/blocks/source) configuration. -Use of data sources allows a Builder to make use of information defined outside of Packer. - -# Using Data Sources +## Using data sources A data source is declared using a data block, and the configuration looks like the following: @@ -30,8 +25,8 @@ data "amazon-ami" "example" { } ``` -A data block requests that Packer read from a given data source ("amazon-ami") and export the result under the given -local name ("example"). The name is used to refer to this data source from elsewhere in the same Packer configuration. +A `data` block requests that Packer read from a given data source (`"amazon-ami"`) and export the result under the given +local name (`"example"`). The name is used to refer to this data source from elsewhere in the same Packer configuration. The data block creates a data instance of the given _type_ (first block label) and _name_ (second block label). The combination of the type and name must be unique within a configuration. @@ -75,7 +70,7 @@ source "amazon-ebs" "basic-example" { } ``` -## Known Limitations +## Known limitations `@include 'datasources/local-dependency-limitation.mdx'` diff --git a/website/content/docs/templates/hcl_templates/expressions.mdx b/website/content/docs/templates/hcl_templates/expressions.mdx index 22b38b24fd4..7c737792f2e 100644 --- a/website/content/docs/templates/hcl_templates/expressions.mdx +++ b/website/content/docs/templates/hcl_templates/expressions.mdx @@ -1,13 +1,14 @@ --- -page_title: Expressions - Configuration Language +page_title: HCL expressions reference description: |- - HCL allows the use of expressions to access data exported - by sources and to transform and combine that data to produce other values. + HCL expresssions provide access to data exported by data sources and transforms and combines the data into other values. Learn how to use HCL expressions in Packer templates. --- -# Expressions +# HCL expressions reference -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about expressions you can use in HCL templates for Packer. + +## Introduction _Expressions_ are used to refer to or compute values within a configuration. The simplest expressions are just literal values, like `"hello"` or `5`, but diff --git a/website/content/docs/templates/hcl_templates/index.mdx b/website/content/docs/templates/hcl_templates/index.mdx index 72d845f8f29..97f2b164bc1 100644 --- a/website/content/docs/templates/hcl_templates/index.mdx +++ b/website/content/docs/templates/hcl_templates/index.mdx @@ -1,20 +1,16 @@ --- -page_title: HCL Templates +page_title: HCL templates overview description: |- - Packer uses text files to describe infrastructure and to set variables. - These text files are called Packer _configurations_ and are - written in the HCL2 HashiCorp Configuration Language. + HCL templates are configuration files that describe infrastructure and set variables using HashiCorp configuration language (HCL). Learn about HCL templates for Packer. --- -# HCL Configuration Language +# HCL templates overview -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides overview information about HashiCorp configuration language (HCL) template for Packer. -Packer uses the HashiCorp Configuration Language - HCL - designed to allow -concise descriptions of the required steps to get to a build file. This page -describes the features of HCL2 exhaustively, if you would like to give a quick -try to HCL2, you can also read the quicker [HCL2 getting started -guide](/packer/guides/hcl). +## Introduction + +Packer reads and applies configurations defined in HCL template files. HCL templates provide concise descriptions of the required steps to get to a build file. You can add arguments, blocks, and expressions to your HCL templates to define your build as code. Refer to [Introduction to Packer HCL2](/packer/guides/hcl) for additional information. ## Builds @@ -28,7 +24,7 @@ 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 +## Arguments, blocks, and expressions The syntax of the HCL language consists of only a few basic elements: @@ -58,7 +54,7 @@ For full details about Packer's syntax, see: - [Configuration Syntax](/packer/docs/templates/hcl_templates/syntax) - [Expressions](/packer/docs/templates/hcl_templates/expressions) -## Code Organization +## 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 @@ -69,7 +65,7 @@ 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 +## 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 diff --git a/website/content/docs/templates/hcl_templates/locals.mdx b/website/content/docs/templates/hcl_templates/locals.mdx index 456f6af90ec..794088022a6 100644 --- a/website/content/docs/templates/hcl_templates/locals.mdx +++ b/website/content/docs/templates/hcl_templates/locals.mdx @@ -1,30 +1,22 @@ --- -page_title: Local Variables - HCL Configuration Language +page_title: Local variables description: >- - Local variables assign a name to an expression that you can use multiple - times within a folder. + The `local` and `locals` blocks define local variables that assign a name to an expression. Learn how to configure local variables. --- -# Local Variables +# Local variables -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the `local` and `locals` blocks, which define local variables that you can use in your Packer templates. To learn about input variables, refer to +[Input variables](/packer/docs/templates/hcl_templates/variables). -There are two kinds of variables in HCL Packer templates: Input variables, -sometimes simply called "variables", and Local variables, also known as -"locals". Input variables may have defaults, but those defaults can be -overridden using command line options, environment variables, or variable -definitions files. Local variables can not be overridden. - -This page is about local variables. To learn about input variables, see the -[input variables](/packer/docs/templates/hcl_templates/variables) page. +## Introduction Local variables assign a name to an expression, which you can use multiple times within a folder. The expression is evaluated at run time, and can reference input variables, other local variables, data sources, and HCL -functions. +functions. You cannot overwrite local variables. -Input variable and local variable usage are introduced in the [_Variables -Guide_](/packer/guides/hcl/variables). +Refer to [Input Variables and local variables](/packer/guides/hcl/variables) for additional information about variables in Packer. ## Examples @@ -126,7 +118,7 @@ _unrelated_ local variables in _separate_ blocks, and consider annotating each block with a comment describing any context common to all of the enclosed locals. -## Known Limitations +## Known limitations `@include 'datasources/local-dependency-limitation.mdx'` diff --git a/website/content/docs/templates/hcl_templates/onlyexcept.mdx b/website/content/docs/templates/hcl_templates/onlyexcept.mdx index 3aab1084c5d..3ca8832653c 100644 --- a/website/content/docs/templates/hcl_templates/onlyexcept.mdx +++ b/website/content/docs/templates/hcl_templates/onlyexcept.mdx @@ -1,21 +1,22 @@ --- -page_title: Only Except - HCL Configuration Language +page_title: only and except keywords reference description: >- - Only and Except can be used as a command line argument to selectively run - builds. Only and Except can also be used in a provisioner to not run it for a - source. + The `only` and `except` keywords are filters for Packer builds. Learn how to use `only` and `except` to selectively run provisioners and post-processors. --- -# Only and Except +# `only` and `except` keywords -`only` and `except` are keywords used to filter what runs in your Packer build, -they can be seen as a command line argument: +The `only` and `except` keywords are filters that let you selectively run provisioners and post-processors in your Packer build. You can use the keywords in your Packer templates and as flags on the Packer CLI. + +## Command line flags `@include 'commands/except.mdx'` `@include 'commands/only.mdx'` -They can also be seen in a template to run or skip provisioners and/or +## Templates + +You can add the `only` and `except` keywords to run or skip provisioners and post-processors for a specific source: ```hcl @@ -63,7 +64,7 @@ build { # amazon-ebs.third-example ``` -Note that cli arguments can be used with a glob operator, using the previous +Note that CLI arguments can be used with a glob operator, using the previous configuration: - `packer build -only 'my_build.*' dir`: will only run the builds in blocks diff --git a/website/content/docs/templates/hcl_templates/path-variables.mdx b/website/content/docs/templates/hcl_templates/path-variables.mdx index fb9b74defc9..420ff3af3d2 100644 --- a/website/content/docs/templates/hcl_templates/path-variables.mdx +++ b/website/content/docs/templates/hcl_templates/path-variables.mdx @@ -1,14 +1,17 @@ --- -page_title: Path Variables - HCL Configuration Language +page_title: Path variables reference description: |- - Special variables provide directory information. This page covers all path - variables. + Path variables are special variables that enable you to provide directory information. Learn how to use path variables in Packer templates. --- -`@include 'path/separator-note.mdx'` - # Path variables +This topic provides reference information about path variables for Packer templates written in HCL. + +## Description + +Use the following variables to build paths: + - `path.cwd`: the directory from where Packer was started. - `path.root`: the directory of the input HCL file or the input folder. @@ -23,7 +26,11 @@ locals { } ``` -## Related Functions +## Path separators + +`@include 'path/separator-note.mdx'` + +## Related functions - [`abspath`](/packer/docs/templates/hcl_templates/functions/file/abspath) takes a string containing a filesystem path and converts it to an absolute path. diff --git a/website/content/docs/templates/hcl_templates/syntax-json.mdx b/website/content/docs/templates/hcl_templates/syntax-json.mdx index 414f864a0ec..276f78433c2 100644 --- a/website/content/docs/templates/hcl_templates/syntax-json.mdx +++ b/website/content/docs/templates/hcl_templates/syntax-json.mdx @@ -1,21 +1,16 @@ --- -page_title: JSON Configuration Syntax - Configuration Language +page_title: JSON syntax reference 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. + A JSON configuration expresses HCL Packer templates as JSON-compatible syntax. Learn about the JSON syntax for creating HCL Packer templates. --- -# JSON Configuration Syntax +# JSON syntax reference -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the JSON syntax you can use to express HCL Packer templates as JSON. For information about the HCL syntax, refer to [HCL syntax reference](/packer/docs/templates/hcl_templates/syntax). -Most Packer configurations are written in [the native HCL -syntax](/packer/docs/templates/hcl_templates/syntax), which is designed to be easy for humans to read and -update. +## Introduction -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 +Packer supports templates written in JSON, which is useful when generating portions of a configuration programmatically. This is because you can use existing JSON libraries to prepare the generated configuration files. This syntax is not to be confused with the pre-version-1.5 "legacy" Packer diff --git a/website/content/docs/templates/hcl_templates/syntax.mdx b/website/content/docs/templates/hcl_templates/syntax.mdx index 7ed024eca5d..6079104197e 100644 --- a/website/content/docs/templates/hcl_templates/syntax.mdx +++ b/website/content/docs/templates/hcl_templates/syntax.mdx @@ -1,27 +1,18 @@ --- -page_title: Syntax - Configuration Language +page_title: HCL syntax reference 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. + The HCL syntax combines declarative structure with expressions into Packer templates. Learn about the HCL syntax for defining infrastructure as code. --- -# HCL Configuration Syntax +# HCL syntax reference -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about the native HashiCorp configuration language (HCL) syntax you can use to create Packer templates. For information about HCL constructs in JSON, refer to the [JSON syntax reference](/packer/docs/templates/hcl_templates/syntax-json). -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. +## Introduction -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](/packer/docs/templates/hcl_templates/syntax-json), 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 +Learning the HCL syntax helps you understand the building blocks that Packer template constructs +are built from. HCL is a rich language designed to be easy for humans to read and write. +Otherwhich 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 diff --git a/website/content/docs/templates/hcl_templates/variables.mdx b/website/content/docs/templates/hcl_templates/variables.mdx index 4c8f856fafc..a52388779de 100644 --- a/website/content/docs/templates/hcl_templates/variables.mdx +++ b/website/content/docs/templates/hcl_templates/variables.mdx @@ -1,36 +1,19 @@ --- -page_title: Input Variables - HCL Configuration Language +page_title: Input variables reference description: |- Input variables are parameters for Packer modules. - This page covers configuration syntax for variables. + Learn how to use the input variable syntax for Packer templates written in HCL. --- # Input Variables -`@include 'from-1.5/beta-hcl2-note.mdx'` +This topic provides reference information about input variables in Packer templates. Refer to [Local Variables](/packer/docs/templates/hcl_templates/locals) for information about using local variables in Packer. -There are two kinds of variables in HCL Packer templates: Input variables, -sometimes simply called "variables", and Local variables, also known as -"locals". Input variables may have defaults, but those defaults can be -overridden using command line options, environment variables, or variable -definitions files. However, nothing can change the value of an input variable -after the initial override. +## Introduction -This page is about input variables. To learn about local variables, see the -[locals](/packer/docs/templates/hcl_templates/locals) page. +Input variables, sometimes referred to as _variables_ or _Packer variables_, are as parameters for a Packer build. They let you customize aspects of the build without altering the build's own source code. Some input variables have default values that you can override using command line options, environment variables, or variable definitions files. You cannot change the value of an input variable after the initial override. -Input variables serve as parameters for a Packer build, allowing aspects of the -build to be customized without altering the build's own source code. - -Input variable and local variable usage are introduced in the [_Variables -Guide_](/packer/guides/hcl/variables). - --> **Note:** For brevity, input variables are often referred to as just -"variables" or "Packer variables" when it is clear from context what sort of -variable is being discussed. Other kinds of variables in Packer include -_environment variables_ (set by the shell where Packer runs) and _expression -variables_ (used to indirectly represent a value in an -[expression](/packer/docs/templates/hcl_templates/expressions)). +Refer to [Input Variables and local variables](/packer/guides/hcl/variables) for additional information. ## Declaring an Input Variable diff --git a/website/content/partials/from-1.5/contextual-source-variables.mdx b/website/content/partials/from-1.5/contextual-source-variables.mdx index db375ef7074..c609a9ddb1e 100644 --- a/website/content/partials/from-1.5/contextual-source-variables.mdx +++ b/website/content/partials/from-1.5/contextual-source-variables.mdx @@ -1,7 +1,12 @@ -# Source Variables +## Source Variables -It is possible to access the `name` and `type` of your `source` from -provisioners and post-processors: +Use the following syntax to access the `name` and `type` of your `source` from provisioners and post-processors: + +``` +.. +``` + +The following example queries source names used in the build: ```hcl source "null" "first-example" { @@ -26,11 +31,11 @@ build { inline = ["echo ${source.name} and ${source.type}"] } } - -# This will echo something like: -# -# roles.null.consul: consul and null -# roles.null.nomad: nomad and null -# roles.null.vault: vault and null -# roles.null.first-example: first-example and null ``` + +The example returns the following values: + +- `roles.null.consul`: Returns `consul` and `null` +- `roles.null.nomad`: Returns `nomad` and `null` +- `roles.null.vault`: Returns `vault` and `null` +- `roles.null.first-example`: Returns `first-example` and `null` \ No newline at end of file diff --git a/website/content/partials/path/separator-note.mdx b/website/content/partials/path/separator-note.mdx index de383ccd3bd..f2483b46321 100644 --- a/website/content/partials/path/separator-note.mdx +++ b/website/content/partials/path/separator-note.mdx @@ -1,6 +1,3 @@ -~> **Note:** If possible, try to always use a forward slash `/` as the path separator, -especially when dealing with relative paths. A backward slash `\` will work on -Windows and is the official Windows path separator, but when building from any -system that is not Windows, Packer will only treat slashes `/` as path -separators, and treat backslashes as plain text. Which could lead to pathing -errors. +Separate paths with a forward slash (`/`), especially when using relative paths in your configuration. +Windows uses backward slashes (`\`) to separate paths, but Packer only recognizes `/` as path +separators when it creates builds from any non-Windows system. Packer also treat backslashes as plain text, which could lead to errors.