From 1bf8237d64eb12a0c78b1b8200acb449dd52626a Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 18 Jun 2013 14:22:35 -0700 Subject: [PATCH] website: post-processors docs for templates --- .../other/core-configuration.html.markdown | 2 +- .../docs/templates/introduction.html.markdown | 6 ++ .../templates/post-processors.html.markdown | 91 +++++++++++++++++++ website/source/layouts/docs.erb | 2 + 4 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 website/source/docs/templates/post-processors.html.markdown 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 @@
  • Command-Line
  • Introduction
  • Build
    • +
  • Validate
  • Templates
  • Introduction
  • Builders
  • Provisioners
    • +
  • Post-Processors
  • Configuration Templates
  • Builders