355 lines
11 KiB
Plaintext
355 lines
11 KiB
Plaintext
---
|
|
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 EBS - Builders
|
|
sidebar_title: 'EBS'
|
|
sidebar_current: docs-builders-amazon-ebsbacked
|
|
---
|
|
|
|
# AMI Builder (EBS backed)
|
|
|
|
Type: `amazon-ebs`
|
|
|
|
The `amazon-ebs` Packer builder is able to create Amazon AMIs backed by EBS
|
|
volumes for use in [EC2](https://aws.amazon.com/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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device).
|
|
|
|
This builder builds an AMI by launching an EC2 instance from a source AMI,
|
|
provisioning that running machine, and then creating an AMI from that machine.
|
|
This is all done in your own AWS account. The builder will create temporary
|
|
keypairs, security group rules, etc. that provide it temporary access to the
|
|
instance while the image is being created. This simplifies configuration quite
|
|
a bit.
|
|
|
|
The builder does _not_ manage AMIs. Once it creates an AMI and stores it in
|
|
your account, it is up to you to use, delete, etc. the AMI.
|
|
|
|
-> **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 key pairs Packer is able to operate on.
|
|
|
|
## EBS Specific 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.
|
|
|
|
#### Optional:
|
|
|
|
@include 'builder/amazon/ebs/Config-not-required.mdx'
|
|
|
|
### AMI Configuration
|
|
|
|
#### Required:
|
|
|
|
@include 'builder/amazon/common/AMIConfig-required.mdx'
|
|
|
|
#### Optional:
|
|
|
|
@include 'builder/amazon/common/AMIConfig-not-required.mdx'
|
|
|
|
### Access Configuration
|
|
|
|
#### Required:
|
|
|
|
@include 'builder/amazon/common/AccessConfig-required.mdx'
|
|
|
|
#### Optional:
|
|
|
|
@include 'builder/amazon/common/AccessConfig-not-required.mdx'
|
|
|
|
### Run Configuration
|
|
|
|
#### Required:
|
|
|
|
@include 'builder/amazon/common/RunConfig-required.mdx'
|
|
|
|
#### Optional:
|
|
|
|
@include 'builder/amazon/common/RunConfig-not-required.mdx'
|
|
|
|
### Block Devices Configuration
|
|
|
|
Block devices can be nested in the
|
|
[ami_block_device_mappings](#ami_block_device_mappings) or the
|
|
[launch_block_device_mappings](#launch_block_device_mappings) array.
|
|
|
|
@include 'builder/amazon/common/BlockDevice.mdx'
|
|
|
|
#### Optional:
|
|
|
|
@include 'builder/amazon/common/BlockDevice-not-required.mdx'
|
|
|
|
### Communicator Configuration
|
|
|
|
#### Optional:
|
|
|
|
@include 'helper/communicator/Config-not-required.mdx'
|
|
|
|
@include 'helper/communicator/SSH-not-required.mdx'
|
|
|
|
## 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:
|
|
|
|
```json
|
|
{
|
|
"variables": {
|
|
"aws_access_key": "{{env `AWS_ACCESS_KEY_ID`}}",
|
|
"aws_secret_key": "{{env `AWS_SECRET_ACCESS_KEY`}}"
|
|
},
|
|
"builders": [
|
|
{
|
|
"type": "amazon-ebs",
|
|
"access_key": "{{user `aws_access_key`}}",
|
|
"secret_key": "{{user `aws_secret_key`}}",
|
|
"region": "us-east-1",
|
|
"source_ami": "ami-fce3c696",
|
|
"instance_type": "t2.micro",
|
|
"ssh_username": "ubuntu",
|
|
"ami_name": "packer_AWS {{timestamp}}"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
-> **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 the 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.
|
|
|
|
## AMI Block Device Mappings Example
|
|
|
|
Here is an example using the optional AMI block device mappings. Our
|
|
configuration of `launch_block_device_mappings` will expand the root volume
|
|
(`/dev/sda`) to 40gb during the build (up from the default of 8gb). With
|
|
`ami_block_device_mappings` AWS will attach additional volumes `/dev/sdb` and
|
|
`/dev/sdc` when we boot a new instance of our AMI.
|
|
|
|
```json
|
|
{
|
|
"type": "amazon-ebs",
|
|
"access_key": "YOUR KEY HERE",
|
|
"secret_key": "YOUR SECRET KEY HERE",
|
|
"region": "us-east-1",
|
|
"source_ami": "ami-fce3c696",
|
|
"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
|
|
}
|
|
],
|
|
"ami_block_device_mappings": [
|
|
{
|
|
"device_name": "/dev/sdb",
|
|
"virtual_name": "ephemeral0"
|
|
},
|
|
{
|
|
"device_name": "/dev/sdc",
|
|
"virtual_name": "ephemeral1"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 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.
|
|
- `SourceAMIOwner` - The source AMI owner ID.
|
|
- `SourceAMIOwnerName` - The source AMI owner alias/name (for example `amazon`).
|
|
- `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.
|
|
|
|
## Build function template engine variables
|
|
|
|
For the build function of [template engine](/docs/templates/engine.html), the following
|
|
variables are available:
|
|
|
|
- `SourceAMIName` - The source AMI Name (for example
|
|
`ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to
|
|
build the AMI.
|
|
|
|
## Tag Example
|
|
|
|
Here is an example using the optional AMI tags. This will add the tags
|
|
`OS_Version` and `Release` to the finished AMI. As before, you will need to
|
|
provide your access keys, and may need to change the source AMI ID based on
|
|
what images exist when this template is run:
|
|
|
|
```json
|
|
{
|
|
"type": "amazon-ebs",
|
|
"access_key": "YOUR KEY HERE",
|
|
"secret_key": "YOUR SECRET KEY HERE",
|
|
"region": "us-east-1",
|
|
"source_ami": "ami-fce3c696",
|
|
"instance_type": "t2.micro",
|
|
"ssh_username": "ubuntu",
|
|
"ami_name": "packer-quick-start {{timestamp}}",
|
|
"tags": {
|
|
"OS_Version": "Ubuntu",
|
|
"Release": "Latest",
|
|
"Base_AMI_Name": "{{ .SourceAMIName }}",
|
|
"Extra": "{{ .SourceAMITags.TagName }}"
|
|
}
|
|
}
|
|
```
|
|
|
|
-> **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 termination. If you need to preserve those source volumes, you can
|
|
overwrite the termination setting by specifying `delete_on_termination=false`
|
|
in the `launch_block_device_mappings` block for the device.
|
|
|
|
## Connecting to Windows instances using WinRM
|
|
|
|
If you want to launch a Windows instance and connect using WinRM, you will need
|
|
to configure WinRM on that instance. The following is a basic powershell script
|
|
that can be supplied to AWS using the "user_data_file" option. It enables
|
|
WinRM via HTTPS on port 5986, and creates a self-signed certificate to use to
|
|
connect. If you are using a certificate from a CA, rather than creating a
|
|
self-signed certificate, you can omit the "winrm_insecure" option mentioned
|
|
below.
|
|
|
|
autogenerated_password_https_boostrap.txt
|
|
|
|
``` ps1
|
|
<powershell>
|
|
|
|
# MAKE SURE IN YOUR PACKER CONFIG TO SET:
|
|
#
|
|
#
|
|
# "winrm_username": "Administrator",
|
|
# "winrm_insecure": true,
|
|
# "winrm_use_ssl": true,
|
|
#
|
|
#
|
|
|
|
|
|
write-output "Running User Data Script"
|
|
write-host "(host) Running User Data Script"
|
|
|
|
Set-ExecutionPolicy Unrestricted -Scope LocalMachine -Force -ErrorAction Ignore
|
|
|
|
# Don't set this before Set-ExecutionPolicy as it throws an error
|
|
$ErrorActionPreference = "stop"
|
|
|
|
# Remove HTTP listener
|
|
Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse
|
|
|
|
# Create a self-signed certificate to let ssl work
|
|
$Cert = New-SelfSignedCertificate -CertstoreLocation Cert:\LocalMachine\My -DnsName "packer"
|
|
New-Item -Path WSMan:\LocalHost\Listener -Transport HTTPS -Address * -CertificateThumbPrint $Cert.Thumbprint -Force
|
|
|
|
# WinRM
|
|
write-output "Setting up WinRM"
|
|
write-host "(host) setting up WinRM"
|
|
|
|
cmd.exe /c winrm quickconfig -q
|
|
cmd.exe /c winrm set "winrm/config" '@{MaxTimeoutms="1800000"}'
|
|
cmd.exe /c winrm set "winrm/config/winrs" '@{MaxMemoryPerShellMB="1024"}'
|
|
cmd.exe /c winrm set "winrm/config/service" '@{AllowUnencrypted="true"}'
|
|
cmd.exe /c winrm set "winrm/config/client" '@{AllowUnencrypted="true"}'
|
|
cmd.exe /c winrm set "winrm/config/service/auth" '@{Basic="true"}'
|
|
cmd.exe /c winrm set "winrm/config/client/auth" '@{Basic="true"}'
|
|
cmd.exe /c winrm set "winrm/config/service/auth" '@{CredSSP="true"}'
|
|
cmd.exe /c winrm set "winrm/config/listener?Address=*+Transport=HTTPS" "@{Port=`"5986`";Hostname=`"packer`";CertificateThumbprint=`"$($Cert.Thumbprint)`"}"
|
|
cmd.exe /c netsh advfirewall firewall set rule group="remote administration" new enable=yes
|
|
cmd.exe /c netsh firewall add portopening TCP 5986 "Port 5986"
|
|
cmd.exe /c net stop winrm
|
|
cmd.exe /c sc config winrm start= auto
|
|
cmd.exe /c net start winrm
|
|
|
|
</powershell>
|
|
```
|
|
|
|
You'll notice that this config does not define a user or password; instead,
|
|
Packer will ask AWS to provide a random password that it generates
|
|
automatically. The following config will work with the above template:
|
|
|
|
```
|
|
{
|
|
"builders": [
|
|
{
|
|
"type": "amazon-ebs",
|
|
"region": "us-east-1",
|
|
"instance_type": "t2.micro",
|
|
"source_ami_filter": {
|
|
"filters": {
|
|
"virtualization-type": "hvm",
|
|
"name": "*Windows_Server-2012*English-64Bit-Base*",
|
|
"root-device-type": "ebs"
|
|
},
|
|
"most_recent": true,
|
|
"owners": "amazon"
|
|
},
|
|
"ami_name": "default-packer",
|
|
"user_data_file": "winrm_bootstrap.txt",
|
|
"communicator": "winrm",
|
|
"force_deregister": true,
|
|
"winrm_insecure": true,
|
|
"winrm_username": "Administrator",
|
|
"winrm_use_ssl": true
|
|
}]
|
|
}
|
|
```
|
|
|
|
|
|
## Windows 2016 Sysprep Commands - For Amazon Windows AMIs Only
|
|
|
|
For Amazon Windows 2016 AMIs it is necessary to run Sysprep commands which can
|
|
be easily added to the provisioner section.
|
|
|
|
```json
|
|
{
|
|
"type": "powershell",
|
|
"inline": [
|
|
"C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/InitializeInstance.ps1 -Schedule",
|
|
"C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/SysprepInstance.ps1 -NoShutdown"
|
|
]
|
|
}
|
|
```
|
|
|
|
@include 'builders/aws-ssh-differentiation-table.mdx'
|