diff --git a/builder/amazon/common/access_config.go b/builder/amazon/common/access_config.go index d8e5cbc4f..2be4cf3ef 100644 --- a/builder/amazon/common/access_config.go +++ b/builder/amazon/common/access_config.go @@ -116,6 +116,8 @@ type AccessConfig struct { // credential types) and GetFederationToken (for federation\_token // credential types) for more details. // + // JSON example: + // // ```json // { // "vault_aws_engine": { @@ -125,6 +127,16 @@ type AccessConfig struct { // } // } // ``` + // + // HCL2 example: + // + // ```hcl + // 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/block_device.go b/builder/amazon/common/block_device.go index b641849c4..cca863f24 100644 --- a/builder/amazon/common/block_device.go +++ b/builder/amazon/common/block_device.go @@ -21,12 +21,26 @@ import ( // The following mapping will tell Packer to encrypt the root volume of the // build instance at launch using a specific non-default kms key: // +// JSON example: +// // ```json -// [{ -// "device_name": "/dev/sda1", -// "encrypted": true, -// "kms_key_id": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" -// }] +// ami_block_device_mappings: [ +// { +// "device_name": "/dev/sda1", +// "encrypted": true, +// "kms_key_id": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" +// } +// ] +// ``` +// +// HCL2 example: +// +// ```hcl +// ami_block_device_mappings { +// device_name = "/dev/sda1" +// encrypted = true +// kms_key_id = "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" +// } // ``` // // Documentation for Block Devices Mappings can be found here: diff --git a/builder/amazon/common/run_config.go b/builder/amazon/common/run_config.go index b242f5380..c9a8b8c6e 100644 --- a/builder/amazon/common/run_config.go +++ b/builder/amazon/common/run_config.go @@ -89,19 +89,23 @@ type RunConfig struct { // which will stop the instance for you. If this is set to `true`, Packer // *will not* stop the instance but will assume that you will send the stop // signal yourself through your final provisioner. You can do this with a - // [windows-shell - // provisioner](/docs/provisioners/windows-shell). - // Note that Packer will still wait for the instance to be stopped, and - // failing to send the stop signal yourself, when you have set this flag to - // `true`, will cause a timeout. - // Example of a valid shutdown command: + // [windows-shell provisioner](/docs/provisioners/windows-shell). Note that + // Packer will still wait for the instance to be stopped, and failing to + // send the stop signal yourself, when you have set this flag to `true`, + // will cause a timeout. // - // ```json - // { - // "type": "windows-shell", - // "inline": ["\"c:\\Program Files\\Amazon\\Ec2ConfigService\\ec2config.exe\" -sysprep"] - // } + // An example of a valid windows shutdown command in a `windows-shell` + // provisioner is : + // ```shell-session + // ec2config.exe -sysprep // ``` + // or + // ```sell-session + // "%programfiles%\amazon\ec2configservice\"ec2config.exe -sysprep"" + // ``` + // -> Note: The double quotation marks in the command are not required if + // your CMD shell is already in the + // `C:\Program Files\Amazon\EC2ConfigService\` directory. DisableStopInstance bool `mapstructure:"disable_stop_instance" required:"false"` // Mark instance as [EBS // Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html). @@ -162,7 +166,7 @@ type RunConfig struct { // The EC2 instance type to use while building the // AMI, such as t2.small. InstanceType string `mapstructure:"instance_type" required:"true"` - // Filters used to populate the `security_group_ids` field. Example: + // Filters used to populate the `security_group_ids` field. JSON Example: // // ```json // { @@ -174,6 +178,16 @@ type RunConfig struct { // } // ``` // + // HCL2 Example: + // + // ```hcl + // security_group_filter { + // filters = { + // "tag:Class": "packer" + // } + // } + // ``` + // // This selects the SG's with tag `Class` with the value `packer`. // // - `filters` (map of strings) - filters used to select a @@ -209,21 +223,39 @@ type RunConfig struct { // used when from_scratch is set to true. SourceAmi string `mapstructure:"source_ami" required:"true"` // Filters used to populate the `source_ami` - // field. Example: + // field. JSON Example: // - // ```json + // ```json + // "builders" [ // { + // "type": "amazon-ebs", // "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 + // "filters": { + // "virtualization-type": "hvm", + // "name": "ubuntu/images/\*ubuntu-xenial-16.04-amd64-server-\*", + // "root-device-type": "ebs" + // }, + // "owners": ["099720109477"], + // "most_recent": true // } // } - // ``` + // ] + // ``` + // HCL2 example: + // + // ```hcl + // source "amazon-ebs" "basic-example" { + // 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, @@ -291,10 +323,12 @@ type RunConfig struct { // will allow you to create those programatically. SpotTag hcl2template.KeyValues `mapstructure:"spot_tag" required:"false"` // Filters used to populate the `subnet_id` field. - // Example: + // JSON Example: // - // ```json + // ```json + // "builders" [ // { + // "type": "amazon-ebs", // "subnet_filter": { // "filters": { // "tag:Class": "build" @@ -303,7 +337,21 @@ type RunConfig struct { // "random": false // } // } - // ``` + // ] + // ``` + // HCL2 example: + // + // ```hcl + // source "amazon-ebs" "basic-example" { + // 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 @@ -348,12 +396,28 @@ type RunConfig struct { // data when launching the instance. UserDataFile string `mapstructure:"user_data_file" required:"false"` // Filters used to populate the `vpc_id` field. - // Example: + // JSON Example: // // ```json - // { - // "vpc_filter": { - // "filters": { + // "builders" [ + // { + // "type": "amazon-ebs", + // "vpc_filter": { + // "filters": { + // "tag:Class": "build", + // "isDefault": "false", + // "cidr": "/24" + // } + // } + // } + // ] + // ``` + // HCL2 example: + // + // ```hcl + // source "amazon-ebs" "basic-example" { + // vpc_filter { + // filters = { // "tag:Class": "build", // "isDefault": "false", // "cidr": "/24" diff --git a/helper/communicator/config.go b/helper/communicator/config.go index 874fe254e..88c194660 100644 --- a/helper/communicator/config.go +++ b/helper/communicator/config.go @@ -43,23 +43,16 @@ type Config struct { Type string `mapstructure:"communicator"` // We recommend that you enable SSH or WinRM as the very last step in your - // guest's bootstrap script, but sometimes you may have a race condition where - // you need Packer to wait before attempting to connect to your guest. + // guest's bootstrap script, but sometimes you may have a race condition + // where you need Packer to wait before attempting to connect to your + // guest. // // If you end up in this situation, you can use the template option - // `pause_before_connecting`. By default, there is no pause. For example: - // - // ```json - // { - // "communicator": "ssh", - // "ssh_username": "myuser", - // "pause_before_connecting": "10m" - // } - // ``` - // - // In this example, Packer will check whether it can connect, as normal. But once - // a connection attempt is successful, it will disconnect and then wait 10 minutes - // before connecting to the guest and beginning provisioning. + // `pause_before_connecting`. By default, there is no pause. For example if + // you set `pause_before_connecting` to `10m` Packer will check whether it + // can connect, as normal. But once a connection attempt is successful, it + // will disconnect and then wait 10 minutes before connecting to the guest + // and beginning provisioning. PauseBeforeConnect time.Duration `mapstructure:"pause_before_connecting"` SSH `mapstructure:",squash"` diff --git a/website/pages/partials/builder/amazon/common/AccessConfig-not-required.mdx b/website/pages/partials/builder/amazon/common/AccessConfig-not-required.mdx index 715c71c22..3c0faabe7 100644 --- a/website/pages/partials/builder/amazon/common/AccessConfig-not-required.mdx +++ b/website/pages/partials/builder/amazon/common/AccessConfig-not-required.mdx @@ -60,6 +60,8 @@ credential types) and GetFederationToken (for federation\_token credential types) for more details. + JSON example: + ```json { "vault_aws_engine": { @@ -69,3 +71,13 @@ } } ``` + + HCL2 example: + + ```hcl + vault_aws_engine { + name = "myrole" + role_arn = "myarn" + ttl = "3600s" + } + ``` diff --git a/website/pages/partials/builder/amazon/common/BlockDevice.mdx b/website/pages/partials/builder/amazon/common/BlockDevice.mdx index 89536e6c3..2d379812c 100644 --- a/website/pages/partials/builder/amazon/common/BlockDevice.mdx +++ b/website/pages/partials/builder/amazon/common/BlockDevice.mdx @@ -8,12 +8,26 @@ Example use case: The following mapping will tell Packer to encrypt the root volume of the build instance at launch using a specific non-default kms key: +JSON example: + ```json -[{ - "device_name": "/dev/sda1", - "encrypted": true, - "kms_key_id": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" -}] +ami_block_device_mappings: [ + { + "device_name": "/dev/sda1", + "encrypted": true, + "kms_key_id": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" + } +] +``` + +HCL2 example: + +```hcl +ami_block_device_mappings { + device_name = "/dev/sda1" + encrypted = true + kms_key_id = "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d" +} ``` Documentation for Block Devices Mappings can be found here: diff --git a/website/pages/partials/builder/amazon/common/RunConfig-not-required.mdx b/website/pages/partials/builder/amazon/common/RunConfig-not-required.mdx index a454eded7..6c3a3afd6 100644 --- a/website/pages/partials/builder/amazon/common/RunConfig-not-required.mdx +++ b/website/pages/partials/builder/amazon/common/RunConfig-not-required.mdx @@ -19,19 +19,23 @@ which will stop the instance for you. If this is set to `true`, Packer *will not* stop the instance but will assume that you will send the stop signal yourself through your final provisioner. You can do this with a - [windows-shell - provisioner](/docs/provisioners/windows-shell). - Note that Packer will still wait for the instance to be stopped, and - failing to send the stop signal yourself, when you have set this flag to - `true`, will cause a timeout. - Example of a valid shutdown command: + [windows-shell provisioner](/docs/provisioners/windows-shell). Note that + Packer will still wait for the instance to be stopped, and failing to + send the stop signal yourself, when you have set this flag to `true`, + will cause a timeout. - ```json - { - "type": "windows-shell", - "inline": ["\"c:\\Program Files\\Amazon\\Ec2ConfigService\\ec2config.exe\" -sysprep"] - } + An example of a valid windows shutdown command in a `windows-shell` + provisioner is : + ```shell-session + ec2config.exe -sysprep ``` + or + ```sell-session + "%programfiles%\amazon\ec2configservice\"ec2config.exe -sysprep"" + ``` + -> Note: The double quotation marks in the command are not required if + your CMD shell is already in the + `C:\Program Files\Amazon\EC2ConfigService\` directory. - `ebs_optimized` (bool) - Mark instance as [EBS Optimized](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html). @@ -88,7 +92,7 @@ shutdown in case Packer exits ungracefully. Possible values are stop and terminate. Defaults to stop. -- `security_group_filter` (SecurityGroupFilterOptions) - Filters used to populate the `security_group_ids` field. Example: +- `security_group_filter` (SecurityGroupFilterOptions) - Filters used to populate the `security_group_ids` field. JSON Example: ```json { @@ -100,6 +104,16 @@ } ``` + HCL2 Example: + + ```hcl + security_group_filter { + filters = { + "tag:Class": "packer" + } + } + ``` + This selects the SG's with tag `Class` with the value `packer`. - `filters` (map of strings) - filters used to select a @@ -130,21 +144,39 @@ security_group_id. - `source_ami_filter` (AmiFilterOptions) - Filters used to populate the `source_ami` - field. Example: + field. JSON Example: - ```json + ```json + "builders" [ { + "type": "amazon-ebs", "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 + "filters": { + "virtualization-type": "hvm", + "name": "ubuntu/images/\*ubuntu-xenial-16.04-amd64-server-\*", + "root-device-type": "ebs" + }, + "owners": ["099720109477"], + "most_recent": true } } - ``` + ] + ``` + HCL2 example: + + ```hcl + source "amazon-ebs" "basic-example" { + 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, @@ -206,10 +238,12 @@ will allow you to create those programatically. - `subnet_filter` (SubnetFilterOptions) - Filters used to populate the `subnet_id` field. - Example: + JSON Example: - ```json + ```json + "builders" [ { + "type": "amazon-ebs", "subnet_filter": { "filters": { "tag:Class": "build" @@ -218,7 +252,21 @@ "random": false } } - ``` + ] + ``` + HCL2 example: + + ```hcl + source "amazon-ebs" "basic-example" { + 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 @@ -263,12 +311,28 @@ data when launching the instance. - `vpc_filter` (VpcFilterOptions) - Filters used to populate the `vpc_id` field. - Example: + JSON Example: ```json - { - "vpc_filter": { - "filters": { + "builders" [ + { + "type": "amazon-ebs", + "vpc_filter": { + "filters": { + "tag:Class": "build", + "isDefault": "false", + "cidr": "/24" + } + } + } + ] + ``` + HCL2 example: + + ```hcl + source "amazon-ebs" "basic-example" { + vpc_filter { + filters = { "tag:Class": "build", "isDefault": "false", "cidr": "/24" diff --git a/website/pages/partials/builders/aws-session-manager.mdx b/website/pages/partials/builders/aws-session-manager.mdx index df2123937..14bf72219 100644 --- a/website/pages/partials/builders/aws-session-manager.mdx +++ b/website/pages/partials/builders/aws-session-manager.mdx @@ -15,6 +15,9 @@ To use the session manager as the connection interface for the SSH communicator - `session_manager_port`: A local port on the host machine that should be used as the local end of the session tunnel to the remote host. If not specified Packer will find an available port to use. - `temporary_iam_instance_profile_policy_document`: Creates a temporary instance profile policy document to grant Systems Manager permissions to the Ec2 instance. This is an alternative to using an existing `iam_instance_profile`. + + + ```json { "builders": [ @@ -48,6 +51,52 @@ To use the session manager as the connection interface for the SSH communicator } ``` + + + +```hcl +// In order to get these variables to read from the environment, +// set the environment variables to have the same name as the declared +// variables, with the prefix PKR_VAR_. + +// You could also hardcode them into the file, but we recommend that. + + +source "amazon-ebs" "ssm-example" { + ami_name = "packer_AWS {{timestamp}}" + instance_type = "t2.micro" + region = "us-east-1" + 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 + } + ssh_username = "ubuntu" + ssh_interface = "session_manager" + communicator = "ssh" + iam_instance_profile = "myinstanceprofile" +} + +build { + sources = [ + "source.amazon-ebs.ssm-example" + ] + + provisioner "shell" { + inline = [ + "echo Connected via SSM at '${build.User}@${build.Host}:${build.Port}'" + ] + } +} +``` + + + + #### Session Manager Plugin Connectivity via the session manager requires the use of a session-manger-plugin, which needs to be installed alongside Packer, and an instance AMI that is capable of running the AWS ssm-agent - see [About SSM Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/prereqs-ssm-agent.html) for details on supported AMIs. diff --git a/website/pages/partials/helper/communicator/Config-not-required.mdx b/website/pages/partials/helper/communicator/Config-not-required.mdx index 5ad952f90..a0ffb17d3 100644 --- a/website/pages/partials/helper/communicator/Config-not-required.mdx +++ b/website/pages/partials/helper/communicator/Config-not-required.mdx @@ -16,20 +16,13 @@ files. - `pause_before_connecting` (duration string | ex: "1h5m2s") - We recommend that you enable SSH or WinRM as the very last step in your - guest's bootstrap script, but sometimes you may have a race condition where - you need Packer to wait before attempting to connect to your guest. + guest's bootstrap script, but sometimes you may have a race condition + where you need Packer to wait before attempting to connect to your + guest. If you end up in this situation, you can use the template option - `pause_before_connecting`. By default, there is no pause. For example: - - ```json - { - "communicator": "ssh", - "ssh_username": "myuser", - "pause_before_connecting": "10m" - } - ``` - - In this example, Packer will check whether it can connect, as normal. But once - a connection attempt is successful, it will disconnect and then wait 10 minutes - before connecting to the guest and beginning provisioning. + `pause_before_connecting`. By default, there is no pause. For example if + you set `pause_before_connecting` to `10m` Packer will check whether it + can connect, as normal. But once a connection attempt is successful, it + will disconnect and then wait 10 minutes before connecting to the guest + and beginning provisioning.