github.com/hashicorp/packer@v1.14.3/website/content/guides/1.7-template-upgrade.mdx (about)

     1  ---
     2  page_title: Upgrading your template to use Packer init
     3  description: >-
     4    Use packer init and the required_plugins block to better control plugin usage within Packer templates. Learn how to update your template to work with these new features.
     5  ---
     6  
     7  # Upgrading your template to be compatible with `packer init`
     8  
     9  The `packer init` command introduced in version v1.7.0 benefits Packer users by providing better control of plugin
    10  usage within a Packer template configuration.
    11  
    12  In short, `packer init` will look at the `required_plugins` block definition within a template, and download the correct
    13  binaries for that template. For details about how the command works and where the plugins will be installed, please
    14  refer to the [`packer init`](/packer/docs/commands/init) documentation.
    15  
    16  -> **Note:** `packer init` is only supported for HCL templates. You can
    17  upgrade legacy JSON templates to HCL using the [hcl2_upgrade](/packer/docs/commands/hcl2_upgrade) command.
    18  
    19  ## Updating your template with the `required_plugins` block
    20  
    21  ## FAQs
    22  
    23  ### Why do you need to upgrade your template?
    24  
    25  To use the `packer init` command, you must upgrade your template to use the `required_plugins` block. The `init` command
    26  won't work if no `required_plugins` is provided.
    27  
    28  We strongly encourage you to upgrade and start using `required_plugins` block within your templates to manage plugin
    29  installation, but if you prefer not to use the `required_plugins` block you can continue to
    30  [install plugins manually](/packer/docs/plugins#installing-plugins).
    31  
    32  ### What if you only use components that are built into the Packer core?
    33  
    34  You don't need `packer init` for this, as of v1.7.0. But it's a good idea to get familiar with the required_plugins
    35  block anyway, because we are going to start splitting popular HashiCorp-maintained components like the amazon-ebs
    36  builder out of the core into their own multi-component plugins. When we do split these plugins out of the core, we will
    37  provide a tool to help you create the correct required_plugins block.
    38  
    39  ### When should you upgrade your template?
    40  
    41  The `packer init` command can only install plugins that have been upgraded to use the latest version of the
    42  [Packer Plugin SDK](https://github.com/hashicorp/packer-plugin-sdk), and therefore are compatible with Packer's API
    43  version v5.0. The plugin repository on GitHub also needs to use a specific release format. If you are not sure whether
    44  the plugin you use fits those requirements, you can reach out to your maintainer to ask. You can also look for clues
    45  that the plugin is ready for use with `packer init`:
    46  
    47  - Check the plugin's CHANGELOG for notes about migrating to the packer-plugin-sdk.
    48  - Check the name of the repository the plugin resides in. Chances are that if the repository follows the naming
    49    convention `packer-plugin-*` (e.g. `packer-plugin-comment`), then the plugin has been upgraded to be compatible with
    50    `packer init`. If the repository has a name that references a specific Packer component (for example,
    51    `packer-provisioner-*`, `packer-builder-*`, or `packer-post-processor-*`) then the plugin likely still needs to be
    52    upgraded to be compatible with `packer init`. Reach out to your plugin maintainer to request that they upgrade; the
    53    Packer team has written a maintainer-focused guide [here](/packer/guides/1.7-plugin-upgrade).
    54  
    55  If the plugin(s) have been upgraded, then they can be used with the `required_plugins` block in your upgraded template.
    56  
    57  #### What if the plugin you need is not upgraded to API v5.0?
    58  
    59  Since the SDK is being released at the same time as the `init` command, plugin users may face a gap between when the
    60  Packer core v1.7.0 is released, and the plugins you use are upgraded by their maintainers. The Packer team is getting
    61  in touch with all currently known plugin maintainers to provide support during their upgrade process.
    62  
    63  If you are willing to upgrade your template but found out that the plugin you are using hasn't been upgraded yet,
    64  we suggest you reach out to the plugin maintainers and ask for an upgrade; the Packer team has written a
    65  maintainer-focused guide [here](/packer/guides/1.7-plugin-upgrade).
    66  
    67  Check the table below to better understand whether your plugin is compatible with `packer init`, with manual
    68  installation, or with both for the Packer version you are using.
    69  
    70  | Packer Core Version | Single Component Plugin - API v4                  | Single Component Plugin - API v5.0                | Multi Component Plugin - API v5.0                         |
    71  | ------------------- | ------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------- |
    72  | v1.5.0 to v1.6.6    | ✋ Plugin must be manually installed              | ⛔ Plugin cannot be used with this Packer version | ⛔ Plugin cannot be used with this Packer version         |
    73  | v1.7.0              | ⛔ Plugin cannot be used with this Packer version | ✋ Plugin must be manually installed              | 📦 Plugin can be installed manually or with `packer init` |
    74  
    75  ### How to upgrade your template
    76  
    77  Let's use the following template as an example:
    78  
    79  ```hcl
    80  # file: example.pkr.hcl
    81  
    82  source "null" "basic-example" {
    83    communicator = "none"
    84  }
    85  
    86  build {
    87    sources = ["sources.null.basic-example"]
    88  
    89    provisioner "comment" {
    90      comment = "Hello from comment plugin"
    91      ui = true
    92      bubble_text =  true
    93    }
    94  }
    95  ```
    96  
    97  This template uses the example [packer-provisioner-comment](https://github.com/sylviamoss/packer-plugin-comment) plugin.
    98  Until Packer v1.7.0, the binaries were installed manually.
    99  
   100  Since the Packer v1.7.0 release, the plugin has been upgraded by its maintainers and is now called
   101  `packer-plugin-comment`. with its latest version being v0.2.23. Knowing that, our example template can be upgraded to
   102  use the `required_plugins` block.
   103  
   104  ```hcl
   105  # file: example.pkr.hcl
   106  
   107  packer {
   108      required_plugins {
   109          comment = {
   110              version = ">=v0.2.23"
   111              source = "github.com/sylviamoss/comment"
   112          }
   113      }
   114  }
   115  
   116  source "null" "basic-example" {
   117    communicator = "none"
   118  }
   119  
   120  build {
   121    sources = ["sources.null.basic-example"]
   122  
   123    provisioner "comment" {
   124      comment = "Hello from comment plugin"
   125      ui = true
   126      bubble_text =  true
   127    }
   128  }
   129  ```
   130  
   131  The upgraded template is now telling Packer that it requires a plugin named `comment` stored in a github repository
   132  owned by the user `sylviamoss`. It also says that the template needs to use a version of the plugin equal to or greater
   133  than `v0.2.23`. Finally, the local_name of the plugin will be `comment`, which means it will be referred to as `comment`
   134  in the rest of the template.
   135  
   136  Here it is a brief explanation of each field:
   137  
   138  - `version` - Should follow the [version constraints](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints).
   139  - `source` - Should have the GitHub hostname, the plugin's organizational namespace, and its short name.
   140    Packer will be responsible for determining the full GitHub
   141    address. For example, if the source is `github.com/sylviamoss/comment`, Packer
   142    will download the binaries from `github.com/sylviamoss/packer-plugin-comment`.
   143    To learn more about the source field, check out the [Source
   144    Address](/packer/docs/plugins#source-addresses) documentation.
   145  - `local_name`- Can be replaced with whatever you want, and the new value will become the name of the plugin.
   146    For example:
   147  
   148    ```hcl
   149    packer {
   150        required_plugins {
   151            bubbled_up = {
   152                # ...
   153            }
   154        }
   155    }
   156  
   157    # ...
   158  
   159    build {
   160        # ...
   161  
   162        provisioner "bubbled_up" {
   163            # ...
   164        }
   165    }
   166    ```
   167  
   168  Once the template is upgraded, you can run `packer init example.pkr.hcl` and the output should tell you the installed
   169  plugin, and the place where it was installed.
   170  
   171  ```shell
   172  ➜ packerdev init example.pkr.hcl
   173  Installed plugin sylviamoss/comment v0.2.23 in "/Users/<user>/.packer.d/plugins/github.com/sylviamoss/comment/packer-plugin-comment_v0.2.23_x5.0_darwin_amd64"
   174  ```
   175  
   176  `packer init` will only download plugin binaries and never delete existing ones. If all the required plugins are installed,
   177  the command won't do anything unless you set the `-upgrade` flag to force download newer versions of the existing plugins.
   178  
   179  You can uninstall a plugin by deleting it from the `.packer.d/plugins/` directory on your computer.
   180  
   181  Now that the required comment plugin is installed via `packer init`, you can run `packer build example.pkr.hcl` as usual
   182  and won't need to run `init` again unless you want to upgrade the plugin version.
   183  
   184  A template with a `required_plugins` block should **always** be initialised at least once with `packer init` before
   185  `packer build`. If the template is built before init, Packer will fail and ask for initialisation.