github.com/phobos182/packer@v0.2.3-0.20130819023704-c84d2aeffc68/website/source/docs/templates/post-processors.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  ---
     4  
     5  # Templates: Post-Processors
     6  
     7  The post-processor section within a template configures any post-processing
     8  that will be done to images built by the builders. Examples of post-processing
     9  would be compressing files, uploading artifacts, etc.
    10  
    11  Post-processors are _optional_. If no post-processors are defined within a template,
    12  then no post-processing will be done to the image. The resulting artifact of
    13  a build is just the image outputted by the builder.
    14  
    15  This documentation page will cover how to configure a post-processor in a
    16  template. The specific configuration options available for each post-processor,
    17  however, must be referenced from the documentation for that specific post-processor.
    18  
    19  Within a template, a section of post-processor definitions looks like this:
    20  
    21  <pre class="prettyprint">
    22  {
    23    "post-processors": [
    24      ... one or more post-processor definitions here ...
    25    ]
    26  }
    27  </pre>
    28  
    29  For each post-processor definition, Packer will take the result of each of the
    30  defined builders and send it through the post-processors. This means that if you
    31  have one post-processor defined and two builders defined in a template, the
    32  post-processor will run twice (once for each builder), by default. There are
    33  ways, which will be covered later, to control what builders post-processors
    34  apply to, if you wish.
    35  
    36  ## Post-Processor Definition
    37  
    38  Within the `post-processors` array in a template, there are three ways to
    39  define a post-processor. There are _simple_ definitions, _detailed_ definitions,
    40  and _sequence_ definitions. Don't worry, they're all very easy to understand,
    41  and the "simple" and "detailed" definitions are simply shortcuts for the
    42  "sequence" definition.
    43  
    44  A **simple definition** is just a string; the name of the post-processor. An
    45  example is shown below. Simple definitions are used when no additional configuration
    46  is needed for the post-processor.
    47  
    48  <pre class="prettyprint">
    49  {
    50    "post-processors": ["compress"]
    51  }
    52  </pre>
    53  
    54  A **detailed definition** is a JSON object. It is very similar to a builder
    55  or provisioner definition. It contains a `type` field to denote the type of
    56  the post-processor, but may also contain additional configuration for the
    57  post-processor. A detailed definition is used when additional configuration
    58  is needed beyond simply the type for the post-processor. An example is shown below.
    59  
    60  <pre class="prettyprint">
    61  {
    62    "post-processors": [
    63      {
    64        "type": "compress",
    65        "format": "tar.gz"
    66      }
    67    ]
    68  }
    69  </pre>
    70  
    71  A **sequence definition** is a JSON array comprised of other **simple** or
    72  **detailed** definitions. The post-processors defined in the array are run
    73  in order, with the artifact of each feeding into the next, and any intermediary
    74  artifacts being discarded. A sequence definition may not contain another
    75  sequence definition. Sequence definitions are used to chain together multiple
    76  post-processors. An example is shown below, where the artifact of a build is
    77  compressed then uploaded, but the compressed result is not kept.
    78  
    79  <pre class="prettyprint">
    80  {
    81    "post-processors": [
    82      [
    83        "compress",
    84        { "type": "upload", "endpoint": "http://fake.com" }
    85      ]
    86    ]
    87  }
    88  </pre>
    89  
    90  As you may be able to imagine, the **simple** and **detailed** definitions
    91  are simply shortcuts for a **sequence** definition of only one element.
    92  
    93  ## Input Artifacts
    94  
    95  When using post-processors, the input artifact (coming from a builder or
    96  another post-processor) is discarded by default after the post-processor runs.
    97  This is because generally, you don't want the intermediary artifacts on the
    98  way to the final artifact created.
    99  
   100  In some cases, however, you may want to keep the intermediary artifacts.
   101  You can tell Packer to keep these artifacts by setting the
   102  `keep_input_artifact` configuration to `true`. An example is shown below:
   103  
   104  <pre class="prettyprint">
   105  {
   106    "post-processors": [
   107      {
   108        "type": "compress",
   109        "keep_input_artifact": true
   110      }
   111    ]
   112  }
   113  </pre>
   114  
   115  This setting will only keep the input artifact to _that specific_
   116  post-processor. If you're specifying a sequence of post-processors, then
   117  all intermediaries are discarded by default except for the input artifacts
   118  to post-processors that explicitly state to keep the input artifact.
   119  
   120  <div class="alert alert-info alert-block">
   121  <strong>Note:</strong> The intuitive reader may be wondering what happens
   122  if multiple post-processors are specified (not in a sequence). Does Packer require the
   123  configuration to keep the input artifact on all the post-processors?
   124  The answer is no, of course not. Packer is smart enough to figure out
   125  that at least one post-processor requested that the input be kept, so it will keep
   126  it around.
   127  </div>