diff --git a/builder/amazon/common/access_config.go b/builder/amazon/common/access_config.go index 3dd5b2fa4..c1b9ed2fb 100644 --- a/builder/amazon/common/access_config.go +++ b/builder/amazon/common/access_config.go @@ -86,33 +86,39 @@ type AccessConfig struct { // environmental variable. Token string `mapstructure:"token" required:"false"` session *session.Session - // Get credentials from Hashicorp Vault's aws - // secrets engine. You must already have created a role to use. For more - // information about generating credentials via the Vault engine, see the - // Vault - // docs. + // Get credentials from Hashicorp Vault's aws secrets engine. You must + // already have created a role to use. For more information about + // generating credentials via the Vault engine, see the [Vault + // docs.](https://www.vaultproject.io/api/secret/aws/index.html#generate-credentials) // If you set this flag, you must also set the below options: - // - `name` (string) - Required. Specifies the name of the role to generate - // credentials against. This is part of the request URL. - // - `engine_name` (string) - The name of the aws secrets engine. In the - // Vault docs, this is normally referred to as "aws", and Packer will - // default to "aws" if `engine_name` is not set. - // - `role_arn` (string)- The ARN of the role to assume if credential\_type - // on the Vault role is assumed\_role. Must match one of the allowed role - // ARNs in the Vault role. Optional if the Vault role only allows a single - // AWS role ARN; required otherwise. - // - `ttl` (string) - Specifies the TTL for the use of the STS token. This - // is specified as a string with a duration suffix. Valid only when - // credential\_type is assumed\_role or federation\_token. When not - // specified, the default\_sts\_ttl set for the role will be used. If that - // is also not set, then the default value of 3600s will be used. AWS - // places limits on the maximum TTL allowed. See the AWS documentation on - // the DurationSeconds parameter for AssumeRole (for assumed\_role - // credential types) and GetFederationToken (for federation\_token - // credential types) for more details. + // - `name` (string) - Required. Specifies the name of the role to generate + // credentials against. This is part of the request URL. + // - `engine_name` (string) - The name of the aws secrets engine. In the + // Vault docs, this is normally referred to as "aws", and Packer will + // default to "aws" if `engine_name` is not set. + // - `role_arn` (string)- The ARN of the role to assume if credential\_type + // on the Vault role is assumed\_role. Must match one of the allowed role + // ARNs in the Vault role. Optional if the Vault role only allows a single + // AWS role ARN; required otherwise. + // - `ttl` (string) - Specifies the TTL for the use of the STS token. This + // is specified as a string with a duration suffix. Valid only when + // credential\_type is assumed\_role or federation\_token. When not + // specified, the default\_sts\_ttl set for the role will be used. If that + // is also not set, then the default value of 3600s will be used. AWS + // places limits on the maximum TTL allowed. See the AWS documentation on + // the DurationSeconds parameter for AssumeRole (for assumed\_role + // credential types) and GetFederationToken (for federation\_token + // credential types) for more details. // - // Example: - // `json { "vault_aws_engine": { "name": "myrole", "role_arn": "myarn", + // ``` json + // { + // "vault_aws_engine": { + // "name": "myrole", + // "role_arn": "myarn", + // "ttl": "3600s" + // } + // } + // ``` VaultAWSEngine VaultAWSEngineOptions `mapstructure:"vault_aws_engine" required:"false"` getEC2Connection func() ec2iface.EC2API diff --git a/builder/amazon/common/ami_config.go b/builder/amazon/common/ami_config.go index efd919424..b43b0ed13 100644 --- a/builder/amazon/common/ami_config.go +++ b/builder/amazon/common/ami_config.go @@ -59,13 +59,12 @@ type AMIConfig struct { // documentation on enabling enhanced // networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). AMIENASupport *bool `mapstructure:"ena_support" required:"false"` - // Enable enhanced networking (SriovNetSupport but - // not ENA) on HVM-compatible AMIs. If true, add - // ec2:ModifyInstanceAttribute to your AWS IAM policy. Note: you must make - // sure enhanced networking is enabled on your instance. See Amazon's - // documentation on enabling enhanced - // networking. - // Default false. + // Enable enhanced networking (SriovNetSupport but not ENA) on + // HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your + // AWS IAM policy. Note: you must make sure enhanced networking is enabled + // on your instance. See [Amazon's documentation on enabling enhanced + // networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). + // Default `false`. AMISriovNetSupport bool `mapstructure:"sriov_support" required:"false"` // Force Packer to first deregister an existing // AMI if one with the same name already exists. Default false. @@ -87,20 +86,21 @@ type AMIConfig struct { // This field is validated by Packer, when using an alias, you will have to // prefix `kms_key_id` with `alias/`. AMIKmsKeyId string `mapstructure:"kms_key_id" required:"false"` - // a map of regions to copy the ami to, along with the custom kms key id - // (alias or arn) to use for encryption for that region. Keys must match - // the regions provided in ami_regions. If you just want to encrypt using a - // default ID, you can stick with kms_key_id and ami_regions. If you want a + // regions to copy the ami to, along with the custom kms key id (alias or + // arn) to use for encryption for that region. Keys must match the regions + // provided in `ami_regions`. If you just want to encrypt using a default + // ID, you can stick with `kms_key_id` and `ami_regions`. If you want a // region to be encrypted with that region's default key ID, you can use an - // empty string "" instead of a key id in this map. (e.g. "us-east-1": "") - // However, you cannot use default key IDs if you are using this in - // conjunction with snapshot_users -- in that situation you must use custom - // keys. For valid formats see KmsKeyId in the AWS API docs - CopyImage. + // empty string `""` instead of a key id in this map. (e.g. `"us-east-1": + // ""`) However, you cannot use default key IDs if you are using this in + // conjunction with `snapshot_users` -- in that situation you must use + // custom keys. For valid formats see *KmsKeyId* in the [AWS API docs - + // CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). AMIRegionKMSKeyIDs map[string]string `mapstructure:"region_kms_key_ids" required:"false"` // Tags to apply to snapshot. // They will override AMI tags if already applied to snapshot. This is a - // template engine, see Build template - // data for more information. + // [template engine](../templates/engine.html), see [Build template + // data](#build-template-data) for more information. SnapshotTags TagMap `mapstructure:"snapshot_tags" required:"false"` // A list of account IDs that have // access to create volumes from the snapshot(s). By default no additional diff --git a/builder/amazon/common/block_device.go b/builder/amazon/common/block_device.go index 494a71e9c..39dabb60d 100644 --- a/builder/amazon/common/block_device.go +++ b/builder/amazon/common/block_device.go @@ -69,27 +69,75 @@ type BlockDevices struct { } type AMIBlockDevices struct { - // Add one or - // more block device - // mappings + // Add one or more [block device + // mappings](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html) // to the AMI. These will be attached when booting a new instance from your - // AMI. If this field is populated, and you are building from an existing source image, - // the block device mappings in the source image will be overwritten. This means you - // must have a block device mapping entry for your root volume, root_volume_size, - // and root_device_name. `Your options here may vary depending on the type of VM - // you use. The block device mappings allow for the following configuration: + // AMI. To add a block device during the Packer build see + // `launch_block_device_mappings` below. Your options here may vary + // depending on the type of VM you use. The block device mappings allow for + // the following configuration: + // - `delete_on_termination` (boolean) - Indicates whether the EBS volume is + // deleted on instance termination. Default `false`. **NOTE**: If this + // value is not explicitly set to `true` and volumes are not cleaned up by + // an alternative method, additional volumes will accumulate after every + // build. + // + // - `device_name` (string) - The device name exposed to the instance (for + // example, `/dev/sdh` or `xvdh`). Required for every device in the block + // device mapping. + // + // - `encrypted` (boolean) - Indicates whether or not to encrypt the volume. + // By default, Packer will keep the encryption setting to what it was in + // the source image. Setting `false` will result in an unencrypted device, + // and `true` will result in an encrypted one. + // + // - `iops` (number) - The number of I/O operations per second (IOPS) that + // the volume supports. See the documentation on + // [IOPs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) + // for more information + // + // - `kms_key_id` (string) - The ARN for the KMS encryption key. When + // specifying `kms_key_id`, `encrypted` needs to be set to `true`. For + // valid formats see *KmsKeyId* in the [AWS API docs - + // CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). + // + // - `no_device` (boolean) - Suppresses the specified device included in the + // block device mapping of the AMI. + // + // - `snapshot_id` (string) - The ID of the snapshot. + // + // - `virtual_name` (string) - The virtual device name. See the + // documentation on [Block Device + // Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) + // for more information. + // + // - `volume_size` (number) - The size of the volume, in GiB. Required if + // not specifying a `snapshot_id`. + // + // - `volume_type` (string) - The volume type. `gp2` for General Purpose + // (SSD) volumes, `io1` for Provisioned IOPS (SSD) volumes, `st1` for + // Throughput Optimized HDD, `sc1` for Cold HDD, and `standard` for + // Magnetic volumes. AMIMappings []BlockDevice `mapstructure:"ami_block_device_mappings" required:"false"` } type LaunchBlockDevices struct { - // Add one - // or more block devices before the Packer build starts. If you add instance - // store volumes or EBS volumes in addition to the root device volume, the - // created AMI will contain block device mapping information for those - // volumes. Amazon creates snapshots of the source instance's root volume and - // any other EBS volumes described here. When you launch an instance from this - // new AMI, the instance automatically launches with these additional volumes, - // and will restore them from snapshots taken from the source instance. + // Add one or more block devices before the Packer build starts. If you add + // instance store volumes or EBS volumes in addition to the root device + // volume, the created AMI will contain block device mapping information + // for those volumes. Amazon creates snapshots of the source instance's + // root volume and any other EBS volumes described here. When you launch an + // instance from this new AMI, the instance automatically launches with + // these additional volumes, and will restore them from snapshots taken + // from the source instance. + // + // In addition to the fields available in ami_block_device_mappings, you + // may optionally use the following field: + // - `omit_from_artifact` (boolean) - If true, this block device will not + // be snapshotted and the created AMI will not contain block device mapping + // information for this volume. If false, the block device will be mapped + // into the final created AMI. Set this option to true if you need a block + // device mounted in the surrogate AMI but not in the final created AMI. LaunchMappings []BlockDevice `mapstructure:"launch_block_device_mappings" required:"false"` } diff --git a/builder/amazon/common/run_config.go b/builder/amazon/common/run_config.go index 11c1f0e14..0f038f0d6 100644 --- a/builder/amazon/common/run_config.go +++ b/builder/amazon/common/run_config.go @@ -149,14 +149,14 @@ type RunConfig struct { // `security_group_ids`. Any filter described in the docs for // [DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html) // is valid. - + // // `security_group_ids` take precedence over this. SecurityGroupFilter SecurityGroupFilterOptions `mapstructure:"security_group_filter" required:"false"` - // Tags to apply to the instance - // that is launched to create the AMI. These tags are not applied to the - // resulting AMI unless they're duplicated in tags. This is a template - // engine, see Build template - // data for more information. + // Tags to apply to the instance that is *launched* to create the AMI. + // These tags are *not* applied to the resulting AMI unless they're + // duplicated in `tags`. This is a [template + // engine](/docs/templates/engine.html), see [Build template + // data](#build-template-data) for more information. RunTags map[string]string `mapstructure:"run_tags" required:"false"` // The ID (not the name) of the security // group to assign to the instance. By default this is not set and Packer will @@ -173,8 +173,47 @@ type RunConfig struct { // AMI with a root volume snapshot that you have access to. Note: this is not // used when from_scratch is set to true. SourceAmi string `mapstructure:"source_ami" required:"true"` - // Filters used to populate the source_ami + // Filters used to populate the `source_ami` // field. Example: + // + // ``` json + // { + // "source_ami_filter": { + // "filters": { + // "virtualization-type": "hvm", + // "name": "ubuntu/images/\*ubuntu-xenial-16.04-amd64-server-\*", + // "root-device-type": "ebs" + // }, + // "owners": ["099720109477"], + // "most_recent": true + // } + // } + // ``` + // + // This selects the most recent Ubuntu 16.04 HVM EBS AMI from Canonical. NOTE: + // This will fail unless *exactly* one AMI is returned. In the above example, + // `most_recent` will cause this to succeed by selecting the newest image. + // + // - `filters` (map of strings) - filters used to select a `source_ami`. + // NOTE: This will fail unless *exactly* one AMI is returned. Any filter + // described in the docs for + // [DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html) + // is valid. + // + // - `owners` (array of strings) - Filters the images by their owner. You + // may specify one or more AWS account IDs, "self" (which will use the + // account whose credentials you are using to run Packer), or an AWS owner + // alias: for example, `amazon`, `aws-marketplace`, or `microsoft`. This + // option is required for security reasons. + // + // - `most_recent` (boolean) - Selects the newest created image when true. + // This is most useful for selecting a daily distro build. + // + // You may set this in place of `source_ami` or in conjunction with it. If you + // set this in conjunction with `source_ami`, the `source_ami` will be added + // to the filter. The provided `source_ami` must meet all of the filtering + // criteria provided in `source_ami_filter`; this pins the AMI returned by the + // filter, but will cause Packer to fail if the `source_ami` does not exist. SourceAmiFilter AmiFilterOptions `mapstructure:"source_ami_filter" required:"false"` // a list of acceptable instance // types to run your build on. We will request a spot instance using the max @@ -203,8 +242,39 @@ type RunConfig struct { // Requires spot_price to be // set. This tells Packer to apply tags to the spot request that is issued. SpotTags map[string]string `mapstructure:"spot_tags" required:"false"` - // Filters used to populate the subnet_id field. + // Filters used to populate the `subnet_id` field. // Example: + // + // ``` json + // { + // "subnet_filter": { + // "filters": { + // "tag:Class": "build" + // }, + // "most_free": true, + // "random": false + // } + // } + // ``` + // + // This selects the Subnet with tag `Class` with the value `build`, which has + // the most free IP addresses. NOTE: This will fail unless *exactly* one + // Subnet is returned. By using `most_free` or `random` one will be selected + // from those matching the filter. + // + // - `filters` (map of strings) - filters used to select a `subnet_id`. + // NOTE: This will fail unless *exactly* one Subnet is returned. Any + // filter described in the docs for + // [DescribeSubnets](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html) + // is valid. + // + // - `most_free` (boolean) - The Subnet with the most free IPv4 addresses + // will be used if multiple Subnets matches the filter. + // + // - `random` (boolean) - A random Subnet will be used if multiple Subnets + // matches the filter. `most_free` have precendence over this. + // + // `subnet_id` take precedence over this. SubnetFilter SubnetFilterOptions `mapstructure:"subnet_filter" required:"false"` // If using VPC, the ID of the subnet, such as // subnet-12345def, where Packer will launch the EC2 instance. This field is @@ -212,10 +282,13 @@ type RunConfig struct { SubnetId string `mapstructure:"subnet_id" required:"false"` // The name of the temporary key pair to // generate. By default, Packer generates a name that looks like - // packer_, where is a 36 character unique identifier. + // `packer_`, where <UUID> is a 36 character unique identifier. TemporaryKeyPairName string `mapstructure:"temporary_key_pair_name" required:"false"` - // A list of IPv4 - // CIDR blocks to be authorized access to the instance, when packer is creating a temporary security group. + // A list of IPv4 CIDR blocks to be authorized access to the instance, when + // packer is creating a temporary security group. + // + // The default is [`0.0.0.0/0`] (i.e., allow any IPv4 source). This is only + // used when `security_group_id` or `security_group_ids` is not specified. TemporarySGSourceCidrs []string `mapstructure:"temporary_security_group_source_cidrs" required:"false"` // User data to apply when launching the instance. Note // that you need to be careful about escaping characters due to the templates diff --git a/builder/amazon/ebs/builder.go b/builder/amazon/ebs/builder.go index d847f9d57..4554e3070 100644 --- a/builder/amazon/ebs/builder.go +++ b/builder/amazon/ebs/builder.go @@ -1,3 +1,5 @@ +//go:generate struct-markdown + // The amazonebs package contains a packer.Builder implementation that // builds AMIs for Amazon EC2. // @@ -28,7 +30,12 @@ type Config struct { awscommon.AMIConfig `mapstructure:",squash"` awscommon.BlockDevices `mapstructure:",squash"` awscommon.RunConfig `mapstructure:",squash"` - VolumeRunTags awscommon.TagMap `mapstructure:"run_volume_tags"` + // Tags to apply to the volumes that are *launched* to create the AMI. + // These tags are *not* applied to the resulting AMI unless they're + // duplicated in `tags`. This is a [template + // engine](/docs/templates/engine.html), see [Build template + // data](#build-template-data) for more information. + VolumeRunTags awscommon.TagMap `mapstructure:"run_volume_tags"` ctx interpolate.Context } diff --git a/builder/amazon/ebssurrogate/builder.go b/builder/amazon/ebssurrogate/builder.go index 92ca1a76f..e48f5bdf3 100644 --- a/builder/amazon/ebssurrogate/builder.go +++ b/builder/amazon/ebssurrogate/builder.go @@ -27,10 +27,19 @@ type Config struct { awscommon.RunConfig `mapstructure:",squash"` awscommon.BlockDevices `mapstructure:",squash"` awscommon.AMIConfig `mapstructure:",squash"` - // A block device mapping - // describing the root device of the AMI. This looks like the mappings in - // ami_block_device_mapping, except with an additional field: - RootDevice RootBlockDevice `mapstructure:"ami_root_device" required:"true"` + // A block device mapping describing the root device of the AMI. This looks + // like the mappings in `ami_block_device_mapping`, except with an + // additional field: + // + // - `source_device_name` (string) - The device name of the block device on + // the source instance to be used as the root device for the AMI. This + // must correspond to a block device in `launch_block_device_mapping`. + RootDevice RootBlockDevice `mapstructure:"ami_root_device" required:"true"` + // Tags to apply to the volumes that are *launched* to create the AMI. + // These tags are *not* applied to the resulting AMI unless they're + // duplicated in `tags`. This is a [template + // engine](/docs/templates/engine.html), see [Build template + // data](#build-template-data) for more information. VolumeRunTags awscommon.TagMap `mapstructure:"run_volume_tags"` // what architecture to use when registering the // final AMI; valid options are "x86_64" or "arm64". Defaults to "x86_64". diff --git a/builder/amazon/ebsvolume/builder.go b/builder/amazon/ebsvolume/builder.go index 3556dcc61..b715f2726 100644 --- a/builder/amazon/ebsvolume/builder.go +++ b/builder/amazon/ebsvolume/builder.go @@ -27,22 +27,19 @@ type Config struct { // Add the block device // mappings to the AMI. The block device mappings allow for keys: VolumeMappings []BlockDevice `mapstructure:"ebs_volumes" required:"false"` - // Enable enhanced networking (ENA but not - // SriovNetSupport) on HVM-compatible AMIs. If set, add - // ec2:ModifyInstanceAttribute to your AWS IAM policy. If false, this will - // disable enhanced networking in the final AMI as opposed to passing the - // setting through unchanged from the source. Note: you must make sure - // enhanced networking is enabled on your instance. See Amazon's - // documentation on enabling enhanced - // networking. + // Enable enhanced networking (ENA but not SriovNetSupport) on + // HVM-compatible AMIs. If set, add ec2:ModifyInstanceAttribute to your AWS + // IAM policy. If false, this will disable enhanced networking in the final + // AMI as opposed to passing the setting through unchanged from the source. + // Note: you must make sure enhanced networking is enabled on your + // instance. See Amazon's documentation on enabling enhanced networking. AMIENASupport *bool `mapstructure:"ena_support" required:"false"` - // Enable enhanced networking (SriovNetSupport but - // not ENA) on HVM-compatible AMIs. If true, add - // ec2:ModifyInstanceAttribute to your AWS IAM policy. Note: you must make - // sure enhanced networking is enabled on your instance. See Amazon's - // documentation on enabling enhanced - // networking. - // Default false. + // Enable enhanced networking (SriovNetSupport but not ENA) on + // HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your + // AWS IAM policy. Note: you must make sure enhanced networking is enabled + // on your instance. See [Amazon's documentation on enabling enhanced + // networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking). + // Default `false`. AMISriovNetSupport bool `mapstructure:"sriov_support" required:"false"` launchBlockDevices awscommon.BlockDevices