From 72d393c95a9ccf23dd443b69ac3b8fdf4302f871 Mon Sep 17 00:00:00 2001
From: Megan Marsh <megan@hashicorp.com>
Date: Wed, 25 Sep 2019 16:48:04 -0700
Subject: [PATCH] update docs to show a use case for block device mappings

---
 builder/amazon/common/block_device.go         | 20 ++++++++++++++-----
 .../amazon/common/_BlockDevice.html.md        | 20 ++++++++++++++-----
 2 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/builder/amazon/common/block_device.go b/builder/amazon/common/block_device.go
index ebce9dc96..7e6b4c47c 100644
--- a/builder/amazon/common/block_device.go
+++ b/builder/amazon/common/block_device.go
@@ -13,17 +13,27 @@ import (
 )
 
 // These will be attached when booting a new instance from your AMI. Your
-// options here may vary depending on the type of VM you use. Example value:
+// options here may vary depending on the type of VM you use.
+//
+// Example use case:
+//
+// The following mapping will tell Packer to encrypt the root volume of the
+// build instance at launch using a specific non-default kms key:
 //
 // ``` json
-// [{
-//      "device_name":"xvda",
-//      "delete_on_termination":true,
-//      "volume_type":"gp2"
+// "launch_block_device_mappings": [{
+//		"device_name": "/dev/sda1",
+//		"encrypted": true,
+//		"kms_key_id": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
 // }]
 // ```
+//
 // Documentation for Block Devices Mappings can be found here:
 // https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html
+//
+// These mappings give you control over either the volumes generated for the
+// Packer build via `launch_block_device_mappings`, or the volumes that Packer will
+// save with the artifact AMI via `ami_block_device_mappings`.
 type BlockDevice struct {
 	// Indicates whether the EBS volume is deleted on instance termination.
 	// Default false. NOTE: If this value is not explicitly set to true and
diff --git a/website/source/partials/builder/amazon/common/_BlockDevice.html.md b/website/source/partials/builder/amazon/common/_BlockDevice.html.md
index 37eb0577e..8e04ec9f9 100644
--- a/website/source/partials/builder/amazon/common/_BlockDevice.html.md
+++ b/website/source/partials/builder/amazon/common/_BlockDevice.html.md
@@ -1,13 +1,23 @@
 <!-- Code generated from the comments of the BlockDevice struct in builder/amazon/common/block_device.go; DO NOT EDIT MANUALLY -->
 These will be attached when booting a new instance from your AMI. Your
-options here may vary depending on the type of VM you use. Example value:
+options here may vary depending on the type of VM you use.
+
+Example use case:
+
+The following mapping will tell Packer to encrypt the root volume of the
+build instance at launch using a specific non-default kms key:
 
 ``` json
-[{
-     "device_name":"xvda",
-     "delete_on_termination":true,
-     "volume_type":"gp2"
+"launch_block_device_mappings": [{
+		"device_name": "/dev/sda1",
+		"encrypted": true,
+		"kms_key_id": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
 }]
 ```
+
 Documentation for Block Devices Mappings can be found here:
 https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html
+
+These mappings give you control over either the volumes generated for the
+Packer build via `launch_block_device_mappings`, or the volumes that Packer will
+save with the artifact AMI via `ami_block_device_mappings`.