From eab8b7389d8fcfae45cfd7d96fac83f9ae6ba320 Mon Sep 17 00:00:00 2001 From: Mahmood Ali Date: Mon, 2 Nov 2020 12:27:53 -0500 Subject: [PATCH] First draft of HCLv2 docs (#9218) This is a first draft of HCLv2 docs - I added the details under hcl2 doc with some minimal info highlighting the hcl2 introductions. As a longer term strategy, we'll want to mimic the Packer HCL docs structure that details all the blocks and allowed expressions/functions in greater details. However, given that the exact functions and templating syntax is still somewhat influx, I opt to push that to another time. --- website/data/docs-navigation.js | 1 + website/pages/docs/commands/job/plan.mdx | 2 + website/pages/docs/commands/job/run.mdx | 2 + website/pages/docs/job-specification/hcl2.mdx | 95 +++++++++++++++++++ .../pages/docs/upgrade/upgrade-specific.mdx | 5 + 5 files changed, 105 insertions(+) create mode 100644 website/pages/docs/job-specification/hcl2.mdx diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 158cb7d3b..e2192edd2 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -180,6 +180,7 @@ export default [ { category: 'job-specification', content: [ + 'hcl2', 'artifact', 'affinity', 'check_restart', diff --git a/website/pages/docs/commands/job/plan.mdx b/website/pages/docs/commands/job/plan.mdx index 46fdf0209..832dfa686 100644 --- a/website/pages/docs/commands/job/plan.mdx +++ b/website/pages/docs/commands/job/plan.mdx @@ -61,6 +61,8 @@ Plan will return one of the following exit codes: - `-policy-override`: Sets the flag to force override any soft mandatory Sentinel policies. +- `-hcl1` 1.0 Beta: If set, HCL1 parser is used for parsing the job spec. + - `-verbose`: Increase diff verbosity. ## Examples diff --git a/website/pages/docs/commands/job/run.mdx b/website/pages/docs/commands/job/run.mdx index 05f2f0abf..b12a8677f 100644 --- a/website/pages/docs/commands/job/run.mdx +++ b/website/pages/docs/commands/job/run.mdx @@ -83,6 +83,8 @@ precedence, going from highest to lowest: the `-vault-token` flag, the storing it in the job file. This overrides the token found in the `$VAULT_TOKEN` environment variable and that found in the job. +- `-hcl1` 1.0 Beta: If set, HCL1 parser is used for parsing the job spec. + - `-verbose`: Show full information. ## Examples diff --git a/website/pages/docs/job-specification/hcl2.mdx b/website/pages/docs/job-specification/hcl2.mdx new file mode 100644 index 000000000..07992f832 --- /dev/null +++ b/website/pages/docs/job-specification/hcl2.mdx @@ -0,0 +1,95 @@ +--- +layout: docs +page_title: HCL2 +sidebar_title: HCL2 Beta +description: Learn about the Job specification HCL2 used to submit jobs to Nomad. +--- + +# HCL2 Beta + +~> **NOTE:** This page is about Nomad 1.0 Beta. Details are subject to change before final release. + +Nomad 1.0 adopts +[HCL2](https://github.com/hashicorp/hcl2/blob/master/README.md), the second +generation of HashiCorp Configuration Language. HCL2 extends the HCL language by +adding expressions and input variables support to improve job spec +reusability and readability. Also, the new HCL2 parser improves the error +messages for invalid jobs. + +## Expressions + +Nomad 1.0 supports expressions and built-in functions, allowing for a more concise job spec. HCL2 allows use of the following expressions: + +- value literals: e.g. `42`, `"hello"`, `true` +- arithmetic expression: `5*100` +- for-each expressions: `[for s in [3, 4, 5]: s+1]` (which evaluates to `[4, 5, 6]`) +- invocation of function calls: `upper("FOO")`. + +For a full list of available functions, see [the function reference](https://www.packer.io/docs/from-1.5/functions). + +The following snippet illustrates the power of expressions and built-in functions: + +```hcl +template { + # `file` function can load external files without embedding them in the jobspec file + data = file("scripts.sh") + destination = "local/scripts.sh" +} + +template { + # jsonencode eases maintaining json field + data = jsonencode({ regions = { tokyo = 4, mumbai = 2, us_east = 3 }}) + destination = "local/region_mapping.json" +} + +resources { + # arithmetics can make values more obvious + memory = 2 * 1014 +} +``` + +## Input Variables + +Input variables serve as parameters for Nomad jobs, allowing reuse of the job spec +to target multiple environments or contexts without altering the job spec source. + +Input variables don't need to be explicitly declared, and can be referenced +within expressions as `vars.`. You can set the variable in the CLI by +passing `-var =`. + +For example, to repurpose the job spec to target different environments (e.g. +staging vs production), you can use `vars.environment` in the job spec, and pass +`--var environment=production`. + +## Backward Compatibilities + +HCL2 syntax closely mirrors HCL1, but has some minor changes. Most existing +Nomad job specifications will not require any changes. + +When you run `nomad job run` or `nomad job plan`, the CLI will report any +required changes. Also, you can activate a backwards compatibility mode by +passing `-hcl1` to use Nomad's HCL1 parser instead. + +### Blocks + +Nomad 0.12 and earlier allowed a few variations for defining blocks. For example, the following variations of `meta` were accepted: + +```hcl +meta { + # meta attributes can be quoted or not + "team" = "..." + organization = "..." +} + +# meta can be an assignment to a map +meta = { "team" = "...", organization = "..." } +``` + +Starting with Nomad 1.0 and the HCL2 parser, only the block syntax with unquoted attributes is accepted: + +```hcl +meta { + team = "..." + organization = "..." +} +``` diff --git a/website/pages/docs/upgrade/upgrade-specific.mdx b/website/pages/docs/upgrade/upgrade-specific.mdx index c1e094685..a7eb00636 100644 --- a/website/pages/docs/upgrade/upgrade-specific.mdx +++ b/website/pages/docs/upgrade/upgrade-specific.mdx @@ -17,6 +17,11 @@ standard upgrade flow. ## Nomad 1.0.0 +### HCL2 for Job specification + +Nomad 1.0.0 adopts HCL2 for parsing the job spec. HCL2 extends HCL with more +expression and reuse support, but adds some stricter schema for HCL blocks (a.k.a. stanzas). Check [HCL](/docs/job-specification/hcl2) for more details. + ### Signal used when stopping Docker tasks When stopping tasks running with the Docker task driver, Nomad documents that a