From a476ab79d7fffc736392d18254400604b8458916 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Tue, 18 Jun 2019 17:05:10 +0200 Subject: [PATCH] document chroot builder using partials --- builder/amazon/chroot/builder.go | 17 +-- builder/amazon/common/block_device.go | 14 +- .../docs/builders/amazon-chroot.html.md.erb | 52 +++++-- .../chroot/_BlockDevice-not-required.html.md | 10 ++ .../chroot/_Config-not-required.html.md | 141 +++++++++--------- .../amazon/chroot/_Config-required.html.md | 8 +- .../builder/amazon/chroot/_Config.html.md | 4 +- .../_AMIBlockDevices-not-required.html.md | 52 ------- .../common/_BlockDevice-not-required.html.md | 57 +++---- .../amazon/common/_BlockDevice.html.md | 14 +- .../_LaunchBlockDevices-not-required.html.md | 19 --- .../amazon/ebs/_Config-not-required.html.md | 2 + .../_BlockDevice-not-required.html.md | 4 + .../ebssurrogate/_Config-not-required.html.md | 2 + .../_BlockDevice-not-required.html.md | 1 + .../ebsvolume/_Config-not-required.html.md | 4 +- .../instance/_Config-not-required.html.md | 2 + .../iso/_Config-not-required.html.md | 117 +++++++-------- 18 files changed, 249 insertions(+), 271 deletions(-) create mode 100644 website/source/partials/builder/amazon/chroot/_BlockDevice-not-required.html.md delete mode 100644 website/source/partials/builder/amazon/common/_AMIBlockDevices-not-required.html.md delete mode 100644 website/source/partials/builder/amazon/common/_LaunchBlockDevices-not-required.html.md create mode 100644 website/source/partials/builder/amazon/ebssurrogate/_BlockDevice-not-required.html.md diff --git a/builder/amazon/chroot/builder.go b/builder/amazon/chroot/builder.go index cb0ae92f7..0c0e5771e 100644 --- a/builder/amazon/chroot/builder.go +++ b/builder/amazon/chroot/builder.go @@ -29,18 +29,13 @@ type Config struct { common.PackerConfig `mapstructure:",squash"` awscommon.AMIConfig `mapstructure:",squash"` awscommon.AccessConfig `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 - // documentation for fields. + // Add one or more block device mappings to the AMI. If this field is + // populated, and you are building from an existing source image, the block + // device mappings in the source image will be overwritten. This means you + // must have a block device mapping entry for your root volume, + // `root_volume_size` and `root_device_name`. See the + // [BlockDevices](#block-devices-configuration) documentation for fields. AMIMappings BlockDevices `mapstructure:"ami_block_device_mappings" required:"false"` - // 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 - // documentation for fields. - LaunchMappings BlockDevices `mapstructure:"launch_block_device_mappings" required:"false"` // This is a list of devices to mount into the chroot environment. This // configuration parameter requires some additional documentation which is // in the Chroot Mounts section. Please read that section for more diff --git a/builder/amazon/common/block_device.go b/builder/amazon/common/block_device.go index 15c1ddd9b..b0647849f 100644 --- a/builder/amazon/common/block_device.go +++ b/builder/amazon/common/block_device.go @@ -11,7 +11,19 @@ import ( "github.com/hashicorp/packer/template/interpolate" ) -// TODO(adrien): doc correctly +// 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: +// +// ``` json +// "builders":[{ +// "type":"...", +// "ami_block_device_mappings":[{ +// "device_name":"xvda", +// "delete_on_termination":true, +// "volume_type":"gp2" +// }] +// } +// ``` 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/docs/builders/amazon-chroot.html.md.erb b/website/source/docs/builders/amazon-chroot.html.md.erb index 3fc819bf0..f2dc33d0a 100644 --- a/website/source/docs/builders/amazon-chroot.html.md.erb +++ b/website/source/docs/builders/amazon-chroot.html.md.erb @@ -31,7 +31,7 @@ builder](/docs/builders/amazon-ebs.html), which is much easier to use. The builder does *not* manage AMIs. Once it creates an AMI and stores it in your account, it is up to you to use, delete, etc., the AMI. -## How Does it Work? +### How Does it Work? This builder works by creating a new EBS volume from an existing source AMI and attaching it into an already-running EC2 instance. Once attached, a @@ -49,23 +49,53 @@ expensive because the EC2 instance must be kept running persistently in order to build AMIs, whereas the other AMI builders start instances on-demand to build AMIs as needed. -## Configuration Reference +## Chroot 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) and +[Access](#acces-config-configuration) configuration references, which are +necessary for this build to succeed and can be found further down the page. -### Required: +#### Required: -<%= partial "partials/builder/amazon/common/AccessConfig-required" %> <%= partial "partials/builder/amazon/chroot/Config-required" %> -### Optional: - +#### Optional: <%= partial "partials/builder/amazon/chroot/Config-not-required" %> -<%= partial "partials/builder/amazon/common/AccessConfig-not-required" %> + +## General Common Configuration Reference + +Following will be a set of fields that are also settable for other aws +builders. + +### AMI Configuration + +#### Optional: <%= partial "partials/builder/amazon/common/AMIConfig-not-required" %> -<%= partial "partials/builder/amazon/common/AMIBlockDevices-not-required" %> + +### Block Devices Configuration + +Block devices can be nested in the +[ami_block_device_mappings](#ami_block_device_mappings) array. + +<%= partial "partials/builder/amazon/common/BlockDevice" %> + + +#### Optional: +<%= partial "partials/builder/amazon/common/BlockDevice-not-required" %> +<%= partial "partials/builder/amazon/chroot/BlockDevice-not-required" %> + +### Acces Config Configuration + +#### Required: + +<%= partial "partials/builder/amazon/common/AccessConfig-required" %> + +#### Optional: + +<%= partial "partials/builder/amazon/common/AccessConfig-not-required" %> ## Basic Example diff --git a/website/source/partials/builder/amazon/chroot/_BlockDevice-not-required.html.md b/website/source/partials/builder/amazon/chroot/_BlockDevice-not-required.html.md new file mode 100644 index 000000000..be5d68ffe --- /dev/null +++ b/website/source/partials/builder/amazon/chroot/_BlockDevice-not-required.html.md @@ -0,0 +1,10 @@ + + +- `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot volume encryption. This + only applies to the main region, other regions where the AMI will be + copied will be encrypted by the default EBS KMS key. For valid formats + see KmsKeyId in the [AWS API docs - + CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html) + This field is validated by Packer, when using an alias, you will have to + prefix kms_key_id with alias/. + \ No newline at end of file diff --git a/website/source/partials/builder/amazon/chroot/_Config-not-required.html.md b/website/source/partials/builder/amazon/chroot/_Config-not-required.html.md index e21aaf40d..34814ca51 100644 --- a/website/source/partials/builder/amazon/chroot/_Config-not-required.html.md +++ b/website/source/partials/builder/amazon/chroot/_Config-not-required.html.md @@ -1,96 +1,96 @@ -- `chroot_mounts` ([][]string) - This is a list of devices to - mount into the chroot environment. This configuration parameter requires - some additional documentation which is in the Chroot - Mounts section. Please read that section for more +- `ami_block_device_mappings` (BlockDevices) - Add one or more block device mappings to the AMI. If this field is + populated, and you are building from an existing source image, the block + device mappings in the source image will be overwritten. This means you + must have a block device mapping entry for your root volume, + `root_volume_size` and `root_device_name`. See the + [BlockDevices](#block-devices-configuration) documentation for fields. + +- `chroot_mounts` ([][]string) - This is a list of devices to mount into the chroot environment. This + configuration parameter requires some additional documentation which is + in the Chroot Mounts section. Please read that section for more information on how to use this. -- `command_wrapper` (string) - How to run shell commands. This defaults to - {{.Command}}. This may be useful to set if you want to set environmental - variables or perhaps run it with sudo or so on. This is a configuration - template where the .Command variable is replaced with the command to be - run. Defaults to {{.Command}}. +- `command_wrapper` (string) - How to run shell commands. This defaults to {{.Command}}. This may be + useful to set if you want to set environmental variables or perhaps run + it with sudo or so on. This is a configuration template where the + .Command variable is replaced with the command to be run. Defaults to + {{.Command}}. -- `copy_files` ([]string) - Paths to files on the running EC2 - instance that will be copied into the chroot environment prior to - provisioning. Defaults to /etc/resolv.conf so that DNS lookups work. Pass - an empty list to skip copying /etc/resolv.conf. You may need to do this - if you're building an image that uses systemd. +- `copy_files` ([]string) - Paths to files on the running EC2 instance that will be copied into the + chroot environment prior to provisioning. Defaults to /etc/resolv.conf + so that DNS lookups work. Pass an empty list to skip copying + /etc/resolv.conf. You may need to do this if you're building an image + that uses systemd. -- `device_path` (string) - The path to the device where the root volume of - the source AMI will be attached. This defaults to "" (empty string), which - forces Packer to find an open device automatically. +- `device_path` (string) - The path to the device where the root volume of the source AMI will be + attached. This defaults to "" (empty string), which forces Packer to + find an open device automatically. -- `nvme_device_path` (string) - When we call the mount command (by default - mount -o device dir), the string provided in nvme_mount_path will - replace device in that command. When this option is not set, device in - that command will be something like /dev/sdf1, mirroring the attached - device name. This assumption works for most instances but will fail with c5 - and m5 instances. In order to use the chroot builder with c5 and m5 - instances, you must manually set nvme_device_path and device_path. +- `nvme_device_path` (string) - When we call the mount command (by default mount -o device dir), the + string provided in nvme_mount_path will replace device in that command. + When this option is not set, device in that command will be something + like /dev/sdf1, mirroring the attached device name. This assumption + works for most instances but will fail with c5 and m5 instances. In + order to use the chroot builder with c5 and m5 instances, you must + manually set nvme_device_path and device_path. -- `from_scratch` (bool) - Build a new volume instead of starting from an - existing AMI root volume snapshot. Default false. If true, source_ami - is no longer used and the following options become required: - ami_virtualization_type, pre_mount_commands and root_volume_size. The - below options are also required in this mode only: +- `from_scratch` (bool) - Build a new volume instead of starting from an existing AMI root volume + snapshot. Default false. If true, source_ami is no longer used and the + following options become required: ami_virtualization_type, + pre_mount_commands and root_volume_size. The below options are also + required in this mode only: -- `mount_options` ([]string) - Options to supply the mount command - when mounting devices. Each option will be prefixed with -o and supplied - to the mount command ran by Packer. Because this command is ran in a - shell, user discretion is advised. See this manual page for the mount - command for valid file +- `mount_options` ([]string) - Options to supply the mount command when mounting devices. Each option + will be prefixed with -o and supplied to the mount command ran by + Packer. Because this command is ran in a shell, user discretion is + advised. See this manual page for the mount command for valid file system specific options. -- `mount_partition` (string) - The partition number containing the / - partition. By default this is the first partition of the volume, (for - example, xvda1) but you can designate the entire block device by setting - "mount_partition": "0" in your config, which will mount xvda instead. +- `mount_partition` (string) - The partition number containing the / partition. By default this is the + first partition of the volume, (for example, xvda1) but you can + designate the entire block device by setting "mount_partition": "0" in + your config, which will mount xvda instead. -- `mount_path` (string) - The path where the volume will be mounted. This is - where the chroot environment will be. This defaults to +- `mount_path` (string) - The path where the volume will be mounted. This is where the chroot + environment will be. This defaults to /mnt/packer-amazon-chroot-volumes/{{.Device}}. This is a configuration template where the .Device variable is replaced with the name of the device where the volume is attached. -- `post_mount_commands` ([]string) - As pre_mount_commands, but the - commands are executed after mounting the root device and before the extra - mount and copy steps. The device and mount path are provided by - {{.Device}} and {{.MountPath}}. +- `post_mount_commands` ([]string) - As pre_mount_commands, but the commands are executed after mounting the + root device and before the extra mount and copy steps. The device and + mount path are provided by {{.Device}} and {{.MountPath}}. -- `pre_mount_commands` ([]string) - A series of commands to execute - after attaching the root volume and before mounting the chroot. This is not - required unless using from_scratch. If so, this should include any - partitioning and filesystem creation commands. The path to the device is - provided by {{.Device}}. +- `pre_mount_commands` ([]string) - A series of commands to execute after attaching the root volume and + before mounting the chroot. This is not required unless using + from_scratch. If so, this should include any partitioning and filesystem + creation commands. The path to the device is provided by {{.Device}}. - `root_device_name` (string) - The root device name. For example, xvda. -- `root_volume_size` (int64) - The size of the root volume in GB for the - chroot environment and the resulting AMI. Default size is the snapshot size - of the source_ami unless from_scratch is true, in which case this - field must be defined. +- `root_volume_size` (int64) - The size of the root volume in GB for the chroot environment and the + resulting AMI. Default size is the snapshot size of the source_ami + unless from_scratch is true, in which case this field must be defined. -- `root_volume_type` (string) - The type of EBS volume for the chroot - environment and resulting AMI. The default value is the type of the - source_ami, unless from_scratch is true, in which case the default - value is gp2. You can only specify io1 if building based on top of a - source_ami which is also io1. +- `root_volume_type` (string) - The type of EBS volume for the chroot environment and resulting AMI. The + default value is the type of the source_ami, unless from_scratch is + true, in which case the default value is gp2. You can only specify io1 + if building based on top of a source_ami which is also io1. -- `source_ami_filter` (awscommon.AmiFilterOptions) - Filters used to populate the source_ami - field. Example: +- `source_ami_filter` (awscommon.AmiFilterOptions) - Filters used to populate the source_ami field. Example: ``` json { "source_ami_filter": { - "filters": { - "virtualization-type": "hvm", - "name": "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*", - "root-device-type": "ebs" - }, - "owners": ["099720109477"], - "most_recent": true + "filters": { + "virtualization-type": "hvm", + "name": "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*", + "root-device-type": "ebs" + }, + "owners": ["099720109477"], + "most_recent": true } } ``` @@ -120,11 +120,10 @@ criteria provided in `source_ami_filter`; this pins the AMI returned by the filter, but will cause Packer to fail if the `source_ami` does not exist. -- `root_volume_tags` (awscommon.TagMap) - Tags to apply to the - volumes that are *launched*. This is a [template +- `root_volume_tags` (awscommon.TagMap) - Tags to apply to the volumes that are *launched*. This is a [template engine](/docs/templates/engine.html), see [Build template data](#build-template-data) for more information. -- `ami_architecture` (string) - what architecture to use when registering the - final AMI; valid options are "x86_64" or "arm64". Defaults to "x86_64". +- `ami_architecture` (string) - what architecture to use when registering the final AMI; valid options + are "x86_64" or "arm64". Defaults to "x86_64". \ No newline at end of file diff --git a/website/source/partials/builder/amazon/chroot/_Config-required.html.md b/website/source/partials/builder/amazon/chroot/_Config-required.html.md index 61be88601..68243a7d3 100644 --- a/website/source/partials/builder/amazon/chroot/_Config-required.html.md +++ b/website/source/partials/builder/amazon/chroot/_Config-required.html.md @@ -1,7 +1,7 @@ -- `source_ami` (string) - The source AMI whose root volume will be copied and - provisioned on the currently running instance. This must be an EBS-backed - AMI with a root volume snapshot that you have access to. Note: this is not - used when from_scratch is set to true. +- `source_ami` (string) - The source AMI whose root volume will be copied and provisioned on the + currently running instance. This must be an EBS-backed AMI with a root + volume snapshot that you have access to. Note: this is not used when + from_scratch is set to true. \ No newline at end of file diff --git a/website/source/partials/builder/amazon/chroot/_Config.html.md b/website/source/partials/builder/amazon/chroot/_Config.html.md index 7831c185a..3edb22fee 100644 --- a/website/source/partials/builder/amazon/chroot/_Config.html.md +++ b/website/source/partials/builder/amazon/chroot/_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. diff --git a/website/source/partials/builder/amazon/common/_AMIBlockDevices-not-required.html.md b/website/source/partials/builder/amazon/common/_AMIBlockDevices-not-required.html.md deleted file mode 100644 index 831deb552..000000000 --- a/website/source/partials/builder/amazon/common/_AMIBlockDevices-not-required.html.md +++ /dev/null @@ -1,52 +0,0 @@ - - -- `ami_block_device_mappings` ([]BlockDevice) - Add one or more [block device - mappings](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html) - 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. The block device mappings allow for - the following configuration: - - `delete_on_termination` (boolean) - Indicates whether the EBS volume is - deleted on instance termination. Default `false`. **NOTE**: If this - value is not explicitly set to `true` and volumes are not cleaned up by - an alternative method, additional volumes will accumulate after every - build. - - - `device_name` (string) - The device name exposed to the instance (for - example, `/dev/sdh` or `xvdh`). Required for every device in the block - device mapping. - - - `encrypted` (boolean) - Indicates whether or not to encrypt the volume. - By default, Packer will keep the encryption setting to what it was in - the source image. Setting `false` will result in an unencrypted device, - and `true` will result in an encrypted one. - - - `iops` (number) - The number of I/O operations per second (IOPS) that - the volume supports. See the documentation on - [IOPs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) - for more information - - - `kms_key_id` (string) - The ARN for the KMS encryption key. When - specifying `kms_key_id`, `encrypted` needs to be set to `true`. For - valid formats see *KmsKeyId* in the [AWS API docs - - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). - - - `no_device` (boolean) - Suppresses the specified device included in the - block device mapping of the AMI. - - - `snapshot_id` (string) - The ID of the snapshot. - - - `virtual_name` (string) - The virtual device name. See the - documentation on [Block Device - Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) - for more information. - - - `volume_size` (number) - The size of the volume, in GiB. Required if - not specifying a `snapshot_id`. - - - `volume_type` (string) - The volume type. `gp2` for General Purpose - (SSD) volumes, `io1` for Provisioned IOPS (SSD) volumes, `st1` for - Throughput Optimized HDD, `sc1` for Cold HDD, and `standard` for - Magnetic volumes. - \ No newline at end of file diff --git a/website/source/partials/builder/amazon/common/_BlockDevice-not-required.html.md b/website/source/partials/builder/amazon/common/_BlockDevice-not-required.html.md index 8f85eda56..e8c1616ec 100644 --- a/website/source/partials/builder/amazon/common/_BlockDevice-not-required.html.md +++ b/website/source/partials/builder/amazon/common/_BlockDevice-not-required.html.md @@ -1,50 +1,33 @@ -- `delete_on_termination` (bool) - Indicates whether the EBS volume is - deleted on instance termination. Default false. NOTE: If this - value is not explicitly set to true and volumes are not cleaned up by - an alternative method, additional volumes will accumulate after every - build. +- `delete_on_termination` (bool) - Indicates whether the EBS volume is deleted on instance termination. + Default false. NOTE: If this value is not explicitly set to true and + volumes are not cleaned up by an alternative method, additional volumes + will accumulate after every build. -- `device_name` (string) - The device name exposed to the instance (for - example, /dev/sdh or xvdh). Required for every device in the block - device mapping. +- `device_name` (string) - The device name exposed to the instance (for example, /dev/sdh or xvdh). + Required for every device in the block device mapping. -- `encrypted` (*bool) - Indicates whether or not to encrypt the volume. - By default, Packer will keep the encryption setting to what it was in - the source image. Setting false will result in an unencrypted device, - and true will result in an encrypted one. +- `encrypted` (*bool) - Indicates whether or not to encrypt the volume. By default, Packer will + keep the encryption setting to what it was in the source image. Setting + false will result in an unencrypted device, and true will result in an + encrypted one. -- `iops` (int64) - The number of I/O operations per second (IOPS) that - the volume supports. See the documentation on - IOPs - for more information +- `iops` (int64) - The number of I/O operations per second (IOPS) that the volume supports. + See the documentation on IOPs for more information -- `no_device` (bool) - Suppresses the specified device included in the - block device mapping of the AMI. +- `no_device` (bool) - Suppresses the specified device included in the block device mapping of + the AMI. - `snapshot_id` (string) - The ID of the snapshot. -- `virtual_name` (string) - The virtual device name. See the - documentation on Block Device - Mapping +- `virtual_name` (string) - The virtual device name. See the documentation on Block Device Mapping for more information. -- `volume_type` (string) - The volume type. gp2 for General Purpose - (SSD) volumes, io1 for Provisioned IOPS (SSD) volumes, st1 for - Throughput Optimized HDD, sc1 for Cold HDD, and standard for - Magnetic volumes. +- `volume_type` (string) - The volume type. gp2 for General Purpose (SSD) volumes, io1 for + Provisioned IOPS (SSD) volumes, st1 for Throughput Optimized HDD, sc1 + for Cold HDD, and standard for Magnetic volumes. -- `volume_size` (int64) - The size of the volume, in GiB. Required if - not specifying a snapshot_id. - -- `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot - volume encryption. This only applies to the main region, other regions - where the AMI will be copied will be encrypted by the default EBS KMS key. - For valid formats see KmsKeyId in the [AWS API docs - - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html) - This field is validated by Packer, when using an alias, you will have to - prefix kms_key_id with alias/. - -- `omit_from_artifact` (bool) - ebssurrogate only +- `volume_size` (int64) - The size of the volume, in GiB. Required if not specifying a + snapshot_id. \ No newline at end of file diff --git a/website/source/partials/builder/amazon/common/_BlockDevice.html.md b/website/source/partials/builder/amazon/common/_BlockDevice.html.md index 3d831aa0d..2d1cbc473 100644 --- a/website/source/partials/builder/amazon/common/_BlockDevice.html.md +++ b/website/source/partials/builder/amazon/common/_BlockDevice.html.md @@ -1,2 +1,14 @@ -BlockDevice +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: + +``` json +"builders":[{ +"type":"...", +"ami_block_device_mappings":[{ + "device_name":"xvda", + "delete_on_termination":true, + "volume_type":"gp2" + }] + } +``` diff --git a/website/source/partials/builder/amazon/common/_LaunchBlockDevices-not-required.html.md b/website/source/partials/builder/amazon/common/_LaunchBlockDevices-not-required.html.md deleted file mode 100644 index d9efd82e8..000000000 --- a/website/source/partials/builder/amazon/common/_LaunchBlockDevices-not-required.html.md +++ /dev/null @@ -1,19 +0,0 @@ - - -- `launch_block_device_mappings` ([]BlockDevice) - 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. - - In addition to the fields available in ami_block_device_mappings, you - may optionally use the following field: - - `omit_from_artifact` (boolean) - If true, this block device will not - be snapshotted and the created AMI will not contain block device mapping - information for this volume. If false, the block device will be mapped - into the final created AMI. Set this option to true if you need a block - device mounted in the surrogate AMI but not in the final created AMI. - \ No newline at end of file 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 80f25ce3e..c797c893a 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,5 +1,7 @@ +- `ami_block_device_mappings` (awscommon.BlockDevices) - AMI Mappings +- `launch_block_device_mappings` (awscommon.BlockDevices) - Launch Mappings - `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 diff --git a/website/source/partials/builder/amazon/ebssurrogate/_BlockDevice-not-required.html.md b/website/source/partials/builder/amazon/ebssurrogate/_BlockDevice-not-required.html.md new file mode 100644 index 000000000..c1694fdaa --- /dev/null +++ b/website/source/partials/builder/amazon/ebssurrogate/_BlockDevice-not-required.html.md @@ -0,0 +1,4 @@ + + +- `omit_from_artifact` (bool) - ebssurrogate only + \ No newline at end of file diff --git a/website/source/partials/builder/amazon/ebssurrogate/_Config-not-required.html.md b/website/source/partials/builder/amazon/ebssurrogate/_Config-not-required.html.md index db9846f2a..934fb5add 100644 --- a/website/source/partials/builder/amazon/ebssurrogate/_Config-not-required.html.md +++ b/website/source/partials/builder/amazon/ebssurrogate/_Config-not-required.html.md @@ -1,5 +1,7 @@ +- `ami_block_device_mappings` (awscommon.BlockDevices) - AMI Mappings +- `launch_block_device_mappings` (BlockDevices) - Launch Mappings - `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 diff --git a/website/source/partials/builder/amazon/ebsvolume/_BlockDevice-not-required.html.md b/website/source/partials/builder/amazon/ebsvolume/_BlockDevice-not-required.html.md index c27a24348..4d7e40a97 100644 --- a/website/source/partials/builder/amazon/ebsvolume/_BlockDevice-not-required.html.md +++ b/website/source/partials/builder/amazon/ebsvolume/_BlockDevice-not-required.html.md @@ -1,5 +1,6 @@ +- `omit_from_artifact` (bool) - Omit From Artifact - `tags` (awscommon.TagMap) - Tags applied to the AMI. This is a template engine, see Build template data for more information. diff --git a/website/source/partials/builder/amazon/ebsvolume/_Config-not-required.html.md b/website/source/partials/builder/amazon/ebsvolume/_Config-not-required.html.md index 6ec436c83..3582c5d28 100644 --- a/website/source/partials/builder/amazon/ebsvolume/_Config-not-required.html.md +++ b/website/source/partials/builder/amazon/ebsvolume/_Config-not-required.html.md @@ -1,7 +1,7 @@ -- `ebs_volumes` ([]BlockDevice) - Add the block device - mappings to the AMI. The block device mappings allow for keys: +- `ebs_volumes` (BlockDevices) - Add the block device mappings to the AMI. The block device mappings + allow for keys: - `ena_support` (*bool) - Enable enhanced networking (ENA but not SriovNetSupport) on HVM-compatible AMIs. If set, add ec2:ModifyInstanceAttribute to your AWS 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 fd4a09cd4..1c71412e5 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,5 +1,7 @@ +- `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. diff --git a/website/source/partials/builder/virtualbox/iso/_Config-not-required.html.md b/website/source/partials/builder/virtualbox/iso/_Config-not-required.html.md index 3cf87b358..951f63183 100644 --- a/website/source/partials/builder/virtualbox/iso/_Config-not-required.html.md +++ b/website/source/partials/builder/virtualbox/iso/_Config-not-required.html.md @@ -1,77 +1,74 @@ -- `disk_size` (uint) - The size, in megabytes, of the hard disk to create - for the VM. By default, this is 40000 (about 40 GB). +- `disk_size` (uint) - The size, in megabytes, of the hard disk to create for the VM. By + default, this is 40000 (about 40 GB). -- `guest_additions_mode` (string) - The method by which guest additions are - made available to the guest for installation. Valid options are upload, - attach, or disable. If the mode is attach the guest additions ISO will - be attached as a CD device to the virtual machine. If the mode is upload - the guest additions ISO will be uploaded to the path specified by - guest_additions_path. The default value is upload. If disable is used, - guest additions won't be downloaded, either. +- `guest_additions_mode` (string) - The method by which guest additions are made available to the guest for + installation. Valid options are upload, attach, or disable. If the mode + is attach the guest additions ISO will be attached as a CD device to the + virtual machine. If the mode is upload the guest additions ISO will be + uploaded to the path specified by guest_additions_path. The default + value is upload. If disable is used, guest additions won't be + downloaded, either. -- `guest_additions_path` (string) - The path on the guest virtual machine - where the VirtualBox guest additions ISO will be uploaded. By default this - is VBoxGuestAdditions.iso which should upload into the login directory of - the user. This is a configuration - template where the Version - variable is replaced with the VirtualBox version. +- `guest_additions_path` (string) - The path on the guest virtual machine where the VirtualBox guest + additions ISO will be uploaded. By default this is + VBoxGuestAdditions.iso which should upload into the login directory of + the user. This is a configuration template where the Version variable is + replaced with the VirtualBox version. -- `guest_additions_sha256` (string) - The SHA256 checksum of the guest - additions ISO that will be uploaded to the guest VM. By default the - checksums will be downloaded from the VirtualBox website, so this only needs - to be set if you want to be explicit about the checksum. +- `guest_additions_sha256` (string) - The SHA256 checksum of the guest additions ISO that will be uploaded to + the guest VM. By default the checksums will be downloaded from the + VirtualBox website, so this only needs to be set if you want to be + explicit about the checksum. -- `guest_additions_url` (string) - The URL to the guest additions ISO - to upload. This can also be a file URL if the ISO is at a local path. By - default, the VirtualBox builder will attempt to find the guest additions ISO - on the local file system. If it is not available locally, the builder will - download the proper guest additions ISO from the internet. +- `guest_additions_url` (string) - The URL to the guest additions ISO to upload. This can also be a file + URL if the ISO is at a local path. By default, the VirtualBox builder + will attempt to find the guest additions ISO on the local file system. + If it is not available locally, the builder will download the proper + guest additions ISO from the internet. -- `guest_additions_interface` (string) - The interface type to use to mount - guest additions when guest_additions_mode is set to attach. Will - default to the value set in iso_interface, if iso_interface is set. - Will default to "ide", if iso_interface is not set. Options are "ide" and - "sata". +- `guest_additions_interface` (string) - The interface type to use to mount guest additions when + guest_additions_mode is set to attach. Will default to the value set in + iso_interface, if iso_interface is set. Will default to "ide", if + iso_interface is not set. Options are "ide" and "sata". -- `guest_os_type` (string) - The guest OS type being installed. By default - this is other, but you can get dramatic performance improvements by - setting this to the proper value. To view all available values for this run - VBoxManage list ostypes. Setting the correct value hints to VirtualBox how - to optimize the virtual hardware to work best with that operating system. +- `guest_os_type` (string) - The guest OS type being installed. By default this is other, but you can + get dramatic performance improvements by setting this to the proper + value. To view all available values for this run VBoxManage list + ostypes. Setting the correct value hints to VirtualBox how to optimize + the virtual hardware to work best with that operating system. -- `hard_drive_discard` (bool) - When this value is set to true, a VDI - image will be shrunk in response to the trim command from the guest OS. - The size of the cleared area must be at least 1MB. Also set - hard_drive_nonrotational to true to enable TRIM support. +- `hard_drive_discard` (bool) - When this value is set to true, a VDI image will be shrunk in response + to the trim command from the guest OS. The size of the cleared area must + be at least 1MB. Also set hard_drive_nonrotational to true to enable + TRIM support. -- `hard_drive_interface` (string) - The type of controller that the primary - hard drive is attached to, defaults to ide. When set to sata, the drive - is attached to an AHCI SATA controller. When set to scsi, the drive is - attached to an LsiLogic SCSI controller. +- `hard_drive_interface` (string) - The type of controller that the primary hard drive is attached to, + defaults to ide. When set to sata, the drive is attached to an AHCI SATA + controller. When set to scsi, the drive is attached to an LsiLogic SCSI + controller. -- `sata_port_count` (int) - The number of ports available on any SATA - controller created, defaults to 1. VirtualBox supports up to 30 ports on a - maximum of 1 SATA controller. Increasing this value can be useful if you - want to attach additional drives. +- `sata_port_count` (int) - The number of ports available on any SATA controller created, defaults + to 1. VirtualBox supports up to 30 ports on a maximum of 1 SATA + controller. Increasing this value can be useful if you want to attach + additional drives. -- `hard_drive_nonrotational` (bool) - Forces some guests (i.e. Windows 7+) - to treat disks as SSDs and stops them from performing disk fragmentation. - Also set hard_drive_discard to true to enable TRIM support. +- `hard_drive_nonrotational` (bool) - Forces some guests (i.e. Windows 7+) to treat disks as SSDs and stops + them from performing disk fragmentation. Also set hard_drive_discard to + true to enable TRIM support. -- `iso_interface` (string) - The type of controller that the ISO is attached - to, defaults to ide. When set to sata, the drive is attached to an AHCI - SATA controller. +- `iso_interface` (string) - The type of controller that the ISO is attached to, defaults to ide. + When set to sata, the drive is attached to an AHCI SATA controller. -- `keep_registered` (bool) - Set this to true if you would like to keep - the VM registered with virtualbox. Defaults to false. +- `keep_registered` (bool) - Set this to true if you would like to keep the VM registered with + virtualbox. Defaults to false. -- `skip_export` (bool) - Defaults to false. When enabled, Packer will - not export the VM. Useful if the build output is not the resultant image, - but created inside the VM. +- `skip_export` (bool) - Defaults to false. When enabled, Packer will not export the VM. Useful + if the build output is not the resultant image, but created inside the + VM. -- `vm_name` (string) - This is the name of the OVF file for the new virtual - machine, without the file extension. By default this is packer-BUILDNAME, - where "BUILDNAME" is the name of the build. +- `vm_name` (string) - This is the name of the OVF file for the new virtual machine, without + the file extension. By default this is packer-BUILDNAME, where + "BUILDNAME" is the name of the build. \ No newline at end of file