108 lines
4.7 KiB
Plaintext
108 lines
4.7 KiB
Plaintext
---
|
|
description: >
|
|
Packer Post-processors are the components of Packer that transform one
|
|
artifact
|
|
|
|
into another, for example by compressing files, or uploading them.
|
|
layout: docs
|
|
page_title: Custom Post-Processors - Extending
|
|
sidebar_title: 'Custom Post-Processors'
|
|
sidebar_current: docs-extending-custom-post-processors
|
|
---
|
|
|
|
# Custom Post-Processors
|
|
|
|
Packer Post-processors are the components of Packer that transform one artifact
|
|
into another, for example by compressing files, or uploading them.
|
|
|
|
In the compression example, the transformation would be taking an artifact with
|
|
a set of files, compressing those files, and returning a new artifact with only
|
|
a single file (the compressed archive). For the upload example, the
|
|
transformation would be taking an artifact with some set of files, uploading
|
|
those files, and returning an artifact with a single ID: the URL of the upload.
|
|
|
|
Prior to reading this page, it is assumed you have read the page on [plugin
|
|
development basics](/docs/extending/plugins.html).
|
|
|
|
Post-processor plugins implement the `packer.PostProcessor` interface and are
|
|
served using the `plugin.ServePostProcessor` function.
|
|
|
|
~> **Warning!** This is an advanced topic. If you're new to Packer, we
|
|
recommend getting a bit more comfortable before you dive into writing plugins.
|
|
|
|
## The Interface
|
|
|
|
The interface that must be implemented for a post-processor is the
|
|
`packer.PostProcessor` interface. It is reproduced below for reference. The
|
|
actual interface in the source code contains some basic documentation as well
|
|
explaining what each method should do.
|
|
|
|
```go
|
|
type PostProcessor interface {
|
|
ConfigSpec() hcldec.ObjectSpec
|
|
Configure(interface{}) error
|
|
PostProcess(context.Context, Ui, Artifact) (a Artifact, keep, mustKeep bool, err error)
|
|
}
|
|
```
|
|
|
|
### The "ConfigSpec" Method
|
|
|
|
This method returns a hcldec.ObjectSpec, which is a spec necessary for using
|
|
HCL2 templates with Packer. For information on how to use and implement this
|
|
function, check our
|
|
[object spec docs](https://www.packer.io/guides/hcl/component-object-spec)
|
|
|
|
### The "Configure" Method
|
|
|
|
The `Configure` method for each post-processor is called early in the build
|
|
process to configure the post-processor. The configuration is passed in as a
|
|
raw `interface{}`. The configure method is responsible for translating this
|
|
configuration into an internal structure, validating it, and returning any
|
|
errors.
|
|
|
|
For decoding the `interface{}` into a meaningful structure, the
|
|
[mapstructure](https://github.com/mitchellh/mapstructure) library is
|
|
recommended. Mapstructure will take an `interface{}` and decode it into an
|
|
arbitrarily complex struct. If there are any errors, it generates very
|
|
human-friendly errors that can be returned directly from the configure method.
|
|
|
|
While it is not actively enforced, **no side effects** should occur from
|
|
running the `Configure` method. Specifically, don't create files, don't create
|
|
network connections, etc. Configure's purpose is solely to setup internal state
|
|
and validate the configuration as much as possible.
|
|
|
|
`Configure` being run is not an indication that `PostProcess` will ever run.
|
|
For example, `packer validate` will run `Configure` to verify the configuration
|
|
validates, but will never actually run the build.
|
|
|
|
### The "PostProcess" Method
|
|
|
|
The `PostProcess` method is where the real work goes. PostProcess is
|
|
responsible for taking one `packer.Artifact` implementation, and transforming
|
|
it into another.
|
|
A `PostProcess` call can be cancelled at any moment. Cancellation is triggered
|
|
when the done chan of the context struct (`<-ctx.Done()`) unblocks .
|
|
|
|
When we say "transform," we don't mean actually modifying the existing
|
|
`packer.Artifact` value itself. We mean taking the contents of the artifact and
|
|
creating a new artifact from that. For example, if we were creating a
|
|
"compress" post-processor that is responsible for compressing files, the
|
|
transformation would be taking the `Files()` from the original artifact,
|
|
compressing them, and creating a new artifact with a single file: the
|
|
compressed archive.
|
|
|
|
The result signature of this method is `(Artifact, bool, bool, error)`. Each
|
|
return value is explained below:
|
|
|
|
- `Artifact` - The newly created artifact if no errors occurred.
|
|
- `bool` - If keep true, the input artifact will forcefully be kept. By default,
|
|
Packer typically deletes all input artifacts, since the user doesn't
|
|
generally want intermediary artifacts. However, some post-processors depend
|
|
on the previous artifact existing. If this is `true`, it forces packer to
|
|
keep the artifact around.
|
|
- `bool` - If forceOverride is true, then any user input for
|
|
keep_input_artifact is ignored and the artifact is either kept or discarded
|
|
according to the value set in `keep`.
|
|
- `error` - Non-nil if there was an error in any way. If this is the case,
|
|
the other two return values are ignored.
|