+ Bug Tracker:
+ Issue tracker
+ on GitHub. Please only use this for reporting bugs. Do not ask
+ for general help here. Use IRC or the mailing list for that.
+
+
+ Training:
+ Paid HashiCorp training courses
+ are also available in a city near you. Private training courses are also available.
+
+
People
+
+ The following people are some of the faces behind Packer. They each
+ contribute to Packer in some core way. Over time, faces may appear and
+ disappear from this list as contributors come and go. In addition to
+ the faces below, Packer is a project by
+ HashiCorp, so many HashiCorp
+ employees actively contribute to Packer.
+
+ Mitchell Hashimoto is the creator of Packer. He developed the
+ core of Packer as well as the Amazon, VirtualBox, and VMware
+ builders. In addition to Packer, Mitchell is the creator of
+ Vagrant. He is self
+ described as "automation obsessed."
+
+ Jack Pearkes created and maintains the DigitalOcean builder
+ for Packer. Outside of Packer, Jack is an avid open source
+ contributor and software consultant.
+
+ Ross Smith maintains our
+ VMware builder on Windows, and provides other valuable assistance. Ross is an
+ open source enthusiast, published author, and freelance consultant.
+
Matt maintains Packer for HashiCorp. After
+ picking up Chef for a job, he decided that continually provisioning the
+ same machine was bound for trouble. Luckily Packer had just been created,
+ and was the answer to his prayers. Now he works on it professionally, and
+ couldn't be happier.
+
+
+
+
+
+
diff --git a/website/source/community/index.html.md b/website/source/community/index.html.md
deleted file mode 100644
index 044092d33..000000000
--- a/website/source/community/index.html.md
+++ /dev/null
@@ -1,125 +0,0 @@
----
-description: |
- Packer is a new project with a growing community. Despite this, there are
- dedicated users willing to help through various mediums.
-layout: community
-page_title: Community
----
-
-# Community
-
-Packer is a new project with a growing community. Despite this, there are
-dedicated users willing to help through various mediums.
-
-**IRC:** `#packer-tool` on Freenode.
-
-**Mailing List:** [Packer Google
-Group](https://groups.google.com/group/packer-tool)
-
-**Bug Tracker:** [Issue tracker on
-GitHub](https://github.com/mitchellh/packer/issues). Please only use this for
-reporting bugs. Do not ask for general help here. Use IRC or the mailing list
-for that.
-
-## People
-
-The following people are some of the faces behind Packer. They each contribute
-to Packer in some core way. Over time, faces may appear and disappear from this
-list as contributors come and go.
-
-
- Mitchell Hashimoto is the creator of Packer. He developed the
- core of Packer as well as the Amazon, VirtualBox, and VMware
- builders. In addition to Packer, Mitchell is the creator of
- Vagrant. He is self
- described as "automation obsessed."
-
- Jack Pearkes created and maintains the DigitalOcean builder
- for Packer. Outside of Packer, Jack is an avid open source
- contributor and software consultant.
-
-Ross Smith maintains our
-VMware builder on Windows, and provides other valuable assistance. Ross is an
-open source enthusiast, published author, and freelance consultant.
-
Matt maintains Packer for HashiCorp. After
- picking up Chef for a job, he decided that continually provisioning the
- same machine was bound for trouble. Luckily Packer had just been created,
- and was the answer to his prayers. Now he works on it professionally, and
- couldn't be happier.
-
-
-
-
-
-
-
-
-
-
diff --git a/website/source/docs/basics/terminology.html.md b/website/source/docs/basics/terminology.html.md
index 18487c5d5..3566b0587 100644
--- a/website/source/docs/basics/terminology.html.md
+++ b/website/source/docs/basics/terminology.html.md
@@ -1,13 +1,13 @@
---
-description: |
- There are a handful of terms used throughout the Packer documentation where the
- meaning may not be immediately obvious if you haven't used Packer before.
- Luckily, there are relatively few. This page documents all the terminology
- required to understand and use Packer. The terminology is in alphabetical order
- for easy referencing.
layout: docs
-page_title: Packer Terminology
-...
+page_title: Terminology
+description: |-
+ There are a handful of terms used throughout the Packer documentation where
+ the meaning may not be immediately obvious if you haven't used Packer before.
+ Luckily, there are relatively few. This page documents all the terminology
+ required to understand and use Packer. The terminology is in alphabetical
+ order for easy referencing.
+---
# Packer Terminology
@@ -17,40 +17,39 @@ Luckily, there are relatively few. This page documents all the terminology
required to understand and use Packer. The terminology is in alphabetical order
for easy referencing.
-- `Artifacts` are the results of a single build, and are usually a set of IDs
- or files to represent a machine image. Every builder produces a
- single artifact. As an example, in the case of the Amazon EC2 builder, the
- artifact is a set of AMI IDs (one per region). For the VMware builder, the
- artifact is a directory of files comprising the created virtual machine.
+- `Artifacts` are the results of a single build, and are usually a set of IDs or
+ files to represent a machine image. Every builder produces a single artifact.
+ As an example, in the case of the Amazon EC2 builder, the artifact is a set of
+ AMI IDs (one per region). For the VMware builder, the artifact is a directory
+ of files comprising the created virtual machine.
-- `Builds` are a single task that eventually produces an image for a
- single platform. Multiple builds run in parallel. Example usage in a
- sentence: "The Packer build produced an AMI to run our web application." Or:
- "Packer is running the builds now for VMware, AWS, and VirtualBox."
+- `Builds` are a single task that eventually produces an image for a single
+ platform. Multiple builds run in parallel. Example usage in a sentence: "The
+ Packer build produced an AMI to run our web application." Or: "Packer is
+ running the builds now for VMware, AWS, and VirtualBox."
-- `Builders` are components of Packer that are able to create a machine image
- for a single platform. Builders read in some configuration and use that to
- run and generate a machine image. A builder is invoked as part of a build in
- order to create the actual resulting images. Example builders include
- VirtualBox, VMware, and Amazon EC2. Builders can be created and added to
- Packer in the form of plugins.
+- `Builders` are components of Packer that are able to create a machine image
+ for a single platform. Builders read in some configuration and use that to run
+ and generate a machine image. A builder is invoked as part of a build in order
+ to create the actual resulting images. Example builders include VirtualBox,
+ VMware, and Amazon EC2. Builders can be created and added to Packer in the
+ form of plugins.
-- `Commands` are sub-commands for the `packer` program that perform some job.
- An example command is "build", which is invoked as `packer build`. Packer
- ships with a set of commands out of the box in order to define its
- command-line interface.
+- `Commands` are sub-commands for the `packer` program that perform some job. An
+ example command is "build", which is invoked as `packer build`. Packer ships
+ with a set of commands out of the box in order to define its command-line
+ interface.
-- `Post-processors` are components of Packer that take the result of a builder
- or another post-processor and process that to create a new artifact.
- Examples of post-processors are compress to compress artifacts, upload to
- upload artifacts, etc.
+- `Post-processors` are components of Packer that take the result of a builder
+ or another post-processor and process that to create a new artifact. Examples
+ of post-processors are compress to compress artifacts, upload to upload
+ artifacts, etc.
-- `Provisioners` are components of Packer that install and configure software
- within a running machine prior to that machine being turned into a
- static image. They perform the major work of making the image contain
- useful software. Example provisioners include shell scripts, Chef,
- Puppet, etc.
+- `Provisioners` are components of Packer that install and configure software
+ within a running machine prior to that machine being turned into a static
+ image. They perform the major work of making the image contain useful
+ software. Example provisioners include shell scripts, Chef, Puppet, etc.
-- `Templates` are JSON files which define one or more builds by configuring
- the various components of Packer. Packer is able to read a template and use
- that information to create multiple machine images in parallel.
+- `Templates` are JSON files which define one or more builds by configuring the
+ various components of Packer. Packer is able to read a template and use that
+ information to create multiple machine images in parallel.
diff --git a/website/source/docs/builders/amazon-chroot.html.md b/website/source/docs/builders/amazon-chroot.html.md
index 7adb6bc32..f0ffd249a 100644
--- a/website/source/docs/builders/amazon-chroot.html.md
+++ b/website/source/docs/builders/amazon-chroot.html.md
@@ -1,11 +1,12 @@
---
-description: |
- The `amazon-chroot` Packer builder is able to create Amazon AMIs backed by an
- EBS volume as the root device. For more information on the difference between
- instance storage and EBS-backed instances, storage for the root device section
- in the EC2 documentation.
layout: docs
-page_title: 'Amazon AMI Builder (chroot)'
+sidebar_current: docs-builders-amazon-chroot
+page_title: Amazon chroot - Builders
+description: |-
+ The amazon-chroot Packer builder is able to create Amazon AMIs backed by an
+ EBS volume as the root device. For more information on the difference between
+ instance storage and EBS-backed instances, storage for the root device section
+ in the EC2 documentation.
---
# AMI Builder (chroot)
@@ -23,7 +24,7 @@ builder is able to build an EBS-backed AMI without launching a new EC2 instance.
This can dramatically speed up AMI builds for organizations who need the extra
fast build.
-\~> **This is an advanced builder** If you're just getting started with
+~> **This is an advanced builder** If you're just getting started with
Packer, we recommend starting with the [amazon-ebs
builder](/docs/builders/amazon-ebs.html), which is much easier to use.
@@ -56,200 +57,200 @@ each category, the available configuration keys are alphabetized.
### Required:
-- `access_key` (string) - The access key used to communicate with AWS. [Learn
- how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
+- `access_key` (string) - The access key used to communicate with AWS. [Learn
+ how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `ami_name` (string) - The name of the resulting AMI that will appear when
- managing AMIs in the AWS console or via APIs. This must be unique. To help
- make this unique, use a function like `timestamp` (see [configuration
- templates](/docs/templates/configuration-templates.html) for more info)
+- `ami_name` (string) - The name of the resulting AMI that will appear when
+ managing AMIs in the AWS console or via APIs. This must be unique. To help
+ make this unique, use a function like `timestamp` (see [configuration
+ templates](/docs/templates/configuration-templates.html) for more info)
-- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
- how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
+- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
+ how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `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.
### Optional:
-- `ami_description` (string) - The description to set for the
+- `ami_description` (string) - The description to set for the
resulting AMI(s). By default this description is empty. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with name of the region where this
is built.
-- `ami_groups` (array of strings) - A list of groups that have access to
+- `ami_groups` (array of strings) - A list of groups that have access to
launch the resulting AMI(s). By default no groups have permission to launch
the AMI. `all` will make the AMI publicly accessible.
-- `ami_product_codes` (array of strings) - A list of product codes to
+- `ami_product_codes` (array of strings) - A list of product codes to
associate with the AMI. By default no product codes are associated with
the AMI.
-- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
+- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
Tags and attributes are copied along with the AMI. AMI copying takes time
depending on the size of the AMI, but will generally take many minutes.
-- `ami_users` (array of strings) - A list of account IDs that have access to
+- `ami_users` (array of strings) - A list of account IDs that have access to
launch the resulting AMI(s). By default no additional users other than the
user creating the AMI has permissions to launch it.
-- `ami_virtualization_type` (string) - The type of virtualization for the AMI
+- `ami_virtualization_type` (string) - The type of virtualization for the AMI
you are building. This option is required to register HVM images. Can be
"paravirtual" (default) or "hvm".
-- `chroot_mounts` (array of array of strings) - This is a list of devices
+- `chroot_mounts` (array of array of strings) - 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 below. Please read that section for more information on how to
use this.
-- `command_wrapper` (string) - How to run shell commands. This defaults to
+- `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` (array of strings) - Paths to files on the running EC2 instance
+- `copy_files` (array of strings) - 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
+- `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.
-- `enhanced_networking` (boolean) - Enable enhanced
+- `enhanced_networking` (boolean) - Enable enhanced
networking (SriovNetSupport and ENA) on HVM-compatible AMIs. If true, add
`ec2:ModifyInstanceAttribute` to your AWS IAM policy.
-- `force_deregister` (boolean) - Force Packer to first deregister an existing
+- `force_deregister` (boolean) - Force Packer to first deregister an existing
AMI if one with the same name already exists. Default `false`.
-- `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
+- `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
AMIs, which have been deregistered by `force_deregister`. Default `false`.
-- `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the
+- `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the
AMI with an encrypted boot volume (discarding the initial unencrypted AMI in the
process). Default `false`.
-- `kms_key_id` (string) - The ID of the KMS key to use for boot volume encryption.
+- `kms_key_id` (string) - The ID 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.
-- `from_scratch` (boolean) - Build a new volume instead of starting from an
+- `from_scratch` (boolean) - 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:
-- `ami_block_device_mappings` (array of block device mappings) - Add one or
+- `ami_block_device_mappings` (array of block device mappings) - 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. 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
+ - `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
+ - `device_name` (string) - The device name exposed to the instance (for
example, `/dev/sdh` or `xvdh`). Required when specifying `volume_size`.
- - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
+ - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
- - `iops` (integer) - The number of I/O operations per second (IOPS) that the
+ - `iops` (integer) - 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
- - `no_device` (boolean) - Suppresses the specified device included in the
+ - `no_device` (boolean) - Suppresses the specified device included in the
block device mapping of the AMI
- - `snapshot_id` (string) - The ID of the snapshot
+ - `snapshot_id` (string) - The ID of the snapshot
- - `virtual_name` (string) - The virtual device name. See the documentation on
+ - `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` (integer) - The size of the volume, in GiB. Required if not
+ - `volume_size` (integer) - 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)
+ - `volume_type` (string) - The volume type. gp2 for General Purpose (SSD)
volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic
volumes
-- `root_device_name` (string) - The root device name. For example, `xvda`.
+- `root_device_name` (string) - The root device name. For example, `xvda`.
-- `mount_path` (string) - The path where the volume will be mounted. This is
+- `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.
-- `mount_partition` (integer) - The partition number containing the
+- `mount_partition` (integer) - The partition number containing the
/ partition. By default this is the first partition of the volume.
-- `mount_options` (array of strings) - Options to supply the `mount` command
+- `mount_options` (array of strings) - 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 discrestion is advised. See [this manual page for the mount
command](http://linuxcommand.org/man_pages/mount8.html) for valid file
system specific options
-- `pre_mount_commands` (array of strings) - A series of commands to execute
+- `pre_mount_commands` (array of strings) - 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}}`.
-- `post_mount_commands` (array of strings) - As `pre_mount_commands`, but the
+- `post_mount_commands` (array of strings) - 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}}`.
-- `root_volume_size` (integer) - The size of the root volume in GB for the
+- `root_volume_size` (integer) - 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.
-- `skip_region_validation` (boolean) - Set to true if you want to skip
+- `skip_region_validation` (boolean) - Set to true if you want to skip
validation of the `ami_regions` configuration option. Default `false`.
-- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
+- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
They will override AMI tags if already applied to snapshot. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with name of the region where this
is built.
-- `snapshot_groups` (array of strings) - A list of groups that have access to
+- `snapshot_groups` (array of strings) - A list of groups that have access to
create volumes from the snapshot(s). By default no groups have permission to create
volumes form the snapshot(s). `all` will make the snapshot publicly accessible.
-- `snapshot_users` (array of strings) - A list of account IDs that have access to
+- `snapshot_users` (array of strings) - A list of account IDs that have access to
create volumes from the snapshot(s). By default no additional users other than the
user creating the AMI has permissions to create volumes from the backing snapshot(s).
-- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
+- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
Example:
- ``` {.javascript}
+ ```json
"source_ami_filter": {
- "filters": {
- "virtualization-type": "hvm",
- "name": "*ubuntu-xenial-16.04-amd64-server-*",
- "root-device-type": "ebs"
- },
- "owners": ["099720109477"],
- "most_recent": true
+ "filters": {
+ "virtualization-type": "hvm",
+ "name": "*ubuntu-xenial-16.04-amd64-server-*",
+ "root-device-type": "ebs"
+ },
+ "owners": ["099720109477"],
+ "most_recent": true
}
```
@@ -257,18 +258,18 @@ each category, the available configuration keys are alphabetized.
NOTE: This will fail unless *exactly* one AMI is returned. In the above
example, `most_recent` will cause this to succeed by selecting the newest image.
- - `filters` (map of strings) - filters used to select a `source_ami`.
+ - `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless *exactly* one AMI is returned.
Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
+ - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
This is helpful to limit the AMIs to a trusted third party, or to your own account.
- - `most_recent` (bool) - Selects the newest created image when true.
+ - `most_recent` (bool) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
-- `tags` (object of key/value strings) - Tags applied to the AMI. This is a
+- `tags` (object of key/value strings) - Tags applied to the AMI. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with name of the region where this
@@ -279,7 +280,7 @@ each category, the available configuration keys are alphabetized.
Here is a basic example. It is completely valid except for the access keys:
-``` {.javascript}
+```javascript
{
"type": "amazon-chroot",
"access_key": "YOUR KEY HERE",
@@ -295,18 +296,18 @@ The `chroot_mounts` configuration can be used to mount specific devices within
the chroot. By default, the following additional mounts are added into the
chroot by Packer:
-- `/proc` (proc)
-- `/sys` (sysfs)
-- `/dev` (bind to real `/dev`)
-- `/dev/pts` (devpts)
-- `/proc/sys/fs/binfmt_misc` (binfmt\_misc)
+- `/proc` (proc)
+- `/sys` (sysfs)
+- `/dev` (bind to real `/dev`)
+- `/dev/pts` (devpts)
+- `/proc/sys/fs/binfmt_misc` (binfmt\_misc)
These default mounts are usually good enough for anyone and are sane defaults.
However, if you want to change or add the mount points, you may using the
`chroot_mounts` configuration. Here is an example configuration which only
mounts `/prod` and `/dev`:
-``` {.javascript}
+```javascript
{
"chroot_mounts": [
["proc", "proc", "/proc"],
@@ -318,12 +319,12 @@ mounts `/prod` and `/dev`:
`chroot_mounts` is a list of a 3-tuples of strings. The three components of the
3-tuple, in order, are:
-- The filesystem type. If this is "bind", then Packer will properly bind the
+- The filesystem type. If this is "bind", then Packer will properly bind the
filesystem to another mount point.
-- The source device.
+- The source device.
-- The mount directory.
+- The mount directory.
## Parallelism
@@ -346,7 +347,7 @@ For debian based distributions you can setup a
file which will prevent packages installed by your provisioners from starting
services:
-``` {.javascript}
+```javascript
{
"type": "shell",
"inline": [
@@ -374,7 +375,7 @@ The device setup commands partition the device with one partition for use as an
HVM image and format it ext4. This builder block should be followed by
provisioning commands to install the os and bootloader.
-``` {.javascript}
+```json
{
"type": "amazon-chroot",
"ami_name": "packer-from-scratch {{timestamp}}",
diff --git a/website/source/docs/builders/amazon-ebs.html.md b/website/source/docs/builders/amazon-ebs.html.md
index 55941f0a0..0f2233ff1 100644
--- a/website/source/docs/builders/amazon-ebs.html.md
+++ b/website/source/docs/builders/amazon-ebs.html.md
@@ -1,12 +1,13 @@
---
-description: |
- The `amazon-ebs` Packer builder is able to create Amazon AMIs backed by EBS
- volumes for use in EC2. For more information on the difference between
- EBS-backed instances and instance-store backed instances, see the storage for
- the root device section in the EC2 documentation.
layout: docs
-page_title: 'Amazon AMI Builder (EBS backed)'
-...
+sidebar_current: docs-builders-amazon-ebsbacked
+page_title: Amazon EBS - Builders
+description: |-
+ The amazon-ebs Packer builder is able to create Amazon AMIs backed by EBS
+ volumes for use in EC2. For more information on the difference between
+ EBS-backed instances and instance-store backed instances, see the storage for
+ the root device section in the EC2 documentation.
+---
# AMI Builder (EBS backed)
@@ -44,199 +45,200 @@ builder.
### Required:
-- `access_key` (string) - The access key used to communicate with AWS. [Learn
- how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
+- `access_key` (string) - The access key used to communicate with AWS. [Learn
+ how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `ami_name` (string) - The name of the resulting AMI that will appear when
- managing AMIs in the AWS console or via APIs. This must be unique. To help
- make this unique, use a function like `timestamp` (see [configuration
- templates](/docs/templates/configuration-templates.html) for more info)
+- `ami_name` (string) - The name of the resulting AMI that will appear when
+ managing AMIs in the AWS console or via APIs. This must be unique. To help
+ make this unique, use a function like `timestamp` (see [configuration
+ templates](/docs/templates/configuration-templates.html) for more info)
-- `instance_type` (string) - The EC2 instance type to use while building the
- AMI, such as `m1.small`.
+- `instance_type` (string) - The EC2 instance type to use while building the
+ AMI, such as `m1.small`.
-- `region` (string) - The name of the region, such as `us-east-1`, in which to
- launch the EC2 instance to create the AMI.
+- `region` (string) - The name of the region, such as `us-east-1`, in which to
+ launch the EC2 instance to create the AMI.
-- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
- how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
+- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
+ how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `source_ami` (string) - The initial AMI used as a base for the newly
- created machine. `source_ami_filter` may be used instead to populate this
- automatically.
+- `source_ami` (string) - The initial AMI used as a base for the newly
+ created machine. `source_ami_filter` may be used instead to populate this
+ automatically.
### Optional:
-- `ami_block_device_mappings` (array of block device mappings) - 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:
+- `ami_block_device_mappings` (array of block device mappings) - 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.
+ - `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 when specifying `volume_size`.
+ - `device_name` (string) - The device name exposed to the instance (for
+ example, `/dev/sdh` or `xvdh`). Required when specifying `volume_size`.
- - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
+ - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
- - `iops` (integer) - 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
+ - `iops` (integer) - 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
- - `no_device` (boolean) - Suppresses the specified device included in the
- block device mapping of the AMI
+ - `no_device` (boolean) - Suppresses the specified device included in the
+ block device mapping of the AMI
- - `snapshot_id` (string) - The ID of the snapshot
+ - `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
+ - `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` (integer) - The size of the volume, in GiB. Required if not
- specifying a `snapshot_id`
+ - `volume_size` (integer) - 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, and `standard` for Magnetic
- volumes
+ - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD)
+ volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic
+ volumes
-- `ami_description` (string) - The description to set for the
- resulting AMI(s). By default this description is empty. This is a
- [configuration template](/docs/templates/configuration-templates.html)
- where the `SourceAMI` variable is replaced with the source AMI ID and
- `BuildRegion` variable is replaced with the value of `region`.
+- `ami_description` (string) - The description to set for the
+ resulting AMI(s). By default this description is empty. This is a
+ [configuration template](/docs/templates/configuration-templates.html)
+ where the `SourceAMI` variable is replaced with the source AMI ID and
+ `BuildRegion` variable is replaced with the value of `region`.
-- `ami_groups` (array of strings) - A list of groups that have access to
- launch the resulting AMI(s). By default no groups have permission to launch
- the AMI. `all` will make the AMI publicly accessible. AWS currently doesn't
- accept any value other than `all`.
+- `ami_groups` (array of strings) - A list of groups that have access to
+ launch the resulting AMI(s). By default no groups have permission to launch
+ the AMI. `all` will make the AMI publicly accessible. AWS currently doesn't
+ accept any value other than `all`.
-- `ami_product_codes` (array of strings) - A list of product codes to
- associate with the AMI. By default no product codes are associated with
- the AMI.
+- `ami_product_codes` (array of strings) - A list of product codes to
+ associate with the AMI. By default no product codes are associated with
+ the AMI.
-- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
- Tags and attributes are copied along with the AMI. AMI copying takes time
- depending on the size of the AMI, but will generally take many minutes.
+- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
+ Tags and attributes are copied along with the AMI. AMI copying takes time
+ depending on the size of the AMI, but will generally take many minutes.
-- `ami_users` (array of strings) - A list of account IDs that have access to
- launch the resulting AMI(s). By default no additional users other than the
- user creating the AMI has permissions to launch it.
+- `ami_users` (array of strings) - A list of account IDs that have access to
+ launch the resulting AMI(s). By default no additional users other than the
+ user creating the AMI has permissions to launch it.
-- `ami_virtualization_type` (string) - The type of virtualization for the AMI
- you are building. This option must match the supported virtualization
- type of `source_ami`. Can be `paravirtual` or `hvm`.
+- `ami_virtualization_type` (string) - The type of virtualization for the AMI
+ you are building. This option must match the supported virtualization
+ type of `source_ami`. Can be `paravirtual` or `hvm`.
-- `associate_public_ip_address` (boolean) - If using a non-default VPC, public
- IP addresses are not provided by default. If this is toggled, your new
- instance will get a Public IP.
+- `associate_public_ip_address` (boolean) - If using a non-default VPC, public
+ IP addresses are not provided by default. If this is toggled, your new
+ instance will get a Public IP.
-- `availability_zone` (string) - Destination availability zone to launch
- instance in. Leave this empty to allow Amazon to auto-assign.
+- `availability_zone` (string) - Destination availability zone to launch
+ instance in. Leave this empty to allow Amazon to auto-assign.
-- `disable_stop_instance` (boolean) - Packer normally stops the build instance
- after all provisioners have run. For Windows instances, it is sometimes
- desirable to [run Sysprep](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ami-create-standard.html)
- which will stop the instance for you. If this is set to true, Packer *will not*
- stop the instance and will wait for you to stop it manually. You can do this
- with a [windows-shell provisioner](https://www.packer.io/docs/provisioners/windows-shell.html).
+- `disable_stop_instance` (boolean) - Packer normally stops the build instance
+ after all provisioners have run. For Windows instances, it is sometimes
+ desirable to [run Sysprep](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ami-create-standard.html)
+ which will stop the instance for you. If this is set to true, Packer *will not*
+ stop the instance and will wait for you to stop it manually. You can do this
+ with a [windows-shell provisioner](https://www.packer.io/docs/provisioners/windows-shell.html).
- ``` {.javascript}
+ ```javascript
{
"type": "windows-shell",
"inline": ["\"c:\\Program Files\\Amazon\\Ec2ConfigService\\ec2config.exe\" -sysprep"]
}
```
-- `ebs_optimized` (boolean) - Mark instance as [EBS
- Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html).
- Default `false`.
+- `ebs_optimized` (boolean) - Mark instance as [EBS
+ Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html).
+ Default `false`.
-- `enhanced_networking` (boolean) - Enable enhanced
- networking (SriovNetSupport and ENA) on HVM-compatible AMIs. If true, add
- `ec2:ModifyInstanceAttribute` to your AWS IAM policy.
+- `enhanced_networking` (boolean) - Enable enhanced
+ networking (SriovNetSupport and ENA) on HVM-compatible AMIs. If true, add
+ `ec2:ModifyInstanceAttribute` to your AWS IAM policy.
-- `force_deregister` (boolean) - Force Packer to first deregister an existing
- AMI if one with the same name already exists. Default `false`.
+- `force_deregister` (boolean) - Force Packer to first deregister an existing
+ AMI if one with the same name already exists. Default `false`.
-- `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
- AMIs, which have been deregistered by `force_deregister`. Default `false`.
+- `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
+ AMIs, which have been deregistered by `force_deregister`. Default `false`.
-- `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the
- AMI with an encrypted boot volume (discarding the initial unencrypted AMI in the
- process). Default `false`.
+- `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the
+ AMI with an encrypted boot volume (discarding the initial unencrypted AMI in the
+ process). Default `false`.
-- `kms_key_id` (string) - The ID 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.
+- `kms_key_id` (string) - The ID 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.
-- `iam_instance_profile` (string) - The name of an [IAM instance
- profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html)
- to launch the EC2 instance with.
+- `iam_instance_profile` (string) - The name of an [IAM instance
+ profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html)
+ to launch the EC2 instance with.
-- `launch_block_device_mappings` (array of block device mappings) - Add one or
- more block devices before the Packer build starts. These are not necessarily
- preserved when booting from the AMI built with Packer. See
- `ami_block_device_mappings`, above, for details.
+- `launch_block_device_mappings` (array of block device mappings) - Add one or
+ more block devices before the Packer build starts. These are not necessarily
+ preserved when booting from the AMI built with Packer. See
+ `ami_block_device_mappings`, above, for details.
-- `run_tags` (object of key/value strings) - Tags to apply to the instance
- that is *launched* to create the AMI. These tags are *not* applied to the
- resulting AMI unless they're duplicated in `tags`. This is a
- [configuration template](/docs/templates/configuration-templates.html)
- where the `SourceAMI` variable is replaced with the source AMI ID and
- `BuildRegion` variable is replaced with the value of `region`.
+- `run_tags` (object of key/value strings) - Tags to apply to the instance
+ that is *launched* to create the AMI. These tags are *not* applied to the
+ resulting AMI unless they're duplicated in `tags`. This is a
+ [configuration template](/docs/templates/configuration-templates.html)
+ where the `SourceAMI` variable is replaced with the source AMI ID and
+ `BuildRegion` variable is replaced with the value of `region`.
-- `run_volume_tags` (object of key/value strings) - 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
- [configuration template](/docs/templates/configuration-templates.html)
- where the `SourceAMI` variable is replaced with the source AMI ID and
- `BuildRegion` variable is replaced with the value of `region`.
+- `run_volume_tags` (object of key/value strings) - 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
+ [configuration template](/docs/templates/configuration-templates.html)
+ where the `SourceAMI` variable is replaced with the source AMI ID and
+ `BuildRegion` variable is replaced with the value of `region`.
-- `security_group_id` (string) - The ID (*not* the name) of the security group
- to assign to the instance. By default this is not set and Packer will
- automatically create a new temporary security group to allow SSH access.
- Note that if this is specified, you must be sure the security group allows
- access to the `ssh_port` given below.
+- `security_group_id` (string) - The ID (*not* the name) of the security group
+ to assign to the instance. By default this is not set and Packer will
+ automatically create a new temporary security group to allow SSH access.
+ Note that if this is specified, you must be sure the security group allows
+ access to the `ssh_port` given below.
-- `security_group_ids` (array of strings) - A list of security groups as
- described above. Note that if this is specified, you must omit the
- `security_group_id`.
+- `security_group_ids` (array of strings) - A list of security groups as
+ described above. Note that if this is specified, you must omit the
+ `security_group_id`.
-- `shutdown_behavior` (string) - Automatically terminate instances on shutdown
- in case Packer exits ungracefully. Possible values are "stop" and "terminate",
- default is `stop`.
+- `shutdown_behavior` (string) - Automatically terminate instances on shutdown
+ in case Packer exits ungracefully. Possible values are "stop" and "terminate",
+ default is `stop`.
-- `skip_region_validation` (boolean) - Set to true if you want to skip
- validation of the region configuration option. Default `false`.
+- `skip_region_validation` (boolean) - Set to true if you want to skip
+ validation of the region configuration option. Default `false`.
-- `snapshot_groups` (array of strings) - A list of groups that have access to
- create volumes from the snapshot(s). By default no groups have permission to create
- volumes form the snapshot(s). `all` will make the snapshot publicly accessible.
+- `snapshot_groups` (array of strings) - A list of groups that have access to
+ create volumes from the snapshot(s). By default no groups have permission to create
+ volumes form the snapshot(s). `all` will make the snapshot publicly accessible.
-- `snapshot_users` (array of strings) - A list of account IDs that have access to
- create volumes from the snapshot(s). By default no additional users other than the
- user creating the AMI has permissions to create volumes from the backing snapshot(s).
+- `snapshot_users` (array of strings) - A list of account IDs that have access to
+ create volumes from the snapshot(s). By default no additional users other than the
+ user creating the AMI has permissions to create volumes from the backing snapshot(s).
-- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
- They will override AMI tags if already applied to snapshot. This is a
- [configuration template](/docs/templates/configuration-templates.html)
- where the `SourceAMI` variable is replaced with the source AMI ID and
- `BuildRegion` variable is replaced with the value of `region`.
+- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
+ They will override AMI tags if already applied to snapshot. This is a
+ [configuration template](/docs/templates/configuration-templates.html)
+ where the `SourceAMI` variable is replaced with the source AMI ID and
+ `BuildRegion` variable is replaced with the value of `region`.
-- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
- Example:
+- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
+ Example:
- ``` {.javascript}
- "source_ami_filter": {
+ ```javascript
+ {
+ "source_ami_filter": {
"filters": {
"virtualization-type": "hvm",
"name": "*ubuntu-xenial-16.04-amd64-server-*",
@@ -244,95 +246,96 @@ builder.
},
"owners": ["099720109477"],
"most_recent": true
+ }
}
```
- This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical.
- NOTE: This will fail unless *exactly* one AMI is returned. In the above
- example, `most_recent` will cause this to succeed by selecting the newest image.
+ This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical.
+ NOTE: This will fail unless *exactly* one AMI is returned. In the above
+ example, `most_recent` will cause this to succeed by selecting the newest image.
- - `filters` (map of strings) - filters used to select a `source_ami`.
- NOTE: This will fail unless *exactly* one AMI is returned.
- Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
- is valid.
+ - `filters` (map of strings) - filters used to select a `source_ami`.
+ NOTE: This will fail unless *exactly* one AMI is returned.
+ Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
+ is valid.
- - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
- This is helpful to limit the AMIs to a trusted third party, or to your own account.
+ - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
+ This is helpful to limit the AMIs to a trusted third party, or to your own account.
- - `most_recent` (bool) - Selects the newest created image when true.
- This is most useful for selecting a daily distro build.
+ - `most_recent` (bool) - Selects the newest created image when true.
+ This is most useful for selecting a daily distro build.
-- `spot_price` (string) - The maximum hourly price to pay for a spot instance
- to create the AMI. Spot instances are a type of instance that EC2 starts
- when the current spot price is less than the maximum price you specify. Spot
- price will be updated based on available spot instance capacity and current
- spot instance requests. It may save you some costs. You can set this to
- `auto` for Packer to automatically discover the best spot price or to "0"
- to use an on demand instance (default).
+- `spot_price` (string) - The maximum hourly price to pay for a spot instance
+ to create the AMI. Spot instances are a type of instance that EC2 starts
+ when the current spot price is less than the maximum price you specify. Spot
+ price will be updated based on available spot instance capacity and current
+ spot instance requests. It may save you some costs. You can set this to
+ `auto` for Packer to automatically discover the best spot price or to "0"
+ to use an on demand instance (default).
-- `spot_price_auto_product` (string) - Required if `spot_price` is set
- to `auto`. This tells Packer what sort of AMI you're launching to find the
- best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`,
- `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)`
+- `spot_price_auto_product` (string) - Required if `spot_price` is set
+ to `auto`. This tells Packer what sort of AMI you're launching to find the
+ best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`,
+ `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)`
-- `ssh_keypair_name` (string) - If specified, this is the key that will be
- used for SSH with the machine. The key must match a key pair name loaded
- up into Amazon EC2. By default, this is blank, and Packer will
- generate a temporary keypair unless
- [`ssh_password`](/docs/templates/communicator.html#ssh_password) is used.
- [`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file)
- or `ssh_agent_auth` must be specified when `ssh_keypair_name` is utilized.
+- `ssh_keypair_name` (string) - If specified, this is the key that will be
+ used for SSH with the machine. The key must match a key pair name loaded
+ up into Amazon EC2. By default, this is blank, and Packer will
+ generate a temporary keypair unless
+ [`ssh_password`](/docs/templates/communicator.html#ssh_password) is used.
+ [`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file)
+ or `ssh_agent_auth` must be specified when `ssh_keypair_name` is utilized.
-- `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to
- authenticate connections to the source instance. No temporary keypair will
- be created, and the values of `ssh_password` and `ssh_private_key_file` will
- be ignored. To use this option with a key pair already configured in the source
- AMI, leave the `ssh_keypair_name` blank. To associate an existing key pair
- in AWS with the source instance, set the `ssh_keypair_name` field to the name
- of the key pair.
+- `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to
+ authenticate connections to the source instance. No temporary keypair will
+ be created, and the values of `ssh_password` and `ssh_private_key_file` will
+ be ignored. To use this option with a key pair already configured in the source
+ AMI, leave the `ssh_keypair_name` blank. To associate an existing key pair
+ in AWS with the source instance, set the `ssh_keypair_name` field to the name
+ of the key pair.
-- `ssh_private_ip` (boolean) - If true, then SSH will always use the private
- IP if available. Also works for WinRM.
+- `ssh_private_ip` (boolean) - If true, then SSH will always use the private
+ IP if available. Also works for WinRM.
-- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
- `subnet-12345def`, where Packer will launch the EC2 instance. This field is
- required if you are using an non-default VPC.
+- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
+ `subnet-12345def`, where Packer will launch the EC2 instance. This field is
+ required if you are using an non-default VPC.
-- `tags` (object of key/value strings) - Tags applied to the AMI and
- relevant snapshots. This is a
- [configuration template](/docs/templates/configuration-templates.html)
- where the `SourceAMI` variable is replaced with the source AMI ID and
- `BuildRegion` variable is replaced with the value of `region`.
+- `tags` (object of key/value strings) - Tags applied to the AMI and
+ relevant snapshots. This is a
+ [configuration template](/docs/templates/configuration-templates.html)
+ where the `SourceAMI` variable is replaced with the source AMI ID and
+ `BuildRegion` variable is replaced with the value of `region`.
-- `temporary_key_pair_name` (string) - The name of the temporary key pair
- to generate. By default, Packer generates a name that looks like
- `packer_`, where \ is a 36 character unique identifier.
+- `temporary_key_pair_name` (string) - The name of the temporary key pair
+ to generate. By default, Packer generates a name that looks like
+ `packer_`, where \ is a 36 character unique identifier.
-- `token` (string) - The access token to use. This is different from the
- access key and secret key. If you're not sure what this is, then you
- probably don't need it. This will also be read from the `AWS_SESSION_TOKEN`
- environmental variable.
+- `token` (string) - The access token to use. This is different from the
+ access key and secret key. If you're not sure what this is, then you
+ probably don't need it. This will also be read from the `AWS_SESSION_TOKEN`
+ environmental variable.
-- `user_data` (string) - User data to apply when launching the instance. Note
- that you need to be careful about escaping characters due to the templates
- being JSON. It is often more convenient to use `user_data_file`, instead.
+- `user_data` (string) - User data to apply when launching the instance. Note
+ that you need to be careful about escaping characters due to the templates
+ being JSON. It is often more convenient to use `user_data_file`, instead.
-- `user_data_file` (string) - Path to a file that will be used for the user
- data when launching the instance.
+- `user_data_file` (string) - Path to a file that will be used for the user
+ data when launching the instance.
-- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
- in order to create a temporary security group within the VPC. Requires `subnet_id`
- to be set.
+- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
+ in order to create a temporary security group within the VPC. Requires `subnet_id`
+ to be set.
-- `windows_password_timeout` (string) - The timeout for waiting for a Windows
- password for Windows instances. Defaults to 20 minutes. Example value: `10m`
+- `windows_password_timeout` (string) - The timeout for waiting for a Windows
+ password for Windows instances. Defaults to 20 minutes. Example value: `10m`
## Basic Example
Here is a basic example. You will need to provide access keys, and may need to
change the AMI IDs according to what images exist at the time the template is run:
-``` {.javascript}
+```javascript
{
"type": "amazon-ebs",
"access_key": "YOUR KEY HERE",
@@ -345,7 +348,7 @@ change the AMI IDs according to what images exist at the time the template is ru
}
```
--> **Note:** Packer can also read the access key and secret access key from
+-> **Note:** Packer can also read the access key and secret access key from
environmental variables. See the configuration reference in the section above
for more information on what environmental variables Packer will look for.
@@ -369,7 +372,7 @@ configuration of `launch_block_device_mappings` will expand the root volume
`ami_block_device_mappings` AWS will attach additional volumes `/dev/sdb` and
`/dev/sdc` when we boot a new instance of our AMI.
-``` {.javascript}
+```javascript
{
"type": "amazon-ebs",
"access_key": "YOUR KEY HERE",
@@ -379,12 +382,14 @@ configuration of `launch_block_device_mappings` will expand the root volume
"instance_type": "t2.micro",
"ssh_username": "ubuntu",
"ami_name": "packer-quick-start {{timestamp}}",
- "launch_block_device_mappings": [{
- "device_name": "/dev/sda1",
- "volume_size": 40,
- "volume_type": "gp2",
- "delete_on_termination": true
- }],
+ "launch_block_device_mappings": [
+ {
+ "device_name": "/dev/sda1",
+ "volume_size": 40,
+ "volume_type": "gp2",
+ "delete_on_termination": true
+ }
+ ],
"ami_block_device_mappings": [
{
"device_name": "/dev/sdb",
@@ -405,7 +410,7 @@ Here is an example using the optional AMI tags. This will add the tags
provide your access keys, and may need to change the source AMI ID based on what
images exist when this template is run:
-``` {.javascript}
+```javascript
{
"type": "amazon-ebs",
"access_key": "YOUR KEY HERE",
@@ -416,13 +421,13 @@ images exist when this template is run:
"ssh_username": "ubuntu",
"ami_name": "packer-quick-start {{timestamp}}",
"tags": {
- "OS_Version": "Ubuntu",
- "Release": "Latest"
+ "OS_Version": "Ubuntu",
+ "Release": "Latest"
}
}
```
--> **Note:** Packer uses pre-built AMIs as the source for building images.
+-> **Note:** Packer uses pre-built AMIs as the source for building images.
These source AMIs may include volumes that are not flagged to be destroyed on
termination of the instance building the new image. Packer will attempt to clean
up all residual volumes that are not designated by the user to remain after
diff --git a/website/source/docs/builders/amazon-ebssurrogate.html.md b/website/source/docs/builders/amazon-ebssurrogate.html.md
index 07cd53c4a..f425f5fda 100644
--- a/website/source/docs/builders/amazon-ebssurrogate.html.md
+++ b/website/source/docs/builders/amazon-ebssurrogate.html.md
@@ -1,25 +1,26 @@
---
-description: |
- The `amazon-ebssurrogate` Packer builder is like the chroot builder, but does
- not require running inside an EC2 instance.
layout: docs
-page_title: 'Amazon EBS Surrogate Builder'
-...
+sidebar_current: docs-builders-amazon-ebssurrogate
+page_title: Amazon EBS Surrogate - Builders
+description: |-
+ The amazon-ebssurrogate Packer builder is like the chroot builder, but does
+ not require running inside an EC2 instance.
+---
# EBS Surrogate Builder
Type: `amazon-ebssurrogate`
-The `amazon-ebssurrogate` Packer builder is able to create Amazon AMIs by running
-a source instance with an attached volume, provisioning the attached volume in such
-a way that it can be used as the root volume for the AMI, and then snapshotting and
-creating the AMI from that volume.
+The `amazon-ebssurrogate` Packer builder is able to create Amazon AMIs by
+running a source instance with an attached volume, provisioning the attached
+volume in such a way that it can be used as the root volume for the AMI, and
+then snapshotting and creating the AMI from that volume.
-This builder can therefore be used to bootstrap scratch-build images - for example
-FreeBSD or Ubuntu using ZFS as the root file system.
+This builder can therefore be used to bootstrap scratch-build images - for
+example FreeBSD or Ubuntu using ZFS as the root file system.
-This is all done in your own AWS account. The builder will create temporary
-key pairs, security group rules, etc. that provide it temporary access to the
+This is all done in your own AWS account. The builder will create temporary key
+pairs, security group rules, etc. that provide it temporary access to the
instance while the image is being created.
## Configuration Reference
@@ -34,33 +35,33 @@ builder.
### Required:
-- `access_key` (string) - The access key used to communicate with AWS. [Learn
+- `access_key` (string) - The access key used to communicate with AWS. [Learn
how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `instance_type` (string) - The EC2 instance type to use while building the
+- `instance_type` (string) - The EC2 instance type to use while building the
AMI, such as `m1.small`.
-- `region` (string) - The name of the region, such as `us-east-1`, in which to
+- `region` (string) - The name of the region, such as `us-east-1`, in which to
launch the EC2 instance to create the AMI.
-- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
+- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `source_ami` (string) - The initial AMI used as a base for the newly
+- `source_ami` (string) - The initial AMI used as a base for the newly
created machine. `source_ami_filter` may be used instead to populate this
automatically.
-- `ami_root_device` (block device mapping) - A block device mapping describing
+- `ami_root_device` (block device mapping) - A block device mapping describing
the root device of the AMI. This looks like the mappings in `ami_block_device_mapping`,
except with an additional field:
-- `source_device_name` (string) - The device name of the block device on the
+- `source_device_name` (string) - The device name of the block device on the
source instance to be used as the root device for the AMI. This must correspond
to a block device in `launch_block_device_mapping`.
### Optional:
-- `ami_block_device_mappings` (array of block device mappings) - Add one or
+- `ami_block_device_mappings` (array of block device mappings) - 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
@@ -68,168 +69,169 @@ builder.
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
+ - `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
+ - `device_name` (string) - The device name exposed to the instance (for
example, `/dev/sdh` or `xvdh`). Required when specifying `volume_size`.
- - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
+ - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
- - `iops` (integer) - The number of I/O operations per second (IOPS) that the
+ - `iops` (integer) - 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
- - `no_device` (boolean) - Suppresses the specified device included in the
+ - `no_device` (boolean) - Suppresses the specified device included in the
block device mapping of the AMI
- - `snapshot_id` (string) - The ID of the snapshot
+ - `snapshot_id` (string) - The ID of the snapshot
- - `virtual_name` (string) - The virtual device name. See the documentation on
+ - `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` (integer) - The size of the volume, in GiB. Required if not
+ - `volume_size` (integer) - 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)
+ - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD)
volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic
volumes
-- `ami_description` (string) - The description to set for the
+- `ami_description` (string) - The description to set for the
resulting AMI(s). By default this description is empty. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `ami_groups` (array of strings) - A list of groups that have access to
+- `ami_groups` (array of strings) - A list of groups that have access to
launch the resulting AMI(s). By default no groups have permission to launch
the AMI. `all` will make the AMI publicly accessible. AWS currently doesn't
accept any value other than `all`.
-- `ami_product_codes` (array of strings) - A list of product codes to
+- `ami_product_codes` (array of strings) - A list of product codes to
associate with the AMI. By default no product codes are associated with
the AMI.
-- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
+- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
Tags and attributes are copied along with the AMI. AMI copying takes time
depending on the size of the AMI, but will generally take many minutes.
-- `ami_users` (array of strings) - A list of account IDs that have access to
+- `ami_users` (array of strings) - A list of account IDs that have access to
launch the resulting AMI(s). By default no additional users other than the
user creating the AMI has permissions to launch it.
-- `ami_virtualization_type` (string) - The type of virtualization for the AMI
+- `ami_virtualization_type` (string) - The type of virtualization for the AMI
you are building. This option must match the supported virtualization
type of `source_ami`. Can be `paravirtual` or `hvm`.
-- `associate_public_ip_address` (boolean) - If using a non-default VPC, public
+- `associate_public_ip_address` (boolean) - If using a non-default VPC, public
IP addresses are not provided by default. If this is toggled, your new
instance will get a Public IP.
-- `availability_zone` (string) - Destination availability zone to launch
+- `availability_zone` (string) - Destination availability zone to launch
instance in. Leave this empty to allow Amazon to auto-assign.
-- `disable_stop_instance` (boolean) - Packer normally stops the build instance
+- `disable_stop_instance` (boolean) - Packer normally stops the build instance
after all provisioners have run. For Windows instances, it is sometimes
desirable to [run Sysprep](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ami-create-standard.html)
which will stop the instance for you. If this is set to true, Packer *will not*
stop the instance and will wait for you to stop it manually. You can do this
with a [windows-shell provisioner](https://www.packer.io/docs/provisioners/windows-shell.html).
- ``` {.javascript}
+ ```javascript
{
"type": "windows-shell",
"inline": ["\"c:\\Program Files\\Amazon\\Ec2ConfigService\\ec2config.exe\" -sysprep"]
}
```
-- `ebs_optimized` (boolean) - Mark instance as [EBS
+- `ebs_optimized` (boolean) - Mark instance as [EBS
Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html).
Default `false`.
-- `enhanced_networking` (boolean) - Enable enhanced
+- `enhanced_networking` (boolean) - Enable enhanced
networking (SriovNetSupport) on HVM-compatible AMIs. If true, add
`ec2:ModifyInstanceAttribute` to your AWS IAM policy.
-- `force_deregister` (boolean) - Force Packer to first deregister an existing
+- `force_deregister` (boolean) - Force Packer to first deregister an existing
AMI if one with the same name already exists. Default `false`.
-- `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
+- `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
AMIs, which have been deregistered by `force_deregister`. Default `false`.
-- `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the
+- `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the
AMI with an encrypted boot volume (discarding the initial unencrypted AMI in the
process). Default `false`.
-- `kms_key_id` (string) - The ID of the KMS key to use for boot volume encryption.
+- `kms_key_id` (string) - The ID 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.
-- `iam_instance_profile` (string) - The name of an [IAM instance
+- `iam_instance_profile` (string) - The name of an [IAM instance
profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html)
to launch the EC2 instance with.
-- `launch_block_device_mappings` (array of block device mappings) - Add one or
+- `launch_block_device_mappings` (array of block device mappings) - Add one or
more block devices before the packer build starts. These are not necessarily
preserved when booting from the AMI built with packer. See
`ami_block_device_mappings`, above, for details.
-- `run_tags` (object of key/value strings) - Tags to apply to the instance
+- `run_tags` (object of key/value strings) - Tags to apply to the instance
that is *launched* to create the AMI. These tags are *not* applied to the
resulting AMI unless they're duplicated in `tags`. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `run_volume_tags` (object of key/value strings) - Tags to apply to the volumes
+- `run_volume_tags` (object of key/value strings) - 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
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `security_group_id` (string) - The ID (*not* the name) of the security group
+- `security_group_id` (string) - The ID (*not* the name) of the security group
to assign to the instance. By default this is not set and Packer will
automatically create a new temporary security group to allow SSH access.
Note that if this is specified, you must be sure the security group allows
access to the `ssh_port` given below.
-- `security_group_ids` (array of strings) - A list of security groups as
+- `security_group_ids` (array of strings) - A list of security groups as
described above. Note that if this is specified, you must omit the
`security_group_id`.
-- `shutdown_behavior` (string) - Automatically terminate instances on shutdown
+- `shutdown_behavior` (string) - Automatically terminate instances on shutdown
incase packer exits ungracefully. Possible values are "stop" and "terminate",
default is `stop`.
-- `skip_region_validation` (boolean) - Set to true if you want to skip
+- `skip_region_validation` (boolean) - Set to true if you want to skip
validation of the region configuration option. Default `false`.
-- `snapshot_groups` (array of strings) - A list of groups that have access to
+- `snapshot_groups` (array of strings) - A list of groups that have access to
create volumes from the snapshot(s). By default no groups have permission to create
volumes form the snapshot(s). `all` will make the snapshot publicly accessible.
-- `snapshot_users` (array of strings) - A list of account IDs that have access to
+- `snapshot_users` (array of strings) - A list of account IDs that have access to
create volumes from the snapshot(s). By default no additional users other than the
user creating the AMI has permissions to create volumes from the backing snapshot(s).
-- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
+- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
They will override AMI tags if already applied to snapshot. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
+- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
Example:
- ``` {.javascript}
- "source_ami_filter": {
+ ```json
+ {
+ "source_ami_filter": {
"filters": {
"virtualization-type": "hvm",
"name": "*ubuntu-xenial-16.04-amd64-server-*",
@@ -237,6 +239,7 @@ builder.
},
"owners": ["099720109477"],
"most_recent": true
+ }
}
```
@@ -244,18 +247,18 @@ builder.
NOTE: This will fail unless *exactly* one AMI is returned. In the above
example, `most_recent` will cause this to succeed by selecting the newest image.
- - `filters` (map of strings) - filters used to select a `source_ami`.
+ - `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless *exactly* one AMI is returned.
Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
+ - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
This is helpful to limit the AMIs to a trusted third party, or to your own account.
- - `most_recent` (bool) - Selects the newest created image when true.
+ - `most_recent` (bool) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
-- `spot_price` (string) - The maximum hourly price to pay for a spot instance
+- `spot_price` (string) - The maximum hourly price to pay for a spot instance
to create the AMI. Spot instances are a type of instance that EC2 starts
when the current spot price is less than the maximum price you specify. Spot
price will be updated based on available spot instance capacity and current
@@ -263,12 +266,12 @@ builder.
`auto` for Packer to automatically discover the best spot price or to "0"
to use an on demand instance (default).
-- `spot_price_auto_product` (string) - Required if `spot_price` is set
+- `spot_price_auto_product` (string) - Required if `spot_price` is set
to `auto`. This tells Packer what sort of AMI you're launching to find the
best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`,
`Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)`
-- `ssh_keypair_name` (string) - If specified, this is the key that will be
+- `ssh_keypair_name` (string) - If specified, this is the key that will be
used for SSH with the machine. The key must match a key pair name loaded
up into Amazon EC2. By default, this is blank, and Packer will
generate a temporary keypair unless
@@ -276,7 +279,7 @@ builder.
[`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file)
or `ssh_agent_auth` must be specified when `ssh_keypair_name` is utilized.
-- `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to
+- `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to
authenticate connections to the source instance. No temporary keypair will
be created, and the values of `ssh_password` and `ssh_private_key_file` will
be ignored. To use this option with a key pair already configured in the source
@@ -284,39 +287,39 @@ builder.
in AWS with the source instance, set the `ssh_keypair_name` field to the name
of the key pair.
-- `ssh_private_ip` (boolean) - If true, then SSH will always use the private
+- `ssh_private_ip` (boolean) - If true, then SSH will always use the private
IP if available.
-- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
+- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
`subnet-12345def`, where Packer will launch the EC2 instance. This field is
required if you are using an non-default VPC.
-- `tags` (object of key/value strings) - Tags applied to the AMI and
+- `tags` (object of key/value strings) - Tags applied to the AMI and
relevant snapshots. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `temporary_key_pair_name` (string) - The name of the temporary keypair
+- `temporary_key_pair_name` (string) - The name of the temporary keypair
to generate. By default, Packer generates a name with a UUID.
-- `token` (string) - The access token to use. This is different from the
+- `token` (string) - The access token to use. This is different from the
access key and secret key. If you're not sure what this is, then you
probably don't need it. This will also be read from the `AWS_SESSION_TOKEN`
environmental variable.
-- `user_data` (string) - User data to apply when launching the instance. Note
+- `user_data` (string) - User data to apply when launching the instance. Note
that you need to be careful about escaping characters due to the templates
being JSON. It is often more convenient to use `user_data_file`, instead.
-- `user_data_file` (string) - Path to a file that will be used for the user
+- `user_data_file` (string) - Path to a file that will be used for the user
data when launching the instance.
-- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
+- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
in order to create a temporary security group within the VPC. Requires `subnet_id`
to be set.
-- `windows_password_timeout` (string) - The timeout for waiting for a Windows
+- `windows_password_timeout` (string) - The timeout for waiting for a Windows
password for Windows instances. Defaults to 20 minutes. Example value: `10m`
## Basic Example
@@ -324,7 +327,7 @@ builder.
Here is a basic example. You will need to provide access keys, and may need to
change the AMI IDs according to what images exist at the time the template is run:
-``` {.javascript}
+```javascript
{
"type": "amazon-ebs",
"access_key": "YOUR KEY HERE",
@@ -337,7 +340,7 @@ change the AMI IDs according to what images exist at the time the template is ru
}
```
--> **Note:** Packer can also read the access key and secret access key from
+-> **Note:** Packer can also read the access key and secret access key from
environmental variables. See the configuration reference in the section above
for more information on what environmental variables Packer will look for.
@@ -348,7 +351,7 @@ or [for Windows](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/finding-a
## Basic Example
-``` {.javascript}
+```javascript
{
"type" : "amazon-surrogate",
"secret_key" : "YOUR SECRET KEY HERE",
@@ -358,25 +361,24 @@ or [for Windows](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/finding-a
"instance_type" : "t2.medium",
"source_ami" : "ami-40d28157",
"launch_block_device_mappings" : [
- {
- "volume_type" : "gp2",
- "device_name" : "/dev/xvdf",
- "delete_on_termination" : false,
- "volume_size" : 10
- },
+ {
+ "volume_type" : "gp2",
+ "device_name" : "/dev/xvdf",
+ "delete_on_termination" : false,
+ "volume_size" : 10
+ }
],
"ami_root_device": {
- "source_device_name": "/dev/xvdf",
- "device_name": "/dev/xvda",
- "delete_on_termination": true,
- "volume_size": 16,
- "volume_type": "gp2"
+ "source_device_name": "/dev/xvdf",
+ "device_name": "/dev/xvda",
+ "delete_on_termination": true,
+ "volume_size": 16,
+ "volume_type": "gp2"
}
-
}
```
--> **Note:** Packer can also read the access key and secret access key from
+-> **Note:** Packer can also read the access key and secret access key from
environmental variables. See the configuration reference in the section above
for more information on what environmental variables Packer will look for.
@@ -392,7 +394,7 @@ with the `-debug` flag. In debug mode, the Amazon builder will save the private
key in the current directory and will output the DNS or IP information as well.
You can use this information to access the instance as it is running.
--> **Note:** Packer uses pre-built AMIs as the source for building images.
+-> **Note:** Packer uses pre-built AMIs as the source for building images.
These source AMIs may include volumes that are not flagged to be destroyed on
termination of the instance building the new image. In addition to those volumes
created by this builder, any volumes inn the source AMI which are not marked for
diff --git a/website/source/docs/builders/amazon-ebsvolume.html.md b/website/source/docs/builders/amazon-ebsvolume.html.md
index ce7cf687c..9f3f1cc52 100644
--- a/website/source/docs/builders/amazon-ebsvolume.html.md
+++ b/website/source/docs/builders/amazon-ebsvolume.html.md
@@ -1,10 +1,11 @@
---
-description: |
- The `amazon-ebsvolume` Packer builder is like the EBS builder, but is
- intended to create EBS volumes rather than a machine image.
layout: docs
-page_title: 'Amazon EBS Volume Builder'
-...
+sidebar_current: docs-builders-amazon-ebsvolume
+page_title: Amazon EBS Volume - Builders
+description: |-
+ The amazon-ebsvolume Packer builder is like the EBS builder, but is intended
+ to create EBS volumes rather than a machine image.
+---
# EBS Volume Builder
@@ -14,15 +15,15 @@ The `amazon-ebsvolume` Packer builder is able to create Amazon Elastic Block
Store volumes which are prepopulated with filesystems or data.
This builder builds EBS volumes by launching an EC2 instance from a source AMI,
-provisioning that running machine, and then destroying the source machine, keeping
-the volumes intact.
+provisioning that running machine, and then destroying the source machine,
+keeping the volumes intact.
-This is all done in your own AWS account. The builder will create temporary
-key pairs, security group rules, etc. that provide it temporary access to the
+This is all done in your own AWS account. The builder will create temporary key
+pairs, security group rules, etc. that provide it temporary access to the
instance while the image is being created.
-The builder does *not* manage EBS Volumes. Once it creates volumes and stores
-it in your account, it is up to you to use, delete, etc. the volumes.
+The builder does *not* manage EBS Volumes. Once it creates volumes and stores it
+in your account, it is up to you to use, delete, etc. the volumes.
-> **Note:** Temporary resources are, by default, all created with the prefix
`packer`. This can be useful if you want to restrict the security groups and
@@ -40,110 +41,111 @@ builder.
### Required:
-- `access_key` (string) - The access key used to communicate with AWS. [Learn
+- `access_key` (string) - The access key used to communicate with AWS. [Learn
how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `instance_type` (string) - The EC2 instance type to use while building the
+- `instance_type` (string) - The EC2 instance type to use while building the
AMI, such as `m1.small`.
-- `region` (string) - The name of the region, such as `us-east-1`, in which to
+- `region` (string) - The name of the region, such as `us-east-1`, in which to
launch the EC2 instance to create the AMI.
-- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
+- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `source_ami` (string) - The initial AMI used as a base for the newly
+- `source_ami` (string) - The initial AMI used as a base for the newly
created machine. `source_ami_filter` may be used instead to populate this
automatically.
### Optional:
-- `ebs_volumes` (array of block device mappings) - Add the block
+- `ebs_volumes` (array of block device mappings) - Add the block
device mappings to the AMI. The block device mappings allow for keys:
- - `device_name` (string) - The device name exposed to the instance (for
+ - `device_name` (string) - The device name exposed to the instance (for
example, `/dev/sdh` or `xvdh`). Required when specifying `volume_size`.
- - `delete_on_termination` (boolean) - Indicates whether the EBS volume is
+ - `delete_on_termination` (boolean) - Indicates whether the EBS volume is
deleted on instance termination
- - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
- - `iops` (integer) - The number of I/O operations per second (IOPS) that the
+ - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
+ - `iops` (integer) - 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
- - `no_device` (boolean) - Suppresses the specified device included in the
+ - `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
+ - `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` (integer) - The size of the volume, in GiB. Required if not
+ - `volume_size` (integer) - 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)
+ - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD)
volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic
volumes
- - `tags` (map) - Tags to apply to the volume. These are retained after the
+ - `tags` (map) - Tags to apply to the volume. These are retained after the
builder completes. This is a [configuration template]
(/docs/templates/configuration-templates.html) where the `SourceAMI`
variable is replaced with the source AMI ID and `BuildRegion` variable
is replaced with the value of `region`.
-- `associate_public_ip_address` (boolean) - If using a non-default VPC, public
+- `associate_public_ip_address` (boolean) - If using a non-default VPC, public
IP addresses are not provided by default. If this is toggled, your new
instance will get a Public IP.
-- `availability_zone` (string) - Destination availability zone to launch
+- `availability_zone` (string) - Destination availability zone to launch
instance in. Leave this empty to allow Amazon to auto-assign.
-- `ebs_optimized` (boolean) - Mark instance as [EBS
+- `ebs_optimized` (boolean) - Mark instance as [EBS
Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html).
Default `false`.
-- `enhanced_networking` (boolean) - Enable enhanced
+- `enhanced_networking` (boolean) - Enable enhanced
networking (SriovNetSupport and ENA) on HVM-compatible AMIs. If true, add
`ec2:ModifyInstanceAttribute` to your AWS IAM policy.
-- `iam_instance_profile` (string) - The name of an [IAM instance
+- `iam_instance_profile` (string) - The name of an [IAM instance
profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html)
to launch the EC2 instance with.
-- `run_tags` (object of key/value strings) - Tags to apply to the instance
+- `run_tags` (object of key/value strings) - Tags to apply to the instance
that is *launched* to create the AMI. These tags are *not* applied to the
resulting AMI unless they're duplicated in `tags`. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `security_group_id` (string) - The ID (*not* the name) of the security group
+- `security_group_id` (string) - The ID (*not* the name) of the security group
to assign to the instance. By default this is not set and Packer will
automatically create a new temporary security group to allow SSH access.
Note that if this is specified, you must be sure the security group allows
access to the `ssh_port` given below.
-- `security_group_ids` (array of strings) - A list of security groups as
+- `security_group_ids` (array of strings) - A list of security groups as
described above. Note that if this is specified, you must omit the
`security_group_id`.
-- `shutdown_behavior` (string) - Automatically terminate instances on shutdown
+- `shutdown_behavior` (string) - Automatically terminate instances on shutdown
in case Packer exits ungracefully. Possible values are `stop` and `terminate`.
Defaults to `stop`.
-- `skip_region_validation` (boolean) - Set to `true` if you want to skip
+- `skip_region_validation` (boolean) - Set to `true` if you want to skip
validation of the region configuration option. Defaults to `false`.
-- `snapshot_groups` (array of strings) - A list of groups that have access to
+- `snapshot_groups` (array of strings) - A list of groups that have access to
create volumes from the snapshot(s). By default no groups have permission to create
volumes form the snapshot(s). `all` will make the snapshot publicly accessible.
-- `snapshot_users` (array of strings) - A list of account IDs that have access to
+- `snapshot_users` (array of strings) - A list of account IDs that have access to
create volumes from the snapshot(s). By default no additional users other than the
user creating the AMI has permissions to create volumes from the backing snapshot(s).
-- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
+- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
Example:
- ``` {.javascript}
- "source_ami_filter": {
+ ```json
+ {
+ "source_ami_filter": {
"filters": {
"virtualization-type": "hvm",
"name": "*ubuntu-xenial-16.04-amd64-server-*",
@@ -151,6 +153,7 @@ builder.
},
"owners": ["099720109477"],
"most_recent": true
+ }
}
```
@@ -158,18 +161,18 @@ builder.
NOTE: This will fail unless *exactly* one AMI is returned. In the above
example, `most_recent` will cause this to succeed by selecting the newest image.
- - `filters` (map of strings) - filters used to select a `source_ami`.
+ - `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless *exactly* one AMI is returned.
Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
+ - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
This is helpful to limit the AMIs to a trusted third party, or to your own account.
- - `most_recent` (bool) - Selects the newest created image when true.
+ - `most_recent` (bool) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
-- `spot_price` (string) - The maximum hourly price to pay for a spot instance
+- `spot_price` (string) - The maximum hourly price to pay for a spot instance
to create the AMI. Spot instances are a type of instance that EC2 starts
when the current spot price is less than the maximum price you specify. Spot
price will be updated based on available spot instance capacity and current
@@ -177,95 +180,95 @@ builder.
`auto` for Packer to automatically discover the best spot price or to `0`
to use an on-demand instance (default).
-- `spot_price_auto_product` (string) - Required if `spot_price` is set
+- `spot_price_auto_product` (string) - Required if `spot_price` is set
to `auto`. This tells Packer what sort of AMI you're launching to find the
best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`,
`Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)` or `Windows (Amazon VPC)`
-- `ssh_keypair_name` (string) - If specified, this is the key that will be
+- `ssh_keypair_name` (string) - If specified, this is the key that will be
used for SSH with the machine. By default, this is blank, and Packer will
generate a temporary key pair unless
[`ssh_password`](/docs/templates/communicator.html#ssh_password) is used.
[`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file)
must be specified with this.
-- `ssh_private_ip` (boolean) - If `true`, then SSH will always use the private
+- `ssh_private_ip` (boolean) - If `true`, then SSH will always use the private
IP if available. Also works for WinRM.
-- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
+- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
`subnet-12345def`, where Packer will launch the EC2 instance. This field is
required if you are using an non-default VPC.
-- `temporary_key_pair_name` (string) - The name of the temporary key pair
+- `temporary_key_pair_name` (string) - The name of the temporary key pair
to generate. By default, Packer generates a name that looks like
`packer_`, where \ is a 36 character unique identifier.
-- `token` (string) - The access token to use. This is different from the
+- `token` (string) - The access token to use. This is different from the
access key and secret key. If you're not sure what this is, then you
probably don't need it. This will also be read from the `AWS_SESSION_TOKEN`
environmental variable.
-- `user_data` (string) - User data to apply when launching the instance. Note
+- `user_data` (string) - User data to apply when launching the instance. Note
that you need to be careful about escaping characters due to the templates
being JSON. It is often more convenient to use `user_data_file`, instead.
-- `user_data_file` (string) - Path to a file that will be used for the user
+- `user_data_file` (string) - Path to a file that will be used for the user
data when launching the instance.
-- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
+- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
in order to create a temporary security group within the VPC. Requires `subnet_id`
to be set.
-- `windows_password_timeout` (string) - The timeout for waiting for a Windows
+- `windows_password_timeout` (string) - The timeout for waiting for a Windows
password for Windows instances. Defaults to 20 minutes. Example value: `10m`
## Basic Example
-```
+```json
{
- "type" : "amazon-ebsvolume",
- "secret_key" : "YOUR SECRET KEY HERE",
- "access_key" : "YOUR KEY HERE",
- "region" : "us-east-1",
- "ssh_username" : "ubuntu",
- "instance_type" : "t2.medium",
- "source_ami" : "ami-40d28157",
- "ebs_volumes" : [
- {
- "volume_type" : "gp2",
- "device_name" : "/dev/xvdf",
- "delete_on_termination" : false,
- "tags" : {
- "zpool" : "data",
- "Name" : "Data1"
- },
- "volume_size" : 10
+ "type" : "amazon-ebsvolume",
+ "secret_key" : "YOUR SECRET KEY HERE",
+ "access_key" : "YOUR KEY HERE",
+ "region" : "us-east-1",
+ "ssh_username" : "ubuntu",
+ "instance_type" : "t2.medium",
+ "source_ami" : "ami-40d28157",
+ "ebs_volumes" : [
+ {
+ "volume_type" : "gp2",
+ "device_name" : "/dev/xvdf",
+ "delete_on_termination" : false,
+ "tags" : {
+ "zpool" : "data",
+ "Name" : "Data1"
},
- {
- "volume_type" : "gp2",
- "device_name" : "/dev/xvdg",
- "tags" : {
- "zpool" : "data",
- "Name" : "Data2"
- },
- "delete_on_termination" : false,
- "volume_size" : 10
+ "volume_size" : 10
+ },
+ {
+ "volume_type" : "gp2",
+ "device_name" : "/dev/xvdg",
+ "tags" : {
+ "zpool" : "data",
+ "Name" : "Data2"
},
- {
- "volume_size" : 10,
- "tags" : {
- "Name" : "Data3",
- "zpool" : "data"
- },
- "delete_on_termination" : false,
- "device_name" : "/dev/xvdh",
- "volume_type" : "gp2"
- }
- ]
+ "delete_on_termination" : false,
+ "volume_size" : 10
+ },
+ {
+ "volume_size" : 10,
+ "tags" : {
+ "Name" : "Data3",
+ "zpool" : "data"
+ },
+ "delete_on_termination" : false,
+ "device_name" : "/dev/xvdh",
+ "volume_type" : "gp2"
+ }
+ ]
}
```
--> **Note:** Packer can also read the access key and secret access key from
+-> **Note:** Packer can also read the access key and secret access key from
environmental variables. See the configuration reference in the section above
for more information on what environmental variables Packer will look for.
@@ -281,7 +284,7 @@ with the `-debug` flag. In debug mode, the Amazon builder will save the private
key in the current directory and will output the DNS or IP information as well.
You can use this information to access the instance as it is running.
--> **Note:** Packer uses pre-built AMIs as the source for building images.
+-> **Note:** Packer uses pre-built AMIs as the source for building images.
These source AMIs may include volumes that are not flagged to be destroyed on
termination of the instance building the new image. In addition to those volumes
created by this builder, any volumes inn the source AMI which are not marked for
diff --git a/website/source/docs/builders/amazon-instance.html.md b/website/source/docs/builders/amazon-instance.html.md
index 3f8a66e10..9e8267cf3 100644
--- a/website/source/docs/builders/amazon-instance.html.md
+++ b/website/source/docs/builders/amazon-instance.html.md
@@ -1,12 +1,13 @@
---
-description: |
- The `amazon-instance` Packer builder is able to create Amazon AMIs backed by
- instance storage as the root device. For more information on the difference
- between instance storage and EBS-backed instances, see the storage for the root
- device section in the EC2 documentation.
layout: docs
-page_title: 'Amazon AMI Builder (instance-store)'
-...
+sidebar_current: docs-builders-amazon-instance
+page_title: Amazon instance-store - Builders
+description: |-
+ The amazon-instance Packer builder is able to create Amazon AMIs backed by
+ instance storage as the root device. For more information on the difference
+ between instance storage and EBS-backed instances, see the storage for the
+ root device section in the EC2 documentation.
+---
# AMI Builder (instance-store)
@@ -51,45 +52,45 @@ builder.
### Required:
-- `access_key` (string) - The access key used to communicate with AWS. [Learn
+- `access_key` (string) - The access key used to communicate with AWS. [Learn
how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `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 same* as the access key. You can find your account
ID in the security credentials page of your AWS account.
-- `ami_name` (string) - The name of the resulting AMI that will appear when
+- `ami_name` (string) - The name of the resulting AMI that will appear when
managing AMIs in the AWS console or via APIs. This must be unique. To help
make this unique, use a function like `timestamp` (see [configuration
templates](/docs/templates/configuration-templates.html) for more info)
-- `instance_type` (string) - The EC2 instance type to use while building the
+- `instance_type` (string) - The EC2 instance type to use while building the
AMI, such as `m1.small`.
-- `region` (string) - The name of the region, such as `us-east-1`, in which to
+- `region` (string) - The name of the region, such as `us-east-1`, in which to
launch the EC2 instance to create the AMI.
-- `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 if it doesn't exist.
-- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
+- `secret_key` (string) - The secret key used to communicate with AWS. [Learn
how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `source_ami` (string) - The initial AMI used as a base for the newly
+- `source_ami` (string) - The initial AMI used as a base for the newly
created machine.
-- `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 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
+- `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.
### Optional:
-- `ami_block_device_mappings` (array of block device mappings) - Add one or
+- `ami_block_device_mappings` (array of block device mappings) - 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
@@ -97,145 +98,146 @@ builder.
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
+ - `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
+ - `device_name` (string) - The device name exposed to the instance (for
example, `/dev/sdh` or `xvdh`). Required when specifying `volume_size`.
- - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
+ - `encrypted` (boolean) - Indicates whether to encrypt the volume or not
- - `iops` (integer) - The number of I/O operations per second (IOPS) that the
+ - `iops` (integer) - 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
- - `no_device` (boolean) - Suppresses the specified device included in the
+ - `no_device` (boolean) - Suppresses the specified device included in the
block device mapping of the AMI
- - `snapshot_id` (string) - The ID of the snapshot
+ - `snapshot_id` (string) - The ID of the snapshot
- - `virtual_name` (string) - The virtual device name. See the documentation on
+ - `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` (integer) - The size of the volume, in GiB. Required if not
+ - `volume_size` (integer) - 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)
+ - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD)
volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic
volumes
-- `ami_description` (string) - The description to set for the
+- `ami_description` (string) - The description to set for the
resulting AMI(s). By default this description is empty. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `ami_groups` (array of strings) - A list of groups that have access to
+- `ami_groups` (array of strings) - A list of groups that have access to
launch the resulting AMI(s). By default no groups have permission to launch
the AMI. `all` will make the AMI publicly accessible. AWS currently doesn't
accept any value other than `all`.
-- `ami_product_codes` (array of strings) - A list of product codes to
+- `ami_product_codes` (array of strings) - A list of product codes to
associate with the AMI. By default no product codes are associated with
the AMI.
-- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
+- `ami_regions` (array of strings) - A list of regions to copy the AMI to.
Tags and attributes are copied along with the AMI. AMI copying takes time
depending on the size of the AMI, but will generally take many minutes.
-- `ami_users` (array of strings) - A list of account IDs that have access to
+- `ami_users` (array of strings) - A list of account IDs that have access to
launch the resulting AMI(s). By default no additional users other than the
user creating the AMI has permissions to launch it.
-- `ami_virtualization_type` (string) - The type of virtualization for the AMI
+- `ami_virtualization_type` (string) - The type of virtualization for the AMI
you are building. This option is required to register HVM images. Can be
`paravirtual` (default) or `hvm`.
-- `associate_public_ip_address` (boolean) - If using a non-default VPC, public
+- `associate_public_ip_address` (boolean) - If using a non-default VPC, public
IP addresses are not provided by default. If this is toggled, your new
instance will get a Public IP.
-- `availability_zone` (string) - Destination availability zone to launch
+- `availability_zone` (string) - Destination availability zone to launch
instance in. Leave this empty to allow Amazon to auto-assign.
-- `bundle_destination` (string) - The directory on the running instance where
+- `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_prefix` (string) - The prefix for files created from bundling the
+- `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.
-- `bundle_upload_command` (string) - The command to use to upload the
+- `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
+- `bundle_vol_command` (string) - The command to use to bundle the volume. See
the "custom bundle commands" section below for more information.
-- `ebs_optimized` (boolean) - Mark instance as [EBS
+- `ebs_optimized` (boolean) - Mark instance as [EBS
Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html).
Default `false`.
-- `enhanced_networking` (boolean) - Enable enhanced
+- `enhanced_networking` (boolean) - Enable enhanced
networking (SriovNetSupport and ENA) on HVM-compatible AMIs. If true, add
`ec2:ModifyInstanceAttribute` to your AWS IAM policy.
-- `force_deregister` (boolean) - Force Packer to first deregister an existing
+- `force_deregister` (boolean) - Force Packer to first deregister an existing
AMI if one with the same name already exists. Defaults to `false`.
-- `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
+- `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with
AMIs, which have been deregistered by `force_deregister`. Defaults to `false`.
-- `iam_instance_profile` (string) - The name of an [IAM instance
+- `iam_instance_profile` (string) - The name of an [IAM instance
profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html)
to launch the EC2 instance with.
-- `launch_block_device_mappings` (array of block device mappings) - Add one or
+- `launch_block_device_mappings` (array of block device mappings) - Add one or
more block devices before the Packer build starts. These are not necessarily
preserved when booting from the AMI built with Packer. See
`ami_block_device_mappings`, above, for details.
-- `run_tags` (object of key/value strings) - Tags to apply to the instance
+- `run_tags` (object of key/value strings) - Tags to apply to the instance
that is *launched* to create the AMI. These tags are *not* applied to the
resulting AMI unless they're duplicated in `tags`. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `security_group_id` (string) - The ID (*not* the name) of the security group
+- `security_group_id` (string) - The ID (*not* the name) of the security group
to assign to the instance. By default this is not set and Packer will
automatically create a new temporary security group to allow SSH access.
Note that if this is specified, you must be sure the security group allows
access to the `ssh_port` given below.
-- `security_group_ids` (array of strings) - A list of security groups as
+- `security_group_ids` (array of strings) - A list of security groups as
described above. Note that if this is specified, you must omit the
`security_group_id`.
-- `skip_region_validation` (boolean) - Set to true if you want to skip
+- `skip_region_validation` (boolean) - Set to true if you want to skip
validation of the region configuration option. Defaults to `false`.
-- `snapshot_groups` (array of strings) - A list of groups that have access to
+- `snapshot_groups` (array of strings) - A list of groups that have access to
create volumes from the snapshot(s). By default no groups have permission to create
volumes form the snapshot(s). `all` will make the snapshot publicly accessible.
-- `snapshot_users` (array of strings) - A list of account IDs that have access to
+- `snapshot_users` (array of strings) - A list of account IDs that have access to
create volumes from the snapshot(s). By default no additional users other than the
user creating the AMI has permissions to create volumes from the backing snapshot(s).
-- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
+- `source_ami_filter` (object) - Filters used to populate the `source_ami` field.
Example:
- ``` {.javascript}
- "source_ami_filter": {
+ ```json
+ {
+ "source_ami_filter": {
"filters": {
"virtualization-type": "hvm",
"name": "*ubuntu-xenial-16.04-amd64-server-*",
@@ -243,6 +245,7 @@ builder.
},
"owners": ["099720109477"],
"most_recent": true
+ }
}
```
@@ -250,21 +253,21 @@ builder.
NOTE: This will fail unless *exactly* one AMI is returned. In the above
example, `most_recent` will cause this to succeed by selecting the newest image.
- - `filters` (map of strings) - filters used to select a `source_ami`.
+ - `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless *exactly* one AMI is returned.
Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
+ - `owners` (array of strings) - This scopes the AMIs to certain Amazon account IDs.
This is helpful to limit the AMIs to a trusted third party, or to your own account.
- - `most_recent` (bool) - Selects the newest created image when true.
+ - `most_recent` (bool) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
-- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
+- `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot.
They will override AMI tags if already applied to snapshot.
-- `spot_price` (string) - The maximum hourly price to launch a spot instance
+- `spot_price` (string) - The maximum hourly price to launch a spot instance
to create the AMI. It is a type of instances that EC2 starts when the
maximum price that you specify exceeds the current spot price. Spot price
will be updated based on available spot instance capacity and current spot
@@ -272,12 +275,12 @@ builder.
for Packer to automatically discover the best spot price or to `0` to use
an on-demand instance (default).
-- `spot_price_auto_product` (string) - Required if `spot_price` is set
+- `spot_price_auto_product` (string) - Required if `spot_price` is set
to `auto`. This tells Packer what sort of AMI you're launching to find the
best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`,
`Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)`
-- `ssh_keypair_name` (string) - If specified, this is the key that will be
+- `ssh_keypair_name` (string) - If specified, this is the key that will be
used for SSH with the machine. The key must match a key pair name loaded
up into Amazon EC2. By default, this is blank, and Packer will
generate a temporary key pair unless
@@ -285,7 +288,7 @@ builder.
[`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file)
or `ssh_agent_auth` must be specified when `ssh_keypair_name` is utilized.
-- `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to
+- `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to
authenticate connections to the source instance. No temporary key pair will
be created, and the values of `ssh_password` and `ssh_private_key_file` will
be ignored. To use this option with a key pair already configured in the source
@@ -293,46 +296,46 @@ builder.
in AWS with the source instance, set the `ssh_keypair_name` field to the name
of the key pair.
-- `ssh_private_ip` (boolean) - If true, then SSH will always use the private
+- `ssh_private_ip` (boolean) - If true, then SSH will always use the private
IP if available. Also works for WinRM.
-- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
+- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
`subnet-12345def`, where Packer will launch the EC2 instance. This field is
required if you are using an non-default VPC.
-- `tags` (object of key/value strings) - Tags applied to the AMI. This is a
+- `tags` (object of key/value strings) - Tags applied to the AMI. This is a
[configuration template](/docs/templates/configuration-templates.html)
where the `SourceAMI` variable is replaced with the source AMI ID and
`BuildRegion` variable is replaced with the value of `region`.
-- `temporary_key_pair_name` (string) - The name of the temporary key pair
+- `temporary_key_pair_name` (string) - The name of the temporary key pair
to generate. By default, Packer generates a name that looks like
`packer_`, where \ is a 36 character unique identifier.
-- `user_data` (string) - User data to apply when launching the instance. Note
+- `user_data` (string) - User data to apply when launching the instance. Note
that you need to be careful about escaping characters due to the templates
being JSON. It is often more convenient to use `user_data_file`, instead.
-- `user_data_file` (string) - Path to a file that will be used for the user
+- `user_data_file` (string) - Path to a file that will be used for the user
data when launching the instance.
-- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
+- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
in order to create a temporary security group within the VPC.
-- `x509_upload_path` (string) - The path on the remote machine where the X509
+- `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`.
-- `windows_password_timeout` (string) - The timeout for waiting for a Windows
+- `windows_password_timeout` (string) - The timeout for waiting for a Windows
password for Windows instances. Defaults to 20 minutes. Example value: `10m`
## Basic Example
Here is a basic example. It is completely valid except for the access keys:
-``` {.javascript}
+```json
{
"type": "amazon-instance",
"access_key": "YOUR KEY HERE",
@@ -352,7 +355,7 @@ Here is a basic example. It is completely valid except for the access keys:
}
```
--> **Note:** Packer can also read the access key and secret access key from
+-> **Note:** Packer can also read the access key and secret access key from
environmental variables. See the configuration reference in the section above
for more information on what environmental variables Packer will look for.
@@ -387,7 +390,7 @@ multiple lines for convenience of reading. The bundle volume command is
responsible for executing `ec2-bundle-vol` in order to store and image of the
root filesystem to use to create the AMI.
-``` {.text}
+```text
sudo -i -n ec2-bundle-vol \
-k {{.KeyPath}} \
-u {{.AccountId}} \
@@ -403,7 +406,7 @@ sudo -i -n ec2-bundle-vol \
The available template variables should be self-explanatory based on the
parameters they're used to satisfy the `ec2-bundle-vol` command.
-\~> **Warning!** Some versions of ec2-bundle-vol silently ignore all .pem and
+~> **Warning!** Some versions of ec2-bundle-vol silently ignore all .pem and
.gpg files during the bundling of the AMI, which can cause problems on some
systems, such as Ubuntu. You may want to customize the bundle volume command to
include those files (see the `--no-filter` option of `ec2-bundle-vol`).
@@ -415,7 +418,7 @@ multiple lines for convenience of reading. Access key and secret key are omitted
if using instance profile. The bundle upload command is responsible for taking
the bundled volume and uploading it to S3.
-``` {.text}
+```text
sudo -i -n ec2-upload-bundle \
-b {{.BucketName}} \
-m {{.ManifestPath}} \
diff --git a/website/source/docs/builders/amazon.html.md b/website/source/docs/builders/amazon.html.md
index 82aab89af..566ab6bf6 100644
--- a/website/source/docs/builders/amazon.html.md
+++ b/website/source/docs/builders/amazon.html.md
@@ -1,10 +1,11 @@
---
-description: |
- Packer is able to create Amazon AMIs. To achieve this, Packer comes with
- multiple builders depending on the strategy you want to use to build the AMI.
layout: docs
-page_title: Amazon AMI Builder
-...
+sidebar_current: docs-builders-amazon
+page_title: Amazon AMI - Builders
+description: |-
+ Packer is able to create Amazon AMIs. To achieve this, Packer comes with
+ multiple builders depending on the strategy you want to use to build the AMI.
+---
# Amazon AMI Builder
@@ -33,7 +34,7 @@ Packer supports the following builders at the moment:
not require running in AWS. This is an **advanced builder and should not be
used by newcomers**.
--> **Don't know which builder to use?** If in doubt, use the [amazon-ebs
+-> **Don't know which builder to use?** If in doubt, use the [amazon-ebs
builder](/docs/builders/amazon-ebs.html). It is much easier to use and Amazon
generally recommends EBS-backed images nowadays.
@@ -86,7 +87,7 @@ following steps:
3. Lookup an IAM role for the current EC2 instance (if you're running in EC2)
-\~> **Subtle details of automatic lookup may change over time.** The most
+~> **Subtle details of automatic lookup may change over time.** The most
reliable way to specify your configuration is by setting them in template
variables (directly or indirectly), or by using the `AWS_ACCESS_KEY_ID` and
`AWS_SECRET_ACCESS_KEY` environment variables.
@@ -104,7 +105,7 @@ the instance's IAM profile, if it has one.
The following policy document provides the minimal set permissions necessary for
Packer to work:
-``` {.javascript}
+```javascript
{
"Version": "2012-10-17",
"Statement": [{
@@ -163,7 +164,7 @@ The example policy below may help packer work with IAM roles. Note that this
example provides more than the minimal set of permissions needed for packer to
work, but specifics will depend on your use-case.
-``` {.json}
+```json
{
"Sid": "PackerIAMPassRole",
"Effect": "Allow",
diff --git a/website/source/docs/builders/azure-setup.html.md b/website/source/docs/builders/azure-setup.html.md
index 7607be6f8..882fd072d 100644
--- a/website/source/docs/builders/azure-setup.html.md
+++ b/website/source/docs/builders/azure-setup.html.md
@@ -1,18 +1,24 @@
---
-description: |
-
layout: docs
-page_title: Authorizing Packer Builds in Azure
-...
+sidebar_current: docs-builders-azure-setup
+page_title: Setup - Azure - Builders
+description: |-
+ In order to build VMs in Azure, Packer needs various configuration options.
+ These options and how to obtain them are documented on this page.
+---
# Authorizing Packer Builds in Azure
In order to build VMs in Azure Packer needs 6 configuration options to be specified:
- `subscription_id` - UUID identifying your Azure subscription (where billing is handled)
+
- `client_id` - UUID identifying the Active Directory service principal that will run your Packer builds
+
- `client_secret` - service principal secret / password
+
- `resource_group_name` - name of the resource group where your VHD(s) will be stored
+
- `storage_account` - name of the storage account where your VHD(s) will be stored
-> Behind the scenes Packer uses the OAuth protocol to authenticate against Azure Active Directory and authorize requests to the Azure Service Management API. These topics are unnecessarily complicated so we will try to ignore them for the rest of this document.
You do not need to understand how OAuth works in order to use Packer with Azure, though the Active Directory terms "service principal" and "role" will be useful for understanding Azure's access policies.
@@ -49,7 +55,9 @@ To get the credentials above, we will need to install the Azure CLI. Please refe
If you already have node.js installed you can use `npm` to install `azure-cli`:
- npm install -g azure-cli --no-progress
+```shell
+$ npm install -g azure-cli --no-progress
+```
## Guided Setup
@@ -63,20 +71,26 @@ If you want more control or the script does not work for you, you can also use t
Login using the Azure CLI
- azure config mode arm
- azure login -u USERNAME
+```shell
+$ azure config mode arm
+$ azure login -u USERNAME
+```
Get your account information
- azure account list --json | jq '.[].name'
- azure account set ACCOUNTNAME
- azure account show --json | jq ".[] | .id"
+```shell
+$ azure account list --json | jq -r '.[].name'
+$ azure account set ACCOUNTNAME
+$ azure account show --json | jq -r ".[] | .id"
+```
-> Throughout this document when you see a command pipe to `jq` you may instead omit `--json` and everything after it, but the output will be more verbose. For example you can simply run `azure account list` instead.
This will print out one line that look like this:
- "4f562e88-8caf-421a-b4da-e3f6786c52ec"
+```
+4f562e88-8caf-421a-b4da-e3f6786c52ec
+```
This is your `subscription_id`. Note it for later.
@@ -84,9 +98,12 @@ This is your `subscription_id`. Note it for later.
A [resource group](https://azure.microsoft.com/en-us/documentation/articles/resource-group-overview/#resource-groups) is used to organize related resources. Resource groups and storage accounts are tied to a location. To see available locations, run:
- azure location list
- ...
- azure group create -n GROUPNAME -l LOCATION
+```shell
+$ azure location list
+# ...
+
+$ azure group create -n GROUPNAME -l LOCATION
+```
Your storage account (below) will need to use the same `GROUPNAME` and `LOCATION`.
@@ -94,8 +111,13 @@ Your storage account (below) will need to use the same `GROUPNAME` and `LOCATION
We will need to create a storage account where your Packer artifacts will be stored. We will create a `LRS` storage account which is the least expensive price/GB at the time of writing.
- azure storage account create -g GROUPNAME \
- -l LOCATION --sku-name LRS --kind storage STORAGENAME
+```shell
+$ azure storage account create \
+ -g GROUPNAME \
+ -l LOCATION \
+ --sku-name LRS \
+ --kind storage STORAGENAME
+```
-> `LRS` is meant as a literal "LRS" and not as a variable.
@@ -105,7 +127,13 @@ Make sure that `GROUPNAME` and `LOCATION` are the same as above.
An application represents a way to authorize access to the Azure API. Note that you will need to specify a URL for your application (this is intended to be used for OAuth callbacks) but these do not actually need to be valid URLs.
- azure ad app create -n APPNAME -i APPURL --home-page APPURL -p PASSWORD
+```shell
+$ azure ad app create \
+ -n APPNAME \
+ -i APPURL \
+ --home-page APPURL \
+ -p PASSWORD
+```
Password is your `client_secret` and can be anything you like. I recommend using `openssl rand -base64 24`.
@@ -115,21 +143,31 @@ You cannot directly grant permissions to an application. Instead, you create a s
First, get the `APPID` for the application we just created.
- azure ad app list --json | \
- jq '.[] | select(.displayName | contains("APPNAME")) | .appId'
- azure ad sp create --applicationId APPID
+```shell
+$ azure ad app list --json \
+ | jq '.[] | select(.displayName | contains("APPNAME")) | .appId'
+# ...
+
+$ azure ad sp create --applicationId APPID
+```
### Grant Permissions to Your Application
Finally, we will associate the proper permissions with our application's service principal. We're going to assign the `Owner` role to our Packer application and change the scope to manage our whole subscription. (The `Owner` role can be scoped to a specific resource group to further reduce the scope of the account.) This allows Packer to create temporary resource groups for each build.
- azure role assignment create --spn APPURL -o "Owner" \
- -c /subscriptions/SUBSCRIPTIONID
+```shell
+$ azure role assignment create \
+ --spn APPURL \
+ -o "Owner" \
+ -c /subscriptions/SUBSCRIPTIONID
+```
There are a lot of pre-defined roles and you can define your own with more granular permissions, though this is out of scope. You can see a list of pre-configured roles via:
- azure role list --json | \
- jq ".[] | {name:.Name, description:.Description}"
+```shell
+$ azure role list --json \
+ | jq ".[] | {name:.Name, description:.Description}"
+```
### Configuring Packer
@@ -138,12 +176,17 @@ Now (finally) everything has been setup in Azure. Let's get our configuration ke
Get `subscription_id`:
- azure account show --json | jq ".[] | .id"
+```shell
+$ azure account show --json \
+ | jq ".[] | .id"
+```
Get `client_id`
- azure ad app list --json | \
- jq '.[] | select(.displayName | contains("APPNAME")) | .appId'
+```shell
+$ azure ad app list --json \
+ | jq '.[] | select(.displayName | contains("APPNAME")) | .appId'
+```
Get `client_secret`
@@ -151,8 +194,12 @@ This cannot be retrieved. If you forgot this, you will have to delete and re-cre
Get `resource_group_name`
- azure group list
+```shell
+$ azure group list
+```
Get `storage_account`
- azure storage account list
+```shell
+$ azure storage account list
+```
diff --git a/website/source/docs/builders/azure-arm.html.md b/website/source/docs/builders/azure.html.md
similarity index 71%
rename from website/source/docs/builders/azure-arm.html.md
rename to website/source/docs/builders/azure.html.md
index 20defaf7a..d7f1ec0b4 100644
--- a/website/source/docs/builders/azure-arm.html.md
+++ b/website/source/docs/builders/azure.html.md
@@ -1,9 +1,10 @@
---
-description: |
-
layout: docs
-page_title: Azure Resource Manager
-...
+sidebar_current: docs-builders-azure
+page_title: Azure - Builders
+description: |-
+ Packer supports building VHDs in Azure Resource manager.
+---
# Azure Resource Manager Builder
@@ -25,89 +26,89 @@ builder.
### Required:
-- `client_id` (string) The Active Directory service principal associated with your builder.
+- `client_id` (string) The Active Directory service principal associated with your builder.
-- `client_secret` (string) The password or secret for your service principal.
+- `client_secret` (string) The password or secret for your service principal.
-- `resource_group_name` (string) Resource group under which the final artifact will be stored.
+- `resource_group_name` (string) Resource group under which the final artifact will be stored.
-- `storage_account` (string) Storage account under which the final artifact will be stored.
+- `storage_account` (string) Storage account under which the final artifact will be stored.
-- `subscription_id` (string) Subscription under which the build will be performed. **The service principal specified in `client_id` must have full access to this subscription.**
+- `subscription_id` (string) Subscription under which the build will be performed. **The service principal specified in `client_id` must have full access to this subscription.**
-- `capture_container_name` (string) Destination container name. Essentially the "directory" where your VHD will be organized in Azure. The captured VHD's URL will be https://.blob.core.windows.net/system/Microsoft.Compute/Images//.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.vhd.
+- `capture_container_name` (string) Destination container name. Essentially the "directory" where your VHD will be organized in Azure. The captured VHD's URL will be https://.blob.core.windows.net/system/Microsoft.Compute/Images//.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.vhd.
-- `capture_name_prefix` (string) VHD prefix. The final artifacts will be named `PREFIX-osDisk.UUID` and `PREFIX-vmTemplate.UUID`.
+- `capture_name_prefix` (string) VHD prefix. The final artifacts will be named `PREFIX-osDisk.UUID` and `PREFIX-vmTemplate.UUID`.
-- `image_publisher` (string) PublisherName for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details.
+- `image_publisher` (string) PublisherName for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details.
CLI example `azure vm image list-publishers -l westus`
-- `image_offer` (string) Offer for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details.
+- `image_offer` (string) Offer for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details.
CLI example `azure vm image list-offers -l westus -p Canonical`
-- `image_sku` (string) SKU for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details.
+- `image_sku` (string) SKU for your base image. See [documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/) for details.
CLI example `azure vm image list-skus -l westus -p Canonical -o UbuntuServer`
-- `location` (string) Azure datacenter in which your VM will build.
+- `location` (string) Azure datacenter in which your VM will build.
CLI example `azure location list`
### Optional:
-- `azure_tags` (object of name/value strings) - the user can define up to 15 tags. Tag names cannot exceed 512
+- `azure_tags` (object of name/value strings) - the user can define up to 15 tags. Tag names cannot exceed 512
characters, and tag values cannot exceed 256 characters. Tags are applied to every resource deployed by a Packer
build, i.e. Resource Group, VM, NIC, VNET, Public IP, KeyVault, etc.
-- `cloud_environment_name` (string) One of `Public`, `China`, `Germany`, or
+- `cloud_environment_name` (string) One of `Public`, `China`, `Germany`, or
`USGovernment`. Defaults to `Public`. Long forms such as
`USGovernmentCloud` and `AzureUSGovernmentCloud` are also supported.
-- `image_version` (string) Specify a specific version of an OS to boot from. Defaults to `latest`. There may be a
+- `image_version` (string) Specify a specific version of an OS to boot from. Defaults to `latest`. There may be a
difference in versions available across regions due to image synchronization latency. To ensure a consistent
version across regions set this value to one that is available in all regions where you are deploying.
CLI example `azure vm image list -l westus -p Canonical -o UbuntuServer -k 16.04.0-LTS`
-- `image_url` (string) Specify a custom VHD to use. If this value is set, do not set image_publisher, image_offer,
+- `image_url` (string) Specify a custom VHD to use. If this value is set, do not set image_publisher, image_offer,
image_sku, or image_version.
-
-- `temp_compute_name` (string) temporary name assigned to the VM. If this value is not set, a random value will be assigned. Knowing the resource group and VM name allows one to execute commands to update the VM during a Packer build, e.g. attach a resource disk to the VM.
-- `temp_resource_group_name` (string) temporary name assigned to the resource group. If this value is not set, a random value will be assigned.
+- `temp_compute_name` (string) temporary name assigned to the VM. If this value is not set, a random value will be assigned. Knowing the resource group and VM name allows one to execute commands to update the VM during a Packer build, e.g. attach a resource disk to the VM.
-- `tenant_id` (string) The account identifier with which your `client_id` and `subscription_id` are associated. If not
+- `temp_resource_group_name` (string) temporary name assigned to the resource group. If this value is not set, a random value will be assigned.
+
+- `tenant_id` (string) The account identifier with which your `client_id` and `subscription_id` are associated. If not
specified, `tenant_id` will be looked up using `subscription_id`.
-- `object_id` (string) Specify an OAuth Object ID to protect WinRM certificates
+- `object_id` (string) Specify an OAuth Object ID to protect WinRM certificates
created at runtime. This variable is required when creating images based on
Windows; this variable is not used by non-Windows builds. See `Windows`
behavior for `os_type`, below.
-- `os_type` (string) If either `Linux` or `Windows` is specified Packer will
+- `os_type` (string) If either `Linux` or `Windows` is specified Packer will
automatically configure authentication credentials for the provisioned machine. For
`Linux` this configures an SSH authorized key. For `Windows` this
configures a WinRM certificate.
-
-- `os_disk_size_gb` (int32) Specify the size of the OS disk in GB (gigabytes). Values of zero or less than zero are
+
+- `os_disk_size_gb` (int32) Specify the size of the OS disk in GB (gigabytes). Values of zero or less than zero are
ignored.
-- `virtual_network_name` (string) Use a pre-existing virtual network for the VM. This option enables private
+- `virtual_network_name` (string) Use a pre-existing virtual network for the VM. This option enables private
communication with the VM, no public IP address is **used** or **provisioned**. This value should only be set if
Packer is executed from a host on the same subnet / virtual network.
-- `virtual_network_resource_group_name` (string) If virtual_network_name is set, this value **may** also be set. If
+- `virtual_network_resource_group_name` (string) If virtual_network_name is set, this value **may** also be set. If
virtual_network_name is set, and this value is not set the builder attempts to determine the resource group
containing the virtual network. If the resource group cannot be found, or it cannot be disambiguated, this value
should be set.
-- `virtual_network_subnet_name` (string) If virtual_network_name is set, this value **may** also be set. If
+- `virtual_network_subnet_name` (string) If virtual_network_name is set, this value **may** also be set. If
virtual_network_name is set, and this value is not set the builder attempts to determine the subnet to use with
the virtual network. If the subnet cannot be found, or it cannot be disambiguated, this value should be set.
-- `vm_size` (string) Size of the VM used for building. This can be changed
+- `vm_size` (string) Size of the VM used for building. This can be changed
when you deploy a VM from your VHD. See
[pricing](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/) information. Defaults to `Standard_A1`.
@@ -118,7 +119,7 @@ builder.
Here is a basic example for Azure.
-``` {.javascript}
+```json
{
"type": "azure-arm",
@@ -136,7 +137,7 @@ Here is a basic example for Azure.
"image_publisher": "Canonical",
"image_offer": "UbuntuServer",
"image_sku": "14.04.4-LTS",
-
+
"azure_tags": {
"dept": "engineering"
},
@@ -156,31 +157,37 @@ Please refer to the Azure [examples](https://github.com/mitchellh/packer/tree/ma
The following provisioner snippet shows how to sysprep a Windows VM. Deprovision should be the last operation executed by a build.
-``` {.javascript}
- "provisioners": [
- {
- "type": "powershell",
- "inline": [
- "if( Test-Path $Env:SystemRoot\\windows\\system32\\Sysprep\\unattend.xml ){ rm $Env:SystemRoot\\windows\\system32\\Sysprep\\unattend.xml -Force}",
- "& $Env:SystemRoot\\System32\\Sysprep\\Sysprep.exe /oobe /generalize /shutdown /quiet"
- ]
- }
- ]
+```json
+{
+ "provisioners": [
+ {
+ "type": "powershell",
+ "inline": [
+ "if( Test-Path $Env:SystemRoot\\windows\\system32\\Sysprep\\unattend.xml ){ rm $Env:SystemRoot\\windows\\system32\\Sysprep\\unattend.xml -Force}",
+ "& $Env:SystemRoot\\System32\\Sysprep\\Sysprep.exe /oobe /generalize /shutdown /quiet"
+ ]
+ }
+ ]
+}
```
### Linux
The following provisioner snippet shows how to deprovision a Linux VM. Deprovision should be the last operation executed by a build.
-``` {.javascript}
- "provisioners": [{
- "execute_command": "chmod +x {{ .Path }}; {{ .Vars }} sudo -E sh '{{ .Path }}'",
- "inline": [
- "/usr/sbin/waagent -force -deprovision+user && export HISTSIZE=0 && sync"
- ],
- "inline_shebang": "/bin/sh -x",
- "type": "shell"
- }]
+```json
+{
+ "provisioners": [
+ {
+ "execute_command": "chmod +x {{ .Path }}; {{ .Vars }} sudo -E sh '{{ .Path }}'",
+ "inline": [
+ "/usr/sbin/waagent -force -deprovision+user && export HISTSIZE=0 && sync"
+ ],
+ "inline_shebang": "/bin/sh -x",
+ "type": "shell"
+ }
+ ]
+}
```
To learn more about the Linux deprovision process please see WALinuxAgent's [README](https://github.com/Azure/WALinuxAgent/blob/master/README.md).
@@ -205,7 +212,7 @@ The Azure builder attempts to pick default values that provide for a just works
## Implementation
-\~> **Warning!** This is an advanced topic. You do not need to understand the implementation to use the Azure
+~> **Warning!** This is an advanced topic. You do not need to understand the implementation to use the Azure
builder.
The Azure builder uses ARM
diff --git a/website/source/docs/builders/cloudstack.html.md b/website/source/docs/builders/cloudstack.html.md
index 6ce84cd32..07559d6ac 100644
--- a/website/source/docs/builders/cloudstack.html.md
+++ b/website/source/docs/builders/cloudstack.html.md
@@ -1,12 +1,13 @@
---
-description: |
- The `cloudstack` Packer builder is able to create new templates for use with
- CloudStack. The builder takes either an ISO or an existing template as it's
- source, runs any provisioning necessary on the instance after launching it
- and then creates a new template from that instance.
layout: docs
-page_title: CloudStack Builder
-...
+sidebar_current: docs-builders-cloudstack
+page_title: CloudStack - Builders
+description: |-
+ The cloudstack Packer builder is able to create new templates for use with
+ CloudStack. The builder takes either an ISO or an existing template as it's
+ source, runs any provisioning necessary on the instance after launching it and
+ then creates a new template from that instance.
+---
# CloudStack Builder
@@ -32,101 +33,101 @@ builder.
### Required:
-- `api_url` (string) - The CloudStack API endpoint we will connect to.
+- `api_url` (string) - The CloudStack API endpoint we will connect to.
-- `api_key` (string) - The API key used to sign all API requests.
+- `api_key` (string) - The API key used to sign all API requests.
-- `cidr_list` (array) - List of CIDR's that will have access to the new
+- `cidr_list` (array) - List of CIDR's that will have access to the new
instance. This is needed in order for any provisioners to be able to
connect to the instance. Usually this will be the NAT address of your
current location. Only required when `use_local_ip_address` is `false`.
-- `instance_name` (string) - The name of the instance. Defaults to
+- `instance_name` (string) - The name of the instance. Defaults to
"packer-UUID" where UUID is dynamically generated.
-- `network` (string) - The name or ID of the network to connect the instance
+- `network` (string) - The name or ID of the network to connect the instance
to.
-- `secret_key` (string) - The secret key used to sign all API requests.
+- `secret_key` (string) - The secret key used to sign all API requests.
-- `service_offering` (string) - The name or ID of the service offering used
+- `service_offering` (string) - The name or ID of the service offering used
for the instance.
-- `soure_iso` (string) - The name or ID of an ISO that will be mounted before
+- `soure_iso` (string) - The name or ID of an ISO that will be mounted before
booting the instance. This option is mutual exclusive with `source_template`.
-- `source_template` (string) - The name or ID of the template used as base
+- `source_template` (string) - The name or ID of the template used as base
template for the instance. This option is mutual explusive with `source_iso`.
-- `template_name` (string) - The name of the new template. Defaults to
+- `template_name` (string) - The name of the new template. Defaults to
"packer-{{timestamp}}" where timestamp will be the current time.
-- `template_display_text` (string) - The display text of the new template.
+- `template_display_text` (string) - The display text of the new template.
Defaults to the `template_name`.
-- `template_os` (string) - The name or ID of the template OS for the new
+- `template_os` (string) - The name or ID of the template OS for the new
template that will be created.
-- `zone` (string) - The name or ID of the zone where the instance will be
+- `zone` (string) - The name or ID of the zone where the instance will be
created.
### Optional:
-- `async_timeout` (int) - The time duration to wait for async calls to
+- `async_timeout` (int) - The time duration to wait for async calls to
finish. Defaults to 30m.
-- `disk_offering` (string) - The name or ID of the disk offering used for the
+- `disk_offering` (string) - The name or ID of the disk offering used for the
instance. This option is only available (and also required) when using
`source_iso`.
-- `disk_size` (int) - The size (in GB) of the root disk of the new instance.
+- `disk_size` (int) - The size (in GB) of the root disk of the new instance.
This option is only available when using `source_template`.
-- `http_get_only` (boolean) - Some cloud providers only allow HTTP GET calls to
+- `http_get_only` (boolean) - Some cloud providers only allow HTTP GET calls to
their CloudStack API. If using such a provider, you need to set this to `true`
in order for the provider to only make GET calls and no POST calls.
-- `hypervisor` (string) - The target hypervisor (e.g. `XenServer`, `KVM`) for
+- `hypervisor` (string) - The target hypervisor (e.g. `XenServer`, `KVM`) for
the new template. This option is required when using `source_iso`.
-- `keypair` (string) - The name of the SSH key pair that will be used to
+- `keypair` (string) - The name of the SSH key pair that will be used to
access the instance. The SSH key pair is assumed to be already available
within CloudStack.
-- `project` (string) - The name or ID of the project to deploy the instance to.
+- `project` (string) - The name or ID of the project to deploy the instance to.
-- `public_ip_address` (string) - The public IP address or it's ID used for
+- `public_ip_address` (string) - The public IP address or it's ID used for
connecting any provisioners to. If not provided, a temporary public IP
address will be associated and released during the Packer run.
-- `ssl_no_verify` (boolean) - Set to `true` to skip SSL verification. Defaults
+- `ssl_no_verify` (boolean) - Set to `true` to skip SSL verification. Defaults
to `false`.
-- `template_featured` (boolean) - Set to `true` to indicate that the template
+- `template_featured` (boolean) - Set to `true` to indicate that the template
is featured. Defaults to `false`.
-- `template_public` (boolean) - Set to `true` to indicate that the template is
+- `template_public` (boolean) - Set to `true` to indicate that the template is
available for all accounts. Defaults to `false`.
-- `template_password_enabled` (boolean) - Set to `true` to indicate the template
+- `template_password_enabled` (boolean) - Set to `true` to indicate the template
should be password enabled. Defaults to `false`.
-- `template_requires_hvm` (boolean) - Set to `true` to indicate the template
+- `template_requires_hvm` (boolean) - Set to `true` to indicate the template
requires hardware-assisted virtualization. Defaults to `false`.
-- `template_scalable` (boolean) - Set to `true` to indicate that the template
+- `template_scalable` (boolean) - Set to `true` to indicate that the template
contains tools to support dynamic scaling of VM cpu/memory. Defaults to `false`.
-- `user_data` (string) - User data to launch with the instance.
+- `user_data` (string) - User data to launch with the instance.
-- `use_local_ip_address` (boolean) - Set to `true` to indicate that the
+- `use_local_ip_address` (boolean) - Set to `true` to indicate that the
provisioners should connect to the local IP address of the instance.
## Basic Example
Here is a basic example.
-``` {.javascript}
+```json
{
"type": "cloudstack",
"api_url": "https://cloudstack.company.com/client/api",
@@ -134,7 +135,7 @@ Here is a basic example.
"secret_key": "YOUR_SECRET_KEY",
"disk_offering": "Small - 20GB",
- "cidr_list": ["0.0.0.0/0"]
+ "cidr_list": ["0.0.0.0/0"],
"hypervisor": "KVM",
"network": "management",
"service_offering": "small",
diff --git a/website/source/docs/builders/custom.html.md b/website/source/docs/builders/custom.html.md
index dc6928d4b..64439ebc0 100644
--- a/website/source/docs/builders/custom.html.md
+++ b/website/source/docs/builders/custom.html.md
@@ -1,15 +1,16 @@
---
-description: |
- Packer is extensible, allowing you to write new builders without having to
- modify the core source code of Packer itself. Documentation for creating new
- builders is covered in the custom builders page of the Packer plugin section.
layout: docs
-page_title: Custom Builder
-...
+sidebar_current: docs-builders-custom
+page_title: Custom - Builders
+description: |-
+ Packer is extensible, allowing you to write new builders without having to
+ modify the core source code of Packer itself. Documentation for creating new
+ builders is covered in the custom builders page of the Packer plugin section.
+---
# Custom Builder
Packer is extensible, allowing you to write new builders without having to
modify the core source code of Packer itself. Documentation for creating new
-builders is covered in the [custom builders](/docs/extend/builder.html) page of
+builders is covered in the [custom builders](/docs/extending/custom-builders.html) page of
the Packer plugin section.
diff --git a/website/source/docs/builders/digitalocean.html.md b/website/source/docs/builders/digitalocean.html.md
index c8ce84f39..16d748135 100644
--- a/website/source/docs/builders/digitalocean.html.md
+++ b/website/source/docs/builders/digitalocean.html.md
@@ -1,13 +1,15 @@
---
-description: |
- The `digitalocean` Packer builder is able to create new images for use with
- DigitalOcean. The builder takes a source image, runs any provisioning necessary
- on the image after launching it, then snapshots it into a reusable image. This
- reusable image can then be used as the foundation of new servers that are
- launched within DigitalOcean.
layout: docs
-page_title: DigitalOcean Builder
-...
+sidebar_current: docs-builders-digitalocean
+page_title: DigitalOcean - Builders
+description: |-
+ The digitalocean Packer builder is able to create new images for use with
+ DigitalOcean. The builder takes a source image, runs any provisioning
+ necessary on the image after launching it, then snapshots it into a reusable
+ image. This reusable image can then be used as the foundation of new servers
+ that are launched within DigitalOcean.
+---
+
# DigitalOcean Builder
@@ -34,48 +36,48 @@ builder.
### Required:
-- `api_token` (string) - The client TOKEN to use to access your account. It
+- `api_token` (string) - The client TOKEN to use to access your account. It
can also be specified via environment variable `DIGITALOCEAN_API_TOKEN`,
if set.
-- `image` (string) - The name (or slug) of the base image to use. This is the
+- `image` (string) - The name (or slug) of the base image to use. This is the
image that will be used to launch a new droplet and provision it. See
[https://developers.digitalocean.com/documentation/v2/\#list-all-images](https://developers.digitalocean.com/documentation/v2/#list-all-images) for
details on how to get a list of the accepted image names/slugs.
-- `region` (string) - The name (or slug) of the region to launch the
+- `region` (string) - The name (or slug) of the region to launch the
droplet in. Consequently, this is the region where the snapshot will
be available. See
[https://developers.digitalocean.com/documentation/v2/\#list-all-regions](https://developers.digitalocean.com/documentation/v2/#list-all-regions) for
the accepted region names/slugs.
-- `size` (string) - The name (or slug) of the droplet size to use. See
+- `size` (string) - The name (or slug) of the droplet size to use. See
[https://developers.digitalocean.com/documentation/v2/\#list-all-sizes](https://developers.digitalocean.com/documentation/v2/#list-all-sizes) for
the accepted size names/slugs.
### Optional:
-- `api_url` (string) - Non standard api endpoint URL. Set this if you are
+- `api_url` (string) - Non standard api endpoint URL. Set this if you are
using a DigitalOcean API compatible service. It can also be specified via
environment variable `DIGITALOCEAN_API_URL`.
-- `droplet_name` (string) - The name assigned to the droplet. DigitalOcean
+- `droplet_name` (string) - The name assigned to the droplet. DigitalOcean
sets the hostname of the machine to this value.
-- `private_networking` (boolean) - Set to `true` to enable private networking
+- `private_networking` (boolean) - Set to `true` to enable private networking
for the droplet being created. This defaults to `false`, or not enabled.
-- `snapshot_name` (string) - The name of the resulting snapshot that will
+- `snapshot_name` (string) - The name of the resulting snapshot that will
appear in your account. This must be unique. To help make this unique, use a
function like `timestamp` (see [configuration
templates](/docs/templates/configuration-templates.html) for more info)
-- `state_timeout` (string) - The time to wait, as a duration string, for a
+- `state_timeout` (string) - The time to wait, as a duration string, for a
droplet to enter a desired state (such as "active") before timing out. The
default state timeout is "6m".
-- `user_data` (string) - User data to launch with the Droplet.
-- `user_data_file` (string) - Path to a file that will be used for the user
+- `user_data` (string) - User data to launch with the Droplet.
+- `user_data_file` (string) - Path to a file that will be used for the user
data when launching the Droplet.
@@ -84,7 +86,7 @@ builder.
Here is a basic example. It is completely valid as soon as you enter your own
access tokens:
-``` {.javascript}
+```json
{
"type": "digitalocean",
"api_token": "YOUR API KEY",
diff --git a/website/source/docs/builders/docker.html.md b/website/source/docs/builders/docker.html.md
index 8959d6ba0..ea37b66fc 100644
--- a/website/source/docs/builders/docker.html.md
+++ b/website/source/docs/builders/docker.html.md
@@ -1,11 +1,12 @@
---
-description: |
- The `docker` Packer builder builds Docker images using Docker. The builder
- starts a Docker container, runs provisioners within this container, then exports
- the container for reuse or commits the image.
layout: docs
-page_title: Docker Builder
-...
+sidebar_current: docs-builders-docker
+page_title: Docker - Builders
+description: |-
+ The docker Packer builder builds Docker images using Docker. The builder
+ starts a Docker container, runs provisioners within this container, then
+ exports the container for reuse or commits the image.
+---
# Docker Builder
@@ -34,7 +35,7 @@ Packer within that environment.
Below is a fully functioning example. It doesn't do anything useful, since no
provisioners are defined, but it will effectively repackage an image.
-``` {.javascript}
+```json
{
"type": "docker",
"image": "ubuntu",
@@ -48,7 +49,7 @@ Below is another example, the same as above but instead of exporting the running
container, this one commits the container to an image. The image can then be
more easily tagged, pushed, etc.
-``` {.javascript}
+```json
{
"type": "docker",
"image": "ubuntu",
@@ -62,51 +63,51 @@ Below is an example using the changes argument of the builder. This feature allo
Example uses of all of the options, assuming one is building an NGINX image from ubuntu as an simple example:
-```
+```json
{
- "type": "docker",
- "image": "ubuntu",
- "commit": true,
- "changes": [
- "USER www-data",
- "WORKDIR /var/www",
- "ENV HOSTNAME www.example.com",
- "VOLUME /test1 /test2",
- "EXPOSE 80 443",
- "CMD [\"nginx\", \"-g\", \"daemon off;\"]",
- "MAINTAINER Captain Kirk",
- "ENTRYPOINT /var/www/start.sh"
- ]
+ "type": "docker",
+ "image": "ubuntu",
+ "commit": true,
+ "changes": [
+ "USER www-data",
+ "WORKDIR /var/www",
+ "ENV HOSTNAME www.example.com",
+ "VOLUME /test1 /test2",
+ "EXPOSE 80 443",
+ "CMD [\"nginx\", \"-g\", \"daemon off;\"]",
+ "MAINTAINER Captain Kirk",
+ "ENTRYPOINT /var/www/start.sh"
+ ]
}
```
Allowed metadata fields that can be changed are:
-- CMD
- - String, supports both array (escaped) and string form
- - EX: `"CMD [\"nginx\", \"-g\", \"daemon off;\"]"`
- - EX: `"CMD nginx -g daemon off;"`
-- ENTRYPOINT
- - String
- - EX: `"ENTRYPOINT /var/www/start.sh"`
-- ENV
- - String, note there is no equal sign:
- - EX: `"ENV HOSTNAME www.example.com"` not `"ENV HOSTNAME=www.example.com"`
-- EXPOSE
- - String, space separated ports
- - EX: `"EXPOSE 80 443"`
-- MAINTAINER
- - String
- - EX: `"MAINTAINER NAME"`
-- USER
- - String
- - EX: `"USER USERNAME"`
-- VOLUME
- - String
- - EX: `"VOLUME FROM TO"`
-- WORKDIR
- - String
- - EX: `"WORKDIR PATH"`
+- `CMD`
+ - String, supports both array (escaped) and string form
+ - EX: `”CMD [\"nginx\", \"-g\", \"daemon off;\"]"`
+ - EX: `"CMD nginx -g daemon off;”`
+- `ENTRYPOINT`
+ - String
+ - EX: `“ENTRYPOINT /var/www/start.sh”`
+- `ENV`
+ - String, note there is no equal sign:
+ - EX: `“ENV HOSTNAME www.example.com”` not `“ENV HOSTNAME=www.example.com”`
+- `EXPOSE`
+ - String, space separated ports
+ - EX: `“EXPOSE 80 443”`
+- `MAINTAINER`
+ - String
+ - EX: `“MAINTAINER NAME”`
+- `USER`
+ - String
+ - EX: `“USER USERNAME”`
+- `VOLUME`
+ - String
+ - EX: `“VOLUME FROM TO“`
+- `WORKDIR`
+ - String
+ - EX: `“WORKDIR PATH”`
## Configuration Reference
@@ -122,40 +123,40 @@ builder.
You must specify (only) one of `commit`, `discard`, or `export_path`.
-- `commit` (boolean) - If true, the container will be committed to an image
+- `commit` (boolean) - If true, the container will be committed to an image
rather than exported.
-- `discard` (boolean) - Throw away the container when the build is complete.
+- `discard` (boolean) - Throw away the container when the build is complete.
This is useful for the [artifice
post-processor](https://www.packer.io/docs/post-processors/artifice.html).
-- `export_path` (string) - The path where the final container will be exported
+- `export_path` (string) - The path where the final container will be exported
as a tar file.
-- `image` (string) - The base image for the Docker container that will
+- `image` (string) - The base image for the Docker container that will
be started. This image will be pulled from the Docker registry if it doesn't
already exist.
### Optional:
-- `author` (string) - Set the author (e-mail) of a commit.
+- `author` (string) - Set the author (e-mail) of a commit.
-- `aws_access_key` (string) - The AWS access key used to communicate with AWS.
+- `aws_access_key` (string) - The AWS access key used to communicate with AWS.
[Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `aws_secret_key` (string) - The AWS secret key used to communicate with AWS.
+- `aws_secret_key` (string) - The AWS secret key used to communicate with AWS.
[Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
-- `aws_token` (string) - The AWS access token to use. This is different from the
+- `aws_token` (string) - The AWS access token to use. This is different from the
access key and secret key. If you're not sure what this is, then you
probably don't need it. This will also be read from the `AWS_SESSION_TOKEN`
environmental variable.
-- `changes` (array of strings) - Dockerfile instructions to add to the commit.
+- `changes` (array of strings) - Dockerfile instructions to add to the commit.
Example of instructions are `CMD`, `ENTRYPOINT`, `ENV`, and `EXPOSE`. Example:
`[ "USER ubuntu", "WORKDIR /app", "EXPOSE 8080" ]`
-- `ecr_login` (boolean) - Defaults to false. If true, the builder will login in
+- `ecr_login` (boolean) - Defaults to false. If true, the builder will login in
order to pull the image from
[Amazon EC2 Container Registry (ECR)](https://aws.amazon.com/ecr/).
The builder only logs in for the duration of the pull. If true
@@ -163,33 +164,33 @@ You must specify (only) one of `commit`, `discard`, or `export_path`.
`login_password` will be ignored. For more information see the
[section on ECR](#amazon-ec2-container-registry).
-- `login` (boolean) - Defaults to false. If true, the builder will login in
+- `login` (boolean) - Defaults to false. If true, the builder will login in
order to pull the image. The builder only logs in for the duration of
the pull. It always logs out afterwards. For log into ECR see `ecr_login`.
-- `login_email` (string) - The email to use to authenticate to login.
+- `login_email` (string) - The email to use to authenticate to login.
-- `login_username` (string) - The username to use to authenticate to login.
+- `login_username` (string) - The username to use to authenticate to login.
-- `login_password` (string) - The password to use to authenticate to login.
+- `login_password` (string) - The password to use to authenticate to login.
-- `login_server` (string) - The server address to login to.
+- `login_server` (string) - The server address to login to.
-- `message` (string) - Set a message for the commit.
+- `message` (string) - Set a message for the commit.
-- `privileged` (boolean) - If true, run the docker container with the
+- `privileged` (boolean) - If true, run the docker container with the
`--privileged` flag. This defaults to false if not set.
-- `pull` (boolean) - If true, the configured image will be pulled using
+- `pull` (boolean) - If true, the configured image will be pulled using
`docker pull` prior to use. Otherwise, it is assumed the image already
exists and can be used. This defaults to true if not set.
-- `run_command` (array of strings) - An array of arguments to pass to
+- `run_command` (array of strings) - An array of arguments to pass to
`docker run` in order to run the container. By default this is set to
`["-d", "-i", "-t", "{{.Image}}", "/bin/bash"]`. As you can see, you have a
couple template variables to customize, as well.
-- `volumes` (map of strings to strings) - A mapping of additional volumes to
+- `volumes` (map of strings to strings) - A mapping of additional volumes to
mount into this container. The key of the object is the host path, the value
is the container path.
@@ -209,7 +210,7 @@ created image. This is accomplished using a sequence definition (a collection of
post-processors that are treated as as single pipeline, see
[Post-Processors](/docs/templates/post-processors.html) for more information):
-``` {.javascript}
+```json
{
"post-processors": [
[
@@ -233,7 +234,7 @@ pushing the image to a container repository.
If you want to do this manually, however, perhaps from a script, you can import
the image using the process below:
-``` {.text}
+```shell
$ docker import - registry.mydomain.com/mycontainer:latest < artifact.tar
```
@@ -248,7 +249,7 @@ which tags and pushes an image. This is accomplished using a sequence definition
(a collection of post-processors that are treated as as single pipeline, see
[Post-Processors](/docs/templates/post-processors.html) for more information):
-``` {.javascript}
+```json
{
"post-processors": [
[
@@ -273,7 +274,7 @@ Going a step further, if you wanted to tag and push an image to multiple
container repositories, this could be accomplished by defining two,
nearly-identical sequence definitions, as demonstrated by the example below:
-``` {.javascript}
+```json
{
"post-processors": [
[
@@ -305,7 +306,7 @@ Packer can tag and push images for use in
processors work as described above and example configuration properties are
shown below:
-``` {.javascript}
+```json
{
"post-processors": [
[
@@ -346,11 +347,11 @@ Dockerfiles have some additional features that Packer doesn't support which are
able to be worked around. Many of these features will be automated by Packer in
the future:
-- Dockerfiles will snapshot the container at each step, allowing you to go
+- Dockerfiles will snapshot the container at each step, allowing you to go
back to any step in the history of building. Packer doesn't do this yet, but
inter-step snapshotting is on the way.
-- Dockerfiles can contain information such as exposed ports, shared volumes,
+- Dockerfiles can contain information such as exposed ports, shared volumes,
and other metadata. Packer builds a raw Docker container image that has none
of this metadata. You can pass in much of this metadata at runtime with
`docker run`.
diff --git a/website/source/docs/builders/file.html.md b/website/source/docs/builders/file.html.md
index dc73c4016..cd2fa39b7 100644
--- a/website/source/docs/builders/file.html.md
+++ b/website/source/docs/builders/file.html.md
@@ -1,11 +1,12 @@
---
-description: |
- The `file` Packer builder is not really a builder, it just creates an
- artifact from a file. It can be used to debug post-processors without
- incurring high wait times. It does not run any provisioners.
layout: docs
-page_title: File Builder
-...
+sidebar_current: docs-builders-file
+page_title: File - Builders
+description: |-
+ The file Packer builder is not really a builder, it just creates an artifact
+ from a file. It can be used to debug post-processors without incurring high
+ wait times. It does not run any provisioners.
+---
# File Builder
@@ -20,11 +21,11 @@ wait times. It does not run any provisioners.
Below is a fully functioning example. It doesn't do anything useful, since no
provisioners are defined, but it will connect to the specified host via ssh.
-``` {.javascript}
+```json
{
- "type": "file",
- "content": "Lorem ipsum dolor sit amet",
- "target": "dummy_artifact"
+ "type": "file",
+ "content": "Lorem ipsum dolor sit amet",
+ "target": "dummy_artifact"
}
```
@@ -38,7 +39,7 @@ Any [communicator](/docs/templates/communicator.html) defined is ignored.
### Required:
-- `target` (string) - The path for a file which will be copied as the
+- `target` (string) - The path for a file which will be copied as the
artifact.
### Optional:
@@ -46,7 +47,7 @@ Any [communicator](/docs/templates/communicator.html) defined is ignored.
You can only define one of `source` or `content`. If none of them is
defined the artifact will be empty.
-- `source` (string) - The path for a file which will be copied as the
+- `source` (string) - The path for a file which will be copied as the
artifact.
-- `content` (string) - The content that will be put into the artifact.
+- `content` (string) - The content that will be put into the artifact.
diff --git a/website/source/docs/builders/googlecompute.html.md b/website/source/docs/builders/googlecompute.html.md
index bbfc4dcc7..dad9850ad 100644
--- a/website/source/docs/builders/googlecompute.html.md
+++ b/website/source/docs/builders/googlecompute.html.md
@@ -1,12 +1,11 @@
---
-description: |
- The `googlecompute` Packer builder is able to create images for use with Google
- Compute Engine (GCE) based on existing images. Building GCE images from scratch
- is not possible from Packer at this time. For building images from scratch, please see
- [Building GCE Images from Scratch](https://cloud.google.com/compute/docs/tutorials/building-images).
layout: docs
-page_title: Google Compute Builder
-...
+sidebar_current: docs-builders-googlecompute
+page_title: Google Compute - Builders
+description: |-
+ The googlecompute Packer builder is able to create images for use with
+ Google Cloud Compute Engine (GCE) based on existing images.
+---
# Google Compute Builder
@@ -39,18 +38,17 @@ scopes when launching the instance.
For `gcloud`, do this via the `--scopes` parameter:
-``` {.sh}
-gcloud compute --project YOUR_PROJECT instances create "INSTANCE-NAME" ... \
- --scopes "https://www.googleapis.com/auth/compute,https://www.googleapis.com/auth/devstorage.full_control" \
- ...
+```shell
+$ gcloud compute --project YOUR_PROJECT instances create "INSTANCE-NAME" ... \
+ --scopes "https://www.googleapis.com/auth/compute,https://www.googleapis.com/auth/devstorage.full_control" \
```
For the [Google Developers Console](https://console.developers.google.com):
-1. Choose "Show advanced options"
-2. Tick "Enable Compute Engine service account"
-3. Choose "Read Write" for Compute
-4. Chose "Full" for "Storage"
+1. Choose "Show advanced options"
+1. Tick "Enable Compute Engine service account"
+1. Choose "Read Write" for Compute
+1. Chose "Full" for "Storage"
**The service account will be used automatically by Packer as long as there is
no *account file* specified in the Packer configuration file.**
@@ -62,32 +60,40 @@ you to create and download a credential file that will let you use the
`googlecompute` Packer builder anywhere. To make the process more
straightforwarded, it is documented here.
-1. Log into the [Google Developers
+1. Log into the [Google Developers
Console](https://console.developers.google.com) and select a project.
-2. Under the "APIs & Auth" section, click "Credentials."
+1. Under the "APIs & Auth" section, click "Credentials."
-3. Click the "Create new Client ID" button, select "Service account", and click
+1. Click the "Create new Client ID" button, select "Service account", and click
"Create Client ID"
-4. Click "Generate new JSON key" for the Service Account you just created. A
+1. Click "Generate new JSON key" for the Service Account you just created. A
JSON file will be downloaded automatically. This is your *account file*.
### Precedence of Authentication Methods
Packer looks for credentials in the following places, preferring the first location found:
-1. A `account_file` option in your packer file.
+1. A `account_file` option in your packer file.
-2. A JSON file (Service Account) whose path is specified by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
+1. A JSON file (Service Account) whose path is specified by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
-3. A JSON file in a location known to the `gcloud` command-line tool. (`gcloud` creates it when it's configured)
+1. A JSON file in a location known to the `gcloud` command-line tool. (`gcloud` creates it when it's configured)
- On Windows, this is: `%APPDATA%/gcloud/application_default_credentials.json`.
+ On Windows, this is:
- On other systems: `$HOME/.config/gcloud/application_default_credentials.json`.
+ ```
+ %APPDATA%/gcloud/application_default_credentials.json
+ ```
-4. On Google Compute Engine and Google App Engine Managed VMs, it fetches credentials from the metadata server. (Needs a correct VM authentication scope configuration, see above)
+ On other systems:
+
+ ```
+ $HOME/.config/gcloud/application_default_credentials.json
+ ```
+
+1. On Google Compute Engine and Google App Engine Managed VMs, it fetches credentials from the metadata server. (Needs a correct VM authentication scope configuration, see above)
## Basic Example
@@ -97,15 +103,17 @@ repackage an existing GCE image. The account_file is obtained in the previous
section. If it parses as JSON it is assumed to be the file itself, otherwise it
is assumed to be the path to the file containing the JSON.
-``` {.json}
+```json
{
- "builders": [{
- "type": "googlecompute",
- "account_file": "account.json",
- "project_id": "my project",
- "source_image": "debian-7-wheezy-v20150127",
- "zone": "us-central1-a"
- }]
+ "builders": [
+ {
+ "type": "googlecompute",
+ "account_file": "account.json",
+ "project_id": "my project",
+ "source_image": "debian-7-wheezy-v20150127",
+ "zone": "us-central1-a"
+ }
+ ]
}
```
@@ -147,104 +155,106 @@ builder.
### Required:
-- `project_id` (string) - The project ID that will be used to launch instances
+- `project_id` (string) - The project ID that will be used to launch instances
and store images.
-- `source_image` (string) - The source image to use to create the new image
+- `source_image` (string) - The source image to use to create the new image
from. You can also specify `source_image_family` instead. If both
`source_image` and `source_image_family` are specified, `source_image`
takes precedence. Example: `"debian-8-jessie-v20161027"`
-- `source_image_family` (string) - The source image family to use to create
+- `source_image_family` (string) - The source image family to use to create
the new image from. The image family always returns its latest image that
is not deprecated. Example: `"debian-8"`.
-- `zone` (string) - The zone in which to launch the instance used to create
+- `zone` (string) - The zone in which to launch the instance used to create
the image. Example: `"us-central1-a"`
### Optional:
-- `account_file` (string) - The JSON file containing your account credentials.
+- `account_file` (string) - The JSON file containing your account credentials.
Not required if you run Packer on a GCE instance with a service account.
Instructions for creating file or using service accounts are above.
-- `address` (string) - The name of a pre-allocated static external IP address.
+- `address` (string) - The name of a pre-allocated static external IP address.
Note, must be the name and not the actual IP address.
-- `disk_name` (string) - The name of the disk, if unset the instance name will be
+- `disk_name` (string) - The name of the disk, if unset the instance name will be
used.
-- `disk_size` (integer) - The size of the disk in GB. This defaults to `10`,
+- `disk_size` (integer) - The size of the disk in GB. This defaults to `10`,
which is 10GB.
-- `disk_type` (string) - Type of disk used to back your instance, like `pd-ssd` or `pd-standard`. Defaults to `pd-standard`.
+- `disk_type` (string) - Type of disk used to back your instance, like `pd-ssd` or `pd-standard`. Defaults to `pd-standard`.
-- `image_description` (string) - The description of the resulting image.
+- `image_description` (string) - The description of the resulting image.
-- `image_family` (string) - The name of the image family to which the
+- `image_family` (string) - The name of the image family to which the
resulting image belongs. You can create disks by specifying an image family
instead of a specific image name. The image family always returns its
latest image that is not deprecated.
-- `image_name` (string) - The unique name of the resulting image. Defaults to
+- `image_name` (string) - The unique name of the resulting image. Defaults to
`"packer-{{timestamp}}"`.
-- `instance_name` (string) - A name to give the launched instance. Beware that
+- `instance_name` (string) - A name to give the launched instance. Beware that
this must be unique. Defaults to `"packer-{{uuid}}"`.
-- `machine_type` (string) - The machine type. Defaults to `"n1-standard-1"`.
+- `machine_type` (string) - The machine type. Defaults to `"n1-standard-1"`.
-- `metadata` (object of key/value strings) - Metadata applied to the launched
+- `metadata` (object of key/value strings) - Metadata applied to the launched
instance.
-- `network` (string) - The Google Compute network to use for the
+- `network` (string) - The Google Compute network to use for the
launched instance. Defaults to `"default"`.
-- `network_project_id` (string) - The project ID for the network and subnetwork
+- `network_project_id` (string) - The project ID for the network and subnetwork
to use for launched instance. Defaults to `project_id`.
-- `omit_external_ip` (boolean) - If true, the instance will not have an external IP.
+- `omit_external_ip` (boolean) - If true, the instance will not have an external IP.
`use_internal_ip` must be true if this property is true.
-- `on_host_maintenance` (string) - Sets Host Maintenance Option. Valid
+- `on_host_maintenance` (string) - Sets Host Maintenance Option. Valid
choices are `MIGRATE` and `TERMINATE`. Please see [GCE Instance Scheduling
Options](https://cloud.google.com/compute/docs/instances/setting-instance-scheduling-options),
as not all machine_types support `MIGRATE` (i.e. machines with GPUs).
If preemptible is true this can only be `TERMINATE`. If preemptible
is false, it defaults to `MIGRATE`
-- `preemptible` (boolean) - If true, launch a preembtible instance.
+- `preemptible` (boolean) - If true, launch a preembtible instance.
-- `region` (string) - The region in which to launch the instance. Defaults to
+- `region` (string) - The region in which to launch the instance. Defaults to
to the region hosting the specified `zone`.
-- `scopes` (array of strings) - The service account scopes for launched instance.
+- `scopes` (array of strings) - The service account scopes for launched instance.
Defaults to:
-``` {.json}
-[ "https://www.googleapis.com/auth/userinfo.email",
- "https://www.googleapis.com/auth/compute",
- "https://www.googleapis.com/auth/devstorage.full_control" ]
-```
+ ```json
+ [
+ "https://www.googleapis.com/auth/userinfo.email",
+ "https://www.googleapis.com/auth/compute",
+ "https://www.googleapis.com/auth/devstorage.full_control"
+ ]
+ ```
-- `source_image_project_id` (string) - The project ID of the
+- `source_image_project_id` (string) - The project ID of the
project containing the source image.
-- `startup_script_file` (string) - The filepath to a startup script to run on
+- `startup_script_file` (string) - The filepath to a startup script to run on
the VM from which the image will be made.
-- `state_timeout` (string) - The time to wait for instance state changes.
+- `state_timeout` (string) - The time to wait for instance state changes.
Defaults to `"5m"`.
-- `subnetwork` (string) - The Google Compute subnetwork to use for the launched
+- `subnetwork` (string) - The Google Compute subnetwork to use for the launched
instance. Only required if the `network` has been created with custom
subnetting.
Note, the region of the subnetwork must match the `region` or `zone` in
which the VM is launched.
-- `tags` (array of strings)
+- `tags` (array of strings)
-- `use_internal_ip` (boolean) - If true, use the instance's internal IP
+- `use_internal_ip` (boolean) - If true, use the instance's internal IP
instead of its external IP during building.
## Startup Scripts
diff --git a/website/source/docs/builders/hyperv-iso.html.md b/website/source/docs/builders/hyperv-iso.html.md
index 08cb732a4..d45071cd3 100644
--- a/website/source/docs/builders/hyperv-iso.html.md
+++ b/website/source/docs/builders/hyperv-iso.html.md
@@ -1,8 +1,10 @@
---
+layout: docs
+sidebar_current: docs-builders-hyperv-iso
+page_title: Hyper-V ISO - Builders
description: |-
- The Hyper-V Packer builder is able to create Hyper-V virtual machines and export them.
-layout: "docs"
-page_title: "Hyper-V Builder (from an ISO)"
+ The Hyper-V Packer builder is able to create Hyper-V virtual machines and
+ export them.
---
# Hyper-V Builder (from an ISO)
@@ -23,7 +25,7 @@ Here is a basic example. This example is not functional. It will start the
OS installer but then fail because we don't provide the preseed file for
Ubuntu to self-install. Still, the example serves to show the basic configuration:
-```javascript
+```json
{
"type": "hyperv-iso",
"iso_url": "http://releases.ubuntu.com/12.04/ubuntu-12.04.5-server-amd64.iso",
@@ -51,78 +53,78 @@ can be configured for this builder.
### Required:
-- `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO
+- `iso_checksum` (string) - The checksum for the OS ISO file. Because ISO
files are so large, this is required and Packer will verify it prior
to booting a virtual machine with the ISO attached. The type of the
checksum is specified with `iso_checksum_type`, documented below.
-- `iso_checksum_type` (string) - The type of the checksum specified in
+- `iso_checksum_type` (string) - The type of the checksum specified in
`iso_checksum`. Valid values are "none", "md5", "sha1", "sha256", or
"sha512" currently. While "none" will skip checksumming, this is not
recommended since ISO files are generally large and corruption does happen
from time to time.
-- `iso_url` (string) - A URL to the ISO containing the installation image.
+- `iso_url` (string) - A URL to the ISO containing the installation image.
This URL can be either an HTTP URL or a file URL (or path to a file).
If this is an HTTP URL, Packer will download iso and cache it between
runs.
### Optional:
-- `boot_command` (array of strings) - This is an array of commands to type
+- `boot_command` (array of strings) - This is an array of commands to type
when the virtual machine is first booted. The goal of these commands should
be to type just enough to initialize the operating system installer. Special
keys can be typed as well, and are covered in the section below on the boot
command. If this is not specified, it is assumed the installer will start
itself.
-- `boot_wait` (string) - The time to wait after booting the initial virtual
+- `boot_wait` (string) - The time to wait after booting the initial virtual
machine before typing the `boot_command`. The value of this should be
a duration. Examples are "5s" and "1m30s" which will cause Packer to wait
five seconds and one minute 30 seconds, respectively. If this isn't specified,
the default is 10 seconds.
-- `cpu` (integer) - The number of cpus the virtual machine should use. If this isn't specified,
+- `cpu` (integer) - The number of cpus the virtual machine should use. If this isn't specified,
the default is 1 cpu.
-- `disk_size` (integer) - The size, in megabytes, of the hard disk to create
+- `disk_size` (integer) - The size, in megabytes, of the hard disk to create
for the VM. By default, this is 40 GB.
-- `enable_dynamic_memory` (bool) - If true enable dynamic memory for virtual machine.
+- `enable_dynamic_memory` (bool) - If true enable dynamic memory for virtual machine.
This defaults to false.
-- `enable_mac_spoofing` (bool) - If true enable mac spoofing for virtual machine.
+- `enable_mac_spoofing` (bool) - If true enable mac spoofing for virtual machine.
This defaults to false.
-- `enable_secure_boot` (bool) - If true enable secure boot for virtual machine.
+- `enable_secure_boot` (bool) - If true enable secure boot for virtual machine.
This defaults to false.
-- `enable_virtualization_extensions` (bool) - If true enable virtualization extensions for virtual machine.
+- `enable_virtualization_extensions` (bool) - If true enable virtualization extensions for virtual machine.
This defaults to false. For nested virtualization you need to enable mac spoofing, disable dynamic memory
and have at least 4GB of RAM for virtual machine.
-- `floppy_files` (array of strings) - A list of files to place onto a floppy
+- `floppy_files` (array of strings) - A list of files to place onto a floppy
disk that is attached when the VM is booted. This is most useful
for unattended Windows installs, which look for an `Autounattend.xml` file
on removable media. By default, no floppy will be attached. All files
listed in this setting get placed into the root directory of the floppy
and the floppy is attached as the first floppy device. Currently, no
support exists for creating sub-directories on the floppy. Wildcard
- characters (*, ?, and []) are allowed. Directory names are also allowed,
+ characters (`*`, `?`, and `[]`) are allowed. Directory names are also allowed,
which will add all the files found in the directory to the floppy.
-- `generation` (integer) - The Hyper-V generation for the virtual machine. By
+- `generation` (integer) - The Hyper-V generation for the virtual machine. By
default, this is 1. Generation 2 Hyper-V virtual machines do not support
floppy drives. In this scenario use `secondary_iso_images` instead. Hard
- drives and dvd drives will also be scsi and not ide.
+ drives and dvd drives will also be scsi and not ide.
-- `guest_additions_mode` (string) - How should guest additions be installed.
+- `guest_additions_mode` (string) - How should guest additions be installed.
If value `attach` then attach iso image with by specified by `guest_additions_path`.
Otherwise guest additions is not installed.
-- `guest_additions_path` (string) - The path to the iso image for guest additions.
+- `guest_additions_path` (string) - The path to the iso image for guest additions.
-- `http_directory` (string) - Path to a directory to serve using an HTTP
+- `http_directory` (string) - Path to a directory to serve using an HTTP
server. The files in this directory will be available over HTTP that will
be requestable from the virtual machine. This is useful for hosting
kickstart files and so on. By default this is "", which means no HTTP
@@ -130,68 +132,68 @@ can be configured for this builder.
available as variables in `boot_command`. This is covered in more detail
below.
-- `http_port_min` and `http_port_max` (integer) - These are the minimum and
+- `http_port_min` and `http_port_max` (integer) - These are the minimum and
maximum port to use for the HTTP server started to serve the `http_directory`.
Because Packer often runs in parallel, Packer will choose a randomly available
port in this range to run the HTTP server. If you want to force the HTTP
server to be on one port, make this minimum and maximum port the same.
By default the values are 8000 and 9000, respectively.
-- `iso_urls` (array of strings) - Multiple URLs for the ISO to download.
+- `iso_urls` (array of strings) - Multiple URLs for the ISO to download.
Packer will try these in order. If anything goes wrong attempting to download
or while downloading a single URL, it will move on to the next. All URLs
must point to the same file (same checksum). By default this is empty
and `iso_url` is used. Only one of `iso_url` or `iso_urls` can be specified.
-- `iso_target_extension` (string) - The extension of the iso file after
+- `iso_target_extension` (string) - The extension of the iso file after
download. This defaults to "iso".
-- `iso_target_path` (string) - The path where the iso should be saved after
+- `iso_target_path` (string) - The path where the iso should be saved after
download. By default will go in the packer cache, with a hash of the
original filename as its name.
-- `output_directory` (string) - This is the path to the directory where the
+- `output_directory` (string) - This is the path to the directory where the
resulting virtual machine will be created. This may be relative or absolute.
If relative, the path is relative to the working directory when `packer`
is executed. This directory must not exist or be empty prior to running the builder.
By default this is "output-BUILDNAME" where "BUILDNAME" is the name
of the build.
-- `ram_size` (integer) - The size, in megabytes, of the ram to create
+- `ram_size` (integer) - The size, in megabytes, of the ram to create
for the VM. By default, this is 1 GB.
-* `secondary_iso_images` (array of strings) - A list of iso paths to attached to a
- VM when it is booted. This is most useful for unattended Windows installs, which
- look for an `Autounattend.xml` file on removable media. By default, no
- secondary iso will be attached.
+* `secondary_iso_images` (array of strings) - A list of iso paths to attached to a
+ VM when it is booted. This is most useful for unattended Windows installs, which
+ look for an `Autounattend.xml` file on removable media. By default, no
+ secondary iso will be attached.
-- `shutdown_command` (string) - The command to use to gracefully shut down the machine once all
+- `shutdown_command` (string) - The command to use to gracefully shut down the machine once all
the provisioning is done. By default this is an empty string, which tells Packer to just
forcefully shut down the machine unless a shutdown command takes place inside script so this may
safely be omitted. If one or more scripts require a reboot it is suggested to leave this blank
since reboots may fail and specify the final shutdown command in your last script.
-- `shutdown_timeout` (string) - The amount of time to wait after executing
+- `shutdown_timeout` (string) - The amount of time to wait after executing
the `shutdown_command` for the virtual machine to actually shut down.
If it doesn't shut down in this time, it is an error. By default, the timeout
is "5m", or five minutes.
-- `skip_compaction` (bool) - If true skip compacting the hard disk for virtual machine when
+- `skip_compaction` (bool) - If true skip compacting the hard disk for virtual machine when
exporting. This defaults to false.
-- `switch_name` (string) - The name of the switch to connect the virtual machine to. Be defaulting
+- `switch_name` (string) - The name of the switch to connect the virtual machine to. Be defaulting
this to an empty string, Packer will try to determine the switch to use by looking for
external switch that is up and running.
-- `switch_vlan_id` (string) - This is the vlan of the virtual switch's network card.
+- `switch_vlan_id` (string) - This is the vlan of the virtual switch's network card.
By default none is set. If none is set then a vlan is not set on the switch's network card.
If this value is set it should match the vlan specified in by `vlan_id`.
-- `vlan_id` (string) - This is the vlan of the virtual machine's network card for the new virtual
- machine. By default none is set. If none is set then vlans are not set on the virtual machine's
+- `vlan_id` (string) - This is the vlan of the virtual machine's network card for the new virtual
+ machine. By default none is set. If none is set then vlans are not set on the virtual machine's
network card.
-- `vm_name` (string) - This is the name of the virtual machine for the new virtual
+- `vm_name` (string) - This is the name of the virtual machine for the new virtual
machine, without the file extension. By default this is "packer-BUILDNAME",
where "BUILDNAME" is the name of the build.
@@ -211,47 +213,47 @@ to the machine, simulating a human actually typing the keyboard. There are
a set of special keys available. If these are in your boot command, they
will be replaced by the proper key:
-- `` - Backspace
+- `` - Backspace
-- `` - Delete
+- `` - Delete
-- `` and `` - Simulates an actual "enter" or "return" keypress.
+- `` and `` - Simulates an actual "enter" or "return" keypress.
-- `` - Simulates pressing the escape key.
+- `` - Simulates pressing the escape key.
-- `` - Simulates pressing the tab key.
+- `` - Simulates pressing the tab key.
-- `` - `` - Simulates pressing a function key.
+- `` - `` - Simulates pressing a function key.
-- `` `` `` `` - Simulates pressing an arrow key.
+- `` `` `` `` - Simulates pressing an arrow key.
-- `` - Simulates pressing the spacebar.
+- `` - Simulates pressing the spacebar.
-- `` - Simulates pressing the insert key.
+- `` - Simulates pressing the insert key.
-- `` `` - Simulates pressing the home and end keys.
+- `` `` - Simulates pressing the home and end keys.
-- `` `` - Simulates pressing the page up and page down keys.
+- `` `` - Simulates pressing the page up and page down keys.
-- `` `` - Simulates pressing the alt key.
+- `` `` - Simulates pressing the alt key.
-- `` `` - Simulates pressing the ctrl key.
+- `` `` - Simulates pressing the ctrl key.
-- `` `` - Simulates pressing the shift key.
+- `` `` - Simulates pressing the shift key.
-- `` `` - Simulates pressing and holding the alt key.
+- `` `` - Simulates pressing and holding the alt key.
-- `` `` - Simulates pressing and holding the ctrl key.
+- `` `` - Simulates pressing and holding the ctrl key.
-- `` `` - Simulates pressing and holding the shift key.
+- `` `` - Simulates pressing and holding the shift key.
-- `` `` - Simulates releasing a held alt key.
+- `` `` - Simulates releasing a held alt key.
-- `` `` - Simulates releasing a held ctrl key.
+- `` `` - Simulates releasing a held ctrl key.
-- `` `` - Simulates releasing a held shift key.
+- `` `` - Simulates releasing a held shift key.
-- `` `` `` - Adds a 1, 5 or 10 second pause before
+- `` `` `` - Adds a 1, 5 or 10 second pause before
sending any additional keys. This is useful if you have to generally wait
for the UI to update before typing more.
@@ -269,7 +271,7 @@ The available variables are:
Example boot command. This is actually a working boot command used to start
an Ubuntu 12.04 installer:
-```text
+```json
[
"",
"/install/vmlinuz noapic ",
@@ -290,20 +292,20 @@ for the version of Hyper-V that is running.
## Generation 1 vs Generation 2
-Floppy drives are no longer supported by generation 2 machines. This requires you to
+Floppy drives are no longer supported by generation 2 machines. This requires you to
take another approach when dealing with preseed or answer files. Two possible options
are using virtual dvd drives or using the built in web server.
-When dealing with Windows you need to enable UEFI drives for generation 2 virtual machines.
+When dealing with Windows you need to enable UEFI drives for generation 2 virtual machines.
## Creating iso from directory
-Programs like mkisofs can be used to create an iso from a directory.
+Programs like mkisofs can be used to create an iso from a directory.
There is a [windows version of mkisofs](http://opensourcepack.blogspot.co.uk/p/cdrtools.html).
Example powershell script. This is an actually working powershell script used to create a Windows answer iso:
-```text
+```powershell
$isoFolder = "answer-iso"
if (test-path $isoFolder){
remove-item $isoFolder -Force -Recurse
@@ -323,7 +325,7 @@ copy windows\common\win-updates.ps1 $isoFolder\
copy windows\common\run-sysprep.ps1 $isoFolder\
copy windows\common\run-sysprep.cmd $isoFolder\
-$textFile = "$isoFolder\Autounattend.xml"
+$textFile = "$isoFolder\Autounattend.xml"
$c = Get-Content -Encoding UTF8 $textFile
@@ -342,49 +344,52 @@ if (test-path $isoFolder){
Packer config:
-```javascript
+```json
{
"builders": [
- {
- "vm_name":"windows2012r2",
- "type": "hyperv-iso",
- "disk_size": 61440,
- "floppy_files": [],
- "secondary_iso_images": [
- "./windows/windows-2012R2-serverdatacenter-amd64/answer.iso"
- ],
- "http_directory": "./windows/common/http/",
- "boot_wait": "0s",
- "boot_command": [
- "aaa"
- ],
- "iso_url": "http://download.microsoft.com/download/6/2/A/62A76ABB-9990-4EFC-A4FE-C7D698DAEB96/9600.16384.WINBLUE_RTM.130821-1623_X64FRE_SERVER_EVAL_EN-US-IRM_SSS_X64FREE_EN-US_DV5.ISO",
- "iso_checksum_type": "md5",
- "iso_checksum": "458ff91f8abc21b75cb544744bf92e6a",
- "communicator":"winrm",
- "winrm_username": "vagrant",
- "winrm_password": "vagrant",
- "winrm_timeout" : "4h",
- "shutdown_command": "f:\\run-sysprep.cmd",
- "ram_size": 4096,
- "cpu": 4,
- "generation": 2,
- "switch_name":"LAN",
- "enable_secure_boot":true
- }],
- "provisioners": [{
- "type": "powershell",
- "elevated_user":"vagrant",
- "elevated_password":"vagrant",
- "scripts": [
- "./windows/common/install-7zip.ps1",
- "./windows/common/install-chef.ps1",
- "./windows/common/compile-dotnet-assemblies.ps1",
- "./windows/common/cleanup.ps1",
- "./windows/common/ultradefrag.ps1",
- "./windows/common/sdelete.ps1"
- ]
- }],
+ {
+ "vm_name":"windows2012r2",
+ "type": "hyperv-iso",
+ "disk_size": 61440,
+ "floppy_files": [],
+ "secondary_iso_images": [
+ "./windows/windows-2012R2-serverdatacenter-amd64/answer.iso"
+ ],
+ "http_directory": "./windows/common/http/",
+ "boot_wait": "0s",
+ "boot_command": [
+ "aaa"
+ ],
+ "iso_url": "http://download.microsoft.com/download/6/2/A/62A76ABB-9990-4EFC-A4FE-C7D698DAEB96/9600.16384.WINBLUE_RTM.130821-1623_X64FRE_SERVER_EVAL_EN-US-IRM_SSS_X64FREE_EN-US_DV5.ISO",
+ "iso_checksum_type": "md5",
+ "iso_checksum": "458ff91f8abc21b75cb544744bf92e6a",
+ "communicator":"winrm",
+ "winrm_username": "vagrant",
+ "winrm_password": "vagrant",
+ "winrm_timeout" : "4h",
+ "shutdown_command": "f:\\run-sysprep.cmd",
+ "ram_size": 4096,
+ "cpu": 4,
+ "generation": 2,
+ "switch_name":"LAN",
+ "enable_secure_boot":true
+ }
+ ],
+ "provisioners": [
+ {
+ "type": "powershell",
+ "elevated_user":"vagrant",
+ "elevated_password":"vagrant",
+ "scripts": [
+ "./windows/common/install-7zip.ps1",
+ "./windows/common/install-chef.ps1",
+ "./windows/common/compile-dotnet-assemblies.ps1",
+ "./windows/common/cleanup.ps1",
+ "./windows/common/ultradefrag.ps1",
+ "./windows/common/sdelete.ps1"
+ ]
+ }
+ ],
"post-processors": [
{
"type": "vagrant",
@@ -483,7 +488,7 @@ autounattend.xml:
4
- true
+ truePrimary
@@ -576,7 +581,7 @@ autounattend.xml:
truecache-proxy:3142
-Finish Setup cache proxy during installation -->
+Finish Setup cache proxy during installation -->
@@ -808,7 +813,7 @@ sysprep-unattend.xml:
-
diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md
index 004c3413e..b6ffa695c 100644
--- a/website/source/intro/getting-started/build-image.html.md
+++ b/website/source/intro/getting-started/build-image.html.md
@@ -1,15 +1,13 @@
---
-description: |
- With Packer installed, let's just dive right into it and build our first image.
- Our first image will be an Amazon EC2 AMI with Redis pre-installed. This is just
- an example. Packer can create images for many platforms with anything
- pre-installed.
layout: intro
-next_title: Provision
-next_url: '/intro/getting-started/provision.html'
-page_title: Build an Image
-prev_url: '/intro/getting-started/setup.html'
-...
+sidebar_current: intro-getting-started-build-image
+page_title: Build an Image - Getting Started
+description: |-
+ With Packer installed, let's just dive right into it and build our first
+ image. Our first image will be an Amazon EC2 AMI with Redis pre-installed.
+ This is just an example. Packer can create images for many platforms with
+ anything pre-installed.
+---
# Build an Image
@@ -24,7 +22,7 @@ qualifies under the AWS [free-tier](https://aws.amazon.com/free/), meaning it
will be free. If you already have an AWS account, you may be charged some amount
of money, but it shouldn't be more than a few cents.
--> **Note:** If you're not using an account that qualifies under the AWS
+-> **Note:** If you're not using an account that qualifies under the AWS
free-tier, you may be charged to run these examples. The charge should only be a
few cents, but we're not responsible if it ends up being more.
@@ -46,7 +44,7 @@ as machine generated templates to easily be made.
We'll start by creating the entire template, then we'll go over each section
briefly. Create a file `example.json` and fill it with the following contents:
-``` {.javascript}
+```json
{
"variables": {
"aws_access_key": "",
@@ -94,7 +92,7 @@ syntax as well as the configuration values to verify they look valid. The output
should look similar to below, because the template should be valid. If there are
any errors, this command will tell you.
-``` {.text}
+```text
$ packer validate example.json
Template validated successfully.
```
@@ -113,14 +111,14 @@ With a properly validated template. It is time to build your first image. This
is done by calling `packer build` with the template file. The output should look
similar to below. Note that this process typically takes a few minutes.
--> **Note:** For the tutorial it is convenient to use the credentials in the
+-> **Note:** For the tutorial it is convenient to use the credentials in the
command line. However, it is potentially insecure. See our documentation for
other ways to [specify Amazon credentials](/docs/builders/amazon.html#specifying-amazon-credentials).
--> **Note:** When using packer on Windows, replace the single-quotes in the
+-> **Note:** When using packer on Windows, replace the single-quotes in the
command below with double-quotes.
-``` {.text}
+```text
$ packer build \
-var 'aws_access_key=YOUR ACCESS KEY' \
-var 'aws_secret_key=YOUR SECRET KEY' \
@@ -158,7 +156,7 @@ artifact: the AMI in us-east-1 that was created.
This AMI is ready to use. If you wanted you could go and launch this AMI right now
and it would work great.
--> **Note:** Your AMI ID will surely be different than the one above. If you
+-> **Note:** Your AMI ID will surely be different than the one above. If you
try to launch the one in the example output above, you will get an error. If you
want to try to launch your AMI, get the ID from the Packer output.
@@ -167,10 +165,10 @@ able to determine the default VPC, which the `t2` instance types require. This
can happen if you created your AWS account before `2013-12-04`. You can either
change the `instance_type` to `m3.medium`, or specify a VPC. Please see
http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html for more
-information. If you specify a `vpc_id`, you will also need to set `subnet_id`.
+information. If you specify a `vpc_id`, you will also need to set `subnet_id`.
Unless you modify your subnet's [IPv4 public addressing attribute](
http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/vpc-ip-addressing.html#subnet-public-ip),
-you will also need to set `associate_public_ip_address` to `true`, or set up a
+you will also need to set `associate_public_ip_address` to `true`, or set up a
[VPN](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_VPN.html).
## Managing the Image
diff --git a/website/source/intro/getting-started/setup.html.md b/website/source/intro/getting-started/install.html.md
similarity index 86%
rename from website/source/intro/getting-started/setup.html.md
rename to website/source/intro/getting-started/install.html.md
index 9315a44b0..3ccd45adb 100644
--- a/website/source/intro/getting-started/setup.html.md
+++ b/website/source/intro/getting-started/install.html.md
@@ -1,16 +1,14 @@
---
-description: |
- Packer must first be installed on the machine you want to run it on. To make
- installation easy, Packer is distributed as a binary package for all supported
- platforms and architectures. This page will not cover how to compile Packer from
- source, as that is covered in the README and is only recommended for advanced
- users.
layout: intro
-next_title: Build an Image
-next_url: '/intro/getting-started/build-image.html'
-page_title: Install Packer
-prev_url: '/intro/platforms.html'
-...
+sidebar_current: intro-getting-started-install
+page_title: Install Packer - Getting Started
+description: |-
+ Packer must first be installed on the machine you want to run it on. To make
+ installation easy, Packer is distributed as a binary package for all supported
+ platforms and architectures. This page will not cover how to compile Packer
+ from source, as that is covered in the README and is only recommended for
+ advanced users.
+---
# Install Packer
@@ -45,7 +43,7 @@ contains instructions for setting the PATH on Windows.
After installing Packer, verify the installation worked by opening a new command
prompt or console, and checking that `packer` is available:
-``` {.text}
+```text
$ packer
usage: packer [--version] [--help] []
diff --git a/website/source/intro/getting-started/next.html.md b/website/source/intro/getting-started/next.html.md
index e1e7cc2ae..0094fb976 100644
--- a/website/source/intro/getting-started/next.html.md
+++ b/website/source/intro/getting-started/next.html.md
@@ -1,12 +1,13 @@
---
-description: |
- That concludes the getting started guide for Packer. You should now be
- comfortable with basic Packer usage, should understand templates, defining
- builds, provisioners, etc. At this point you're ready to begin playing with and
- using Packer in real scenarios.
layout: intro
-page_title: Next Steps
-...
+sidebar_current: intro-getting-started-next
+page_title: Next Steps - Getting Started
+description: |-
+ That concludes the getting started guide for Packer. You should now be
+ comfortable with basic Packer usage, should understand templates, defining
+ builds, provisioners, etc. At this point you're ready to begin playing with
+ and using Packer in real scenarios.
+---
# Next Steps
@@ -24,6 +25,6 @@ ecosystem of tools, read our [Atlas getting started
overview](https://atlas.hashicorp.com/help/intro/getting-started).
As you use Packer more, please voice your comments and concerns on the [mailing
-list or IRC](/community). Additionally, Packer is [open
+list or IRC](/community.html). Additionally, Packer is [open
source](https://github.com/mitchellh/packer) so please contribute if you'd like
to. Contributions are very welcome.
diff --git a/website/source/intro/getting-started/parallel-builds.html.md b/website/source/intro/getting-started/parallel-builds.html.md
index c1e5703e8..2cd6a9286 100644
--- a/website/source/intro/getting-started/parallel-builds.html.md
+++ b/website/source/intro/getting-started/parallel-builds.html.md
@@ -1,15 +1,13 @@
---
-description: |
- So far we've shown how Packer can automatically build an image and provision it.
- This on its own is already quite powerful. But Packer can do better than that.
- Packer can create multiple images for multiple platforms in parallel, all
- configured from a single template.
layout: intro
-next_title: Vagrant Boxes
-next_url: '/intro/getting-started/vagrant.html'
-page_title: Parallel Builds
-prev_url: '/intro/getting-started/provision.html'
-...
+sidebar_current: intro-getting-started-parallel-builds
+page_title: Parallel Builds - Getting Started
+description: |-
+ So far we've shown how Packer can automatically build an image and provision
+ it. This on its own is already quite powerful. But Packer can do better than
+ that. Packer can create multiple images for multiple platforms in parallel,
+ all configured from a single template.
+---
# Parallel Builds
@@ -61,7 +59,7 @@ We now have to modify the template to add DigitalOcean to it. Modify the
template we've been using and add the following JSON object to the `builders`
array.
-``` {.javascript}
+```json
{
"type": "digitalocean",
"api_token": "{{user `do_api_token`}}",
@@ -75,7 +73,7 @@ array.
You'll also need to modify the `variables` section of the template to include
the access keys for DigitalOcean.
-``` {.javascript}
+```javascript
"variables": {
"do_api_token": "",
// ...
@@ -84,7 +82,7 @@ the access keys for DigitalOcean.
The entire template should now look like this:
-``` {.javascript}
+```json
{
"variables": {
"aws_access_key": "",
@@ -126,7 +124,7 @@ that as long as you specify a unique `name` for each build.
Validate the template with `packer validate`. This is always a good practice.
--> **Note:** If you're looking for more **DigitalOcean configuration
+-> **Note:** If you're looking for more **DigitalOcean configuration
options**, you can find them on the [DigitalOcean Builder
page](/docs/builders/digitalocean.html) in the documentation. The documentation
is more of a reference manual that contains a listing of all the available
@@ -139,7 +137,7 @@ include all of it, but a portion of it is reproduced below. Note that the
ordering and wording of the lines may be slightly different, but the effect is
the same.
-``` {.text}
+```text
$ packer build \
-var 'aws_access_key=YOUR ACCESS KEY' \
-var 'aws_secret_key=YOUR SECRET KEY' \
diff --git a/website/source/intro/getting-started/provision.html.md b/website/source/intro/getting-started/provision.html.md
index eda1f0346..b95466427 100644
--- a/website/source/intro/getting-started/provision.html.md
+++ b/website/source/intro/getting-started/provision.html.md
@@ -1,17 +1,15 @@
---
-description: |
- In the previous page of this guide, you created your first image with Packer.
- The image you just built, however, was basically just a repackaging of a
- previously existing base AMI. The real utility of Packer comes from being able
- to install and configure software into the images as well. This stage is also
- known as the *provision* step. Packer fully supports automated provisioning in
- order to install software onto the machines prior to turning them into images.
layout: intro
-next_title: Parallel Builds
-next_url: '/intro/getting-started/parallel-builds.html'
-page_title: Provision
-prev_url: '/intro/getting-started/build-image.html'
-...
+sidebar_current: intro-getting-started-provision
+page_title: Provision - Getting Started
+description: |-
+ In the previous page of this guide, you created your first image with Packer.
+ The image you just built, however, was basically just a repackaging of a
+ previously existing base AMI. The real utility of Packer comes from being able
+ to install and configure software into the images as well. This stage is also
+ known as the *provision* step. Packer fully supports automated provisioning in
+ order to install software onto the machines prior to turning them into images.
+---
# Provision
@@ -39,7 +37,7 @@ shell provisioner that comes with Packer to install Redis. Modify the
`example.json` template we made previously and add the following. We'll explain
the various parts of the new configuration following the code block below.
-``` {.javascript}
+```json
{
"variables": ["..."],
"builders": ["..."],
@@ -55,7 +53,7 @@ the various parts of the new configuration following the code block below.
}
```
--> **Note:** The `sleep 30` in the example above is very important. Because
+-> **Note:** The `sleep 30` in the example above is very important. Because
Packer is able to detect and SSH into the instance as soon as SSH is available,
Ubuntu actually doesn't get proper amounts of time to initialize. The sleep
makes sure that the OS properly initializes.
diff --git a/website/source/intro/getting-started/remote-builds.html.md b/website/source/intro/getting-started/remote-builds.html.md
index bc903ec73..7ee554110 100644
--- a/website/source/intro/getting-started/remote-builds.html.md
+++ b/website/source/intro/getting-started/remote-builds.html.md
@@ -1,15 +1,13 @@
---
-description: |
- Up to this point in the guide, you have been running Packer on your local
- machine to build and provision images on AWS and DigitalOcean. However, you can
- use Atlas by HashiCorp to both run Packer builds remotely and store the output
- of builds.
layout: intro
-next_title: Next Steps
-next_url: '/intro/getting-started/next.html'
-page_title: Remote Builds and Storage
-prev_url: '/intro/getting-started/vagrant.html'
-...
+sidebar_current: intro-getting-started-remote-builds
+page_title: Remote Builds and Storage - Getting Started
+description: |-
+ Up to this point in the guide, you have been running Packer on your local
+ machine to build and provision images on AWS and DigitalOcean. However, you
+ can use Atlas by HashiCorp to both run Packer builds remotely and store the
+ output of builds.
+---
# Remote Builds and Storage
@@ -35,7 +33,7 @@ is updating the variables section to read variables from the Atlas environment
rather than the local environment. Remove the `post-processors` section for now
if it is still in your template.
-``` {.javascript}
+```json
{
"variables": {
"aws_access_key": "{{env `aws_access_key`}}",
@@ -80,7 +78,7 @@ with their respective values. Now restart the Packer build by either clicking
'rebuild' in the Atlas UI or by running `packer push example.json` again. Now
when you click on the active build, you can view the logs in real-time.
--> **Note:** Whenever a change is made to the Packer template, you must
+-> **Note:** Whenever a change is made to the Packer template, you must
`packer push` to update the configuration in Atlas.
## Store Packer Outputs
@@ -90,7 +88,7 @@ it's even better to store and version the AMI output so it can be easily
deployed by a tool like [Terraform](https://www.terraform.io). The `atlas`
[post-processor](/docs/post-processors/atlas.html) makes this process simple:
-``` {.javascript}
+```json
{
"variables": ["..."],
"builders": ["..."],
diff --git a/website/source/intro/getting-started/vagrant.html.md b/website/source/intro/getting-started/vagrant.html.md
index 6b5e89620..60709551b 100644
--- a/website/source/intro/getting-started/vagrant.html.md
+++ b/website/source/intro/getting-started/vagrant.html.md
@@ -1,13 +1,11 @@
---
-description: |
- Packer also has the ability to take the results of a builder (such as an AMI or
- plain VMware image) and turn it into a Vagrant box.
layout: intro
-next_title: Remote Builds and Storage
-next_url: '/intro/getting-started/remote-builds.html'
-page_title: Vagrant Boxes
-prev_url: '/intro/getting-started/parallel-builds.html'
-...
+sidebar_current: intro-getting-started-vagrant
+page_title: Vagrant Boxes - Getting Started
+description: |-
+ Packer also has the ability to take the results of a builder (such as an AMI
+ or plain VMware image) and turn it into a Vagrant box.
+---
# Vagrant Boxes
@@ -36,7 +34,7 @@ Post-processors are added in the `post-processors` section of a template, which
we haven't created yet. Modify your `example.json` template and add the section.
Your template should look like the following:
-``` {.javascript}
+```json
{
"builders": ["..."],
"provisioners": ["..."],
@@ -46,7 +44,7 @@ Your template should look like the following:
In this case, we're enabling a single post-processor named "vagrant". This
post-processor is built-in to Packer and will create Vagrant boxes. You can
-always create [new post-processors](/docs/extend/post-processor.html), however.
+always create [new post-processors](/docs/extending/custom-post-processors.html), however.
The details on configuring post-processors is covered in the
[post-processors](/docs/templates/post-processors.html) documentation.
@@ -59,7 +57,7 @@ Packer can't currently make a Vagrant box for DigitalOcean anyway, I recommend
passing the `-only=amazon-ebs` flag to `packer build` so it only builds the AMI.
The command should look like the following:
-``` {.text}
+```text
$ packer build -only=amazon-ebs example.json
```
diff --git a/website/source/intro/hashicorp-ecosystem.html.md b/website/source/intro/hashicorp-ecosystem.html.md
index 2a03962ef..a54d8c107 100644
--- a/website/source/intro/hashicorp-ecosystem.html.md
+++ b/website/source/intro/hashicorp-ecosystem.html.md
@@ -1,11 +1,10 @@
---
-description: Learn how Packer fits in with the rest of the HashiCorp ecosystem of tools
layout: intro
-next_title: 'Getting Started: Install Packer'
-next_url: '/intro/getting-started/setup.html'
-page_title: Packer and the HashiCorp Ecosystem
-prev_url: '/intro/platforms.html'
-...
+sidebar_current: intro-ecosystem
+page_title: Packer and the HashiCorp Ecosystem - Introduction
+description: |-
+ Learn how Packer fits in with the rest of the HashiCorp ecosystem of tools
+---
# Packer and the HashiCorp Ecosystem
diff --git a/website/source/intro/index.html.md b/website/source/intro/index.html.md
index b351d9af2..25ac519cb 100644
--- a/website/source/intro/index.html.md
+++ b/website/source/intro/index.html.md
@@ -1,15 +1,12 @@
---
-description: |
- Welcome to the world of Packer! This introduction guide will show you what
- Packer is, explain why it exists, the benefits it has to offer, and how you can
- get started with it. If you're already familiar with Packer, the documentation
- provides more of a reference for all available features.
layout: intro
-next_title: 'Why Use Packer?'
-next_url: '/intro/why.html'
page_title: Introduction
-prev_url: '# '
-...
+description: |-
+ Welcome to the world of Packer! This introduction guide will show you what
+ Packer is, explain why it exists, the benefits it has to offer, and how you
+ can get started with it. If you're already familiar with Packer, the
+ documentation provides more of a reference for all available features.
+---
# Introduction to Packer
diff --git a/website/source/intro/platforms.html.md b/website/source/intro/platforms.html.md
deleted file mode 100644
index a3b568e2a..000000000
--- a/website/source/intro/platforms.html.md
+++ /dev/null
@@ -1,84 +0,0 @@
----
-description: |
- Packer can create machine images for any platform. Packer ships with support for
- a set of platforms, but can be extended through plugins to support any platform.
- This page documents the list of supported image types that Packer supports
- creating.
-layout: intro
-next_title: 'Packer & the HashiCorp Ecosystem'
-next_url: '/intro/hashicorp-ecosystem.html'
-page_title: Supported Platforms
-prev_url: '/intro/use-cases.html'
-...
-
-# Supported Platforms
-
-Packer can create machine images for any platform. Packer ships with support for
-a set of platforms, but can be [extended through
-plugins](/docs/extend/builder.html) to support any platform. This page documents
-the list of supported image types that Packer supports creating.
-
-If you were looking to see what platforms Packer is able to run on, see the page
-on [installing Packer](/intro/getting-started/setup.html).
-
--> **Note:** We're always looking to officially support more target
-platforms. If you're interested in adding support for another platform, please
-help by opening an issue or pull request within
-[GitHub](https://github.com/mitchellh/packer) so we can discuss how to make it
-happen.
-
-Packer supports creating images for the following platforms or targets. The
-format of the resulting image and any high-level information about the platform
-is noted. They are listed in alphabetical order.
-
-- ***[Amazon EC2 (AMI)](/docs/builders/amazon.html)***. Both EBS-backed and instance-store AMIs within
- [EC2](https://aws.amazon.com/ec2/), optionally distributed to
- multiple regions.
-
-- ***[Azure Resource Manager (VHD)](/docs/builders/azure-arm.html)***. VHDs for [Azure Resource Manager](https://azure.microsoft.com/en-us/documentation/articles/resource-group-overview/), which can be deployed using the Azure Portal or Azure CLI.
-
-- ***[CloudStack](/docs/builders/cloudstack.html)***. Images for [CloudStack](https://cloudstack.apache.org/)
- that can be used to start pre-configured CloudStack servers.
-
-- ***[DigitalOcean](/docs/builders/digitalocean.html)***. Snapshots for
- [DigitalOcean](https://www.digitalocean.com/) that can be used to start a
- pre-configured DigitalOcean instance of any size.
-
-- ***[Docker](/docs/builders/docker.html)***. Snapshots for [Docker](https://www.docker.io/) that can be used
- to start a pre-configured Docker instance.
-
-- ***[Google Compute Engine](/docs/builders/googlecompute.html)***. Snapshots for [Google Compute
- Engine](https://cloud.google.com/products/compute-engine) that can be used
- to start a pre-configured Google Compute Engine instance.
-
-- ***[Hyper-V](/docs/builders/hyperv.html)***. Virtual machines for [Hyper-V](https://www.microsoft.com/en-us/server-cloud/solutions/virtualization.aspx), which are exportable.
-
-- ***[1&1](/docs/builders/oneandone.html)***. Virtual machines for [1&1](https://www.1and1.com/).
-
-- ***[OpenStack](/docs/builders/openstack.html)***. Images for [OpenStack](https://www.openstack.org/) that can
- be used to start pre-configured OpenStack servers.
-
-- ***[Parallels (PVM)](/docs/builders/parallels.html)***. Exported virtual machines for
- [Parallels](https://www.parallels.com/downloads/desktop/), including virtual
- machine metadata such as RAM, CPUs, etc. These virtual machines are portable
- and can be started on any platform Parallels runs on.
-
-- ***[ProfitBricks](/docs/builders/profitbricks.html)***. Virtual machines for [ProfitBricks](https://www.profitbricks.com).
-
-- ***[QEMU](/docs/builders/qemu.html)***. Images for [KVM](http://www.linux-kvm.org/) or
- [Xen](http://www.xenproject.org/) that can be used to start pre-configured
- KVM or Xen instances.
-
-- ***[VirtualBox (OVF)](/docs/builders/virtualbox.html)***. Exported virtual machines for
- [VirtualBox](https://www.virtualbox.org/), including virtual machine
- metadata such as RAM, CPUs, etc. These virtual machines are portable and can
- be started on any platform VirtualBox runs on.
-
-- ***[VMware (VMX)](/docs/builders/vmware.html)***. Exported virtual machines for
- [VMware](https://www.vmware.com/) that can be run within any desktop products
- such as Fusion, Player, or Workstation, as well as server products such
- as vSphere.
-
-As previously mentioned, these are just the target image types that Packer ships
-with out of the box. You can always [extend Packer through
-plugins](/docs/extend/builder.html) to support more.
diff --git a/website/source/intro/use-cases.html.md b/website/source/intro/use-cases.html.md
index 6694b231f..14f35c71c 100644
--- a/website/source/intro/use-cases.html.md
+++ b/website/source/intro/use-cases.html.md
@@ -1,16 +1,14 @@
---
-description: |
- By now you should know what Packer does and what the benefits of image creation
- are. In this section, we'll enumerate *some* of the use cases for Packer. Note
- that this is not an exhaustive list by any means. There are definitely use cases
- for Packer not listed here. This list is just meant to give you an idea of how
- Packer may improve your processes.
layout: intro
-next_title: Supported Platforms
-next_url: '/intro/platforms.html'
-page_title: Use Cases
-prev_url: '/intro/why.html'
-...
+sidebar_current: intro-use-cases
+page_title: Use Cases - Introduction
+description: |-
+ By now you should know what Packer does and what the benefits of image
+ creation are. In this section, we'll enumerate *some* of the use cases for
+ Packer. Note that this is not an exhaustive list by any means. There are
+ definitely use cases for Packer not listed here. This list is just meant to
+ give you an idea of how Packer may improve your processes.
+---
# Use Cases
diff --git a/website/source/intro/why.html.md b/website/source/intro/why.html.md
index ee6b5ad9e..275c5b013 100644
--- a/website/source/intro/why.html.md
+++ b/website/source/intro/why.html.md
@@ -1,17 +1,15 @@
---
-description: |
- Pre-baked machine images have a lot of advantages, but most have been unable to
- benefit from them because images have been too tedious to create and manage.
- There were either no existing tools to automate the creation of machine images
- or they had too high of a learning curve. The result is that, prior to Packer,
- creating machine images threatened the agility of operations teams, and
- therefore aren't used, despite the massive benefits.
layout: intro
-next_title: Packer Use Cases
-next_url: '/intro/use-cases.html'
-page_title: 'Why Use Packer?'
-prev_url: '/intro/index.html'
-...
+sidebar_current: intro-why
+page_title: Why Packer - Introduction
+description: |-
+ Pre-baked machine images have a lot of advantages, but most have been unable
+ to benefit from them because images have been too tedious to create and
+ manage. There were either no existing tools to automate the creation of
+ machine images or they had too high of a learning curve. The result is that,
+ prior to Packer, creating machine images threatened the agility of operations
+ teams, and therefore aren't used, despite the massive benefits.
+---
# Why Use Packer?
diff --git a/website/source/layouts/_sidebar.erb b/website/source/layouts/_sidebar.erb
index e56f69fb9..9257621b8 100644
--- a/website/source/layouts/_sidebar.erb
+++ b/website/source/layouts/_sidebar.erb
@@ -1,26 +1,29 @@
-
-
-
+ 
+ 
+ 
+ 
+ 
+