README
¶
Packer Plugin SDK
This SDK enables building Packer plugins. This allows Packer's users to use both the officially-supported builders, provisioners, and post-processors, and custom in-house solutions.
Packer itself is a tool for building identical machine images for multiple platforms from a single source configuration. You can find more about Packer on its website and its GitHub repository.
Packer CLI Compatibility
Packer v1.7.0 or later is needed for this SDK. Versions of Packer prior to that release are still compatible with third-party plugins, but the plugins should use the plugin tooling from inside earlier versions of Packer to ensure complete API compatibility.
Go Compatibility
The Packer Plugin SDK is built in Go, and uses the support policy of Go as its support policy. The two latest major releases of Go are supported by the SDK.
Currently, that means Go 1.14 or later must be used when building a provider with the SDK.
Getting Started
See the Extending Packer docs for a guided tour of plugin development.
Documentation
See the Extending Packer section on the Packer website.
Packer Scope (Plugins VS Core)
Packer Core
- acts as an RPC client
- interacts with the user
- parses (HCL/JSON) configuration
- manages build as whole, asks plugin(s) to manage the image lifecycle and modify the image being built.
- discovers plugin(s) and their versions per configuration
- manages plugin lifecycles (i.e. spins up & tears down plugin process)
- passes relevant parts of parsed (valid JSON/HCL) and interpolated configuration to plugin(s)
Packer Provider (via this SDK)
- acts as RPC server
- executes any domain-specific logic based on received parsed configuration. For builders this includes managing the vm lifecycle on a give hypervisor or cloud; for provisioners this involves calling the operation on the remote instance.
- tests domain-specific logic via provided acceptance test framework
- provides Core with template validation, artifact information, and information about whether the plugin process succeeded or failed.
Migrating to SDK from built-in SDK
Migrating to the standalone SDK v1 is covered on the Plugin SDK section of the website.
Versioning
The Packer Plugin SDK is a Go module versioned using semantic versioning.
Releasing
The Packer Plugin SDK is distributed as a Go module, so a minimal 'release' is just a git tag on main.
Releases can be triggered via CircleCI, or the release scripts run from one's own machine.
Releasing via CircleCI
Changelog
CHANGELOG.md on the main branch must have a line of the following form:
## x.y.z (Upcoming)
where x.y.z is the SDK version you intend to release.
Underneath the # x.y.z (Upcoming) heading, please write human-readable entries describing the changes made in this version.
Triggering a release
All commits to main trigger the release workflow on CircleCI, but manual approval is needed to proceed with the workflow.
Find all main workflows
Go to https://circleci.com/gh/hashicorp/workflows/packer-plugin-sdk/tree/main and click on the latest workflow.
It should show the latest main commit, which may be updates to the CHANGELOG.
The status should be ON HOLD.
Approve the trigger-release job
Find the trigger-release job on the workflow diagram, click on it, and click Approve.
Verify
The workflow will then run several other jobs to test and perform the release.
The main steps performed by the release.sh script are:
- CHANGELOG.md: remove
(Upcoming)and commit changes - tag
vx.y.z - push to
main
Verify that this has taken place correctly by inspecting the main branch once the release is complete.
Releasing manually
Prerequisites
Same as above in the CircleCI process.
Releasing
Check out main locally and pull.
Run make test and any other steps you need to satisfy yourself that the release works.
Run ./scripts/release.sh.
Contributing
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package acctest provides an acceptance testing framework for testing builders and provisioners.
|
Package acctest provides an acceptance testing framework for testing builders and provisioners. |
|
provisioneracc
Package provisioneracc creates a framework for provisioner acceptance testing.
|
Package provisioneracc creates a framework for provisioner acceptance testing. |
|
testutils
Package testutils provides some simple ease-of-use tools for implementing acceptance testing.
|
Package testutils provides some simple ease-of-use tools for implementing acceptance testing. |
|
Package adapter helps command line tools connect to the guest via a Packer communicator.
|
Package adapter helps command line tools connect to the guest via a Packer communicator. |
|
Package bootcommand generates and sends boot commands to the remote instance.
|
Package bootcommand generates and sends boot commands to the remote instance. |
|
Package chroot provides convenience tooling specific to chroot builders.
|
Package chroot provides convenience tooling specific to chroot builders. |
|
Package common provides the PackerConfig structure that gets passed to every plugin and contains information populated by the Packer core.
|
Package common provides the PackerConfig structure that gets passed to every plugin and contains information populated by the Packer core. |
|
Package communicator provides common steps for connecting to an instance using the Packer communicator.
|
Package communicator provides common steps for connecting to an instance using the Packer communicator. |
|
ssh
Package SSH provides tooling for generating a temporary SSH keypair, and provides tooling for connecting to an instance via a tunnel.
|
Package SSH provides tooling for generating a temporary SSH keypair, and provides tooling for connecting to an instance via a tunnel. |
|
Package filelock makes it easy to create and check file locks for concurrent processes.
|
Package filelock makes it easy to create and check file locks for concurrent processes. |
|
Package guestexec provides a shim for running common operating system commands on the guest/remote instance that is being provisioned.
|
Package guestexec provides a shim for running common operating system commands on the guest/remote instance that is being provisioned. |
|
Package hcl2helper provides helper functions for parsing or getting hcl2 types to and from a Packer plugin config.
|
Package hcl2helper provides helper functions for parsing or getting hcl2 types to and from a Packer plugin config. |
|
multistep is a Go library for building up complex actions using discrete, individual "steps." These steps are strung together and run in sequence to achieve a more complex goal.
|
multistep is a Go library for building up complex actions using discrete, individual "steps." These steps are strung together and run in sequence to achieve a more complex goal. |
|
commonsteps
The commonsteps package contains the multistep runner that comprises the main architectural convention of Packer builder plugins.
|
The commonsteps package contains the multistep runner that comprises the main architectural convention of Packer builder plugins. |
|
Package net contains some helper wrapping functions for the http and net golang libraries that meet Packer-specific needs.
|
Package net contains some helper wrapping functions for the http and net golang libraries that meet Packer-specific needs. |
|
Package packer contains all of the interfaces for key Packer objects.
|
Package packer contains all of the interfaces for key Packer objects. |
|
Package packerbuilderdata provides tooling for setting and getting special builder-generated data that will be passed to the provisioners.
|
Package packerbuilderdata provides tooling for setting and getting special builder-generated data that will be passed to the provisioners. |
|
Package pathing determines where to put the Packer config directory based on host OS architecture and user environment variables.
|
Package pathing determines where to put the Packer config directory based on host OS architecture and user environment variables. |
|
The plugin package provides the functionality to both expose a Packer plugin binary and to connect to an existing Packer plugin binary.
|
The plugin package provides the functionality to both expose a Packer plugin binary and to connect to an existing Packer plugin binary. |
|
example
command
This is an example plugin.
|
This is an example plugin. |
|
Package random is a helper for generating random alphanumeric strings.
|
Package random is a helper for generating random alphanumeric strings. |
|
Package retry provides tooling to retry API calls which are known to be vulnerable to throttling or flakiness due to eventual consistency.
|
Package retry provides tooling to retry API calls which are known to be vulnerable to throttling or flakiness due to eventual consistency. |
|
Package rpc contains the implementation of the remote procedure call code that the Packer core uses to communicate with packer plugins.
|
Package rpc contains the implementation of the remote procedure call code that the Packer core uses to communicate with packer plugins. |
|
sdk-internals
|
|
|
communicator/none
Package none implements the 'none' communicator.
|
Package none implements the 'none' communicator. |
|
communicator/ssh
Package ssh implements the SSH communicator.
|
Package ssh implements the SSH communicator. |
|
communicator/winrm
Package winrm implements the WinRM communicator.
|
Package winrm implements the WinRM communicator. |
|
Package shell defines configuration fields that are common to many different kinds of shell.
|
Package shell defines configuration fields that are common to many different kinds of shell. |
|
Package shutdowncommand is a helper module for builder plugin configuration.
|
Package shutdowncommand is a helper module for builder plugin configuration. |
|
Package template helps plugins parse the Packer template into golang structures.
|
Package template helps plugins parse the Packer template into golang structures. |
|
interpolate/aws/secretsmanager
Package secretsmanager provide methods to get data from AWS Secret Manager
|
Package secretsmanager provide methods to get data from AWS Secret Manager |
|
Package tmp provides temporary directory helpers.
|
Package tmp provides temporary directory helpers. |
|
Package useragent creates a user agent for builders to use when calling out to cloud APIs or other addresses.
|
Package useragent creates a user agent for builders to use when calling out to cloud APIs or other addresses. |
|
Package uuid provides helper functions for creating time-ordered UUIDs.
|
Package uuid provides helper functions for creating time-ordered UUIDs. |
|
Package version helps plugin creators set and track the plugin version using the same convenience functions used by the Packer core.
|
Package version helps plugin creators set and track the plugin version using the same convenience functions used by the Packer core. |