Merge pull request #11025 from hashicorp/remove_isotime_guide

Remove isotime guide
This commit is contained in:
Megan Marsh 2021-05-18 13:31:36 -07:00 committed by GitHub
commit df89b4b52c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 134 additions and 239 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

@ -125,14 +125,15 @@ Here is a full list of the available functions for reference.
`strftime FORMAT` - UTC time, formated using the ISO C standard format
`FORMAT`. See
[jehiah/go-strftime](https://github.com/jehiah/go-strftime) for a list
of available format specifier.
of available format specifiers.
Please note that if you are using a large number of builders,
provisioners or post-processors, the isotime may be slightly
different for each one because it is from when the plugin is
launched not the initial Packer process. In order to avoid this and make
the timestamp consistent across all plugins, set it as a user variable
and then access the user variable within your plugins.
provisioners or post-processors, using the isotime engine directly in the
plugin configuration may cause the timestamp to be slightly diffferent for
each plugin. This is because the timestamp is generated when each plugin is
launched rather than in the initial Packer process. In order to avoid this
and make sure the timestamp is consistent across all plugins, set it as a user
variable and then access the user variable within your plugins.
- `lower` - Lowercases the string.
- `packer_version` - Returns Packer version.
@ -235,6 +236,56 @@ documentation for more information on user variables.
# isotime Function Format Reference
The isotime template engine uses golang to generate timestamps. If you're
unfamiliar with golang, then the way you format the timestamp is going to
feel a bit unusual compared to how you may be used to formatting
datetime strings.
Full docs and examples for the golang time formatting function can be found
[here](https://golang.org/pkg/time/#example_Time_Format)
However, the formatting basics are worth describing here. From the [golang docs](https://golang.org/pkg/time/#pkg-constants):
> These are predefined layouts for use in Time.Format and time.Parse. The
> reference time used in the layouts is the specific time:
>
> Mon Jan 2 15:04:05 MST 2006
>
> which is Unix time 1136239445. Since MST is GMT-0700, the reference time
> can be thought of as
>
> 01/02 03:04:05PM '06 -0700
>
> To define your own format, write down what the reference time would look like
> formatted your way; see the values of constants like ANSIC, StampMicro or
> Kitchen for examples. The model is to demonstrate what the reference time
> looks like so that the Format and Parse methods can apply the same
> transformation to a general time value.
So what does that look like in a Packer template function? Here's an example
of how you'd declare a variable using the isotime function.
```json
"variables": {
"myvar": "packer-{{isotime `2006-01-02 03:04:05`}}"
}
```
You can try and modify the following examples in a packer template or in
`packer console` to get an idea of how to set different timestamps:
| Input | Output |
| ------------------------------------------ | ----------- |
| ``"packer-{{isotime `2006-01-02`}}"`` | "packer-2021-05-17 11:40:16" |
| ``"packer-{{isotime `Jan-_2-15:04:05.000`}}"`` | "packer-May-17-23:40:16.786" |
| ``"packer-{{isotime `3:04PM`}}"`` | "packer-11:40PM" |
| ``"{{ isotime }}"`` | "June 7, 7:22:43pm 2014" |
| ``"{{isotime `2006-01-02`}}"`` | "2014-06-07" |
| ``"{{isotime `Mon 1504`}}"`` | "Sat 1922" |
| ``"{{isotime `02-Jan-06 03\_04\_05`}}"`` | "07-Jun-2014 07\_22\_43" |
| ``"{{isotime `Hour15Year200603`}}"`` | "Hour19Year201407" |
Formatting for the function `isotime` uses the magic reference date **Mon Jan 2
15:04:05 -0700 MST 2006**, which breaks down to the following:
@ -278,47 +329,9 @@ Formatting for the function `isotime` uses the magic reference date **Mon Jan 2
_The values in parentheses are the abbreviated, or 24-hour clock values_
For those unfamiliar with GO date/time formatting, here is a link to the
documentation: [go date/time formatting](https://programming.guide/go/format-parse-string-time-date-example.html)
Note that "-0700" is always formatted into "+0000" because `isotime` is always
UTC time.
Here are some example formatted time, using the above format options:
```liquid
isotime = June 7, 7:22:43pm 2014
{{isotime "2006-01-02"}} = 2014-06-07
{{isotime "Mon 1504"}} = Sat 1922
{{isotime "02-Jan-06 03\_04\_05"}} = 07-Jun-2014 07\_22\_43
{{isotime "Hour15Year200603"}} = Hour19Year201407
```
Please note that double quote characters need escaping inside of templates (in
this case, on the `ami_name` value):
```json
{
"builders": [
{
"type": "amazon-ebs",
"access_key": "...",
"secret_key": "...",
"region": "us-east-1",
"source_ami": "ami-fce3c696",
"instance_type": "t2.micro",
"ssh_username": "ubuntu",
"ami_name": "packer {{isotime \"2006-01-02\"}}"
}
]
}
```
-> **Note:** See the [Amazon builder](/docs/builders/amazon)
documentation for more information on how to correctly configure the Amazon
builder in this example.
# split Function Format Reference
The function `split` takes an input string, a seperator string, and a numeric

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,84 +0,0 @@
---
page_title: Using the isotime template function - Guides
description: |-
It can be a bit confusing to figure out how to format your isotime using the
golang reference date string. Here is a small guide and some examples.
---
# Using the Isotime template function with a format string
The way you format isotime in golang is a bit nontraditional compared to how
you may be used to formatting datetime strings.
Full docs and examples for the golang time formatting function can be found
[here](https://golang.org/pkg/time/#example_Time_Format)
However, the formatting basics are worth describing here. From the [golang docs](https://golang.org/pkg/time/#pkg-constants):
> These are predefined layouts for use in Time.Format and time.Parse. The
> reference time used in the layouts is the specific time:
>
> Mon Jan 2 15:04:05 MST 2006
>
> which is Unix time 1136239445. Since MST is GMT-0700, the reference time
> can be thought of as
>
> 01/02 03:04:05PM '06 -0700
>
> To define your own format, write down what the reference time would look like
> formatted your way; see the values of constants like ANSIC, StampMicro or
> Kitchen for examples. The model is to demonstrate what the reference time
> looks like so that the Format and Parse methods can apply the same
> transformation to a general time value.
So what does that look like in a Packer template function?
```json
{
"variables": {
"myvar": "packer-{{isotime \"2006-01-02 03:04:05\"}}"
},
"builders": [
{
"type": "null",
"communicator": "none"
}
],
"provisioners": [
{
"type": "shell-local",
"inline": ["echo {{ user `myvar`}}"]
}
]
}
```
You can switch out the variables section above with the following examples to
get different timestamps:
Date only, not time:
```json
"variables":
{
"myvar": "packer-{{isotime \"2006-01-02\"}}"
}
```
A timestamp down to the millisecond:
```json
"variables":
{
"myvar": "packer-{{isotime \"Jan-_2-15:04:05.000\"}}"
}
```
Or just the time as it would appear on a digital clock:
```json
"variables":
{
"myvar": "packer-{{isotime \"3:04PM\"}}"
}
```

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,23 +45,6 @@
}
]
},
{
"title": "Workflow Tips and Tricks",
"routes": [
{
"title": "Overview",
"path": "workflow-tips-and-tricks"
},
{
"title": "Isotime Template Function",
"path": "workflow-tips-and-tricks/isotime-template-function"
},
{
"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": [