diff --git a/website/source/docs/other/core-configuration.html.markdown b/website/source/docs/other/core-configuration.html.markdown index f96493dc5..8592b2e08 100644 --- a/website/source/docs/other/core-configuration.html.markdown +++ b/website/source/docs/other/core-configuration.html.markdown @@ -31,6 +31,6 @@ configuration file. None of these are required, since all have sane defaults. By default these are 10,000 and 25,000, respectively. Be sure to set a fairly wide range here, since Packer can easily use over 25 ports on a single run. -* `builders`, `commands`, and `provisioners` are objects that are used to +* `builders`, `commands`, `post-processors`, and `provisioners` are objects that are used to install plugins. The details of how exactly these are set is covered in more detail in the [installing plugins documentation page](/docs/extend/plugins.html). diff --git a/website/source/docs/templates/introduction.html.markdown b/website/source/docs/templates/introduction.html.markdown index 19418f48b..21180f0f7 100644 --- a/website/source/docs/templates/introduction.html.markdown +++ b/website/source/docs/templates/introduction.html.markdown @@ -33,6 +33,12 @@ Along with each key, it is noted whether it is required or not. information on how to define and configure a provisioner, read the sub-section on [configuring provisioners in templates](/docs/templates/provisioners.html). +* `post-processors` (optional) is an array of that defines the various + post-processing steps to take with the built images. This is an optional + field. If not specified, then no post-processing will be done. For more + information on what post-processors do and how they're defined, read the + sub-section on [configuring post-processors in templates](/docs/templates/post-processors.html). + ## Example Template Below is an example of a basic template that is nearly fully functional. It is just diff --git a/website/source/docs/templates/post-processors.html.markdown b/website/source/docs/templates/post-processors.html.markdown new file mode 100644 index 000000000..5dd151daf --- /dev/null +++ b/website/source/docs/templates/post-processors.html.markdown @@ -0,0 +1,91 @@ +--- +layout: "docs" +--- + +# Templates: Post-Processors + +The post-processor section within a template configures any post-processing +that will be done to images built by the builders. Examples of post-processing +would be compressing files, uploading artifacts, etc. + +Post-processors are _optional_. If no post-processors are defined within a template, +then no post-processing will be done to the image. The resulting artifact of +a build is just the image outputted by the builder. + +This documentation page will cover how to configure a post-processor in a +template. The specific configuration options available for each post-processor, +however, must be referenced from the documentation for that specific post-processor. + +Within a template, a section of post-processor definitions looks like this: + +
+{
+ "post-processors": [
+ ... one or more post-processor definitions here ...
+ ]
+}
+
+
+For each post-processor definition, Packer will take the result of each of the
+defined builders and send it through the post-processors. This means that if you
+have one post-processor defined and two builders defined in a template, the
+post-processor will run twice (once for each builder), by default. There are
+ways, which will be covered later, to control what builders post-processors
+apply to, if you wish.
+
+## Post-Processor Definition
+
+Within the `post-processors` array in a template, there are three ways to
+define a post-processor. There are _simple_ definitions, _detailed_ definitions,
+and _sequence_ definitions. Don't worry, they're all very easy to understand,
+and the "simple" and "detailed" definitions are simply shortcuts for the
+"sequence" definition.
+
+A **simple definition** is just a string; the name of the post-processor. An
+example is shown below. Simple definitions are used when no additional configuration
+is needed for the post-processor.
+
+
+{
+ "post-processors": ["compress"]
+}
+
+
+A **detailed definition** is a JSON object. It is very similar to a builder
+or provisioner definition. It contains a `type` field to denote the type of
+the post-processor, but may also contain additional configuration for the
+post-processor. A detailed definition is used when additional configuration
+is needed beyond simply the type for the post-processor. An example is shown below.
+
+
+{
+ "post-processors": [
+ {
+ "type": "compress",
+ "format": "tar.gz"
+ }
+ ]
+}
+
+
+A **sequence definition** is a JSON array comprised of other **simple** or
+**detailed** definitions. The post-processors defined in the array are run
+in order, with the artifact of each feeding into the next, and any intermediary
+artifacts being discarded. A sequence definition may not contain another
+sequence definition. Sequnce definitions are used to chain together multiple
+post-processors. An example is shown below, where the artifact of a build is
+compressed then uploaded, but the compressed result is not kept.
+
+
+{
+ "post-processors": [
+ [
+ "compress",
+ { "type": "upload", "endpoint": "http://fake.com" }
+ ]
+ ]
+}
+
+
+As you may be able to imagine, the **simple** and **detailed** definitions
+are simply shortcuts for a **sequence** definition of only one element.
diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb
index b609e292a..bd760b8f5 100644
--- a/website/source/layouts/docs.erb
+++ b/website/source/layouts/docs.erb
@@ -33,11 +33,13 @@