github.com/aspring/packer@v0.8.1-0.20150629211158-9db281ac0f89/website/source/docs/builders/amazon-ebs.html.markdown (about) 1 --- 2 layout: "docs" 3 page_title: "Amazon AMI Builder (EBS backed)" 4 description: |- 5 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. 6 --- 7 8 # AMI Builder (EBS backed) 9 10 Type: `amazon-ebs` 11 12 The `amazon-ebs` Packer builder is able to create Amazon AMIs backed by EBS 13 volumes for use in [EC2](http://aws.amazon.com/ec2/). For more information 14 on the difference between EBS-backed instances and instance-store backed 15 instances, see the 16 ["storage for the root device" section in the EC2 documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). 17 18 This builder builds an AMI by launching an EC2 instance from a source AMI, 19 provisioning that running machine, and then creating an AMI from that machine. 20 This is all done in your own AWS account. The builder will create temporary 21 keypairs, security group rules, etc. that provide it temporary access to 22 the instance while the image is being created. This simplifies configuration 23 quite a bit. 24 25 The builder does _not_ manage AMIs. Once it creates an AMI and stores it 26 in your account, it is up to you to use, delete, etc. the AMI. 27 28 ## Configuration Reference 29 30 There are many configuration options available for the builder. They are 31 segmented below into two categories: required and optional parameters. Within 32 each category, the available configuration keys are alphabetized. 33 34 In addition to the options listed here, a 35 [communicator](/docs/templates/communicator.html) 36 can be configured for this builder. 37 38 ### Required: 39 40 * `access_key` (string) - The access key used to communicate with AWS. 41 If not specified, Packer will use the key from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file 42 or fall back to environment variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order), if set. 43 44 * `ami_name` (string) - The name of the resulting AMI that will appear 45 when managing AMIs in the AWS console or via APIs. This must be unique. 46 To help make this unique, use a function like `timestamp` (see 47 [configuration templates](/docs/templates/configuration-templates.html) for more info) 48 49 * `instance_type` (string) - The EC2 instance type to use while building 50 the AMI, such as "m1.small". 51 52 * `region` (string) - The name of the region, such as "us-east-1", in which 53 to launch the EC2 instance to create the AMI. 54 55 * `secret_key` (string) - The secret key used to communicate with AWS. 56 If not specified, Packer will use the secret from any [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file 57 or fall back to environment variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order), if set. 58 59 * `source_ami` (string) - The initial AMI used as a base for the newly 60 created machine. 61 62 * `ssh_username` (string) - The username to use in order to communicate 63 over SSH to the running machine. 64 65 ### Optional: 66 67 * `ami_block_device_mappings` (array of block device mappings) - Add the block 68 device mappings to the AMI. The block device mappings allow for keys: 69 70 - `device_name` (string) - The device name exposed to the instance (for 71 example, "/dev/sdh" or "xvdh") 72 - `virtual_name` (string) - The virtual device name. See the documentation on 73 [Block Device Mapping][1] for more information 74 - `snapshot_id` (string) - The ID of the snapshot 75 - `volume_type` (string) - The volume type. gp2 for General Purpose (SSD) 76 volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic 77 volumes 78 - `volume_size` (integer) - The size of the volume, in GiB. Required if not 79 specifying a `snapshot_id` 80 - `delete_on_termination` (boolean) - Indicates whether the EBS volume is 81 deleted on instance termination 82 - `encrypted` (boolean) - Indicates whether to encrypt the volume or not 83 - `no_device` (boolean) - Suppresses the specified device included in the 84 block device mapping of the AMI 85 - `iops` (integer) - The number of I/O operations per second (IOPS) that the 86 volume supports. See the documentation on [IOPs][2] for more information 87 88 89 * `ami_description` (string) - The description to set for the resulting 90 AMI(s). By default this description is empty. 91 92 * `ami_groups` (array of strings) - A list of groups that have access 93 to launch the resulting AMI(s). By default no groups have permission 94 to launch the AMI. `all` will make the AMI publicly accessible. 95 AWS currently doesn't accept any value other than "all". 96 97 * `ami_product_codes` (array of strings) - A list of product codes to 98 associate with the AMI. By default no product codes are associated with 99 the AMI. 100 101 * `ami_regions` (array of strings) - A list of regions to copy the AMI to. 102 Tags and attributes are copied along with the AMI. AMI copying takes time 103 depending on the size of the AMI, but will generally take many minutes. 104 105 * `ami_users` (array of strings) - A list of account IDs that have access 106 to launch the resulting AMI(s). By default no additional users other than the user 107 creating the AMI has permissions to launch it. 108 109 * `associate_public_ip_address` (boolean) - If using a non-default VPC, public 110 IP addresses are not provided by default. If this is toggled, your new 111 instance will get a Public IP. 112 113 * `availability_zone` (string) - Destination availability zone to launch instance in. 114 Leave this empty to allow Amazon to auto-assign. 115 116 * `enhanced_networking` (boolean) - Enable enhanced networking (SriovNetSupport) on 117 HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. 118 119 * `force_deregister` (boolean) - Force Packer to first deregister an existing 120 AMI if one with the same name already exists. Default `false`. 121 122 * `iam_instance_profile` (string) - The name of an 123 [IAM instance profile](http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) 124 to launch the EC2 instance with. 125 126 * `launch_block_device_mappings` (array of block device mappings) - Add the 127 block device mappings to the launch instance. The block device mappings are 128 the same as `ami_block_device_mappings` above. 129 130 * `run_tags` (object of key/value strings) - Tags to apply to the instance 131 that is _launched_ to create the AMI. These tags are _not_ applied to 132 the resulting AMI unless they're duplicated in `tags`. 133 134 * `security_group_id` (string) - The ID (_not_ the name) of the security 135 group to assign to the instance. By default this is not set and Packer 136 will automatically create a new temporary security group to allow SSH 137 access. Note that if this is specified, you must be sure the security 138 group allows access to the `ssh_port` given below. 139 140 * `security_group_ids` (array of strings) - A list of security groups as 141 described above. Note that if this is specified, you must omit the 142 `security_group_id`. 143 144 * `spot_price` (string) - The maximum hourly price to pay for a spot instance 145 to create the AMI. Spot instances are a type of instance that EC2 starts when 146 the current spot price is less than the maximum price you specify. Spot price 147 will be updated based on available spot instance capacity and current spot 148 instance requests. It may save you some costs. You can set this to "auto" for 149 Packer to automatically discover the best spot price. 150 151 * `spot_price_auto_product` (string) - Required if `spot_price` is set to 152 "auto". This tells Packer what sort of AMI you're launching to find the best 153 spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`, 154 `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)` 155 156 * `ssh_keypair_name` (string) - If specified, this is the key that will be 157 used for SSH with the machine. By default, this is blank, and Packer will 158 generate a temporary keypair. `ssh_private_key_file` must be specified 159 with this. 160 161 * `ssh_private_ip` (bool) - If true, then SSH will always use the private 162 IP if available. 163 164 * `subnet_id` (string) - If using VPC, the ID of the subnet, such as 165 "subnet-12345def", where Packer will launch the EC2 instance. This field is 166 required if you are using an non-default VPC. 167 168 * `tags` (object of key/value strings) - Tags applied to the AMI and 169 relevant snapshots. 170 171 * `temporary_key_pair_name` (string) - The name of the temporary keypair 172 to generate. By default, Packer generates a name with a UUID. 173 174 * `token` (string) - The access token to use. This is different from 175 the access key and secret key. If you're not sure what this is, then you 176 probably don't need it. This will also be read from the `AWS_SECURITY_TOKEN` 177 environmental variable. 178 179 * `user_data` (string) - User data to apply when launching the instance. 180 Note that you need to be careful about escaping characters due to the 181 templates being JSON. It is often more convenient to use `user_data_file`, 182 instead. 183 184 * `user_data_file` (string) - Path to a file that will be used for the 185 user data when launching the instance. 186 187 * `vpc_id` (string) - If launching into a VPC subnet, Packer needs the 188 VPC ID in order to create a temporary security group within the VPC. 189 190 * `windows_password_timeout` (string) - The timeout for waiting for 191 a Windows password for Windows instances. Defaults to 20 minutes. 192 Example value: "10m" 193 194 ## Basic Example 195 196 Here is a basic example. It is completely valid except for the access keys: 197 198 ```javascript 199 { 200 "type": "amazon-ebs", 201 "access_key": "YOUR KEY HERE", 202 "secret_key": "YOUR SECRET KEY HERE", 203 "region": "us-east-1", 204 "source_ami": "ami-de0d9eb7", 205 "instance_type": "t1.micro", 206 "ssh_username": "ubuntu", 207 "ami_name": "packer-quick-start {{timestamp}}" 208 } 209 ``` 210 211 -> **Note:** Packer can also read the access key and secret 212 access key from environmental variables. See the configuration reference in 213 the section above for more information on what environmental variables Packer 214 will look for. 215 216 ## Accessing the Instance to Debug 217 218 If you need to access the instance to debug for some reason, run the builder 219 with the `-debug` flag. In debug mode, the Amazon builder will save the 220 private key in the current directory and will output the DNS or IP information 221 as well. You can use this information to access the instance as it is 222 running. 223 224 ## AMI Block Device Mappings Example 225 226 Here is an example using the optional AMI block device mappings. This will add 227 the /dev/sdb and /dev/sdc block device mappings to the finished AMI. 228 229 ```javascript 230 { 231 "type": "amazon-ebs", 232 "access_key": "YOUR KEY HERE", 233 "secret_key": "YOUR SECRET KEY HERE", 234 "region": "us-east-1", 235 "source_ami": "ami-de0d9eb7", 236 "instance_type": "t1.micro", 237 "ssh_username": "ubuntu", 238 "ami_name": "packer-quick-start {{timestamp}}", 239 "ami_block_device_mappings": [ 240 { 241 "device_name": "/dev/sdb", 242 "virtual_name": "ephemeral0" 243 }, 244 { 245 "device_name": "/dev/sdc", 246 "virtual_name": "ephemeral1" 247 } 248 ] 249 } 250 ``` 251 252 ## Tag Example 253 254 Here is an example using the optional AMI tags. This will add the tags 255 "OS_Version" and "Release" to the finished AMI. 256 257 ```javascript 258 { 259 "type": "amazon-ebs", 260 "access_key": "YOUR KEY HERE", 261 "secret_key": "YOUR SECRET KEY HERE", 262 "region": "us-east-1", 263 "source_ami": "ami-de0d9eb7", 264 "instance_type": "t1.micro", 265 "ssh_username": "ubuntu", 266 "ami_name": "packer-quick-start {{timestamp}}", 267 "tags": { 268 "OS_Version": "Ubuntu", 269 "Release": "Latest" 270 } 271 } 272 ``` 273 274 -> **Note:** Packer uses pre-built AMIs as the source for building images. 275 These source AMIs may include volumes that are not flagged to be destroyed on 276 termiation of the instance building the new image. Packer will attempt to clean 277 up all residual volumes that are not designated by the user to remain after 278 termination. If you need to preserve those source volumes, you can overwrite the 279 termination setting by specifying `delete_on_termination=false` in the 280 `launch_device_mappings` block for the device. 281 282 [1]: http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html 283 [2]: http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html