From 10f47b5158c13f677aba9bcade56420108acb454 Mon Sep 17 00:00:00 2001
From: Megan Marsh <megan@hashicorp.com>
Date: Wed, 3 Apr 2019 13:57:22 -0700
Subject: [PATCH] document clearly what keep_input_artifact does for each
 post-processor

---
 packer/build.go                                          | 2 +-
 .../source/docs/post-processors/alicloud-import.html.md  | 3 +++
 .../source/docs/post-processors/amazon-import.html.md    | 3 +++
 website/source/docs/post-processors/artifice.html.md     | 5 +++++
 website/source/docs/post-processors/checksum.html.md     | 5 +++++
 website/source/docs/post-processors/compress.html.md     | 4 +++-
 .../docs/post-processors/digitalocean-import.html.md     | 3 +++
 .../source/docs/post-processors/docker-import.html.md    | 3 +++
 website/source/docs/post-processors/docker-push.html.md  | 4 ++++
 website/source/docs/post-processors/docker-save.html.md  | 7 +++++++
 website/source/docs/post-processors/docker-tag.html.md   | 7 +++++++
 .../docs/post-processors/googlecompute-export.html.md    | 4 ++--
 website/source/docs/post-processors/manifest.html.md     | 7 +++++++
 website/source/docs/post-processors/shell-local.html.md  | 9 +++++++++
 .../source/docs/post-processors/vagrant-cloud.html.md    | 3 +++
 website/source/docs/post-processors/vagrant.html.md      | 8 ++++++--
 .../source/docs/post-processors/vsphere-template.html.md | 6 ++++++
 website/source/docs/post-processors/vsphere.html.md      | 3 +++
 18 files changed, 80 insertions(+), 6 deletions(-)

diff --git a/packer/build.go b/packer/build.go
index af9a307f8..a8c624bbc 100644
--- a/packer/build.go
+++ b/packer/build.go
@@ -281,7 +281,7 @@ PostProcessorRunSeqLoop:
 			// useless if keep isn't set, force an override that still uses
 			// post-processor preference instead of user preference.
 			if corePP.keepInputArtifact != nil {
-				if *corePP.keepInputArtifact == false && forceOverride {
+				if defaultKeep && *corePP.keepInputArtifact == false && forceOverride {
 					log.Printf("The %s post-processor forces "+
 						"keep_input_artifact=true to preserve integrity of the"+
 						"build chain. User-set keep_input_artifact=false will be"+
diff --git a/website/source/docs/post-processors/alicloud-import.html.md b/website/source/docs/post-processors/alicloud-import.html.md
index 7f26c42d7..fb28f6163 100644
--- a/website/source/docs/post-processors/alicloud-import.html.md
+++ b/website/source/docs/post-processors/alicloud-import.html.md
@@ -60,6 +60,9 @@ are two categories: required and optional parameters.
 
 ### Optional:
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the RAW or VHD
+    disk image after importing it to the cloud. Defaults to false.
+
 -   `oss_key_name` (string) - The name of the object key in `oss_bucket_name`
     where the RAW or VHD file will be copied to for import.
 
diff --git a/website/source/docs/post-processors/amazon-import.html.md b/website/source/docs/post-processors/amazon-import.html.md
index 95bb10958..21f24eeea 100644
--- a/website/source/docs/post-processors/amazon-import.html.md
+++ b/website/source/docs/post-processors/amazon-import.html.md
@@ -101,6 +101,9 @@ Optional:
 -   `insecure_skip_tls_verify` (boolean) - This allows skipping TLS
     verification of the AWS EC2 endpoint. The default is `false`.
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the source virtual
+    machine image after importing it to the cloud. Defaults to false.
+
 -   `license_type` (string) - The license type to be used for the Amazon
     Machine Image (AMI) after importing. Valid values: `AWS` or `BYOL`
     (default). For more details regarding licensing, see
diff --git a/website/source/docs/post-processors/artifice.html.md b/website/source/docs/post-processors/artifice.html.md
index e7b287315..e6bd8e89d 100644
--- a/website/source/docs/post-processors/artifice.html.md
+++ b/website/source/docs/post-processors/artifice.html.md
@@ -59,6 +59,11 @@ The configuration allows you to specify which files comprise your artifact.
     packer is complete. These will replace any of the builder's original
     artifacts (such as a VM snapshot).
 
+### Optional:
+
+-   `keep_input_artifact` (boolean) - if true, do not delete the original
+    artifact files after creating your new artifact. Defaults to true.
+
 ### Example Configuration
 
 This minimal example:
diff --git a/website/source/docs/post-processors/checksum.html.md b/website/source/docs/post-processors/checksum.html.md
index fa66cb153..e95a280d9 100644
--- a/website/source/docs/post-processors/checksum.html.md
+++ b/website/source/docs/post-processors/checksum.html.md
@@ -43,6 +43,11 @@ Optional parameters:
 
 -   `checksum_types` (array of strings) - An array of strings of checksum types
     to compute. Allowed values are md5, sha1, sha224, sha256, sha384, sha512.
+
+-   `keep_input_artifact` (boolean) - Unlike most post-processors, setting
+    `keep_input_artifact` will have no effect; the checksum post-processor
+    always saves the artifact that it is calculating the checksum for.
+
 -   `output` (string) - Specify filename to store checksums. This defaults to
     `packer_{{.BuildName}}_{{.BuilderType}}_{{.ChecksumType}}.checksum`. For
     example, if you had a builder named `database`, you might see the file
diff --git a/website/source/docs/post-processors/compress.html.md b/website/source/docs/post-processors/compress.html.md
index c4456f5de..f908612ae 100644
--- a/website/source/docs/post-processors/compress.html.md
+++ b/website/source/docs/post-processors/compress.html.md
@@ -38,7 +38,9 @@ you will need to specify the `output` option.
     algorithms that support it, from 1 through 9 inclusive. Typically higher
     compression levels take longer but produce smaller files. Defaults to `6`
 
--   `keep_input_artifact` (boolean) - Keep source files; defaults to `false`
+-   `keep_input_artifact` (boolean) - if `true`, keep both the source files and
+    the compressed file; if `false`, discard the source files. Defaults to
+    `false`
 
 ### Supported Formats
 
diff --git a/website/source/docs/post-processors/digitalocean-import.html.md b/website/source/docs/post-processors/digitalocean-import.html.md
index 3120b2acb..48a757a76 100644
--- a/website/source/docs/post-processors/digitalocean-import.html.md
+++ b/website/source/docs/post-processors/digitalocean-import.html.md
@@ -67,6 +67,9 @@ Optional:
 -   `image_tags` (array of strings) - A list of tags to apply to the resulting
     imported image.
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the source virtual
+    machine image after importing it to the cloud. Defaults to false.
+
 -   `skip_clean` (boolean) - Whether we should skip removing the image file
     uploaded to Spaces after the import process has completed. "true" means
     that we should leave it in the Space, "false" means to clean it out.
diff --git a/website/source/docs/post-processors/docker-import.html.md b/website/source/docs/post-processors/docker-import.html.md
index 4fb3b0fe3..63665d38a 100644
--- a/website/source/docs/post-processors/docker-import.html.md
+++ b/website/source/docs/post-processors/docker-import.html.md
@@ -38,6 +38,9 @@ is optional.
     commit. Example of instructions are `CMD`, `ENTRYPOINT`, `ENV`, and
     `EXPOSE`. Example: `[ "USER ubuntu", "WORKDIR /app", "EXPOSE 8080" ]`
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the source tar
+    after importing it to docker. Defaults to false.
+
 ## Example
 
 An example is shown below, showing only the post-processor configuration:
diff --git a/website/source/docs/post-processors/docker-push.html.md b/website/source/docs/post-processors/docker-push.html.md
index a63ce9aad..5c626b513 100644
--- a/website/source/docs/post-processors/docker-push.html.md
+++ b/website/source/docs/post-processors/docker-push.html.md
@@ -42,6 +42,10 @@ This post-processor has only optional configuration:
     the duration of the push. If true `login_server` is required and `login`,
     `login_username`, and `login_password` will be ignored.
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the docker image
+    after pushing it to the cloud. Defaults to true, but can be set to false if
+    you do not need to save your local copy of the docker container.
+
 -   `login` (boolean) - Defaults to false. If true, the post-processor will
     login prior to pushing. For log into ECR see `ecr_login`.
 
diff --git a/website/source/docs/post-processors/docker-save.html.md b/website/source/docs/post-processors/docker-save.html.md
index 2fb4bc572..4063d335e 100644
--- a/website/source/docs/post-processors/docker-save.html.md
+++ b/website/source/docs/post-processors/docker-save.html.md
@@ -24,10 +24,17 @@ familiar with this and vice versa.
 
 ## Configuration
 
+### Required
+
 The configuration for this post-processor only requires one option.
 
 -   `path` (string) - The path to save the image.
 
+### Optional
+
+-   `keep_input_artifact` (boolean) - if true, do not delete the docker
+	container, and only save the .tar created by docker save. Defaults to true.
+
 ## Example
 
 An example is shown below, showing only the post-processor configuration:
diff --git a/website/source/docs/post-processors/docker-tag.html.md b/website/source/docs/post-processors/docker-tag.html.md
index 3720bff66..07d441abe 100644
--- a/website/source/docs/post-processors/docker-tag.html.md
+++ b/website/source/docs/post-processors/docker-tag.html.md
@@ -38,6 +38,13 @@ settings are optional.
     after 1.12.0.
     [reference](https://docs.docker.com/engine/deprecated/#/f-flag-on-docker-tag)
 
+-   `keep_input_artifact` (boolean) - Unlike most other post-processors, the
+    keep_input_artifact option will have no effect for the docker-tag
+    post-processor. We will always retain the input artifact for docker-tag,
+    since deleting the image we just tagged is not a behavior anyone should ever
+    expect. `keep_input_artifact will` therefore always be evaluated as true,
+    regardless of the value you enter into this field.
+
 ## Example
 
 An example is shown below, showing only the post-processor configuration:
diff --git a/website/source/docs/post-processors/googlecompute-export.html.md b/website/source/docs/post-processors/googlecompute-export.html.md
index 0484b0c78..79c768a31 100644
--- a/website/source/docs/post-processors/googlecompute-export.html.md
+++ b/website/source/docs/post-processors/googlecompute-export.html.md
@@ -45,8 +45,8 @@ permissions to the GCS `paths`.
 -   `disk_type` (string) - Type of disk used to back export instance, like
     `pd-ssd` or `pd-standard`. Defaults to `pd-ssd`.
 
--   `keep_input_artifact` (boolean) - If true, do not delete the Google Compute
-    Engine (GCE) image being exported.
+-   `keep_input_artifact` (boolean) - If `true`, do not delete the Google Compute
+    Engine (GCE) image being exported. defaults to `false`.
 
 -   `machine_type` (string) - The export instance machine type. Defaults
     to `"n1-highcpu-4"`.
diff --git a/website/source/docs/post-processors/manifest.html.md b/website/source/docs/post-processors/manifest.html.md
index 3bb9bef3b..ace26d528 100644
--- a/website/source/docs/post-processors/manifest.html.md
+++ b/website/source/docs/post-processors/manifest.html.md
@@ -40,6 +40,13 @@ post-processors such as Docker and Artifice.
     file. This defaults to false.
 -   `custom_data` (map of strings) Arbitrary data to add to the manifest.
 
+-   `keep_input_artifact` (boolean) - Unlike most other post-processors, the
+    keep_input_artifact option will have no effect for the manifest
+    post-processor. We will always retain the input artifact for manifest,
+    since deleting the files we just recorded is not a behavior anyone should
+    ever expect. `keep_input_artifact will` therefore always be evaluated as
+    true, regardless of the value you enter into this field.
+
 ### Example Configuration
 
 You can simply add `{"type":"manifest"}` to your post-processor section. Below
diff --git a/website/source/docs/post-processors/shell-local.html.md b/website/source/docs/post-processors/shell-local.html.md
index 7599febf2..0d7c1f4ee 100644
--- a/website/source/docs/post-processors/shell-local.html.md
+++ b/website/source/docs/post-processors/shell-local.html.md
@@ -101,6 +101,15 @@ Optional parameters:
     like the `-e` flag, otherwise individual steps failing won't fail the
     provisioner.
 
+-   `keep_input_artifact` (boolean) - Unlike most other post-processors, the
+    keep_input_artifact option will have no effect for the shell-local
+    post-processor. Packer will always retain the input artifact for
+    shell-local, since the shell-local post-processor merely passes forward the
+    artifact it receives. If your shell-local post-processor produces a file or
+    files which you would like to have replace the input artifact, you may
+    overwrite the input artifact using the [artifice](./artifice.html)
+    post-processor after your shell-local processor has run.
+
 -   `only_on` (array of strings) - This is an array of [runtime operating
     systems](https://golang.org/doc/install/source#environment) where
     `shell-local` will execute. This allows you to execute `shell-local` *only*
diff --git a/website/source/docs/post-processors/vagrant-cloud.html.md b/website/source/docs/post-processors/vagrant-cloud.html.md
index 2accdfb0b..1edac0f8a 100644
--- a/website/source/docs/post-processors/vagrant-cloud.html.md
+++ b/website/source/docs/post-processors/vagrant-cloud.html.md
@@ -84,6 +84,9 @@ on Vagrant Cloud, as well as authentication and version information.
     to set this option to true if your host at vagrant_cloud_url is using a
     self-signed certificate.
 
+-   `keep_input_artifact` (boolean) - When true, preserve the local box
+    after uploading to Vagrant cloud. Defaults to `true`.
+
 -   `version_description` (string) - Optionally markdown text used as a
     full-length and in-depth description of the version, typically for denoting
     changes introduced
diff --git a/website/source/docs/post-processors/vagrant.html.md b/website/source/docs/post-processors/vagrant.html.md
index 253472ed3..62cd0ce0f 100644
--- a/website/source/docs/post-processors/vagrant.html.md
+++ b/website/source/docs/post-processors/vagrant.html.md
@@ -65,8 +65,12 @@ more details about certain options in following sections.
     Vagrant box (regardless of their paths). They can then be used from the
     Vagrantfile.
 
--   `keep_input_artifact` (boolean) - If set to true, do not delete the
-    `output_directory` on a successful build. Defaults to false.
+-   `keep_input_artifact` (boolean) - When true, preserve the artifact we use to
+    create the vagrant box. Defaults to `false`, except when you set a cloud
+    provider (e.g. aws, azure, google, digitalocean). In these cases deleting
+    the input artifact would render the vagrant box useless, so we always keep
+    these artifacts -- even if you specifically set
+    `"keep_input_artifact":false`
 
 -   `output` (string) - The full path to the box file that will be created by
     this post-processor. This is a [configuration
diff --git a/website/source/docs/post-processors/vsphere-template.html.md b/website/source/docs/post-processors/vsphere-template.html.md
index a3ef0e34e..319eeb75e 100644
--- a/website/source/docs/post-processors/vsphere-template.html.md
+++ b/website/source/docs/post-processors/vsphere-template.html.md
@@ -61,6 +61,12 @@ Optional:
 -   `insecure` (boolean) - If it's true skip verification of server
     certificate. Default is false
 
+-   `keep_input_artifact` (boolean) - Unlike most post-processors, this option
+    has no effect for vsphere-template. This is because in order for a template
+    to work, you can't delete the vm that you generate the template from. The
+    vsphere template post-processor will therefore always preserve the original
+    vm.
+
 -   `snapshot_enable` (boolean) - Create a snapshot before marking as a
     template. Default is false
 
diff --git a/website/source/docs/post-processors/vsphere.html.md b/website/source/docs/post-processors/vsphere.html.md
index a6646e2f2..8976e93cc 100644
--- a/website/source/docs/post-processors/vsphere.html.md
+++ b/website/source/docs/post-processors/vsphere.html.md
@@ -54,6 +54,9 @@ Optional:
 -   `insecure` (boolean) - Whether or not the connection to vSphere can be done
     over an insecure connection. By default this is false.
 
+-   `keep_input_artifact` (boolean) - When `true`, preserve the local VM files,
+    even after importing them to vsphere. Defaults to `false`.
+
 -   `resource_pool` (string) - The resource pool to upload the VM to.
 
 -   `vm_folder` (string) - The folder within the datastore to store the VM.