github.com/aclaygray/packer@v1.3.2/website/source/docs/extending/custom-post-processors.html.md (about) 1 --- 2 description: | 3 Packer Post-processors are the components of Packer that transform one 4 artifact into another, for example by compressing files, or uploading them. 5 layout: docs 6 page_title: 'Custom Post-Processors - Extending' 7 sidebar_current: 'docs-extending-custom-post-processors' 8 --- 9 10 # Custom Post-Processors 11 12 Packer Post-processors are the components of Packer that transform one artifact 13 into another, for example by compressing files, or uploading them. 14 15 In the compression example, the transformation would be taking an artifact with 16 a set of files, compressing those files, and returning a new artifact with only 17 a single file (the compressed archive). For the upload example, the 18 transformation would be taking an artifact with some set of files, uploading 19 those files, and returning an artifact with a single ID: the URL of the upload. 20 21 Prior to reading this page, it is assumed you have read the page on [plugin 22 development basics](/docs/extending/plugins.html). 23 24 Post-processor plugins implement the `packer.PostProcessor` interface and are 25 served using the `plugin.ServePostProcessor` function. 26 27 ~> **Warning!** This is an advanced topic. If you're new to Packer, we 28 recommend getting a bit more comfortable before you dive into writing plugins. 29 30 ## The Interface 31 32 The interface that must be implemented for a post-processor is the 33 `packer.PostProcessor` interface. It is reproduced below for reference. The 34 actual interface in the source code contains some basic documentation as well 35 explaining what each method should do. 36 37 ``` go 38 type PostProcessor interface { 39 Configure(interface{}) error 40 PostProcess(Ui, Artifact) (a Artifact, keep bool, err error) 41 } 42 ``` 43 44 ### The "Configure" Method 45 46 The `Configure` method for each post-processor is called early in the build 47 process to configure the post-processor. The configuration is passed in as a raw 48 `interface{}`. The configure method is responsible for translating this 49 configuration into an internal structure, validating it, and returning any 50 errors. 51 52 For decoding the `interface{}` into a meaningful structure, the 53 [mapstructure](https://github.com/mitchellh/mapstructure) library is 54 recommended. Mapstructure will take an `interface{}` and decode it into an 55 arbitrarily complex struct. If there are any errors, it generates very 56 human-friendly errors that can be returned directly from the configure method. 57 58 While it is not actively enforced, **no side effects** should occur from running 59 the `Configure` method. Specifically, don't create files, don't create network 60 connections, etc. Configure's purpose is solely to setup internal state and 61 validate the configuration as much as possible. 62 63 `Configure` being run is not an indication that `PostProcess` will ever run. For 64 example, `packer validate` will run `Configure` to verify the configuration 65 validates, but will never actually run the build. 66 67 ### The "PostProcess" Method 68 69 The `PostProcess` method is where the real work goes. PostProcess is responsible 70 for taking one `packer.Artifact` implementation, and transforming it into 71 another. 72 73 When we say "transform," we don't mean actually modifying the existing 74 `packer.Artifact` value itself. We mean taking the contents of the artifact and 75 creating a new artifact from that. For example, if we were creating a "compress" 76 post-processor that is responsible for compressing files, the transformation 77 would be taking the `Files()` from the original artifact, compressing them, and 78 creating a new artifact with a single file: the compressed archive. 79 80 The result signature of this method is `(Artifact, bool, error)`. Each return 81 value is explained below: 82 83 - `Artifact` - The newly created artifact if no errors occurred. 84 - `bool` - If true, the input artifact will forcefully be kept. By default, 85 Packer typically deletes all input artifacts, since the user doesn't 86 generally want intermediary artifacts. However, some post-processors depend 87 on the previous artifact existing. If this is `true`, it forces packer to 88 keep the artifact around. 89 - `error` - Non-nil if there was an error in any way. If this is the case, the 90 other two return values are ignored.