Packer Plugin Scaffolding

This repository is a template for a Packer multi-component plugin. It is intended as a starting point for creating Packer plugins, containing:

• A builder (builder/scaffolding)
• A provisioner (provisioner/scaffolding)
• A post-processor (post-processor/scaffolding)
• A data source (datasource/scaffolding)
• Docs (docs)
• A working example (example)

These folders contain boilerplate code that you will need to edit to create your own Packer multi-component plugin. A full guide to creating Packer plugins can be found at Extending Packer.

In this repository you will also find a pre-defined GitHub Action configuration for the release workflow (.goreleaser.yml and .github/workflows/release.yml). The release workflow configuration makes sure the GitHub release artifacts are created with the correct binaries and naming conventions.

Please see the GitHub template repository documentation for how to create a new repository from this template on GitHub.

Packer plugin projects

Here's a non exaustive list of Packer plugins that you can checkout:

• github.com/hashicorp/packer-plugin-docker
• github.com/exoscale/packer-plugin-exoscale
• github.com/sylviamoss/packer-plugin-comment
• github.com/hashicorp/packer-plugin-hashicups

Looking at their code will give you good examples.

Setup

The Go Workspace

Go expects a single workspace for third-party Go tools installed via go install. By default, this workspace is located in $HOME/go with source code for these tools stored in $HOME/go/src and the compiled binaries in $HOME/go/bin. Set $GOPATH environment variable to this path first:

export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

Build from source

1. Clone this GitHub repository locally.

2. Run this command from the root directory:

go build -ldflags="-X github.com/hashicorp/packer-plugin-scaffolding/version.VersionPrerelease=dev" -o packer-plugin-scaffolding

3. After you successfully compile, the packer-plugin-scaffolding plugin binary file is in the root directory.

4. To install the compiled plugin, run the following command

packer plugins install --path packer-plugin-scaffolding github.com/hashicorp/scaffolding

Tip

If executing the packer plugins install reports an error, please make sure the version of packer command is the latest. To upgrade to the latest version, please refer to Packer's documentation

Build on *nix systems

Unix like systems with the make, sed, and grep commands installed can use the make dev to execute the build from source steps.

Build on Windows Powershell

The preferred solution for building on Windows are steps 2-4 listed above. If you would prefer to script the building process you can use the following as a guide

$MODULE_NAME = (Get-Content go.mod | Where-Object { $_ -match "^module"  }) -replace 'module ',''
$FQN = $MODULE_NAME -replace 'packer-plugin-',''
go build -ldflags="-X $MODULE_NAME/version.VersionPrerelease=dev" -o packer-plugin-scaffolding.exe
packer plugins install --path packer-plugin-scaffolding.exe $FQN

Running Acceptance Tests

Make sure to install the plugin locally using the steps in Build from source.

Once everything needed is set up, run:

PACKER_ACC=1 go test -count 1 -v ./... -timeout=120m

This will run the acceptance tests for all plugins in this set.

Caution

Please make sure the acceptance tests are running against the local version by deleting all previously installed versions under $HOME/. config/packer/plugins directory. Otherwise, the tests will pick up the old released version if they were installed before. Deleting github.com/QubitPi/hashicorp-aws, for example, would be

rm -rf ~/.config/packer/plugins/github.com/QubitPi/hashicorp-aws

Registering Plugin as Packer Integration

Partner and community plugins can be hard to find if a user doesn't know what they are looking for. To assist with plugin discovery Packer offers an integration portal at https://developer.hashicorp.com/packer/integrations to list known integrations that work with the latest release of Packer.

Registering a plugin as an integration requires metadata configuration within the plugin repository and approval by the Packer team. To initiate the process of registering your plugin as a Packer integration refer to the Developing Plugins page.

Requirements

• packer-plugin-sdk >= v0.5.2
• Go >= 1.20

Packer Compatibility

This scaffolding template is compatible with Packer >= v1.11.0