From 9f4c8fb321cf333f7053abfed03e0eb2a2f17b1a Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Tue, 18 Jun 2019 17:37:33 +0200 Subject: [PATCH] document ebs builder using partials --- builder/amazon/common/block_device.go | 2 + builder/amazon/ebs/builder.go | 18 +++++- .../docs/builders/amazon-ebs.html.md.erb | 64 +++++++++++++++---- .../amazon/common/_BlockDevice.html.md | 2 + .../amazon/ebs/_Config-not-required.html.md | 18 +++++- 5 files changed, 86 insertions(+), 18 deletions(-) diff --git a/builder/amazon/common/block_device.go b/builder/amazon/common/block_device.go index b0647849f..fbc13cf8a 100644 --- a/builder/amazon/common/block_device.go +++ b/builder/amazon/common/block_device.go @@ -24,6 +24,8 @@ import ( // }] // } // ``` +// Documentation for Block Devices Mappings can be found here: +// https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html 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/builder/amazon/ebs/builder.go b/builder/amazon/ebs/builder.go index 1284ee5a6..b46a16487 100644 --- a/builder/amazon/ebs/builder.go +++ b/builder/amazon/ebs/builder.go @@ -28,9 +28,23 @@ 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"` + // Add one or more block device mappings to the AMI. These will be attached + // 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"` // Tags to apply to the volumes that are *launched* to create the AMI. // These tags are *not* applied to the resulting AMI unless they're // duplicated in `tags`. This is a [template diff --git a/website/source/docs/builders/amazon-ebs.html.md.erb b/website/source/docs/builders/amazon-ebs.html.md.erb index 3fd837c45..5dbb2e662 100644 --- a/website/source/docs/builders/amazon-ebs.html.md.erb +++ b/website/source/docs/builders/amazon-ebs.html.md.erb @@ -33,29 +33,65 @@ your account, it is up to you to use, delete, etc. the AMI. prefix `packer`. This can be useful if you want to restrict the security groups and key pairs Packer is able to operate on. -## Configuration Reference +## EBS Specific Configuration Reference -There are many configuration options available for the builder. They are -segmented below into two categories: required and optional parameters. Within -each category, the available configuration keys are alphabetized. +There are many configuration options available for the builder. In addition to +the items listed here, you will want to look at the general configuration +references for [AMI](#ami-configuration), +[BlockDevices](#block-devices-configuration), +[Access](#acces-configuration), +[Run](#run-configuration) and +[Communicator](#communicator-configuration) +configuration references, which are +necessary for this build to succeed and can be found further down the page. -In addition to the options listed here, a -[communicator](../templates/communicator.html) can be configured for this -builder. +#### Optional: -### Required: +<%= partial "partials/builder/amazon/ebs/Config-not-required" %> + + +### AMI Configuration + +#### Optional: +<%= partial "partials/builder/amazon/common/AMIConfig-not-required" %> + +### Acces Configuration + +#### Required: <%= partial "partials/builder/amazon/common/AccessConfig-required" %> -<%= partial "partials/builder/amazon/common/AMIConfig-required" %> -<%= partial "partials/builder/amazon/common/RunConfig-required" %> -### Optional: +#### 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" %> + +### Run Configuration + +#### Required: + +<%= partial "partials/builder/amazon/common/RunConfig-required" %> + +#### Optional: + <%= partial "partials/builder/amazon/common/RunConfig-not-required" %> -<%= partial "partials/builder/amazon/common/LaunchBlockDevices-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 diff --git a/website/source/partials/builder/amazon/common/_BlockDevice.html.md b/website/source/partials/builder/amazon/common/_BlockDevice.html.md index 2d1cbc473..3e2ab3b58 100644 --- a/website/source/partials/builder/amazon/common/_BlockDevice.html.md +++ b/website/source/partials/builder/amazon/common/_BlockDevice.html.md @@ -12,3 +12,5 @@ Your options here may vary depending on the type of VM you use. Example: }] } ``` +Documentation for Block Devices Mappings can be found here: +https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html diff --git a/website/source/partials/builder/amazon/ebs/_Config-not-required.html.md b/website/source/partials/builder/amazon/ebs/_Config-not-required.html.md index c797c893a..d49d105c5 100644 --- a/website/source/partials/builder/amazon/ebs/_Config-not-required.html.md +++ b/website/source/partials/builder/amazon/ebs/_Config-not-required.html.md @@ -1,7 +1,21 @@ -- `ami_block_device_mappings` (awscommon.BlockDevices) - AMI Mappings -- `launch_block_device_mappings` (awscommon.BlockDevices) - Launch Mappings +- `ami_block_device_mappings` (awscommon.BlockDevices) - Add one or more block device mappings to the AMI. These will be attached + 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. + +- `launch_block_device_mappings` (awscommon.BlockDevices) - 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. + - `run_volume_tags` (awscommon.TagMap) - Tags to apply to the volumes that are *launched* to create the AMI. These tags are *not* applied to the resulting AMI unless they're duplicated in `tags`. This is a [template