From 8b4993e44c9fa523c4ce692c3a0392087e0813c1 Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Fri, 14 Aug 2020 02:35:35 -0700 Subject: [PATCH] fix docs for kms key ids (#9766) --- builder/amazon/common/ami_config.go | 28 ++++++++++++++----- builder/amazon/common/block_device.go | 21 ++++++++------ .../amazon/common/AMIConfig-not-required.mdx | 28 ++++++++++++++----- .../common/BlockDevice-not-required.mdx | 12 ++++---- .../builder/amazon/common/BlockDevice.mdx | 9 ++++-- 5 files changed, 68 insertions(+), 30 deletions(-) diff --git a/builder/amazon/common/ami_config.go b/builder/amazon/common/ami_config.go index 8569753e3..e498ebbaa 100644 --- a/builder/amazon/common/ami_config.go +++ b/builder/amazon/common/ami_config.go @@ -79,18 +79,32 @@ type AMIConfig struct { // Default false. AMIForceDeleteSnapshot bool `mapstructure:"force_delete_snapshot" required:"false"` // Whether or not to encrypt the resulting AMI when - // copying a provisioned instance to an AMI. By default, Packer will keep the - // encryption setting to what it was in the source image. Setting false will - // result in an unencrypted image, and true will result in an encrypted one. + // copying a provisioned instance to an AMI. By default, Packer will keep + // the encryption setting to what it was in the source image. Setting false + // will result in an unencrypted image, and true will result in an encrypted + // one. + // // If you have used the `launch_block_device_mappings` to set an encryption // key and that key is the same as the one you want the image encrypted with // at the end, then you don't need to set this field; leaving it empty will // prevent an unnecessary extra copy step and save you some time. AMIEncryptBootVolume config.Trilean `mapstructure:"encrypt_boot" required:"false"` - // ID, alias or ARN of the KMS key to use for boot volume encryption. This - // only applies to the main `region`, other regions where the AMI will be - // copied will be encrypted by the default EBS KMS key. For valid formats - // see *KmsKeyId* in the [AWS API docs - + // ID, alias or ARN of the KMS key to use for AMI encryption. This + // only applies to the main `region` -- any regions the AMI gets copied to + // copied will be encrypted by the default EBS KMS key for that region, + // unless you set region-specific keys in AMIRegionKMSKeyIDs. + // + // Set this value if you select `encrypt_boot`, but don't want to use the + // region's default KMS key. + // + // If you have a custom kms key you'd like to apply to the launch volume, + // and are only building in one region, it is more efficient to leave this + // and `encrypt_boot` empty and to instead set the key id in the + // launch_block_device_mappings (you can find an example below). This saves + // potentially many minutes at the end of the build by preventing Packer + // from having to copy and re-encrypt the image at the end of the build. + // + // For valid formats see *KmsKeyId* in the [AWS API docs - // CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). // This field is validated by Packer, when using an alias, you will have to // prefix `kms_key_id` with `alias/`. diff --git a/builder/amazon/common/block_device.go b/builder/amazon/common/block_device.go index cca863f24..fc0ce28a3 100644 --- a/builder/amazon/common/block_device.go +++ b/builder/amazon/common/block_device.go @@ -13,7 +13,7 @@ import ( "github.com/hashicorp/packer/template/interpolate" ) -// These will be attached when booting a new instance from your AMI. Your +// These will be attached when launching your instance. Your // options here may vary depending on the type of VM you use. // // Example use case: @@ -24,7 +24,7 @@ import ( // JSON example: // // ```json -// ami_block_device_mappings: [ +// launch_block_device_mappings: [ // { // "device_name": "/dev/sda1", // "encrypted": true, @@ -36,13 +36,16 @@ import ( // HCL2 example: // // ```hcl -// ami_block_device_mappings { +// launch_block_device_mappings { // device_name = "/dev/sda1" // encrypted = true // kms_key_id = "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" // } // ``` // +// Please note that the kms_key_id option in this example exists for +// launch_block_device_mappings but not ami_block_device_mappings. +// // Documentation for Block Devices Mappings can be found here: // https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html // @@ -80,12 +83,14 @@ type BlockDevice struct { // The size of the volume, in GiB. Required if not specifying a // snapshot_id. VolumeSize int64 `mapstructure:"volume_size" required:"false"` - // ID, alias or ARN of the KMS key to use for boot volume encryption. This - // only applies to the main region, other regions where the AMI will be - // copied will be encrypted by the default EBS KMS key. For valid formats - // see KmsKeyId in the [AWS API docs - + // ID, alias or ARN of the KMS key to use for boot volume encryption. + // This option exists for launch_block_device_mappings but not + // ami_block_device_mappings. The kms key id defined here only applies to + // the original build region; if the AMI gets copied to other regions, the + // volume in those regions will be encrypted by the default EBS KMS key. + // For valid formats see KmsKeyId in the [AWS API docs - // CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html) - // This field is validated by Packer, when using an alias, you will have to + // This field is validated by Packer. When using an alias, you will have to // prefix kms_key_id with alias/. KmsKeyId string `mapstructure:"kms_key_id" required:"false"` } diff --git a/website/pages/partials/builder/amazon/common/AMIConfig-not-required.mdx b/website/pages/partials/builder/amazon/common/AMIConfig-not-required.mdx index 4f0ab1e31..f5681e72e 100644 --- a/website/pages/partials/builder/amazon/common/AMIConfig-not-required.mdx +++ b/website/pages/partials/builder/amazon/common/AMIConfig-not-required.mdx @@ -60,18 +60,32 @@ Default false. - `encrypt_boot` (boolean) - Whether or not to encrypt the resulting AMI when - copying a provisioned instance to an AMI. By default, Packer will keep the - encryption setting to what it was in the source image. Setting false will - result in an unencrypted image, and true will result in an encrypted one. + copying a provisioned instance to an AMI. By default, Packer will keep + the encryption setting to what it was in the source image. Setting false + will result in an unencrypted image, and true will result in an encrypted + one. + If you have used the `launch_block_device_mappings` to set an encryption key and that key is the same as the one you want the image encrypted with at the end, then you don't need to set this field; leaving it empty will prevent an unnecessary extra copy step and save you some time. -- `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot volume encryption. This - only applies to the main `region`, other regions where the AMI will be - copied will be encrypted by the default EBS KMS key. For valid formats - see *KmsKeyId* in the [AWS API docs - +- `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for AMI encryption. This + only applies to the main `region` -- any regions the AMI gets copied to + copied will be encrypted by the default EBS KMS key for that region, + unless you set region-specific keys in AMIRegionKMSKeyIDs. + + Set this value if you select `encrypt_boot`, but don't want to use the + region's default KMS key. + + If you have a custom kms key you'd like to apply to the launch volume, + and are only building in one region, it is more efficient to leave this + and `encrypt_boot` empty and to instead set the key id in the + launch_block_device_mappings (you can find an example below). This saves + potentially many minutes at the end of the build by preventing Packer + from having to copy and re-encrypt the image at the end of the build. + + For valid formats see *KmsKeyId* in the [AWS API docs - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html). This field is validated by Packer, when using an alias, you will have to prefix `kms_key_id` with `alias/`. diff --git a/website/pages/partials/builder/amazon/common/BlockDevice-not-required.mdx b/website/pages/partials/builder/amazon/common/BlockDevice-not-required.mdx index a81cc9f32..b4b572bec 100644 --- a/website/pages/partials/builder/amazon/common/BlockDevice-not-required.mdx +++ b/website/pages/partials/builder/amazon/common/BlockDevice-not-required.mdx @@ -33,10 +33,12 @@ - `volume_size` (int64) - The size of the volume, in GiB. Required if not specifying a snapshot_id. -- `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot volume encryption. This - only applies to the main region, other regions where the AMI will be - copied will be encrypted by the default EBS KMS key. For valid formats - see KmsKeyId in the [AWS API docs - +- `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot volume encryption. + This option exists for launch_block_device_mappings but not + ami_block_device_mappings. The kms key id defined here only applies to + the original build region; if the AMI gets copied to other regions, the + volume in those regions will be encrypted by the default EBS KMS key. + For valid formats see KmsKeyId in the [AWS API docs - CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html) - This field is validated by Packer, when using an alias, you will have to + This field is validated by Packer. When using an alias, you will have to prefix kms_key_id with alias/. diff --git a/website/pages/partials/builder/amazon/common/BlockDevice.mdx b/website/pages/partials/builder/amazon/common/BlockDevice.mdx index 2d379812c..d6b5029b4 100644 --- a/website/pages/partials/builder/amazon/common/BlockDevice.mdx +++ b/website/pages/partials/builder/amazon/common/BlockDevice.mdx @@ -1,6 +1,6 @@ -These will be attached when booting a new instance from your AMI. Your +These will be attached when launching your instance. Your options here may vary depending on the type of VM you use. Example use case: @@ -11,7 +11,7 @@ build instance at launch using a specific non-default kms key: JSON example: ```json -ami_block_device_mappings: [ +launch_block_device_mappings: [ { "device_name": "/dev/sda1", "encrypted": true, @@ -23,12 +23,15 @@ ami_block_device_mappings: [ HCL2 example: ```hcl -ami_block_device_mappings { +launch_block_device_mappings { device_name = "/dev/sda1" encrypted = true kms_key_id = "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" } ``` +Please note that the kms_key_id option in this example exists for +launch_block_device_mappings but not ami_block_device_mappings. + Documentation for Block Devices Mappings can be found here: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html