iSharkFly-Docs
/
packer-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix docs for kms key ids (#9766)

This commit is contained in:
Megan Marsh 2020-08-14 02:35:35 -07:00 committed by GitHub
parent 99f503a22b
commit 8b4993e44c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 68 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
builder/amazon/common/ami_config.go
View File

@ -79,18 +79,32 @@ type AMIConfig struct {
// Default false. // Default false.
AMIForceDeleteSnapshot bool `mapstructure:"force_delete_snapshot" required:"false"` AMIForceDeleteSnapshot bool `mapstructure:"force_delete_snapshot" required:"false"`
// Whether or not to encrypt the resulting AMI when // Whether or not to encrypt the resulting AMI when
// copying a provisioned instance to an AMI. By default, Packer will keep the // copying a provisioned instance to an AMI. By default, Packer will keep
// encryption setting to what it was in the source image. Setting false will // the encryption setting to what it was in the source image. Setting false
// result in an unencrypted image, and true will result in an encrypted one. // 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 // 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 // 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 // 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. // prevent an unnecessary extra copy step and save you some time.
AMIEncryptBootVolume config.Trilean `mapstructure:"encrypt_boot" required:"false"` AMIEncryptBootVolume config.Trilean `mapstructure:"encrypt_boot" required:"false"`
// ID, alias or ARN of the KMS key to use for boot volume encryption. This // ID, alias or ARN of the KMS key to use for AMI encryption. This
// only applies to the main `region`, other regions where the AMI will be // only applies to the main `region` -- any regions the AMI gets copied to
// copied will be encrypted by the default EBS KMS key. For valid formats // copied will be encrypted by the default EBS KMS key for that region,
// see *KmsKeyId* in the [AWS API docs - // 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). // 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/`. // prefix `kms_key_id` with `alias/`.

21
builder/amazon/common/block_device.go
View File

@ -13,7 +13,7 @@ import (
"github.com/hashicorp/packer/template/interpolate" "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. // options here may vary depending on the type of VM you use.
// //
// Example use case: // Example use case:
@ -24,7 +24,7 @@ import (
// JSON example: // JSON example:
// //
// ```json // ```json
// ami_block_device_mappings: [ // launch_block_device_mappings: [
// { // {
// "device_name": "/dev/sda1", // "device_name": "/dev/sda1",
// "encrypted": true, // "encrypted": true,
@ -36,13 +36,16 @@ import (
// HCL2 example: // HCL2 example:
// //
// ```hcl // ```hcl
// ami_block_device_mappings { // launch_block_device_mappings {
// device_name = "/dev/sda1" // device_name = "/dev/sda1"
// encrypted = true // encrypted = true
// kms_key_id = "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" // 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: // Documentation for Block Devices Mappings can be found here:
// https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html // 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 // The size of the volume, in GiB. Required if not specifying a
// snapshot_id. // snapshot_id.
VolumeSize int64 `mapstructure:"volume_size" required:"false"` VolumeSize int64 `mapstructure:"volume_size" required:"false"`
// ID, alias or ARN of the KMS key to use for boot volume encryption. This // ID, alias or ARN of the KMS key to use for boot volume encryption.
// only applies to the main region, other regions where the AMI will be // This option exists for launch_block_device_mappings but not
// copied will be encrypted by the default EBS KMS key. For valid formats // ami_block_device_mappings. The kms key id defined here only applies to
// see KmsKeyId in the [AWS API docs - // 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) // 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/. // prefix kms_key_id with alias/.
KmsKeyId string `mapstructure:"kms_key_id" required:"false"` KmsKeyId string `mapstructure:"kms_key_id" required:"false"`
} }

28
website/pages/partials/builder/amazon/common/AMIConfig-not-required.mdx
View File

@ -60,18 +60,32 @@
Default false. Default false.
- `encrypt_boot` (boolean) - Whether or not to encrypt the resulting AMI when - `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 copying a provisioned instance to an AMI. By default, Packer will keep
encryption setting to what it was in the source image. Setting false will the encryption setting to what it was in the source image. Setting false
result in an unencrypted image, and true will result in an encrypted one. 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 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 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 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. 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 - `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for AMI encryption. This
only applies to the main `region`, other regions where the AMI will be only applies to the main `region` -- any regions the AMI gets copied to
copied will be encrypted by the default EBS KMS key. For valid formats copied will be encrypted by the default EBS KMS key for that region,
see *KmsKeyId* in the [AWS API docs - 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). 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/`. prefix `kms_key_id` with `alias/`.

12
website/pages/partials/builder/amazon/common/BlockDevice-not-required.mdx
View File

@ -33,10 +33,12 @@
- `volume_size` (int64) - The size of the volume, in GiB. Required if not specifying a - `volume_size` (int64) - The size of the volume, in GiB. Required if not specifying a
snapshot_id. snapshot_id.
- `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot volume encryption. This - `kms_key_id` (string) - ID, alias or ARN of the KMS key to use for boot volume encryption.
only applies to the main region, other regions where the AMI will be This option exists for launch_block_device_mappings but not
copied will be encrypted by the default EBS KMS key. For valid formats ami_block_device_mappings. The kms key id defined here only applies to
see KmsKeyId in the [AWS API docs - 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) 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/. prefix kms_key_id with alias/.

9
website/pages/partials/builder/amazon/common/BlockDevice.mdx
View File

@ -1,6 +1,6 @@
<!-- Code generated from the comments of the BlockDevice struct in builder/amazon/common/block_device.go; DO NOT EDIT MANUALLY --> <!-- Code generated from the comments of the BlockDevice struct in builder/amazon/common/block_device.go; DO NOT EDIT MANUALLY -->
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. options here may vary depending on the type of VM you use.
Example use case: Example use case:
@ -11,7 +11,7 @@ build instance at launch using a specific non-default kms key:
JSON example: JSON example:
```json ```json
ami_block_device_mappings: [ launch_block_device_mappings: [
{ {
"device_name": "/dev/sda1", "device_name": "/dev/sda1",
"encrypted": true, "encrypted": true,
@ -23,12 +23,15 @@ ami_block_device_mappings: [
HCL2 example: HCL2 example:
```hcl ```hcl
ami_block_device_mappings { launch_block_device_mappings {
device_name = "/dev/sda1" device_name = "/dev/sda1"
encrypted = true encrypted = true
kms_key_id = "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" 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: Documentation for Block Devices Mappings can be found here:
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html