Merge pull request #9608 from hashicorp/amazon-inline-docs-hcl

add tabs to generated docs from access_config and run_config structs

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

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
-// [{
+// ami_block_device_mappings: [
-//		"device_name": "/dev/sda1",
+//   {
-//		"encrypted": true,
+//      "device_name": "/dev/sda1",
-//		"kms_key_id": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
+//      "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:

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
+	// [windows-shell provisioner](/docs/provisioners/windows-shell). Note that
-	// provisioner](/docs/provisioners/windows-shell).
+	// Packer will still wait for the instance to be stopped, and failing to
-	// Note that Packer will still wait for the instance to be stopped, and
+	// send the stop signal yourself, when you have set this flag to `true`,
-	// failing to send the stop signal yourself, when you have set this flag to
+	// will cause a timeout.
-	// `true`, will cause a timeout.
-	// Example of a valid shutdown command:
 	//
-	// ```json
+	// An example of a valid windows shutdown command in a `windows-shell`
-	// {
+	// provisioner is :
-	//   "type": "windows-shell",
+	// ```shell-session
-	//   "inline": ["\"c:\\Program Files\\Amazon\\Ec2ConfigService\\ec2config.exe\" -sysprep"]
+	//   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": {
+	//        "filters": {
-	//         "virtualization-type": "hvm",
+	//        "virtualization-type": "hvm",
-	//         "name": "ubuntu/images/\*ubuntu-xenial-16.04-amd64-server-\*",
+	//        "name": "ubuntu/images/\*ubuntu-xenial-16.04-amd64-server-\*",
-	//         "root-device-type": "ebs"
+	//        "root-device-type": "ebs"
-	//       },
+	//        },
-	//       "owners": ["099720109477"],
+	//        "owners": ["099720109477"],
-	//       "most_recent": true
+	//        "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
-	// {
+	// "builders" [
-	//   "vpc_filter": {
+	//   {
-	//     "filters": {
+	//     "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"

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
+	// guest's bootstrap script, but sometimes you may have a race condition
-	// you need Packer to wait before attempting to connect to your guest.
+	// 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:
+	// `pause_before_connecting`. By default, there is no pause. For example if
-	//
+	// you set `pause_before_connecting` to `10m` Packer will check whether it
-	// ```json
+	// can connect, as normal. But once a connection attempt is successful, it
-	// {
+	// will disconnect and then wait 10 minutes before connecting to the guest
-	//   "communicator": "ssh",
+	// and beginning provisioning.
-	//   "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.
 	PauseBeforeConnect time.Duration `mapstructure:"pause_before_connecting"`
 
 	SSH   `mapstructure:",squash"`

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"
+    }
+  ```

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
-[{
+ami_block_device_mappings: [
-		"device_name": "/dev/sda1",
+  {
-		"encrypted": true,
+     "device_name": "/dev/sda1",
-		"kms_key_id": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
+     "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:

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
+  [windows-shell provisioner](/docs/provisioners/windows-shell). Note that
-  provisioner](/docs/provisioners/windows-shell).
+  Packer will still wait for the instance to be stopped, and failing to
-  Note that Packer will still wait for the instance to be stopped, and
+  send the stop signal yourself, when you have set this flag to `true`,
-  failing to send the stop signal yourself, when you have set this flag to
+  will cause a timeout.
-  `true`, will cause a timeout.
-  Example of a valid shutdown command:
   
-  ```json
+  An example of a valid windows shutdown command in a `windows-shell`
-  {
+  provisioner is :
-    "type": "windows-shell",
+  ```shell-session
-    "inline": ["\"c:\\Program Files\\Amazon\\Ec2ConfigService\\ec2config.exe\" -sysprep"]
+    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": {
+         "filters": {
-          "virtualization-type": "hvm",
+         "virtualization-type": "hvm",
-          "name": "ubuntu/images/\*ubuntu-xenial-16.04-amd64-server-\*",
+         "name": "ubuntu/images/\*ubuntu-xenial-16.04-amd64-server-\*",
-          "root-device-type": "ebs"
+         "root-device-type": "ebs"
-        },
+         },
-        "owners": ["099720109477"],
+         "owners": ["099720109477"],
-        "most_recent": true
+         "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
-  {
+  "builders" [
-    "vpc_filter": {
+    {
-      "filters": {
+      "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"

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`.
 
+<Tabs>
+<Tab heading="JSON">
+
 ```json
 {
   "builders": [
@@ -48,6 +51,52 @@ To use the session manager as the connection interface for the SSH communicator
 }
 ```
 
+</Tab>
+<Tab heading="HCL2">
+
+```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}'"
+      ]
+  }
+}
+```
+
+</Tab>
+</Tabs>
+
 #### 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.

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
+  guest's bootstrap script, but sometimes you may have a race condition
-  you need Packer to wait before attempting to connect to your guest.
+  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:
+  `pause_before_connecting`. By default, there is no pause. For example if
-  
+  you set `pause_before_connecting` to `10m` Packer will check whether it
-  ```json
+  can connect, as normal. But once a connection attempt is successful, it
-  {
+  will disconnect and then wait 10 minutes before connecting to the guest
-    "communicator": "ssh",
+  and beginning provisioning.
-    "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.