github.com/aclaygray/packer@v1.3.2/website/source/docs/builders/amazon-ebsvolume.html.md (about) 1 --- 2 description: | 3 The amazon-ebsvolume Packer builder is like the EBS builder, but is intended 4 to create EBS volumes rather than a machine image. 5 layout: docs 6 page_title: 'Amazon EBS Volume - Builders' 7 sidebar_current: 'docs-builders-amazon-ebsvolume' 8 --- 9 10 # EBS Volume Builder 11 12 Type: `amazon-ebsvolume` 13 14 The `amazon-ebsvolume` Packer builder is able to create Amazon Elastic Block 15 Store volumes which are prepopulated with filesystems or data. 16 17 This builder builds EBS volumes by launching an EC2 instance from a source AMI, 18 provisioning that running machine, and then destroying the source machine, 19 keeping the volumes intact. 20 21 This is all done in your own AWS account. The builder will create temporary key 22 pairs, security group rules, etc. that provide it temporary access to the 23 instance while the image is being created. 24 25 The builder does *not* manage EBS Volumes. Once it creates volumes and stores it 26 in your account, it is up to you to use, delete, etc. the volumes. 27 28 -> **Note:** Temporary resources are, by default, all created with the prefix 29 `packer`. This can be useful if you want to restrict the security groups and 30 key pairs Packer is able to operate on. 31 32 ## Configuration Reference 33 34 There are many configuration options available for the builder. They are 35 segmented below into two categories: required and optional parameters. Within 36 each category, the available configuration keys are alphabetized. 37 38 In addition to the options listed here, a 39 [communicator](/docs/templates/communicator.html) can be configured for this 40 builder. 41 42 ### Required: 43 44 - `access_key` (string) - The access key used to communicate with AWS. [Learn 45 how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) 46 47 - `instance_type` (string) - The EC2 instance type to use while building the 48 AMI, such as `m1.small`. 49 50 - `region` (string) - The name of the region, such as `us-east-1`, in which to 51 launch the EC2 instance to create the AMI. 52 53 - `secret_key` (string) - The secret key used to communicate with AWS. [Learn 54 how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) 55 56 - `source_ami` (string) - The initial AMI used as a base for the newly 57 created machine. `source_ami_filter` may be used instead to populate this 58 automatically. 59 60 ### Optional: 61 62 - `ebs_volumes` (array of block device mappings) - Add the block 63 device mappings to the AMI. The block device mappings allow for keys: 64 65 - `device_name` (string) - The device name exposed to the instance (for 66 example, `/dev/sdh` or `xvdh`). Required for every device in the 67 block device mapping. 68 69 - `delete_on_termination` (boolean) - Indicates whether the EBS volume is 70 deleted on instance termination. 71 72 - `encrypted` (boolean) - Indicates whether to encrypt the volume or not 73 74 - `kms_key_id` (string) - The ARN for the KMS encryption key. When 75 specifying `kms_key_id`, `encrypted` needs to be set to `true`. For valid formats 76 see _KmsKeyId_ in the 77 [AWS API docs - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). 78 79 80 - `iops` (number) - The number of I/O operations per second (IOPS) that the 81 volume supports. See the documentation on 82 [IOPs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) 83 for more information 84 85 - `no_device` (boolean) - Suppresses the specified device included in the 86 block device mapping of the AMI 87 88 - `snapshot_id` (string) - The ID of the snapshot 89 90 - `virtual_name` (string) - The virtual device name. See the documentation on 91 [Block Device 92 Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) 93 for more information 94 95 - `volume_size` (number) - The size of the volume, in GiB. Required if not 96 specifying a `snapshot_id` 97 98 - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD) 99 volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic 100 volumes 101 102 - `tags` (map) - Tags to apply to the volume. These are retained after the 103 builder completes. This is a 104 [template engine](/docs/templates/engine.html), 105 see [Build template data](#build-template-data) for more information. 106 107 - `associate_public_ip_address` (boolean) - If using a non-default VPC, public 108 IP addresses are not provided by default. If this is toggled, your new 109 instance will get a Public IP. 110 111 - `availability_zone` (string) - Destination availability zone to launch 112 instance in. Leave this empty to allow Amazon to auto-assign. 113 114 - `block_duration_minutes` (int64) - Requires `spot_price` to 115 be set. The required duration for the Spot Instances (also known as Spot blocks). 116 This value must be a multiple of 60 (60, 120, 180, 240, 300, or 360). 117 You can't specify an Availability Zone group or a launch group if you specify a duration. 118 119 - `custom_endpoint_ec2` (string) - This option is useful if you use a cloud 120 provider whose API is compatible with aws EC2. Specify another endpoint 121 like this `https://ec2.custom.endpoint.com`. 122 123 - `disable_stop_instance` (boolean) - Packer normally stops the build instance 124 after all provisioners have run. For Windows instances, it is sometimes 125 desirable to [run Sysprep](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ami-create-standard.html) 126 which will stop the instance for you. If this is set to true, Packer *will not* 127 stop the instance but will assume that you will send the stop signal 128 yourself through your final provisioner. You can do this with a 129 [windows-shell provisioner](https://www.packer.io/docs/provisioners/windows-shell.html). 130 131 Note that Packer will still wait for the instance to be stopped, and failing 132 to send the stop signal yourself, when you have set this flag to `true`, 133 will cause a timeout. 134 135 Example of a valid shutdown command: 136 137 ``` json 138 { 139 "type": "windows-shell", 140 "inline": ["\"c:\\Program Files\\Amazon\\Ec2ConfigService\\ec2config.exe\" -sysprep"] 141 } 142 ``` 143 144 - `decode_authorization_messages` (boolean) - Enable automatic decoding of any 145 encoded authorization (error) messages using the `sts:DecodeAuthorizationMessage` API. 146 Note: requires that the effective user/role have permissions to `sts:DecodeAuthorizationMessage` 147 on resource `*`. Default `false`. 148 149 - `ebs_optimized` (boolean) - Mark instance as [EBS 150 Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html). 151 Default `false`. 152 153 - `ena_support` (boolean) - Enable enhanced networking (ENA but not SriovNetSupport) 154 on HVM-compatible AMIs. If set, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. 155 If false, this will disable enhanced networking in the final AMI as opposed to passing 156 the setting through unchanged from the source. Note: you must make sure enhanced 157 networking is enabled on your instance. See [Amazon's documentation on enabling enhanced 158 networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). 159 160 - `enable_t2_unlimited` (boolean) - Enabling T2 Unlimited allows the source 161 instance to burst additional CPU beyond its available [CPU Credits] 162 (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-credits-baseline-concepts.html) 163 for as long as the demand exists. 164 This is in contrast to the standard configuration that only allows an 165 instance to consume up to its available CPU Credits. 166 See the AWS documentation for [T2 Unlimited] 167 (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-unlimited.html) 168 and the 'T2 Unlimited Pricing' section of the [Amazon EC2 On-Demand 169 Pricing](https://aws.amazon.com/ec2/pricing/on-demand/) document for more 170 information. 171 By default this option is disabled and Packer will set up a [T2 172 Standard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-std.html) 173 instance instead. 174 175 To use T2 Unlimited you must use a T2 instance type e.g. t2.micro. 176 Additionally, T2 Unlimited cannot be used in conjunction with Spot 177 Instances e.g. when the `spot_price` option has been configured. 178 Attempting to do so will cause an error. 179 180 !> **Warning!** Additional costs may be incurred by enabling T2 181 Unlimited - even for instances that would usually qualify for the 182 [AWS Free Tier](https://aws.amazon.com/free/). 183 184 - `iam_instance_profile` (string) - The name of an [IAM instance 185 profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) 186 to launch the EC2 instance with. 187 188 - `mfa_code` (string) - The MFA [TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm) 189 code. This should probably be a user variable since it changes all the time. 190 191 - `profile` (string) - The profile to use in the shared credentials file for 192 AWS. See Amazon's documentation on [specifying 193 profiles](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-profiles) 194 for more details. 195 196 - `run_tags` (object of key/value strings) - Tags to apply to the instance 197 that is *launched* to create the AMI. These tags are *not* applied to the 198 resulting AMI unless they're duplicated in `tags`. This is a 199 [template engine](/docs/templates/engine.html), 200 see [Build template data](#build-template-data) for more information. 201 202 - `security_group_id` (string) - The ID (*not* the name) of the security group 203 to assign to the instance. By default this is not set and Packer will 204 automatically create a new temporary security group to allow SSH access. 205 Note that if this is specified, you must be sure the security group allows 206 access to the `ssh_port` given below. 207 208 - `security_group_ids` (array of strings) - A list of security groups as 209 described above. Note that if this is specified, you must omit the 210 `security_group_id`. 211 212 - `security_group_filter` (object) - Filters used to populate the `security_group_ids` field. 213 Example: 214 215 ``` json 216 { 217 "security_group_filter": { 218 "filters": { 219 "tag:Class": "packer" 220 } 221 } 222 } 223 ``` 224 225 This selects the SG's with tag `Class` with the value `packer`. 226 227 - `filters` (map of strings) - filters used to select a `security_group_ids`. 228 Any filter described in the docs for [DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html) 229 is valid. 230 231 `security_group_ids` take precedence over this. 232 233 - `shutdown_behavior` (string) - Automatically terminate instances on shutdown 234 in case Packer exits ungracefully. Possible values are `stop` and `terminate`. 235 Defaults to `stop`. 236 237 - `skip_region_validation` (boolean) - Set to `true` if you want to skip 238 validation of the region configuration option. Defaults to `false`. 239 240 - `snapshot_groups` (array of strings) - A list of groups that have access to 241 create volumes from the snapshot(s). By default no groups have permission to create 242 volumes from the snapshot(s). `all` will make the snapshot publicly accessible. 243 244 - `snapshot_users` (array of strings) - A list of account IDs that have access to 245 create volumes from the snapshot(s). By default no additional users other than the 246 user creating the AMI has permissions to create volumes from the backing snapshot(s). 247 248 - `source_ami_filter` (object) - Filters used to populate the `source_ami` field. 249 Example: 250 251 ``` json 252 { 253 "source_ami_filter": { 254 "filters": { 255 "virtualization-type": "hvm", 256 "name": "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*", 257 "root-device-type": "ebs" 258 }, 259 "owners": ["099720109477"], 260 "most_recent": true 261 } 262 } 263 ``` 264 265 This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical. 266 NOTE: This will fail unless *exactly* one AMI is returned. In the above 267 example, `most_recent` will cause this to succeed by selecting the newest image. 268 269 - `filters` (map of strings) - filters used to select a `source_ami`. 270 NOTE: This will fail unless *exactly* one AMI is returned. 271 Any filter described in the docs for [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html) 272 is valid. 273 274 - `owners` (array of strings) - Filters the images by their owner. You may 275 specify one or more AWS account IDs, "self" (which will use the account 276 whose credentials you are using to run Packer), or an AWS owner alias: 277 for example, "amazon", "aws-marketplace", or "microsoft". 278 This option is required for security reasons. 279 280 - `most_recent` (boolean) - Selects the newest created image when true. 281 This is most useful for selecting a daily distro build. 282 283 You may set this in place of `source_ami` or in conjunction with it. If you 284 set this in conjunction with `source_ami`, the `source_ami` will be added to 285 the filter. The provided `source_ami` must meet all of the filtering criteria 286 provided in `source_ami_filter`; this pins the AMI returned by the filter, 287 but will cause Packer to fail if the `source_ami` does not exist. 288 289 - `spot_price` (string) - The maximum hourly price to pay for a spot instance 290 to create the AMI. Spot instances are a type of instance that EC2 starts 291 when the current spot price is less than the maximum price you specify. Spot 292 price will be updated based on available spot instance capacity and current 293 spot instance requests. It may save you some costs. You can set this to 294 `auto` for Packer to automatically discover the best spot price or to `0` 295 to use an on-demand instance (default). 296 297 - `spot_price_auto_product` (string) - Required if `spot_price` is set 298 to `auto`. This tells Packer what sort of AMI you're launching to find the 299 best spot price. This must be one of: `Linux/UNIX`, `SUSE Linux`, `Windows`, 300 `Linux/UNIX (Amazon VPC)`, `SUSE Linux (Amazon VPC)` or `Windows (Amazon VPC)` 301 302 - `spot_tags` (object of key/value strings) - Requires `spot_price` to 303 be set. This tells Packer to apply tags to the spot request that is 304 issued. 305 306 - `sriov_support` (boolean) - Enable enhanced networking (SriovNetSupport but not ENA) 307 on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM 308 policy. Note: you must make sure enhanced networking is enabled on your instance. See [Amazon's 309 documentation on enabling enhanced networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). 310 Default `false`. 311 312 - `ssh_keypair_name` (string) - If specified, this is the key that will be 313 used for SSH with the machine. By default, this is blank, and Packer will 314 generate a temporary key pair unless 315 [`ssh_password`](/docs/templates/communicator.html#ssh_password) is used. 316 [`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file) 317 must be specified with this. 318 319 - `ssh_private_ip` (boolean) - No longer supported. See 320 [`ssh_interface`](#ssh_interface). A fixer exists to migrate. 321 322 - `ssh_interface` (string) - One of `public_ip`, `private_ip`, 323 `public_dns` or `private_dns`. If set, either the public IP address, 324 private IP address, public DNS name or private DNS name will used as the host for SSH. 325 The default behaviour if inside a VPC is to use the public IP address if available, 326 otherwise the private IP address will be used. If not in a VPC the public DNS name 327 will be used. Also works for WinRM. 328 329 Where Packer is configured for an outbound proxy but WinRM traffic should be direct, 330 `ssh_interface` must be set to `private_dns` and `<region>.compute.internal` included 331 in the `NO_PROXY` environment variable. 332 333 - `subnet_id` (string) - If using VPC, the ID of the subnet, such as 334 `subnet-12345def`, where Packer will launch the EC2 instance. This field is 335 required if you are using an non-default VPC. 336 337 - `subnet_filter` (object) - Filters used to populate the `subnet_id` field. 338 Example: 339 340 ``` json 341 { 342 "subnet_filter": { 343 "filters": { 344 "tag:Class": "build" 345 }, 346 "most_free": true, 347 "random": false 348 } 349 } 350 ``` 351 352 This selects the Subnet with tag `Class` with the value `build`, which has 353 the most free IP addresses. 354 NOTE: This will fail unless *exactly* one Subnet is returned. By using 355 `most_free` or `random` one will be selected from those matching the filter. 356 357 - `filters` (map of strings) - filters used to select a `subnet_id`. 358 NOTE: This will fail unless *exactly* one Subnet is returned. 359 Any filter described in the docs for [DescribeSubnets](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html) 360 is valid. 361 362 - `most_free` (boolean) - The Subnet with the most free IPv4 addresses 363 will be used if multiple Subnets matches the filter. 364 365 - `random` (boolean) - A random Subnet will be used if multiple Subnets 366 matches the filter. `most_free` have precendence over this. 367 368 `subnet_id` take precedence over this. 369 370 - `temporary_key_pair_name` (string) - The name of the temporary key pair 371 to generate. By default, Packer generates a name that looks like 372 `packer_<UUID>`, where <UUID> is a 36 character unique identifier. 373 374 - `temporary_security_group_source_cidr` (string) - An IPv4 CIDR block to be authorized 375 access to the instance, when packer is creating a temporary security group. 376 The default is `0.0.0.0/0` (i.e., allow any IPv4 source). This is only used 377 when `security_group_id` or `security_group_ids` is not specified. 378 379 - `token` (string) - The access token to use. This is different from the 380 access key and secret key. If you're not sure what this is, then you 381 probably don't need it. This will also be read from the `AWS_SESSION_TOKEN` 382 environmental variable. 383 384 - `user_data` (string) - User data to apply when launching the instance. Note 385 that you need to be careful about escaping characters due to the templates 386 being JSON. It is often more convenient to use `user_data_file`, instead. 387 388 - `user_data_file` (string) - Path to a file that will be used for the user 389 data when launching the instance. 390 391 - `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID 392 in order to create a temporary security group within the VPC. Requires `subnet_id` 393 to be set. If this field is left blank, Packer will try to get the VPC ID from the 394 `subnet_id`. 395 396 - `vpc_filter` (object) - Filters used to populate the `vpc_id` field. 397 Example: 398 399 ``` json 400 { 401 "vpc_filter": { 402 "filters": { 403 "tag:Class": "build", 404 "isDefault": "false", 405 "cidr": "/24" 406 } 407 } 408 } 409 ``` 410 411 This selects the VPC with tag `Class` with the value `build`, which is not the 412 default VPC, and have a IPv4 CIDR block of `/24`. 413 NOTE: This will fail unless *exactly* one VPC is returned. 414 415 - `filters` (map of strings) - filters used to select a `vpc_id`. 416 NOTE: This will fail unless *exactly* one VPC is returned. 417 Any filter described in the docs for [DescribeVpcs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcs.html) 418 is valid. 419 420 `vpc_id` take precedence over this. 421 422 - `windows_password_timeout` (string) - The timeout for waiting for a Windows 423 password for Windows instances. Defaults to 20 minutes. Example value: `10m` 424 425 ## Basic Example 426 427 ``` json 428 { 429 "type" : "amazon-ebsvolume", 430 "secret_key" : "YOUR SECRET KEY HERE", 431 "access_key" : "YOUR KEY HERE", 432 "region" : "us-east-1", 433 "ssh_username" : "ubuntu", 434 "instance_type" : "t2.medium", 435 "source_ami" : "ami-40d28157", 436 "ebs_volumes" : [ 437 { 438 "volume_type" : "gp2", 439 "device_name" : "/dev/xvdf", 440 "delete_on_termination" : false, 441 "tags" : { 442 "zpool" : "data", 443 "Name" : "Data1" 444 }, 445 "volume_size" : 10 446 }, 447 { 448 "volume_type" : "gp2", 449 "device_name" : "/dev/xvdg", 450 "tags" : { 451 "zpool" : "data", 452 "Name" : "Data2" 453 }, 454 "delete_on_termination" : false, 455 "volume_size" : 10 456 }, 457 { 458 "volume_size" : 10, 459 "tags" : { 460 "Name" : "Data3", 461 "zpool" : "data" 462 }, 463 "delete_on_termination" : false, 464 "device_name" : "/dev/xvdh", 465 "volume_type" : "gp2" 466 } 467 ] 468 } 469 ``` 470 471 -> **Note:** Packer can also read the access key and secret access key from 472 environmental variables. See the configuration reference in the section above 473 for more information on what environmental variables Packer will look for. 474 475 Further information on locating AMI IDs and their relationship to instance 476 types and regions can be found in the AWS EC2 Documentation 477 [for Linux](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html) 478 or [for Windows](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/finding-an-ami.html). 479 480 ## Accessing the Instance to Debug 481 482 If you need to access the instance to debug for some reason, run the builder 483 with the `-debug` flag. In debug mode, the Amazon builder will save the private 484 key in the current directory and will output the DNS or IP information as well. 485 You can use this information to access the instance as it is running. 486 487 ## Build template data 488 489 In configuration directives marked as a template engine above, the 490 following variables are available: 491 492 - `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI. 493 - `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI. 494 - `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI. 495 - `SourceAMITags` - The source AMI Tags, as a `map[string]string` object. 496 497 -> **Note:** Packer uses pre-built AMIs as the source for building images. 498 These source AMIs may include volumes that are not flagged to be destroyed on 499 termination of the instance building the new image. In addition to those volumes 500 created by this builder, any volumes inn the source AMI which are not marked for 501 deletion on termination will remain in your account.