github.com/kikitux/packer@v0.10.1-0.20160322154024-6237df566f9f/website/source/docs/extend/post-processor.html.md (about)

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