From 934f622f95eafb0024fea46c1c7be81e42766bb0 Mon Sep 17 00:00:00 2001 From: Chris Baker <1675087+cgbaker@users.noreply.github.com> Date: Wed, 2 Dec 2020 20:41:53 +0000 Subject: [PATCH 1/3] added some discussion of HCL parsing context --- website/pages/docs/job-specification/hcl2/index.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/website/pages/docs/job-specification/hcl2/index.mdx b/website/pages/docs/job-specification/hcl2/index.mdx index 7bf39b948..ddbc2acaf 100644 --- a/website/pages/docs/job-specification/hcl2/index.mdx +++ b/website/pages/docs/job-specification/hcl2/index.mdx @@ -29,6 +29,17 @@ a quick try to HCL2, you can also read the quicker [HCL2 getting started guide](/guides/hcl). ---> +## HCL Parsing Context + +It is important to acknowledge that the Nomad API uses JSON to represent Nomad jobs. +When running commands like `nomad job run` and `nomad job plan`, the Nomad CLI +parses HCL and ultimately converts it to JSON. Because this parsing happens locally +(i.e., where the operator is running the CLI) before job submission, there are some +limits to the capabilities that can be accessed by HCL job specifications. For +example, scheduling information is not yet available, including information about +the client. Similarly, HCL features that depend on external context will take that +context from the local environment of the CLI (e.g., files, environment variables). + ## Syntax The main purpose of the HCL language in Nomad is defining jobs. All other From e68b66253b8c6983264c3e1cabf1e329999f7333 Mon Sep 17 00:00:00 2001 From: Chris Baker <1675087+cgbaker@users.noreply.github.com> Date: Wed, 2 Dec 2020 16:12:07 -0600 Subject: [PATCH 2/3] Update website/pages/docs/job-specification/hcl2/index.mdx Co-authored-by: Michael Schurter --- website/pages/docs/job-specification/hcl2/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/pages/docs/job-specification/hcl2/index.mdx b/website/pages/docs/job-specification/hcl2/index.mdx index ddbc2acaf..6e147cac1 100644 --- a/website/pages/docs/job-specification/hcl2/index.mdx +++ b/website/pages/docs/job-specification/hcl2/index.mdx @@ -31,7 +31,9 @@ guide](/guides/hcl). ## HCL Parsing Context -It is important to acknowledge that the Nomad API uses JSON to represent Nomad jobs. +The [Nomad API uses JSON][jobs-api], not HCL, to represent Nomad jobs. + +[jobs-api]: /api-docs/jobs When running commands like `nomad job run` and `nomad job plan`, the Nomad CLI parses HCL and ultimately converts it to JSON. Because this parsing happens locally (i.e., where the operator is running the CLI) before job submission, there are some From 0e137703977e9cb3c5065373ee623058a0d42682 Mon Sep 17 00:00:00 2001 From: Chris Baker <1675087+cgbaker@users.noreply.github.com> Date: Wed, 2 Dec 2020 22:25:36 +0000 Subject: [PATCH 3/3] formatting fix from github-based commit --- website/pages/docs/job-specification/hcl2/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/pages/docs/job-specification/hcl2/index.mdx b/website/pages/docs/job-specification/hcl2/index.mdx index 6e147cac1..a842e2061 100644 --- a/website/pages/docs/job-specification/hcl2/index.mdx +++ b/website/pages/docs/job-specification/hcl2/index.mdx @@ -32,8 +32,6 @@ guide](/guides/hcl). ## HCL Parsing Context The [Nomad API uses JSON][jobs-api], not HCL, to represent Nomad jobs. - -[jobs-api]: /api-docs/jobs When running commands like `nomad job run` and `nomad job plan`, the Nomad CLI parses HCL and ultimately converts it to JSON. Because this parsing happens locally (i.e., where the operator is running the CLI) before job submission, there are some @@ -42,6 +40,8 @@ example, scheduling information is not yet available, including information abou the client. Similarly, HCL features that depend on external context will take that context from the local environment of the CLI (e.g., files, environment variables). +[jobs-api]: /api-docs/jobs + ## Syntax The main purpose of the HCL language in Nomad is defining jobs. All other