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 follows Go’s official support policy. Refer to go.mod for the minimum required Go version.

Getting Started

See the Extending Packer docs for a guided tour of plugin development.

Documentation

See the Extending Packer section on the Packer website.

Testing

The SDK embeds tests to ensure we don't introduce a regression in the future. Up to version 0.5.0 of the SDK, tests would be runnable with make test on their own but since we removed the replace statement for go-cty tests won't work out-of-the-box. Contributors will need to invoke packer-sdc fix . in order to fix the go.mod and go.sum files before running tests.

Please do not commit these changes, as adding this replace section to the go.mod file will make it impossible for dependents to run go install for packer-sdc afterwards.

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.

Contributing

See .github/CONTRIBUTING.md

License

Mozilla Public License v2.0