github.com/aclaygray/packer@v1.3.2/website/source/docs/builders/amazon-ebs.html.md (about) 1 --- 2 description: | 3 The amazon-ebs Packer builder is able to create Amazon AMIs backed by EBS 4 volumes for use in EC2. For more information on the difference between 5 EBS-backed instances and instance-store backed instances, see the storage for 6 the root device section in the EC2 documentation. 7 layout: docs 8 page_title: 'Amazon EBS - Builders' 9 sidebar_current: 'docs-builders-amazon-ebsbacked' 10 --- 11 12 # AMI Builder (EBS backed) 13 14 Type: `amazon-ebs` 15 16 The `amazon-ebs` Packer builder is able to create Amazon AMIs backed by EBS 17 volumes for use in [EC2](https://aws.amazon.com/ec2/). For more information on 18 the difference between EBS-backed instances and instance-store backed instances, 19 see the ["storage for the root device" section in the EC2 20 documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). 21 22 This builder builds an AMI by launching an EC2 instance from a source AMI, 23 provisioning that running machine, and then creating an AMI from that machine. 24 This is all done in your own AWS account. The builder will create temporary 25 keypairs, security group rules, etc. that provide it temporary access to the 26 instance while the image is being created. This simplifies configuration quite a 27 bit. 28 29 The builder does *not* manage AMIs. Once it creates an AMI and stores it in your 30 account, it is up to you to use, delete, etc. the AMI. 31 32 -> **Note:** Temporary resources are, by default, all created with the prefix 33 `packer`. This can be useful if you want to restrict the security groups and 34 key pairs Packer is able to operate on. 35 36 ## Configuration Reference 37 38 There are many configuration options available for the builder. They are 39 segmented below into two categories: required and optional parameters. Within 40 each category, the available configuration keys are alphabetized. 41 42 In addition to the options listed here, a 43 [communicator](../templates/communicator.html) can be configured for this 44 builder. 45 46 ### Required: 47 48 - `access_key` (string) - The access key used to communicate with AWS. [Learn 49 how to set this](amazon.html#specifying-amazon-credentials) 50 51 - `ami_name` (string) - The name of the resulting AMI that will appear when 52 managing AMIs in the AWS console or via APIs. This must be unique. To help 53 make this unique, use a function like `timestamp` (see [template 54 engine](../templates/engine.html) for more info). 55 56 - `instance_type` (string) - The EC2 instance type to use while building the 57 AMI, such as `t2.small`. 58 59 - `region` (string) - The name of the region, such as `us-east-1`, in which to 60 launch the EC2 instance to create the AMI. 61 62 - `secret_key` (string) - The secret key used to communicate with AWS. [Learn 63 how to set this](amazon.html#specifying-amazon-credentials) 64 65 - `source_ami` (string) - The initial AMI used as a base for the newly 66 created machine. `source_ami_filter` may be used instead to populate this 67 automatically. 68 69 ### Optional: 70 71 - `ami_block_device_mappings` (array of block device mappings) - Add one or 72 more [block device mappings](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html) 73 to the AMI. These will be attached when booting a new instance from your 74 AMI. To add a block device during the Packer build see 75 `launch_block_device_mappings` below. Your options here may vary depending 76 on the type of VM you use. The block device mappings allow for the following 77 configuration: 78 79 - `delete_on_termination` (boolean) - Indicates whether the EBS volume is 80 deleted on instance termination. Default `false`. **NOTE**: If this 81 value is not explicitly set to `true` and volumes are not cleaned up by 82 an alternative method, additional volumes will accumulate after 83 every build. 84 85 - `device_name` (string) - The device name exposed to the instance (for 86 example, `/dev/sdh` or `xvdh`). Required for every device in the 87 block device mapping. 88 89 - `encrypted` (boolean) - Indicates whether to encrypt the volume or not 90 91 - `iops` (number) - The number of I/O operations per second (IOPS) that the 92 volume supports. See the documentation on 93 [IOPs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) 94 for more information 95 96 - `no_device` (boolean) - Suppresses the specified device included in the 97 block device mapping of the AMI 98 99 - `snapshot_id` (string) - The ID of the snapshot 100 101 - `virtual_name` (string) - The virtual device name. See the documentation on 102 [Block Device 103 Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) 104 for more information 105 106 - `volume_size` (number) - The size of the volume, in GiB. Required if not 107 specifying a `snapshot_id` 108 109 - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD) 110 volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic 111 volumes 112 113 - `ami_description` (string) - The description to set for the 114 resulting AMI(s). By default this description is empty. This is a 115 [template engine](../templates/engine.html), 116 see [Build template data](#build-template-data) for more information. 117 118 - `ami_groups` (array of strings) - A list of groups that have access to 119 launch the resulting AMI(s). By default no groups have permission to launch 120 the AMI. `all` will make the AMI publicly accessible. AWS currently doesn't 121 accept any value other than `all`. 122 123 - `ami_product_codes` (array of strings) - A list of product codes to 124 associate with the AMI. By default no product codes are associated with 125 the AMI. 126 127 - `ami_regions` (array of strings) - A list of regions to copy the AMI to. 128 Tags and attributes are copied along with the AMI. AMI copying takes time 129 depending on the size of the AMI, but will generally take many minutes. 130 131 - `ami_users` (array of strings) - A list of account IDs that have access to 132 launch the resulting AMI(s). By default no additional users other than the 133 user creating the AMI has permissions to launch it. 134 135 - `ami_virtualization_type` (string) - The type of virtualization for the AMI 136 you are building. This option must match the supported virtualization 137 type of `source_ami`. Can be `paravirtual` or `hvm`. 138 139 - `associate_public_ip_address` (boolean) - If using a non-default VPC, public 140 IP addresses are not provided by default. If this is toggled, your new 141 instance will get a Public IP. 142 143 - `availability_zone` (string) - Destination availability zone to launch 144 instance in. Leave this empty to allow Amazon to auto-assign. 145 146 - `block_duration_minutes` (int64) - Requires `spot_price` to 147 be set. The required duration for the Spot Instances (also known as Spot blocks). 148 This value must be a multiple of 60 (60, 120, 180, 240, 300, or 360). 149 You can't specify an Availability Zone group or a launch group if you specify a duration. 150 151 - `custom_endpoint_ec2` (string) - This option is useful if you use a cloud 152 provider whose API is compatible with aws EC2. Specify another endpoint 153 like this `https://ec2.custom.endpoint.com`. 154 155 - `decode_authorization_messages` (boolean) - Enable automatic decoding of any 156 encoded authorization (error) messages using the `sts:DecodeAuthorizationMessage` API. 157 Note: requires that the effective user/role have permissions to `sts:DecodeAuthorizationMessage` 158 on resource `*`. Default `false`. 159 160 - `disable_stop_instance` (boolean) - Packer normally stops the build instance 161 after all provisioners have run. For Windows instances, it is sometimes 162 desirable to [run Sysprep](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ami-create-standard.html) 163 which will stop the instance for you. If this is set to `true`, Packer *will not* 164 stop the instance but will assume that you will send the stop signal 165 yourself through your final provisioner. You can do this with a 166 [windows-shell provisioner](https://www.packer.io/docs/provisioners/windows-shell.html). 167 168 Note that Packer will still wait for the instance to be stopped, and failing 169 to send the stop signal yourself, when you have set this flag to `true`, 170 will cause a timeout. 171 172 Example of a valid shutdown command: 173 174 ``` json 175 { 176 "type": "windows-shell", 177 "inline": ["\"c:\\Program Files\\Amazon\\Ec2ConfigService\\ec2config.exe\" -sysprep"] 178 } 179 ``` 180 181 - `ebs_optimized` (boolean) - Mark instance as [EBS 182 Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html). 183 Default `false`. 184 185 - `ena_support` (boolean) - Enable enhanced networking (ENA but not SriovNetSupport) 186 on HVM-compatible AMIs. If set, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. 187 If false, this will disable enhanced networking in the final AMI as opposed to passing 188 the setting through unchanged from the source. Note: you must make sure enhanced 189 networking is enabled on your instance. See [Amazon's documentation on enabling enhanced 190 networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). 191 192 - `enable_t2_unlimited` (boolean) - Enabling T2 Unlimited allows the source 193 instance to burst additional CPU beyond its available [CPU Credits] 194 (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-credits-baseline-concepts.html) 195 for as long as the demand exists. 196 This is in contrast to the standard configuration that only allows an 197 instance to consume up to its available CPU Credits. 198 See the AWS documentation for [T2 Unlimited] 199 (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-unlimited.html) 200 and the **T2 Unlimited Pricing** section of the [Amazon EC2 On-Demand 201 Pricing](https://aws.amazon.com/ec2/pricing/on-demand/) document for more 202 information. 203 By default this option is disabled and Packer will set up a [T2 204 Standard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-std.html) 205 instance instead. 206 207 To use T2 Unlimited you must use a T2 instance type e.g. `t2.micro`. 208 Additionally, T2 Unlimited cannot be used in conjunction with Spot 209 Instances, e.g., when the `spot_price` option has been configured. 210 Attempting to do so will cause an error. 211 212 !> **Warning!** Additional costs may be incurred by enabling T2 213 Unlimited - even for instances that would usually qualify for the 214 [AWS Free Tier](https://aws.amazon.com/free/). 215 216 - `encrypt_boot` (boolean) - Instruct packer to automatically create a copy of the 217 AMI with an encrypted boot volume (discarding the initial unencrypted AMI in the 218 process). Packer will always run this operation, even if the base 219 AMI has an encrypted boot volume to start with. Default `false`. 220 221 - `force_delete_snapshot` (boolean) - Force Packer to delete snapshots associated with 222 AMIs, which have been deregistered by `force_deregister`. Default `false`. 223 224 - `force_deregister` (boolean) - Force Packer to first deregister an existing 225 AMI if one with the same name already exists. Default `false`. 226 227 - `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot volume encryption. 228 This only applies to the main `region`, other regions where the AMI will be copied 229 will be encrypted by the default EBS KMS key. For valid formats 230 see _KmsKeyId_ in the 231 [AWS API docs - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). 232 233 - `iam_instance_profile` (string) - The name of an [IAM instance 234 profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) 235 to launch the EC2 instance with. 236 237 - `launch_block_device_mappings` (array of block device mappings) - Add one 238 or more block devices before the Packer build starts. If you add instance 239 store volumes or EBS volumes in addition to the root device volume, the 240 created AMI will contain block device mapping information for those 241 volumes. Amazon creates snapshots of the source instance's root volume and 242 any other EBS volumes described here. When you launch an instance from this 243 new AMI, the instance automatically launches with these additional volumes, 244 and will restore them from snapshots taken from the source instance. 245 246 - `mfa_code` (string) - The MFA [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm) 247 code. This should probably be a user variable since it changes all the time. 248 249 - `profile` (string) - The profile to use in the shared credentials file for 250 AWS. See Amazon's documentation on [specifying 251 profiles](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-profiles) 252 for more details. 253 254 - `region_kms_key_ids` (map of strings) - a map of regions to copy the ami to, 255 along with the custom kms key id (alias or arn) to use for encryption for that region. 256 Keys must match the regions provided in `ami_regions`. If you just want to 257 encrypt using a default ID, you can stick with `kms_key_id` and `ami_regions`. 258 If you want a region to be encrypted with that region's default key ID, you can 259 use an empty string `""` instead of a key id in this map. (e.g. `"us-east-1": ""`) 260 However, you cannot use default key IDs if you are using this in conjunction with 261 `snapshot_users` -- in that situation you must use custom keys. For valid formats 262 see _KmsKeyId_ in the 263 [AWS API docs - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). 264 265 - `run_tags` (object of key/value strings) - Tags to apply to the instance 266 that is *launched* to create the AMI. These tags are *not* applied to the 267 resulting AMI unless they're duplicated in `tags`. This is a 268 [template engine](../templates/engine.html), 269 see [Build template data](#build-template-data) for more information. 270 271 - `run_volume_tags` (object of key/value strings) - Tags to apply to the volumes 272 that are *launched* to create the AMI. These tags are *not* applied to the 273 resulting AMI unless they're duplicated in `tags`. This is a 274 [template engine](../templates/engine.html), 275 see [Build template data](#build-template-data) for more information. 276 277 - `security_group_id` (string) - The ID (*not* the name) of the security group 278 to assign to the instance. By default this is not set and Packer will 279 automatically create a new temporary security group to allow SSH access. 280 Note that if this is specified, you must be sure the security group allows 281 access to the `ssh_port` given below. 282 283 - `security_group_ids` (array of strings) - A list of security groups as 284 described above. Note that if this is specified, you must omit the 285 `security_group_id`. 286 287 - `security_group_filter` (object) - Filters used to populate the `security_group_ids` field. 288 Example: 289 290 ``` json 291 { 292 "security_group_filter": { 293 "filters": { 294 "tag:Class": "packer" 295 } 296 } 297 } 298 ``` 299 300 This selects the SG's with tag `Class` with the value `packer`. 301 302 - `filters` (map of strings) - filters used to select a `security_group_ids`. 303 Any filter described in the docs for [DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html) 304 is valid. 305 306 `security_group_ids` take precedence over this. 307 308 - `shutdown_behavior` (string) - Automatically terminate instances on shutdown 309 in case Packer exits ungracefully. Possible values are "stop" and "terminate", 310 default is `stop`. 311 312 - `skip_region_validation` (boolean) - Set to true if you want to skip 313 validation of the region configuration option. Default `false`. 314 315 - `snapshot_groups` (array of strings) - A list of groups that have access to 316 create volumes from the snapshot(s). By default no groups have permission to create 317 volumes from the snapshot(s). `all` will make the snapshot publicly accessible. 318 319 - `snapshot_users` (array of strings) - A list of account IDs that have access to 320 create volumes from the snapshot(s). By default no additional users other than the 321 user creating the AMI has permissions to create volumes from the backing snapshot(s). 322 323 - `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot. 324 They will override AMI tags if already applied to snapshot. This is a 325 [template engine](../templates/engine.html), 326 see [Build template data](#build-template-data) for more information. 327 328 - `source_ami_filter` (object) - Filters used to populate the `source_ami` field. 329 Example: 330 331 ``` json 332 { 333 "source_ami_filter": { 334 "filters": { 335 "virtualization-type": "hvm", 336 "name": "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*", 337 "root-device-type": "ebs" 338 }, 339 "owners": ["099720109477"], 340 "most_recent": true 341 } 342 } 343 ``` 344 345 This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical. 346 NOTE: This will fail unless *exactly* one AMI is returned. In the above 347 example, `most_recent` will cause this to succeed by selecting the newest image. 348 349 - `filters` (map of strings) - filters used to select a `source_ami`. 350 NOTE: This will fail unless *exactly* one AMI is returned. 351 Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html) 352 is valid. 353 354 - `owners` (array of strings) - Filters the images by their owner. You may 355 specify one or more AWS account IDs, "self" (which will use the account 356 whose credentials you are using to run Packer), or an AWS owner alias: 357 for example, `amazon`, `aws-marketplace`, or `microsoft`. 358 This option is required for security reasons. 359 360 - `most_recent` (boolean) - Selects the newest created image when true. 361 This is most useful for selecting a daily distro build. 362 363 You may set this in place of `source_ami` or in conjunction with it. If you 364 set this in conjunction with `source_ami`, the `source_ami` will be added to 365 the filter. The provided `source_ami` must meet all of the filtering criteria 366 provided in `source_ami_filter`; this pins the AMI returned by the filter, 367 but will cause Packer to fail if the `source_ami` does not exist. 368 369 - `spot_price` (string) - The maximum hourly price to pay for a spot instance 370 to create the AMI. Spot instances are a type of instance that EC2 starts 371 when the current spot price is less than the maximum price you specify. Spot 372 price will be updated based on available spot instance capacity and current 373 spot instance requests. It may save you some costs. You can set this to 374 `auto` for Packer to automatically discover the best spot price or to "0" 375 to use an on demand instance (default). 376 377 - `spot_price_auto_product` (string) - Required if `spot_price` is set 378 to `auto`. This tells Packer what sort of AMI you're launching to find the 379 best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`, 380 `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)`, `Windows (Amazon VPC)` 381 382 - `spot_tags` (object of key/value strings) - Requires `spot_price` to 383 be set. This tells Packer to apply tags to the spot request that is 384 issued. 385 386 - `sriov_support` (boolean) - Enable enhanced networking (SriovNetSupport but not ENA) 387 on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM 388 policy. Note: you must make sure enhanced networking is enabled on your instance. See [Amazon's 389 documentation on enabling enhanced networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). 390 Default `false`. 391 392 - `ssh_keypair_name` (string) - If specified, this is the key that will be 393 used for SSH with the machine. The key must match a key pair name loaded 394 up into Amazon EC2. By default, this is blank, and Packer will 395 generate a temporary keypair unless 396 [`ssh_password`](../templates/communicator.html#ssh_password) is used. 397 [`ssh_private_key_file`](../templates/communicator.html#ssh_private_key_file) 398 or `ssh_agent_auth` must be specified when `ssh_keypair_name` is utilized. 399 400 - `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to 401 authenticate connections to the source instance. No temporary keypair will 402 be created, and the values of `ssh_password` and `ssh_private_key_file` will 403 be ignored. To use this option with a key pair already configured in the source 404 AMI, leave the `ssh_keypair_name` blank. To associate an existing key pair 405 in AWS with the source instance, set the `ssh_keypair_name` field to the name 406 of the key pair. 407 408 - `ssh_private_ip` (boolean) - No longer supported. See 409 [`ssh_interface`](#ssh_interface). A fixer exists to migrate. 410 411 - `ssh_interface` (string) - One of `public_ip`, `private_ip`, 412 `public_dns`, or `private_dns`. If set, either the public IP address, 413 private IP address, public DNS name or private DNS name will used as the host for SSH. 414 The default behaviour if inside a VPC is to use the public IP address if available, 415 otherwise the private IP address will be used. If not in a VPC the public DNS name 416 will be used. Also works for WinRM. 417 418 Where Packer is configured for an outbound proxy but WinRM traffic should be direct, 419 `ssh_interface` must be set to `private_dns` and `<region>.compute.internal` included 420 in the `NO_PROXY` environment variable. 421 422 - `subnet_id` (string) - If using VPC, the ID of the subnet, such as 423 `subnet-12345def`, where Packer will launch the EC2 instance. This field is 424 required if you are using an non-default VPC. 425 426 - `subnet_filter` (object) - Filters used to populate the `subnet_id` field. 427 Example: 428 429 ``` json 430 { 431 "subnet_filter": { 432 "filters": { 433 "tag:Class": "build" 434 }, 435 "most_free": true, 436 "random": false 437 } 438 } 439 ``` 440 441 This selects the Subnet with tag `Class` with the value `build`, which has 442 the most free IP addresses. 443 NOTE: This will fail unless *exactly* one Subnet is returned. By using 444 `most_free` or `random` one will be selected from those matching the filter. 445 446 - `filters` (map of strings) - filters used to select a `subnet_id`. 447 NOTE: This will fail unless *exactly* one Subnet is returned. 448 Any filter described in the docs for [DescribeSubnets](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html) 449 is valid. 450 451 - `most_free` (boolean) - The Subnet with the most free IPv4 addresses 452 will be used if multiple Subnets matches the filter. 453 454 - `random` (boolean) - A random Subnet will be used if multiple Subnets 455 matches the filter. `most_free` have precendence over this. 456 457 `subnet_id` take precedence over this. 458 459 - `tags` (object of key/value strings) - Tags applied to the AMI and 460 relevant snapshots. This is a 461 [template engine](../templates/engine.html), 462 see [Build template data](#build-template-data) for more information. 463 464 - `temporary_key_pair_name` (string) - The name of the temporary key pair 465 to generate. By default, Packer generates a name that looks like 466 `packer_<UUID>`, where <UUID> is a 36 character unique identifier. 467 468 - `temporary_security_group_source_cidr` (string) - An IPv4 CIDR block to be authorized 469 access to the instance, when packer is creating a temporary security group. 470 The default is `0.0.0.0/0` (i.e., allow any IPv4 source). This is only used 471 when `security_group_id` or `security_group_ids` is not specified. 472 473 - `token` (string) - The access token to use. This is different from the 474 access key and secret key. If you're not sure what this is, then you 475 probably don't need it. This will also be read from the `AWS_SESSION_TOKEN` 476 environmental variable. 477 478 - `user_data` (string) - User data to apply when launching the instance. Note 479 that you need to be careful about escaping characters due to the templates 480 being JSON. It is often more convenient to use `user_data_file`, instead. 481 482 - `user_data_file` (string) - Path to a file that will be used for the user 483 data when launching the instance. 484 485 - `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID 486 in order to create a temporary security group within the VPC. Requires `subnet_id` 487 to be set. If this field is left blank, Packer will try to get the VPC ID from the 488 `subnet_id`. 489 490 - `vpc_filter` (object) - Filters used to populate the `vpc_id` field. 491 Example: 492 493 ``` json 494 { 495 "vpc_filter": { 496 "filters": { 497 "tag:Class": "build", 498 "isDefault": "false", 499 "cidr": "/24" 500 } 501 } 502 } 503 ``` 504 505 This selects the VPC with tag `Class` with the value `build`, which is not the 506 default VPC, and have a IPv4 CIDR block of `/24`. 507 NOTE: This will fail unless *exactly* one VPC is returned. 508 509 - `filters` (map of strings) - filters used to select a `vpc_id`. 510 NOTE: This will fail unless *exactly* one VPC is returned. 511 Any filter described in the docs for [DescribeVpcs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcs.html) 512 is valid. 513 514 `vpc_id` take precedence over this. 515 516 - `windows_password_timeout` (string) - The timeout for waiting for a Windows 517 password for Windows instances. Defaults to 20 minutes. Example value: `10m` 518 519 ## Basic Example 520 521 Here is a basic example. You will need to provide access keys, and may need to 522 change the AMI IDs according to what images exist at the time the template is run: 523 524 ``` json 525 { 526 "type": "amazon-ebs", 527 "access_key": "YOUR KEY HERE", 528 "secret_key": "YOUR SECRET KEY HERE", 529 "region": "us-east-1", 530 "source_ami": "ami-fce3c696", 531 "instance_type": "t2.micro", 532 "ssh_username": "ubuntu", 533 "ami_name": "packer-quick-start {{timestamp}}" 534 } 535 ``` 536 537 -> **Note:** Packer can also read the access key and secret access key from 538 environmental variables. See the configuration reference in the section above 539 for more information on what environmental variables Packer will look for. 540 541 Further information on locating AMI IDs and their relationship to instance types 542 and regions can be found in the AWS EC2 Documentation 543 [for Linux](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html) 544 or [for Windows](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/finding-an-ami.html). 545 546 ## Accessing the Instance to Debug 547 548 If you need to access the instance to debug for some reason, run the builder 549 with the `-debug` flag. In debug mode, the Amazon builder will save the private 550 key in the current directory and will output the DNS or IP information as well. 551 You can use this information to access the instance as it is running. 552 553 ## AMI Block Device Mappings Example 554 555 Here is an example using the optional AMI block device mappings. Our 556 configuration of `launch_block_device_mappings` will expand the root volume 557 (`/dev/sda`) to 40gb during the build (up from the default of 8gb). With 558 `ami_block_device_mappings` AWS will attach additional volumes `/dev/sdb` and 559 `/dev/sdc` when we boot a new instance of our AMI. 560 561 ``` json 562 { 563 "type": "amazon-ebs", 564 "access_key": "YOUR KEY HERE", 565 "secret_key": "YOUR SECRET KEY HERE", 566 "region": "us-east-1", 567 "source_ami": "ami-fce3c696", 568 "instance_type": "t2.micro", 569 "ssh_username": "ubuntu", 570 "ami_name": "packer-quick-start {{timestamp}}", 571 "launch_block_device_mappings": [ 572 { 573 "device_name": "/dev/sda1", 574 "volume_size": 40, 575 "volume_type": "gp2", 576 "delete_on_termination": true 577 } 578 ], 579 "ami_block_device_mappings": [ 580 { 581 "device_name": "/dev/sdb", 582 "virtual_name": "ephemeral0" 583 }, 584 { 585 "device_name": "/dev/sdc", 586 "virtual_name": "ephemeral1" 587 } 588 ] 589 } 590 ``` 591 592 ## Build template data 593 594 In configuration directives marked as a template engine above, the 595 following variables are available: 596 597 - `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI. 598 - `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI. 599 - `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI. 600 - `SourceAMITags` - The source AMI Tags, as a `map[string]string` object. 601 602 ## Tag Example 603 604 Here is an example using the optional AMI tags. This will add the tags 605 `OS_Version` and `Release` to the finished AMI. As before, you will need to 606 provide your access keys, and may need to change the source AMI ID based on what 607 images exist when this template is run: 608 609 ``` json 610 { 611 "type": "amazon-ebs", 612 "access_key": "YOUR KEY HERE", 613 "secret_key": "YOUR SECRET KEY HERE", 614 "region": "us-east-1", 615 "source_ami": "ami-fce3c696", 616 "instance_type": "t2.micro", 617 "ssh_username": "ubuntu", 618 "ami_name": "packer-quick-start {{timestamp}}", 619 "tags": { 620 "OS_Version": "Ubuntu", 621 "Release": "Latest", 622 "Base_AMI_Name": "{{ .SourceAMIName }}", 623 "Extra": "{{ .SourceAMITags.TagName }}" 624 } 625 } 626 ``` 627 628 -> **Note:** Packer uses pre-built AMIs as the source for building images. 629 These source AMIs may include volumes that are not flagged to be destroyed on 630 termination of the instance building the new image. Packer will attempt to clean 631 up all residual volumes that are not designated by the user to remain after 632 termination. If you need to preserve those source volumes, you can overwrite the 633 termination setting by specifying `delete_on_termination=false` in the 634 `launch_block_device_mappings` block for the device. 635 636 ## Windows 2016 Sysprep Commands - For Amazon Windows AMIs Only 637 638 For Amazon Windows 2016 AMIs it is necessary to run Sysprep commands which can be easily added 639 to the provisioner section. 640 641 ```json 642 { 643 "type": "powershell", 644 "inline": [ 645 "C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/InitializeInstance.ps1 -Schedule", 646 "C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/SysprepInstance.ps1 -NoShutdown" 647 ] 648 649 } 650 ```