JSON Templates

These Packer templates are JSON files that configure the various components of Packer in order to create one or more machine images. Templates are portable, static, and readable and writable by both humans and computers.

Templates are given to commands such as packer build, which will take the template and actually run the builds within it, producing any resulting machine images.

JSON Template Structure

The template is a JSON object that has a set of keys configuring various components of Packer. The available keys within a template are listed below. Along with each key, it is noted whether it is required or not.

• builders (required) is an array of one or more objects that defines the builders that will be used to create machine images for this template, and configures each of those builders. For more information on how to define and configure a builder, read the sub-section on configuring builders in templates.

• description (optional) is a string providing a description of what the template does. This output is used only in the inspect command.

• min_packer_version (optional) is a string that has a minimum Packer version that is required to parse the template. This can be used to ensure that proper versions of Packer are used with the template. A max version can't be specified because Packer retains backwards compatibility with packer fix.

• post-processors (optional) is an array of one or more objects that defines the various post-processing steps to take with the built images. If not specified, then no post-processing will be done. For more information on what post-processors do and how they're defined, read the sub-section on configuring post-processors in templates.

• provisioners (optional) is an array of one or more objects that defines the provisioners that will be used to install and configure software for the machines created by each of the builders. If it is not specified, then no provisioners will be run. For more information on how to define and configure a provisioner, read the sub-section on configuring provisioners in templates.

• variables (optional) is an object of one or more key/value strings that defines user variables contained in the template. If it is not specified, then no variables are defined. For more information on how to define and use user variables, read the sub-section on user variables in templates.

Comments

JSON doesn't support comments and Packer reports unknown keys as validation errors. If you'd like to comment your template, you can prefix a root level key with an underscore. Example:

{
  "_comment": "This is a comment",
  "builders": [{}]
}

Important: Only root level keys can be underscore prefixed. Keys within builders, provisioners, etc. will still result in validation errors.

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:

{
  "_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:

$ jq 'walk(if type == "object" then del(._comment) else . end)' commented_template.json > uncommented_template.json

The tool will produce a new file containing:

{
  "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

jq: error: walk/1 is not defined at <top-level>,

You can create a file ~/.jq and add the walk function to it by hand.

Example Template

Below is an example of a basic template that could be invoked with packer build. It would create an instance in AWS, and once running copy a script to it and run that script using SSH.

{
  "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 {{timestamp}}"
    }
  ],

  "provisioners": [
    {
      "type": "shell",
      "script": "setup_things.sh"
    }
  ]
}