document amazon-instance builder with partials

builder/amazon/instance/builder.go

@@ -24,52 +24,64 @@ import (
 // The unique ID for this builder
 const BuilderId = "mitchellh.amazon.instance"
 
-// Config is the configuration that is chained through the steps and
+// Config is the configuration that is chained through the steps and settable
-// settable from the template.
+// from the template.
 type Config struct {
 	common.PackerConfig    `mapstructure:",squash"`
 	awscommon.AccessConfig `mapstructure:",squash"`
 	awscommon.AMIConfig    `mapstructure:",squash"`
-	AMIMappings            awscommon.BlockDevices `mapstructure:"ami_block_device_mappings" required:"false"`
-	LaunchMappings         awscommon.BlockDevices `mapstructure:"launch_block_device_mappings" required:"false"`
 	awscommon.RunConfig    `mapstructure:",squash"`
-	// Your AWS account ID. This is required for bundling
+
-	// the AMI. This is not the same as the access key. You can find your
+	// Add one or more block device mappings to the AMI. These will be attached
-	// account ID in the security credentials page of your AWS account.
+	// when booting a new instance from your AMI. To add a block device during
+	// the Packer build see `launch_block_device_mappings` below. Your options
+	// here may vary depending on the type of VM you use. See the
+	// [BlockDevices](#block-devices-configuration) documentation for fields.
+	AMIMappings awscommon.BlockDevices `mapstructure:"ami_block_device_mappings" required:"false"`
+	// Add one or more block devices before the Packer build starts. If you add
+	// instance store volumes or EBS volumes in addition to the root device
+	// volume, the created AMI will contain block device mapping information
+	// for those volumes. Amazon creates snapshots of the source instance's
+	// root volume and any other EBS volumes described here. When you launch an
+	// instance from this new AMI, the instance automatically launches with
+	// these additional volumes, and will restore them from snapshots taken
+	// from the source instance. See the
+	// [BlockDevices](#block-devices-configuration) documentation for fields.
+	LaunchMappings awscommon.BlockDevices `mapstructure:"launch_block_device_mappings" required:"false"`
+	// Your AWS account ID. This is required for bundling the AMI. This is not
+	// the same as the access key. You can find your account ID in the security
+	// credentials page of your AWS account.
 	AccountId string `mapstructure:"account_id" required:"true"`
-	// The directory on the running instance where
+	// The directory on the running instance where the bundled AMI will be
-	// the bundled AMI will be saved prior to uploading. By default this is
+	// saved prior to uploading. By default this is /tmp. This directory must
-	// /tmp. This directory must exist and be writable.
+	// exist and be writable.
 	BundleDestination string `mapstructure:"bundle_destination" required:"false"`
-	// The prefix for files created from bundling the
+	// The prefix for files created from bundling the root volume. By default
-	// root volume. By default this is image-{{timestamp}}. The timestamp
+	// this is image-{{timestamp}}. The timestamp variable should be used to
-	// variable should be used to make sure this is unique, otherwise it can
+	// make sure this is unique, otherwise it can collide with other created
-	// collide with other created AMIs by Packer in your account.
+	// AMIs by Packer in your account.
 	BundlePrefix string `mapstructure:"bundle_prefix" required:"false"`
-	// The command to use to upload the bundled
+	// The command to use to upload the bundled volume. See the "custom bundle
-	// volume. See the "custom bundle commands" section below for more
+	// commands" section below for more information.
-	// information.
 	BundleUploadCommand string `mapstructure:"bundle_upload_command" required:"false"`
-	// The command to use to bundle the volume.
+	// The command to use to bundle the volume. See the "custom bundle
-	// See the "custom bundle commands" section below for more information.
+	// commands" section below for more information.
 	BundleVolCommand string `mapstructure:"bundle_vol_command" required:"false"`
-	// The name of the S3 bucket to upload the AMI. This
+	// The name of the S3 bucket to upload the AMI. This bucket will be created
-	// bucket will be created if it doesn't exist.
+	// if it doesn't exist.
 	S3Bucket string `mapstructure:"s3_bucket" required:"true"`
-	// The local path to a valid X509 certificate for
+	// The local path to a valid X509 certificate for your AWS account. This is
-	// your AWS account. This is used for bundling the AMI. This X509 certificate
+	// used for bundling the AMI. This X509 certificate must be registered with
-	// must be registered with your account from the security credentials page in
+	// your account from the security credentials page in the AWS console.
-	// the AWS console.
 	X509CertPath string `mapstructure:"x509_cert_path" required:"true"`
-	// The local path to the private key for the X509
+	// The local path to the private key for the X509 certificate specified by
-	// certificate specified by x509_cert_path. This is used for bundling the
+	// x509_cert_path. This is used for bundling the AMI.
-	// AMI.
 	X509KeyPath string `mapstructure:"x509_key_path" required:"true"`
-	// The path on the remote machine where the X509
+	// The path on the remote machine where the X509 certificate will be
-	// certificate will be uploaded. This path must already exist and be writable.
+	// uploaded. This path must already exist and be writable. X509
-	// X509 certificates are uploaded after provisioning is run, so it is
+	// certificates are uploaded after provisioning is run, so it is perfectly
-	// perfectly okay to create this directory as part of the provisioning
+	// okay to create this directory as part of the provisioning process.
-	// process. Defaults to /tmp.
+	// Defaults to /tmp.
 	X509UploadPath string `mapstructure:"x509_upload_path" required:"false"`
 
 	ctx interpolate.Context

website/source/docs/builders/amazon-instance.html.md.erb

@@ -43,30 +43,67 @@ builder finishes running.
 
 ## Configuration Reference
 
-There are many configuration options available for this builder. They are
+There are many configuration options available for the builder. In addition to
-segmented below into two categories: required and optional parameters. Within
+the items listed here, you will want to look at the general configuration
-each category, the available configuration keys are alphabetized.
+references for [AMI](#ami-configuration),
-
+[BlockDevices](#block-devices-configuration),
-In addition to the options listed here, a
+[Access](#acces-configuration),
-[communicator](/docs/templates/communicator.html) can be configured for this
+[Run](#run-configuration) and
-builder.
+[Communicator](#communicator-configuration)
+configuration references, which are
+necessary for this build to succeed and can be found further down the page.
 
 ### Required:
 
-
-<%= partial "partials/builder/amazon/common/AccessConfig-required" %>
-<%= partial "partials/builder/amazon/common/AMIConfig-required" %>
-<%= partial "partials/builder/amazon/common/RunConfig-required" %>
 <%= partial "partials/builder/amazon/instance/Config-required" %>
 
 ### Optional:
 
-<%= partial "partials/builder/amazon/common/AMIBlockDevices-not-required" %>
-<%= partial "partials/builder/amazon/common/AccessConfig-not-required" %>
-<%= partial "partials/builder/amazon/common/AMIConfig-not-required" %>
-<%= partial "partials/builder/amazon/common/BlockDevice-not-required" %>
-<%= partial "partials/builder/amazon/common/RunConfig-not-required" %>
 <%= partial "partials/builder/amazon/instance/Config-not-required" %>
+
+
+### AMI Configuration
+
+#### Optional:
+<%= partial "partials/builder/amazon/common/AMIConfig-not-required" %>
+
+### Acces Configuration
+
+#### Required:
+
+<%= partial "partials/builder/amazon/common/AccessConfig-required" %>
+
+#### Optional:
+
+<%= partial "partials/builder/amazon/common/AccessConfig-not-required" %>
+
+### Run Configuration
+
+#### Required:
+
+<%= partial "partials/builder/amazon/common/RunConfig-required" %>
+
+#### Optional:
+
+<%= partial "partials/builder/amazon/common/RunConfig-not-required" %>
+
+
+### Block Devices Configuration
+
+Block devices can be nested in the
+[ami_block_device_mappings](#ami_block_device_mappings) or the 
+[launch_block_device_mappings](#launch_block_device_mappings) array.
+
+<%= partial "partials/builder/amazon/common/BlockDevice" %>
+
+
+#### Optional:
+<%= partial "partials/builder/amazon/common/BlockDevice-not-required" %>
+
+### Communicator Configuration
+
+#### Optional:
+
 <%= partial "partials/helper/communicator/Config-not-required" %>
 
 ## Basic Example

website/source/partials/builder/amazon/instance/_Config-not-required.html.md

@@ -1,26 +1,39 @@
 <!-- Code generated from the comments of the Config struct in builder/amazon/instance/builder.go; DO NOT EDIT MANUALLY -->
 
--   `ami_block_device_mappings` (awscommon.BlockDevices) - AMI Mappings
+-   `ami_block_device_mappings` (awscommon.BlockDevices) - Add one or more block device mappings to the AMI. These will be attached
--   `launch_block_device_mappings` (awscommon.BlockDevices) - Launch Mappings
+    when booting a new instance from your AMI. To add a block device during
--   `bundle_destination` (string) - The directory on the running instance where
+    the Packer build see `launch_block_device_mappings` below. Your options
-    the bundled AMI will be saved prior to uploading. By default this is
+    here may vary depending on the type of VM you use. See the
-    /tmp. This directory must exist and be writable.
+    [BlockDevices](#block-devices-configuration) documentation for fields.
     
--   `bundle_prefix` (string) - The prefix for files created from bundling the
+-   `launch_block_device_mappings` (awscommon.BlockDevices) - Add one or more block devices before the Packer build starts. If you add
-    root volume. By default this is image-{{timestamp}}. The timestamp
+    instance store volumes or EBS volumes in addition to the root device
-    variable should be used to make sure this is unique, otherwise it can
+    volume, the created AMI will contain block device mapping information
-    collide with other created AMIs by Packer in your account.
+    for those volumes. Amazon creates snapshots of the source instance's
+    root volume and any other EBS volumes described here. When you launch an
+    instance from this new AMI, the instance automatically launches with
+    these additional volumes, and will restore them from snapshots taken
+    from the source instance. See the
+    [BlockDevices](#block-devices-configuration) documentation for fields.
     
--   `bundle_upload_command` (string) - The command to use to upload the bundled
+-   `bundle_destination` (string) - The directory on the running instance where the bundled AMI will be
-    volume. See the "custom bundle commands" section below for more
+    saved prior to uploading. By default this is /tmp. This directory must
-    information.
+    exist and be writable.
     
--   `bundle_vol_command` (string) - The command to use to bundle the volume.
+-   `bundle_prefix` (string) - The prefix for files created from bundling the root volume. By default
-    See the "custom bundle commands" section below for more information.
+    this is image-{{timestamp}}. The timestamp variable should be used to
+    make sure this is unique, otherwise it can collide with other created
+    AMIs by Packer in your account.
     
--   `x509_upload_path` (string) - The path on the remote machine where the X509
+-   `bundle_upload_command` (string) - The command to use to upload the bundled volume. See the "custom bundle
-    certificate will be uploaded. This path must already exist and be writable.
+    commands" section below for more information.
-    X509 certificates are uploaded after provisioning is run, so it is
+    
-    perfectly okay to create this directory as part of the provisioning
+-   `bundle_vol_command` (string) - The command to use to bundle the volume. See the "custom bundle
-    process. Defaults to /tmp.
+    commands" section below for more information.
+    
+-   `x509_upload_path` (string) - The path on the remote machine where the X509 certificate will be
+    uploaded. This path must already exist and be writable. X509
+    certificates are uploaded after provisioning is run, so it is perfectly
+    okay to create this directory as part of the provisioning process.
+    Defaults to /tmp.
     

website/source/partials/builder/amazon/instance/_Config-required.html.md

@@ -1,18 +1,16 @@
 <!-- Code generated from the comments of the Config struct in builder/amazon/instance/builder.go; DO NOT EDIT MANUALLY -->
 
--   `account_id` (string) - Your AWS account ID. This is required for bundling
+-   `account_id` (string) - Your AWS account ID. This is required for bundling the AMI. This is not
-    the AMI. This is not the same as the access key. You can find your
+    the same as the access key. You can find your account ID in the security
-    account ID in the security credentials page of your AWS account.
+    credentials page of your AWS account.
     
--   `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. This
+-   `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. This bucket will be created
-    bucket will be created if it doesn't exist.
+    if it doesn't exist.
     
--   `x509_cert_path` (string) - The local path to a valid X509 certificate for
+-   `x509_cert_path` (string) - The local path to a valid X509 certificate for your AWS account. This is
-    your AWS account. This is used for bundling the AMI. This X509 certificate
+    used for bundling the AMI. This X509 certificate must be registered with
-    must be registered with your account from the security credentials page in
+    your account from the security credentials page in the AWS console.
-    the AWS console.
     
--   `x509_key_path` (string) - The local path to the private key for the X509
+-   `x509_key_path` (string) - The local path to the private key for the X509 certificate specified by
-    certificate specified by x509_cert_path. This is used for bundling the
+    x509_cert_path. This is used for bundling the AMI.
-    AMI.
     

website/source/partials/builder/amazon/instance/_Config.html.md

@@ -1,3 +1,3 @@
 <!-- Code generated from the comments of the Config struct in builder/amazon/instance/builder.go; DO NOT EDIT MANUALLY -->
-Config is the configuration that is chained through the steps and
+Config is the configuration that is chained through the steps and settable
-settable from the template.
+from the template.