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

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

add tabs to generated docs from access_config and run_config structs
This commit is contained in:
Megan Marsh 2020-07-21 16:34:49 -07:00 committed by GitHub
parent 7d1b6969b0 810f161d22
commit 6e7618ca1a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 313 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
builder/amazon/common/access_config.go
View File

@ -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

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

@ -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:

122
builder/amazon/common/run_config.go
View File

@ -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"

23
helper/communicator/config.go
View File

@ -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"`

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

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

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

@ -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:

122
website/pages/partials/builder/amazon/common/RunConfig-not-required.mdx
View File

@ -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"

49
website/pages/partials/builders/aws-session-manager.mdx
View File

@ -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.

23
website/pages/partials/helper/communicator/Config-not-required.mdx
View File

@ -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.