Merge pull request #11030 from hashicorp/remove_comment_guide

delete comment guide, moving contents to the comment section of the t…
This commit is contained in:
Megan Marsh 2021-05-18 13:19:13 -07:00 committed by GitHub
commit 70739cf1a1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 77 additions and 107 deletions

6
go.mod
View File

@ -21,7 +21,7 @@ require (
github.com/hashicorp/packer-plugin-alicloud v0.0.2
github.com/hashicorp/packer-plugin-amazon v0.0.1
github.com/hashicorp/packer-plugin-ansible v0.0.3
github.com/hashicorp/packer-plugin-azure v0.0.2
github.com/hashicorp/packer-plugin-azure v0.0.3
github.com/hashicorp/packer-plugin-chef v0.0.2
github.com/hashicorp/packer-plugin-cloudstack v0.0.1
github.com/hashicorp/packer-plugin-converge v0.0.1
@ -44,7 +44,7 @@ require (
github.com/hashicorp/packer-plugin-puppet v0.0.2
github.com/hashicorp/packer-plugin-qemu v0.0.1
github.com/hashicorp/packer-plugin-scaleway v0.0.1
github.com/hashicorp/packer-plugin-sdk v0.2.1
github.com/hashicorp/packer-plugin-sdk v0.2.2
github.com/hashicorp/packer-plugin-tencentcloud v0.0.1
github.com/hashicorp/packer-plugin-triton v0.0.0-20210421085122-768dd7c764d9
github.com/hashicorp/packer-plugin-ucloud v0.0.1
@ -54,7 +54,7 @@ require (
github.com/hashicorp/packer-plugin-vsphere v0.0.1
github.com/hashicorp/packer-plugin-yandex v0.0.4
github.com/klauspost/pgzip v0.0.0-20151221113845-47f36e165cec
github.com/masterzen/winrm v0.0.0-20201030141608-56ca5c5f2380
github.com/masterzen/winrm v0.0.0-20210504160029-28ed956f5227
github.com/mattn/go-tty v0.0.0-20191112051231-74040eebce08
github.com/mitchellh/cli v1.1.0
github.com/mitchellh/go-homedir v1.1.0

11
go.sum
View File

@ -547,8 +547,8 @@ github.com/hashicorp/packer-plugin-amazon v0.0.1 h1:EuyjNK9bL7WhQeIJzhBJxOx8nyc6
github.com/hashicorp/packer-plugin-amazon v0.0.1/go.mod h1:12c9msibyHdId+Mk/pCbdRb1KaLIhaNyxeJ6n8bZt30=
github.com/hashicorp/packer-plugin-ansible v0.0.3 h1:pLL2ZqRt4LVBwhtcG/PVgr9WbhfYfIDJ2aWT+Q7ef9U=
github.com/hashicorp/packer-plugin-ansible v0.0.3/go.mod h1:5/wOgs7TBwziYCznulfv5AwncLHavXQr83EtpkBVlXg=
github.com/hashicorp/packer-plugin-azure v0.0.2 h1:wNEWpkIUzFr/K0ddlipn7W7oJ/m8+RiWZ1xJMsX+hbM=
github.com/hashicorp/packer-plugin-azure v0.0.2/go.mod h1:ySskXX3DJV9Z9Yzt3dyrWsN1XUcjeIOtyL7/ZNHs6zw=
github.com/hashicorp/packer-plugin-azure v0.0.3 h1:kqHWW5bVXyYq6E9BqcdWTs1XL1ZkWauh3CKSh+JZ8T8=
github.com/hashicorp/packer-plugin-azure v0.0.3/go.mod h1:j+tJcKI1nF2I+06c3f6KUdchlgGP2Kc9tgWZ+Cr7uCo=
github.com/hashicorp/packer-plugin-chef v0.0.2 h1:JiciRcYGHaHB0LoJ0Y4oSJXrZeH0xbnshcEYGqC3lgI=
github.com/hashicorp/packer-plugin-chef v0.0.2/go.mod h1:PxGw+J6PTW74b8MzMDEIoVYHAIr+vCS1n0etz8pqdiM=
github.com/hashicorp/packer-plugin-cloudstack v0.0.1 h1:BF9nXRlA0xQV5W/+CoLjWn0aLO60gTbsxnLi/o37ktc=
@ -608,8 +608,8 @@ github.com/hashicorp/packer-plugin-sdk v0.1.3-0.20210407232143-c217d82aefb6/go.m
github.com/hashicorp/packer-plugin-sdk v0.1.3/go.mod h1:xePpgQgQYv/bamiypx3hH9ukidxDdcN8q0R0wLi8IEQ=
github.com/hashicorp/packer-plugin-sdk v0.1.4/go.mod h1:xePpgQgQYv/bamiypx3hH9ukidxDdcN8q0R0wLi8IEQ=
github.com/hashicorp/packer-plugin-sdk v0.2.0/go.mod h1:0DiOMEBldmB0HEhp0npFSSygC8bIvW43pphEgWkp2WU=
github.com/hashicorp/packer-plugin-sdk v0.2.1 h1:NZJ9h2ddzZb6E3eaYFD7L4mSjqFia3FDoDTxDGQKNMs=
github.com/hashicorp/packer-plugin-sdk v0.2.1/go.mod h1:4V7lS35FRhukvZrW41IPctTPY7JmHPOkFZcR7XGXZPk=
github.com/hashicorp/packer-plugin-sdk v0.2.2 h1:z0y0mIk4LoGHleheFNuAjw1/mOoaUPdXSTErICgOBYk=
github.com/hashicorp/packer-plugin-sdk v0.2.2/go.mod h1:MAOhxLneNh27t6N6SMyRcIR5qSE86e6yYCcEfRScwIE=
github.com/hashicorp/packer-plugin-tencentcloud v0.0.1 h1:DR7GETCzrK/DPFMUPbULIklCxwGhstbbz6pl+2S+UnM=
github.com/hashicorp/packer-plugin-tencentcloud v0.0.1/go.mod h1:FmdacMLvDKiT6OdMAc2x4LXtqu/soLApH3jF57SWOik=
github.com/hashicorp/packer-plugin-triton v0.0.0-20210421085122-768dd7c764d9 h1:No5oPI9Wa7FhTKkFJwI3hcfUVvEpgPC8QMcG9l/Vxzo=
@ -725,8 +725,9 @@ github.com/masterzen/simplexml v0.0.0-20160608183007-4572e39b1ab9/go.mod h1:kCEb
github.com/masterzen/simplexml v0.0.0-20190410153822-31eea3082786 h1:2ZKn+w/BJeL43sCxI2jhPLRv73oVVOjEKZjKkflyqxg=
github.com/masterzen/simplexml v0.0.0-20190410153822-31eea3082786/go.mod h1:kCEbxUJlNDEBNbdQMkPSp6yaKcRXVI6f4ddk8Riv4bc=
github.com/masterzen/winrm v0.0.0-20200615185753-c42b5136ff88/go.mod h1:a2HXwefeat3evJHxFXSayvRHpYEPJYtErl4uIzfaUqY=
github.com/masterzen/winrm v0.0.0-20201030141608-56ca5c5f2380 h1:uKhPH5dYpx3Z8ZAnaTGfGZUiHOWa5p5mdG8wZlh+tLo=
github.com/masterzen/winrm v0.0.0-20201030141608-56ca5c5f2380/go.mod h1:a2HXwefeat3evJHxFXSayvRHpYEPJYtErl4uIzfaUqY=
github.com/masterzen/winrm v0.0.0-20210504160029-28ed956f5227 h1:Vcl9dr3dZMIEGpwP1+QSkqFUVQVOopV1nP+I3a6r6tw=
github.com/masterzen/winrm v0.0.0-20210504160029-28ed956f5227/go.mod h1:a2HXwefeat3evJHxFXSayvRHpYEPJYtErl4uIzfaUqY=
github.com/matryer/moq v0.0.0-20190312154309-6cfb0558e1bd/go.mod h1:9ELz6aaclSIGnZBoaSLZ3NAl1VTufbOrXBPvtcy6WiQ=
github.com/mattn/go-colorable v0.0.9/go.mod h1:9vuHe8Xs5qXnSaW/c/ABM9alt+Vo+STaOChaDxuIBZU=
github.com/mattn/go-colorable v0.1.2/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=

View File

@ -79,6 +79,74 @@ key with an underscore. Example:
**Important:** Only _root level_ keys can be underscore prefixed. Keys within
builders, provisioners, etc. will still result in validation errors.
-> **Note:** Packer supports HCL2 from version 1.6.0. The Hashicorp
Configuration Language does support comments anywhere in template files.
If comments are important to you, consider upgrading your
JSON template to HCL2 using the `packer hcl2_upgrade` command.
One workaround if you are not ready to upgrade to HCL is to use jq to strip
unsupported comments from a Packer template before you run `packer build`.
For example, here is a file named `commented_template.json`:
```json
{
"_comment": ["this is", "a multi-line", "comment"],
"builders": [
{
"_comment": "this is a comment inside a builder",
"type": "null",
"communicator": "none"
}
],
"_comment": "this is a root level comment",
"provisioners": [
{
"_comment": "this is a different comment",
"type": "shell",
"_comment": "this is yet another comment",
"inline": ["echo hellooooo"]
}
]
}
```
If you use the following jq command:
```shell-session
$ jq 'walk(if type == "object" then del(._comment) else . end)' commented_template.json > uncommented_template.json
```
The tool will produce a new file containing:
```json
{
"builders": [
{
"type": "null",
"communicator": "none"
}
],
"provisioners": [
{
"type": "shell",
"inline": ["echo hellooooo"]
}
]
}
```
Once you've got your uncommented file, you can call `packer build` on it like
you normally would.
If your install of jq does not have the walk function and you get an error like
```text
jq: error: walk/1 is not defined at <top-level>,
```
You can create a file `~/.jq` and add the [walk function](https://github.com/stedolan/jq/blob/ad9fc9f559e78a764aac20f669f23cdd020cd943/src/builtin.jq#L255-L262) to it by hand.
## Example Template
Below is an example of a basic template that could be invoked with

View File

@ -1,11 +0,0 @@
---
page_title: Tips and Tricks
description: |-
The guides stored in this section are miscellanious tips and tricks that might
make your experience of using Packer easier
---
# Tips and Tricks
Click the sidebar navigation to check out the miscellaneous guides we have for
making your life with Packer just a bit easier.

View File

@ -1,75 +0,0 @@
---
page_title: Use jq and Packer to comment your templates - Guides
description: |-
You can add detailed comments beyond the root-level underscore-prefixed field
supported by Packer, and remove them using jq.
---
# How to use jq to strip unsupported comments from a Packer template
-> **Note:** Packer supports HCL2 from version 1.6.0, the Hashicorp Configuration
Language allows to comment directly in template files. Consider upgrading your
JSON template to HCL2 using the `packer hcl2_upgrade` command.
One of the biggest complaints we get about Packer is that JSON doesn't use comments.
For Packer JSON templates, you can add detailed comments beyond the root-level underscore-prefixed field supported by Packer, and remove them using jq.
Let's say we have a file named `commented_template.json`
```json
{
"_comment": ["this is", "a multi-line", "comment"],
"builders": [
{
"_comment": "this is a comment inside a builder",
"type": "null",
"communicator": "none"
}
],
"_comment": "this is a root level comment",
"provisioners": [
{
"_comment": "this is a different comment",
"type": "shell",
"_comment": "this is yet another comment",
"inline": ["echo hellooooo"]
}
]
}
```
```shell-session
$ jq 'walk(if type == "object" then del(._comment) else . end)' commented_template.json > uncommented_template.json
```
will produce a new file containing:
```json
{
"builders": [
{
"type": "null",
"communicator": "none"
}
],
"provisioners": [
{
"type": "shell",
"inline": ["echo hellooooo"]
}
]
}
```
Once you've got your uncommented file, you can call `packer build` on it like
you normally would.
## The walk function
If your install of jq does not have the walk function and you get an error like
```text
jq: error: walk/1 is not defined at <top-level>,
```
You can create a file `~/.jq` and add the [walk function](https://github.com/stedolan/jq/blob/ad9fc9f559e78a764aac20f669f23cdd020cd943/src/builtin.jq#L255-L262) to it by hand.

View File

@ -45,19 +45,6 @@
}
]
},
{
"title": "Workflow Tips and Tricks",
"routes": [
{
"title": "Overview",
"path": "workflow-tips-and-tricks"
},
{
"title": "Use jq to strip comments from a Packer template",
"path": "workflow-tips-and-tricks/use-packer-with-comment"
}
]
},
{
"title": "Build Immutable Infrastructure with Packer in CI/CD",
"routes": [