170 lines
5.3 KiB
Plaintext
170 lines
5.3 KiB
Plaintext
---
|
|
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 - Builders'
|
|
sidebar_current: 'docs-builders-amazon-ebssurrogate'
|
|
---
|
|
|
|
# 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.
|
|
|
|
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. This 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
|
|
|
|
There are many configuration options available for the builder. In addition to
|
|
the items listed here, you will want to look at the general configuration
|
|
references for [AMI](#ami-configuration),
|
|
[BlockDevices](#block-devices-configuration),
|
|
[Access](#access-configuration),
|
|
[Run](#run-configuration) and
|
|
[Communicator](#communicator-configuration)
|
|
configuration references, which are
|
|
necessary for this build to succeed and can be found further down the page.
|
|
|
|
### Required:
|
|
|
|
<%= partial "partials/builder/amazon/ebssurrogate/Config-required" %>
|
|
|
|
### Optional:
|
|
|
|
<%= partial "partials/builder/amazon/ebssurrogate/Config-not-required" %>
|
|
|
|
|
|
### AMI Configuration
|
|
|
|
#### Required:
|
|
|
|
<%= partial "partials/builder/amazon/common/AMIConfig-required" %>
|
|
|
|
#### Optional:
|
|
<%= partial "partials/builder/amazon/common/AMIConfig-not-required" %>
|
|
|
|
### Access Configuration
|
|
|
|
#### Required:
|
|
|
|
<%= partial "partials/builder/amazon/common/AccessConfig-required" %>
|
|
|
|
#### Optional:
|
|
|
|
<%= partial "partials/builder/amazon/common/AccessConfig-not-required" %>
|
|
|
|
### Run Configuration
|
|
|
|
#### Required:
|
|
|
|
<%= partial "partials/builder/amazon/common/RunConfig-required" %>
|
|
|
|
#### Optional:
|
|
|
|
<%= partial "partials/builder/amazon/common/RunConfig-not-required" %>
|
|
|
|
|
|
### Block Devices Configuration
|
|
|
|
Block devices can be nested in the
|
|
[ami_block_device_mappings](#ami_block_device_mappings) array.
|
|
|
|
|
|
<%= partial "partials/builder/amazon/common/BlockDevice" %>
|
|
|
|
#### Optional only for [launch_block_device_mappings](#launch_block_device_mappings)
|
|
|
|
<%= partial "partials/builder/amazon/ebssurrogate/BlockDevice-not-required" %>
|
|
|
|
#### Optional:
|
|
<%= partial "partials/builder/amazon/common/BlockDevice-not-required" %>
|
|
|
|
|
|
|
|
### Communicator Configuration
|
|
|
|
#### Optional:
|
|
|
|
<%= partial "partials/helper/communicator/Config-not-required" %>
|
|
<%= partial "partials/helper/communicator/SSH-not-required" %>
|
|
<%= partial "partials/helper/communicator/SSHInterface-not-required" %>
|
|
|
|
## Basic Example
|
|
|
|
``` json
|
|
{
|
|
"type" : "amazon-ebssurrogate",
|
|
"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",
|
|
"launch_block_device_mappings" : [
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
```
|
|
|
|
-> **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.
|
|
|
|
Further information on locating AMI IDs and their relationship to instance
|
|
types and regions can be found in the AWS EC2 Documentation [for
|
|
Linux](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html)
|
|
or [for
|
|
Windows](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/finding-an-ami.html).
|
|
|
|
## Accessing the Instance to Debug
|
|
|
|
If you need to access the instance to debug for some reason, run this builder
|
|
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.
|
|
|
|
## Build template data
|
|
|
|
In configuration directives marked as a template engine above, the following
|
|
variables are available:
|
|
|
|
- `BuildRegion` - The region (for example `eu-central-1`) where Packer is
|
|
building the AMI.
|
|
- `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build
|
|
the AMI.
|
|
- `SourceAMIName` - The source AMI Name (for example
|
|
`ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to
|
|
build the AMI.
|
|
- `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.
|
|
|
|
-> **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 deletion on termination will remain in your account.
|
|
|
|
|
|
<%= partial "partials/builders/aws-ssh-differentiation-table" %>
|