github.com/hashicorp/packer@v1.14.3/website/content/docs/templates/hcl_templates/blocks/packer.mdx (about)

     1  ---
     2  page_title: packer block reference
     3  description: |-
     4    The `packer` block configures Packer behavior. Learn how to configure the `packer` in Packer templates written in HCL.  
     5  ---
     6  
     7  # `packer` block
     8  
     9  This topic provides reference information about the `packer` block. 
    10  
    11  ## Description
    12  
    13  The `packer` block configures Packer version requirements and specifies which plugins to install upon initialization.
    14  
    15  ## Packer Block Syntax
    16  
    17  Packer settings are gathered together into `packer` blocks:
    18  
    19  ```hcl
    20  packer {
    21    # ...
    22  }
    23  ```
    24  
    25  Each `packer` block can contain a number of settings related to Packer's
    26  behavior. Within a `packer` block, only constant values can be used;
    27  arguments may not refer to named objects such as resources, input variables,
    28  etc, and may not use any of the Packer language built-in functions.
    29  
    30  The various options supported within a `packer` block are described in the
    31  following sections.
    32  
    33  ## Specifying a Required Packer Version
    34  
    35  The `required_version` setting accepts a [version constraint
    36  string,](#version-constraints) which specifies which versions of Packer
    37  can be used with your configuration.
    38  
    39  If the running version of Packer doesn't match the constraints specified,
    40  Packer will produce an error and exit without taking any further actions.
    41  
    42  Use Packer version constraints in a collaborative environment to
    43  ensure that everyone is using a specific Packer version, or using at least
    44  a minimum Packer version that has behavior expected by the configuration.
    45  
    46  ## Specifying Plugin Requirements
    47  
    48  -> **Note:** The `required_plugins` block is only available in Packer v1.7.0 and
    49  later.
    50  
    51  The `required_plugins` block specifies all of the plugins required by the
    52  current template, mapping each local plugin name to a source address and a
    53  version constraint.
    54  
    55  ```hcl
    56  packer {
    57    required_plugins {
    58      happycloud = {
    59        version = ">= 2.7.0"
    60        source = "github.com/hashicorp/happycloud"
    61      }
    62    }
    63  }
    64  ```
    65  
    66  Using the `required_plugins` block to codify the plugins required for invoking a 
    67  `packer build` on your template(s) is a great way to ensure consistent builds across
    68  different platforms or hosts.
    69  
    70  The block codifies two pieces of information that we've found critical to ensure reproducible builds:
    71  1. **The source of a required plugin** indicates to users where a plugin where a plugin was downloaded from
    72  and where to reach out if there are issues with the plugin. 
    73  1. **The version of a required plugin** indicates to users the exact or minimum version needed for the build. 
    74  This is a great way to pin approved versions of a plugin that can be installed across your environment or team.
    75  
    76  For more information on plugins, refer to [Plugins](/packer/docs/plugins).
    77  
    78  ### Define plugin source
    79  Specify the path to the plugin source code in the `source` field using the following format:
    80  
    81  `<HOSTNAME>/[SUBFOLDER/]<NAMESPACE>/<TYPE>`
    82  
    83  - `<Hostname>`: Specifies the hostname of the location or service that distributes the plugin. Packer only supports using `github.com` as the hostname when you install plugins using the `packer init` command. You can point to non-GitHub addresses, such as an internal proxy or plugin binary store, but Packer only pins the required version if you install the plugin using the `packer plugins install –path` command. Refer to the following documentation for additional information.
    84    - [`init` command](/packer/docs/commands/init)
    85    - [`plugins install`](/packer/docs/commands/plugins/install)
    86  - `<Subfolder>`: The subfolder path segment is an optional part of the address that enables you to download plugin sources from custom addresses. You can specify a source containing up to 13 total path segments.   
    87  - `<Namespace>`: An organizational namespace within the specified host. This often is the organization that publishes the plugin.
    88    Type: A short name for the platform or system the plugin manages. The type is usually the plugin's preferred local name.
    89  
    90  For example, the value of the `source` field for a plugin named `myawesomecloud` is `github.com/hashicorp/myawesomecloud` if it belongs to the `hashicorp` namespace on the host `github.com`.
    91  
    92  The actual repository that `myawesomecloud` comes from must always have the name format `github.com/hashicorp/packer-plugin-myawesomecloud`, but the `required_plugins` block omits the redundant `packer-plugin-` repository prefix for brevity.
    93  
    94  ## Version Constraints
    95  
    96  Anywhere that Packer lets you specify a range of acceptable versions for
    97  something, it expects a specially formatted string known as a version
    98  constraint.
    99  
   100  ### Version Constraint Syntax
   101  
   102  Packer's syntax for version constraints is very similar to the syntax used by
   103  other dependency management systems like Bundler and NPM.
   104  
   105  ```hcl
   106  required_version = ">= 1.2.0, < 2.0.0"
   107  ```
   108  
   109  A version constraint is a [string literal](/packer/docs/templates/hcl_templates/expressions#string-literals)
   110  containing one or more conditions, which are separated by commas.
   111  
   112  Each condition consists of an operator and a version number.
   113  
   114  Version numbers should be a series of numbers separated by periods (like
   115  `1.2.0`), optionally with a suffix to indicate a beta release.
   116  
   117  The following operators are valid:
   118  
   119  - `=` (or no operator): Allows only one exact version number. Cannot be combined
   120    with other conditions.
   121  
   122  - `!=`: Excludes an exact version number.
   123  
   124  - `>`, `>=`, `<`, `<=`: Comparisons against a specified version, allowing
   125    versions for which the comparison is true. "Greater-than" requests newer
   126    versions, and "less-than" requests older versions.
   127  
   128  - `~>`: Allows the specified version, plus newer versions that only
   129    increase the _most specific_ segment of the specified version number. For
   130    example, `~> 0.9` is equivalent to `>= 0.9, < 1.0`, and `~> 0.8.4`, is
   131    equivalent to `>= 0.8.4, < 0.9`. This is usually called the pessimistic
   132    constraint operator.
   133  
   134  ### Version Constraint Behavior
   135  
   136  A version number that meets every applicable constraint is considered acceptable.
   137  
   138  Packer consults version constraints to determine whether it has acceptable
   139  versions of itself.
   140  
   141  A prerelease version is a version number that contains a suffix introduced by
   142  a dash, like `1.2.0-beta`. A prerelease version can be selected only by an
   143  _exact_ version constraint (the `=` operator or no operator). Prerelease
   144  versions do not match inexact operators such as `>=`, `~>`, etc.