From aeb898d598d4b480e93f81331e7bbcc6295dfe52 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Tue, 18 Jun 2019 18:08:29 +0200 Subject: [PATCH] document amazon-instance builder with partials --- builder/amazon/instance/builder.go | 78 +++++++++++-------- .../docs/builders/amazon-instance.html.md.erb | 69 ++++++++++++---- .../instance/_Config-not-required.html.md | 51 +++++++----- .../amazon/instance/_Config-required.html.md | 22 +++--- .../builder/amazon/instance/_Config.html.md | 4 +- 5 files changed, 142 insertions(+), 82 deletions(-) diff --git a/builder/amazon/instance/builder.go b/builder/amazon/instance/builder.go index 54f8f662f..8acea943b 100644 --- a/builder/amazon/instance/builder.go +++ b/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 -// settable from the template. +// Config is the configuration that is chained through the steps and settable +// 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 - // account ID in the security credentials page of your AWS account. + + // 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"` + // 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 bundled AMI will be saved prior to uploading. By default this is - // /tmp. This directory must exist and be writable. + // The directory on the running instance where the bundled AMI will be + // saved prior to uploading. By default this is /tmp. This directory must + // exist and be writable. BundleDestination string `mapstructure:"bundle_destination" required:"false"` - // The prefix for files created from bundling the - // root volume. By default 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. + // The prefix for files created from bundling the root volume. By default + // 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. BundlePrefix string `mapstructure:"bundle_prefix" required:"false"` - // The command to use to upload the bundled - // volume. See the "custom bundle commands" section below for more - // information. + // The command to use to upload the bundled volume. See the "custom bundle + // commands" section below for more information. BundleUploadCommand string `mapstructure:"bundle_upload_command" required:"false"` - // The command to use to bundle the volume. - // See the "custom bundle commands" section below for more information. + // The command to use to bundle the volume. See the "custom bundle + // 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 - // bucket will be created if it doesn't exist. + // The name of the S3 bucket to upload the AMI. This bucket will be created + // if it doesn't exist. S3Bucket string `mapstructure:"s3_bucket" required:"true"` - // The local path to a valid X509 certificate for - // your AWS account. This is used for bundling the AMI. This X509 certificate - // must be registered with your account from the security credentials page in - // the AWS console. + // The local path to a valid X509 certificate for your AWS account. This is + // used for bundling the AMI. This X509 certificate must be registered with + // your account from the security credentials page in the AWS console. X509CertPath string `mapstructure:"x509_cert_path" required:"true"` - // The local path to the private key for the X509 - // certificate specified by x509_cert_path. This is used for bundling the - // AMI. + // The local path to the private key for the X509 certificate specified by + // x509_cert_path. This is used for bundling the AMI. X509KeyPath string `mapstructure:"x509_key_path" required:"true"` - // 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. + // 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. X509UploadPath string `mapstructure:"x509_upload_path" required:"false"` ctx interpolate.Context diff --git a/website/source/docs/builders/amazon-instance.html.md.erb b/website/source/docs/builders/amazon-instance.html.md.erb index 62025b43f..3aca829a2 100644 --- a/website/source/docs/builders/amazon-instance.html.md.erb +++ b/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 -segmented below into two categories: required and optional parameters. Within -each category, the available configuration keys are alphabetized. - -In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) can be configured for this -builder. +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. ### 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 diff --git a/website/source/partials/builder/amazon/instance/_Config-not-required.html.md b/website/source/partials/builder/amazon/instance/_Config-not-required.html.md index 1c71412e5..5ee3923b2 100644 --- a/website/source/partials/builder/amazon/instance/_Config-not-required.html.md +++ b/website/source/partials/builder/amazon/instance/_Config-not-required.html.md @@ -1,26 +1,39 @@ -- `ami_block_device_mappings` (awscommon.BlockDevices) - AMI Mappings -- `launch_block_device_mappings` (awscommon.BlockDevices) - Launch Mappings -- `bundle_destination` (string) - The directory on the running instance where - the bundled AMI will be saved prior to uploading. By default this is - /tmp. This directory must exist and be writable. +- `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. -- `bundle_prefix` (string) - The prefix for files created from bundling the - root volume. By default 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. +- `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. -- `bundle_upload_command` (string) - The command to use to upload the bundled - volume. See the "custom bundle commands" section below for more - information. +- `bundle_destination` (string) - The directory on the running instance where the bundled AMI will be + saved prior to uploading. By default this is /tmp. This directory must + exist and be writable. -- `bundle_vol_command` (string) - The command to use to bundle the volume. - See the "custom bundle commands" section below for more information. +- `bundle_prefix` (string) - The prefix for files created from bundling the root volume. By default + 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 - 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. +- `bundle_upload_command` (string) - The command to use to upload the bundled volume. See the "custom bundle + commands" section below for more information. + +- `bundle_vol_command` (string) - The command to use to bundle the volume. See the "custom bundle + 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. \ No newline at end of file diff --git a/website/source/partials/builder/amazon/instance/_Config-required.html.md b/website/source/partials/builder/amazon/instance/_Config-required.html.md index afcc402e7..f60edb89c 100644 --- a/website/source/partials/builder/amazon/instance/_Config-required.html.md +++ b/website/source/partials/builder/amazon/instance/_Config-required.html.md @@ -1,18 +1,16 @@ -- `account_id` (string) - 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. +- `account_id` (string) - 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. -- `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. This - bucket will be created if it doesn't exist. +- `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. This bucket will be created + if it doesn't exist. -- `x509_cert_path` (string) - The local path to a valid X509 certificate for - your AWS account. This is used for bundling the AMI. This X509 certificate - must be registered with your account from the security credentials page in - the AWS console. +- `x509_cert_path` (string) - The local path to a valid X509 certificate for your AWS account. This is + used for bundling the AMI. This X509 certificate must be registered with + your account from the security credentials page in the AWS console. -- `x509_key_path` (string) - The local path to the private key for the X509 - certificate specified by x509_cert_path. This is used for bundling the - AMI. +- `x509_key_path` (string) - The local path to the private key for the X509 certificate specified by + x509_cert_path. This is used for bundling the AMI. \ No newline at end of file diff --git a/website/source/partials/builder/amazon/instance/_Config.html.md b/website/source/partials/builder/amazon/instance/_Config.html.md index dd749cca0..92c4a64f0 100644 --- a/website/source/partials/builder/amazon/instance/_Config.html.md +++ b/website/source/partials/builder/amazon/instance/_Config.html.md @@ -1,3 +1,3 @@ -Config is the configuration that is chained through the steps and -settable from the template. +Config is the configuration that is chained through the steps and settable +from the template.