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

Document exception to encryption (#10395) 

* Update docs on ebs encrypt_boot to clarify that packer will not override global account settings

* Update struct-markdown generator and regenerate partials with new website location. This overwrites some linting that got automatically applied when the files got moved
This commit is contained in:
Megan Marsh 2020-12-16 01:35:34 -08:00 committed by GitHub
parent eecac40d77
commit 75803397cb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
63 changed files with 678 additions and 719 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -87,6 +87,11 @@ type AMIConfig struct {
// 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.
//
// Please note that if you are using an account with the global "Always
// encrypt new EBS volumes" option set to `true`, Packer will be unable to
// override this setting, and the final image will be encryoted whether
// you set this value or not.
AMIEncryptBootVolume config.Trilean `mapstructure:"encrypt_boot" required:"false"`
// 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

2
cmd/struct-markdown/main.go
View File

@ -152,7 +152,7 @@ func main() {
}
}
dir := filepath.Join(projectRoot, "website", "pages", "partials", builderName)
dir := filepath.Join(projectRoot, "website", "content", "partials", builderName)
os.MkdirAll(dir, 0755)
for _, str := range []Struct{header, required, notRequired} {

7
website/content/partials/builder/alicloud/ecs/AlicloudDiskDevice-not-required.mdx
View File

@ -3,10 +3,13 @@
- `disk_name` (string) - The value of disk name is blank by default. [2,
128] English or Chinese characters, must begin with an
uppercase/lowercase letter or Chinese character. Can contain numbers,
., \_ and -. The disk name will appear on the console. It cannot
., _ and -. The disk name will appear on the console. It cannot
begin with `http://` or `https://`.
- `disk_category` (string) - Category of the system disk. Optional values are: - cloud - general cloud disk - cloud_efficiency - efficiency cloud disk - cloud_ssd - cloud SSD
- `disk_category` (string) - Category of the system disk. Optional values are:
- cloud - general cloud disk
- cloud_efficiency - efficiency cloud disk
- cloud_ssd - cloud SSD
- `disk_size` (int) - Size of the system disk, measured in GiB. Value
range: [20, 500]. The specified value must be equal to or greater

6
website/content/partials/builder/alicloud/ecs/AlicloudDiskDevices-not-required.mdx
View File

@ -4,7 +4,7 @@
See the [disk device configuration](#disk-devices-configuration) section
for more information on options.
Usage example:
```json
"builders": [{
"type":"alicloud-ecs",
@ -20,7 +20,7 @@
See the [disk device configuration](#disk-devices-configuration) section
for more information on options.
Usage example:
```json
"builders": [{
"type":"alicloud-ecs",
@ -32,4 +32,4 @@
],
...
}
```
```

4
website/content/partials/builder/alicloud/ecs/AlicloudImageConfig-not-required.mdx
View File

@ -17,10 +17,10 @@
- `image_copy_names` ([]string) - The name of the destination image, [2, 128] English or Chinese
characters. It must begin with an uppercase/lowercase letter or a
Chinese character, and may contain numbers, \_ or -. It cannot begin with
Chinese character, and may contain numbers, _ or -. It cannot begin with
`http://` or `https://`.
- `image_encrypted` (boolean) - Whether or not to encrypt the target images, including those
- `image_encrypted` (boolean) - Whether or not to encrypt the target images, including those
copied if image_copy_regions is specified. If this option is set to
true, a temporary image will be created from the provisioned instance in
the main region and an encrypted copy will be generated in the same

24
website/content/partials/builder/alicloud/ecs/RunConfig-not-required.mdx
View File

@ -12,7 +12,7 @@
- `force_stop_instance` (bool) - Whether to force shutdown upon device
restart. The default value is `false`.
If it is set to `false`, the system is shut down normally; if it is set to
`true`, the system is forced to shut down.
@ -34,7 +34,7 @@
- `security_group_name` (string) - The security group name. The default value
is blank. [2, 128] English or Chinese characters, must begin with an
uppercase/lowercase letter or Chinese character. Can contain numbers, .,
\_ or -. It cannot begin with `http://` or `https://`.
_ or -. It cannot begin with `http://` or `https://`.
- `user_data` (string) - User data to apply when launching the instance. Note
that you need to be careful about escaping characters due to the templates
@ -49,7 +49,7 @@
- `vpc_name` (string) - The VPC name. The default value is blank. [2, 128]
English or Chinese characters, must begin with an uppercase/lowercase
letter or Chinese character. Can contain numbers, \_ and -. The disk
letter or Chinese character. Can contain numbers, _ and -. The disk
description will appear on the console. Cannot begin with `http://` or
`https://`.
@ -69,23 +69,21 @@
- `internet_charge_type` (string) - Internet charge type, which can be
`PayByTraffic` or `PayByBandwidth`. Optional values:
- `PayByBandwidth`
- `PayByTraffic`
- `PayByBandwidth`
- `PayByTraffic`
If this parameter is not specified, the default value is `PayByBandwidth`.
For the regions out of China, currently only support `PayByTraffic`, you
must set it manfully.
- `internet_max_bandwidth_out` (int) - Maximum outgoing bandwidth to the
public network, measured in Mbps (Mega bits per second).
Value range:
- `PayByBandwidth`: \[0, 100\]. If this parameter is not specified, API
automatically sets it to 0 Mbps.
- `PayByTraffic`: \[1, 100\]. If this parameter is not specified, an
error is returned.
- `PayByBandwidth`: \[0, 100\]. If this parameter is not specified, API
automatically sets it to 0 Mbps.
- `PayByTraffic`: \[1, 100\]. If this parameter is not specified, an
error is returned.
- `wait_snapshot_ready_timeout` (int) - Timeout of creating snapshot(s).
The default timeout is 3600 seconds if this option is not set or is set

58
website/content/partials/builder/amazon/chroot/Config-not-required.mdx
View File

@ -81,47 +81,47 @@
if building based on top of a source_ami which is also io1.
- `source_ami_filter` (awscommon.AmiFilterOptions) - Filters used to populate the source_ami field. Example:
```json
{
"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
}
"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,
This will fail unless *exactly* one AMI is returned. In the above example,
`most_recent` will cause this to succeed by selecting the newest image.
- `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless _exactly_ one AMI is returned. Any filter
described in the docs for
[DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- `owners` (array of strings) - Filters the images by their owner. You
may specify one or more AWS account IDs, "self" (which will use the
account whose credentials you are using to run Packer), or an AWS owner
alias: for example, "amazon", "aws-marketplace", or "microsoft". This
option is required for security reasons.
- `most_recent` (boolean) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
- `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless *exactly* one AMI is returned. Any filter
described in the docs for
[DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- `owners` (array of strings) - Filters the images by their owner. You
may specify one or more AWS account IDs, "self" (which will use the
account whose credentials you are using to run Packer), or an AWS owner
alias: for example, "amazon", "aws-marketplace", or "microsoft". This
option is required for security reasons.
- `most_recent` (boolean) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
You may set this in place of `source_ami` or in conjunction with it. If you
set this in conjunction with `source_ami`, the `source_ami` will be added
to the filter. The provided `source_ami` must meet all of the filtering
criteria provided in `source_ami_filter`; this pins the AMI returned by the
filter, but will cause Packer to fail if the `source_ami` does not exist.
- `root_volume_tags` (map[string]string) - Key/value pair tags to apply to the volumes that are _launched_. This is
- `root_volume_tags` (map[string]string) - Key/value pair tags to apply to the volumes that are *launched*. This is
a [template engine](/docs/templates/engine), see [Build template
data](#build-template-data) for more information.

26
website/content/partials/builder/amazon/common/AMIConfig-not-required.mdx
View File

@ -1,7 +1,7 @@
<!-- Code generated from the comments of the AMIConfig struct in builder/amazon/common/ami_config.go; DO NOT EDIT MANUALLY -->
- `ami_description` (string) - The description to set for the resulting
AMI(s). By default this description is empty. This is a
AMI(s). By default this description is empty. This is a
[template engine](/docs/templates/engine), see [Build template
data](#build-template-data) for more information.
@ -40,7 +40,7 @@
- `ena_support` (boolean) - Enable enhanced networking (ENA but not SriovNetSupport) on
HVM-compatible AMIs. If set, add `ec2:ModifyInstanceAttribute` to your
AWS IAM policy.
Note: you must make sure enhanced networking is enabled on your
instance. See [Amazon's documentation on enabling enhanced
networking](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking.html#enabling_enhanced_networking).
@ -64,28 +64,33 @@
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.
Please note that if you are using an account with the global "Always
encrypt new EBS volumes" option set to `true`, Packer will be unable to
override this setting, and the final image will be encryoted whether
you set this value or not.
- `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 -
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/`.
@ -95,11 +100,12 @@
provided in `ami_regions`. If you just want to encrypt using a default
ID, you can stick with `kms_key_id` and `ami_regions`. If you want a
region to be encrypted with that region's default key ID, you can use an
empty string `""` instead of a key id in this map. (e.g. `"us-east-1": ""`) However, you cannot use default key IDs if you are using this in
empty string `""` instead of a key id in this map. (e.g. `"us-east-1":
""`) However, you cannot use default key IDs if you are using this in
conjunction with `snapshot_users` -- in that situation you must use
custom keys. For valid formats see _KmsKeyId_ in the [AWS API docs -
custom keys. For valid formats see *KmsKeyId* in the [AWS API docs -
CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html).
This option supercedes the `kms_key_id` option -- if you set both, and
they are different, Packer will respect the value in
`region_kms_key_ids` for your build region and silently disregard the

2
website/content/partials/builder/amazon/common/AWSPollingConfig.mdx
View File

@ -5,7 +5,6 @@ volumes or importing image.
Usage example:
In JSON:
```json
"aws_polling" : {
"delay_seconds": 30,
@ -14,7 +13,6 @@ In JSON:
```
In HCL2:
```hcl
aws_polling {
delay_seconds = 30

55
website/content/partials/builder/amazon/common/AccessConfig-not-required.mdx
View File

@ -47,40 +47,39 @@
generating credentials via the Vault engine, see the [Vault
docs.](https://www.vaultproject.io/api/secret/aws#generate-credentials)
If you set this flag, you must also set the below options:
- `name` (string) - Required. Specifies the name of the role to generate
credentials against. This is part of the request URL.
- `engine_name` (string) - The name of the aws secrets engine. In the
Vault docs, this is normally referred to as "aws", and Packer will
default to "aws" if `engine_name` is not set.
- `role_arn` (string)- The ARN of the role to assume if credential_type
on the Vault role is assumed_role. Must match one of the allowed role
ARNs in the Vault role. Optional if the Vault role only allows a single
AWS role ARN; required otherwise.
- `ttl` (string) - Specifies the TTL for the use of the STS token. This
is specified as a string with a duration suffix. Valid only when
credential_type is assumed_role or federation_token. When not
specified, the default_sts_ttl set for the role will be used. If that
is also not set, then the default value of 3600s will be used. AWS
places limits on the maximum TTL allowed. See the AWS documentation on
the DurationSeconds parameter for AssumeRole (for assumed_role
credential types) and GetFederationToken (for federation_token
credential types) for more details.
- `name` (string) - Required. Specifies the name of the role to generate
credentials against. This is part of the request URL.
- `engine_name` (string) - The name of the aws secrets engine. In the
Vault docs, this is normally referred to as "aws", and Packer will
default to "aws" if `engine_name` is not set.
- `role_arn` (string)- The ARN of the role to assume if credential\_type
on the Vault role is assumed\_role. Must match one of the allowed role
ARNs in the Vault role. Optional if the Vault role only allows a single
AWS role ARN; required otherwise.
- `ttl` (string) - Specifies the TTL for the use of the STS token. This
is specified as a string with a duration suffix. Valid only when
credential\_type is assumed\_role or federation\_token. When not
specified, the default\_sts\_ttl set for the role will be used. If that
is also not set, then the default value of 3600s will be used. AWS
places limits on the maximum TTL allowed. See the AWS documentation on
the DurationSeconds parameter for AssumeRole (for assumed\_role
credential types) and GetFederationToken (for federation\_token
credential types) for more details.
JSON example:
```json
{
"vault_aws_engine": {
"name": "myrole",
"role_arn": "myarn",
"ttl": "3600s"
}
"vault_aws_engine": {
"name": "myrole",
"role_arn": "myarn",
"ttl": "3600s"
}
}
```
HCL2 example:
```hcl
vault_aws_engine {
name = "myrole"

2
website/content/partials/builder/amazon/common/AccessConfig-required.mdx
View File

@ -1,6 +1,6 @@
<!-- Code generated from the comments of the AccessConfig struct in builder/amazon/common/access_config.go; DO NOT EDIT MANUALLY -->
- `access_key` (string) - The access key used to communicate with AWS. [Learn how to set this]
- `access_key` (string) - The access key used to communicate with AWS. [Learn how to set this]
(/docs/builders/amazon#specifying-amazon-credentials). On EBS, this
is not required if you are using `use_vault_aws_engine` for
authentication instead.

242
website/content/partials/builder/amazon/common/RunConfig-not-required.mdx
View File

@ -17,26 +17,22 @@
run. For Windows instances, it is sometimes desirable to [run
Sysprep](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ami-create-standard.html)
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
*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.
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.
@ -58,12 +54,12 @@
up a [T2
Standard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-std.html)
instance instead.
To use T2 Unlimited you must use a T2 instance type, e.g. `t2.micro`.
Additionally, T2 Unlimited cannot be used in conjunction with Spot
Instances, e.g. when the `spot_price` option has been configured.
Attempting to do so will cause an error.
!&gt; **Warning!** Additional costs may be incurred by enabling T2
Unlimited - even for instances that would usually qualify for the
[AWS Free Tier](https://aws.amazon.com/free/).
@ -76,17 +72,19 @@
- `temporary_iam_instance_profile_policy_document` (\*PolicyDocument) - Temporary IAM instance profile policy document
If IamInstanceProfile is specified it will be used instead. Example:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": ["logs:*"],
"Effect": "Allow",
"Resource": "*"
}
]
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"logs:*"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
@ -95,7 +93,7 @@
terminate. Defaults to stop.
- `security_group_filter` (SecurityGroupFilterOptions) - Filters used to populate the `security_group_ids` field. JSON Example:
```json
{
"security_group_filter": {
@ -105,9 +103,9 @@
}
}
```
HCL2 Example:
```hcl
security_group_filter {
filters = {
@ -115,17 +113,17 @@
}
}
```
This selects the SG's with tag `Class` with the value `packer`.
- `filters` (map of strings) - filters used to select a
`security_group_ids`. Any filter described in the docs for
[DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html)
is valid.
- `filters` (map of strings) - filters used to select a
`security_group_ids`. Any filter described in the docs for
[DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html)
is valid.
`security_group_ids` take precedence over this.
- `run_tags` (map[string]string) - Key/value pair tags to apply to the instance that is that is _launched_
- `run_tags` (map[string]string) - Key/value pair tags to apply to the instance that is that is *launched*
to create the EBS volumes. This is a [template
engine](/docs/templates/engine), see [Build template
data](#build-template-data) for more information.
@ -147,26 +145,25 @@
- `source_ami_filter` (AmiFilterOptions) - Filters used to populate the `source_ami`
field. JSON Example:
```json
"builders"[
"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 {
@ -180,37 +177,37 @@
}
}
```
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,
`most_recent` will cause this to succeed by selecting the newest image.
- `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless _exactly_ one AMI is returned. Any filter
described in the docs for
[DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- `owners` (array of strings) - Filters the images by their owner. You
may specify one or more AWS account IDs, "self" (which will use the
account whose credentials you are using to run Packer), or an AWS owner
alias: for example, `amazon`, `aws-marketplace`, or `microsoft`. This
option is required for security reasons.
- `most_recent` (boolean) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
You may set this in place of `source_ami` or in conjunction with it. If you
set this in conjunction with `source_ami`, the `source_ami` will be added
to the filter. The provided `source_ami` must meet all of the filtering
criteria provided in `source_ami_filter`; this pins the AMI returned by the
filter, but will cause Packer to fail if the `source_ami` does not exist.
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,
`most_recent` will cause this to succeed by selecting the newest image.
- `filters` (map of strings) - filters used to select a `source_ami`.
NOTE: This will fail unless *exactly* one AMI is returned. Any filter
described in the docs for
[DescribeImages](http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeImages.html)
is valid.
- `owners` (array of strings) - Filters the images by their owner. You
may specify one or more AWS account IDs, "self" (which will use the
account whose credentials you are using to run Packer), or an AWS owner
alias: for example, `amazon`, `aws-marketplace`, or `microsoft`. This
option is required for security reasons.
- `most_recent` (boolean) - Selects the newest created image when true.
This is most useful for selecting a daily distro build.
You may set this in place of `source_ami` or in conjunction with it. If you
set this in conjunction with `source_ami`, the `source_ami` will be added
to the filter. The provided `source_ami` must meet all of the filtering
criteria provided in `source_ami_filter`; this pins the AMI returned by the
filter, but will cause Packer to fail if the `source_ami` does not exist.
- `spot_instance_types` ([]string) - a list of acceptable instance
types to run your build on. We will request a spot instance using the max
price of spot_price and the allocation strategy of "lowest price".
Your instance will be launched on an instance type of the lowest available
price that you have in your list. This is used in place of instance_type.
price that you have in your list. This is used in place of instance_type.
You may only set either spot_instance_types or instance_type, not both.
This feature exists to help prevent situations where a Packer build fails
because a particular availability zone does not have capacity for the
@ -220,7 +217,7 @@
time period your instances are running. Spot Instance prices are set by
Amazon EC2 and adjust gradually based on long-term trends in supply and
demand for Spot Instance capacity.
When this field is set, it represents the maximum hourly price you are
willing to pay for a spot instance. If you do not set this value, it
defaults to a maximum price equal to the on demand price of the
@ -242,9 +239,9 @@
- `subnet_filter` (SubnetFilterOptions) - Filters used to populate the `subnet_id` field.
JSON Example:
```json
"builders"[
"builders" [
{
"type": "amazon-ebs",
"subnet_filter": {
@ -257,9 +254,8 @@
}
]
```
HCL2 example:
```hcl
source "amazon-ebs" "basic-example" {
subnet_filter {
@ -271,25 +267,25 @@
}
}
```
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
Subnet is returned. By using `most_free` or `random` one will be selected
from those matching the filter.
- `filters` (map of strings) - filters used to select a `subnet_id`.
NOTE: This will fail unless _exactly_ one Subnet is returned. Any
filter described in the docs for
[DescribeSubnets](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html)
is valid.
- `most_free` (boolean) - The Subnet with the most free IPv4 addresses
will be used if multiple Subnets matches the filter.
- `random` (boolean) - A random Subnet will be used if multiple Subnets
matches the filter. `most_free` have precendence over this.
`subnet_id` take precedence over this.
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
Subnet is returned. By using `most_free` or `random` one will be selected
from those matching the filter.
- `filters` (map of strings) - filters used to select a `subnet_id`.
NOTE: This will fail unless *exactly* one Subnet is returned. Any
filter described in the docs for
[DescribeSubnets](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html)
is valid.
- `most_free` (boolean) - The Subnet with the most free IPv4 addresses
will be used if multiple Subnets matches the filter.
- `random` (boolean) - A random Subnet will be used if multiple Subnets
matches the filter. `most_free` have precendence over this.
`subnet_id` take precedence over this.
- `subnet_id` (string) - If using VPC, the ID of the subnet, such as
subnet-12345def, where Packer will launch the EC2 instance. This field is
@ -297,13 +293,13 @@
- `tenancy` (string) - [Tenancy](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/dedicated-instance.html) used
when Packer launches the EC2 instance, allowing it to be launched on dedicated hardware.
The default is "default", meaning shared tenancy. Allowed values are "default",
"dedicated" and "host".
- `temporary_security_group_source_cidrs` ([]string) - A list of IPv4 CIDR blocks to be authorized access to the instance, when
packer is creating a temporary security group.
The default is [`0.0.0.0/0`] (i.e., allow any IPv4 source). This is only
used when `security_group_id` or `security_group_ids` is not specified.
@ -318,9 +314,9 @@
- `vpc_filter` (VpcFilterOptions) - Filters used to populate the `vpc_id` field.
JSON Example:
```json
"builders"[
"builders" [
{
"type": "amazon-ebs",
"vpc_filter": {
@ -333,9 +329,8 @@
}
]
```
HCL2 example:
```hcl
source "amazon-ebs" "basic-example" {
vpc_filter {
@ -347,17 +342,17 @@
}
}
```
This selects the VPC with tag `Class` with the value `build`, which is not
the default VPC, and have a IPv4 CIDR block of `/24`. NOTE: This will fail
unless _exactly_ one VPC is returned.
- `filters` (map of strings) - filters used to select a `vpc_id`. NOTE:
This will fail unless _exactly_ one VPC is returned. Any filter
described in the docs for
[DescribeVpcs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcs.html)
is valid.
unless *exactly* one VPC is returned.
- `filters` (map of strings) - filters used to select a `vpc_id`. NOTE:
This will fail unless *exactly* one VPC is returned. Any filter
described in the docs for
[DescribeVpcs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcs.html)
is valid.
`vpc_id` take precedence over this.
- `vpc_id` (string) - If launching into a VPC subnet, Packer needs the VPC ID
@ -370,26 +365,25 @@
10m
- `ssh_interface` (string) - One of `public_ip`, `private_ip`, `public_dns`, `private_dns` or `session_manager`.
If set, either the public IP address, private IP address, public DNS name
or private DNS name will be used as the host for SSH. The default behaviour
if inside a VPC is to use the public IP address if available, otherwise
the private IP address will be used. If not in a VPC the public DNS name
will be used. Also works for WinRM.
Where Packer is configured for an outbound proxy but WinRM traffic
should be direct, `ssh_interface` must be set to `private_dns` and
`<region>.compute.internal` included in the `NO_PROXY` environment
variable.
When using `session_manager` the machine running Packer must have
the AWS Session Manager Plugin installed and within the users' system path.
Connectivity via the `session_manager` interface establishes a secure tunnel
between the local host and the remote host on an available local port to the specified `ssh_port`.
See [Session Manager Connections](#session-manager-connections) for more information.
- Session manager connectivity is currently only implemented for the SSH communicator, not the WinRM communicator.
- Upon termination the secure tunnel will be terminated automatically, if however there is a failure in
terminating the tunnel it will automatically terminate itself after 20 minutes of inactivity.
If set, either the public IP address, private IP address, public DNS name
or private DNS name will be used as the host for SSH. The default behaviour
if inside a VPC is to use the public IP address if available, otherwise
the private IP address will be used. If not in a VPC the public DNS name
will be used. Also works for WinRM.
Where Packer is configured for an outbound proxy but WinRM traffic
should be direct, `ssh_interface` must be set to `private_dns` and
`<region>.compute.internal` included in the `NO_PROXY` environment
variable.
When using `session_manager` the machine running Packer must have
the AWS Session Manager Plugin installed and within the users' system path.
Connectivity via the `session_manager` interface establishes a secure tunnel
between the local host and the remote host on an available local port to the specified `ssh_port`.
See [Session Manager Connections](#session-manager-connections) for more information.
- Session manager connectivity is currently only implemented for the SSH communicator, not the WinRM communicator.
- Upon termination the secure tunnel will be terminated automatically, if however there is a failure in
terminating the tunnel it will automatically terminate itself after 20 minutes of inactivity.
- `pause_before_ssm` (duration string | ex: "1h5m2s") - The time to wait before establishing the Session Manager session.
The value of this should be a duration. Examples are

6
website/content/partials/builder/amazon/ebs/Config-not-required.mdx
View File

@ -16,8 +16,8 @@
from the source instance. See the
[BlockDevices](#block-devices-configuration) documentation for fields.
- `run_volume_tags` (map[string]string) - Tags to apply to the volumes that are _launched_ to create the AMI.
These tags are _not_ applied to the resulting AMI unless they're
- `run_volume_tags` (map[string]string) - Tags to apply to the volumes that are *launched* to create the AMI.
These tags are *not* applied to the resulting AMI unless they're
duplicated in `tags`. This is a [template
engine](/docs/templates/engine), see [Build template
data](#build-template-data) for more information.
@ -34,5 +34,5 @@
For more information, see
https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/InstanceStorage.html.
Because we don't validate the OS type of your guest, it is up to you to
make sure you don't set this for \*nix guests; behavior may be
make sure you don't set this for *nix guests; behavior may be
unpredictable.

4
website/content/partials/builder/amazon/ebssurrogate/Config-not-required.mdx
View File

@ -16,8 +16,8 @@
from the source instance. See the
[BlockDevices](#block-devices-configuration) documentation for fields.
- `run_volume_tags` (map[string]string) - Tags to apply to the volumes that are _launched_ to create the AMI.
These tags are _not_ applied to the resulting AMI unless they're
- `run_volume_tags` (map[string]string) - Tags to apply to the volumes that are *launched* to create the AMI.
These tags are *not* applied to the resulting AMI unless they're
duplicated in `tags`. This is a [template
engine](/docs/templates/engine), see [Build template
data](#build-template-data) for more information.

8
website/content/partials/builder/amazon/ebssurrogate/Config-required.mdx
View File

@ -3,7 +3,7 @@
- `ami_root_device` (RootBlockDevice) - A block device mapping describing the root device of the AMI. This looks
like the mappings in `ami_block_device_mapping`, except with an
additional field:
- `source_device_name` (string) - The device name of the block device on
the source instance to be used as the root device for the AMI. This
must correspond to a block device in `launch_block_device_mapping`.
- `source_device_name` (string) - The device name of the block device on
the source instance to be used as the root device for the AMI. This
must correspond to a block device in `launch_block_device_mapping`.

6
website/content/partials/builder/amazon/ebsvolume/Config-not-required.mdx
View File

@ -24,13 +24,13 @@
documentation for fields.
- `run_volume_tags` (map[string]string) - Key/value pair tags to apply to the volumes of the instance that is
_launched_ to create EBS Volumes. These tags will _not_ appear in the
*launched* to create EBS Volumes. These tags will *not* appear in the
tags of the resulting EBS volumes unless they're duplicated under `tags`
in the `ebs_volumes` setting. This is a [template
engine](/docs/templates/engine), see [Build template
data](#build-template-data) for more information.
Note: The tags specified here will be _temporarily_ applied to volumes
Note: The tags specified here will be *temporarily* applied to volumes
specified in `ebs_volumes` - but only while the instance is being
created. Packer will replace all tags on the volume with the tags
configured in the `ebs_volumes` section as soon as the instance is

48
website/content/partials/builder/azure/arm/Config-not-required.mdx
View File

@ -13,12 +13,11 @@
- `shared_image_gallery` (SharedImageGallery) - Use a [Shared Gallery
image](https://azure.microsoft.com/en-us/blog/announcing-the-public-preview-of-shared-image-gallery/)
as the source for this build. _VHD targets are incompatible with this
build type_ - the target must be a _Managed Image_. When using shared_image_gallery as a source, image_publisher,
as the source for this build. *VHD targets are incompatible with this
build type* - the target must be a *Managed Image*. When using shared_image_gallery as a source, image_publisher,
image_offer, image_sku, image_version, and custom_managed_image_name should not be set.
In JSON
```json
"shared_image_gallery": {
"subscription": "00000000-0000-0000-0000-00000000000",
@ -30,9 +29,7 @@
"managed_image_name": "TargetImageName",
"managed_image_resource_group_name": "TargetResourceGroup"
```
In HCL2
```hcl
shared_image_gallery {
subscription = "00000000-0000-0000-0000-00000000000"
@ -46,11 +43,10 @@
```
- `shared_image_gallery_destination` (SharedImageGalleryDestination) - The name of the Shared Image Gallery under which the managed image will be published as Shared Gallery Image version.
Following is an example.
In JSON
```json
"shared_image_gallery_destination": {
"subscription": "00000000-0000-0000-0000-00000000000",
@ -63,9 +59,7 @@
"managed_image_name": "TargetImageName",
"managed_image_resource_group_name": "TargetResourceGroup"
```
In HCL2
```hcl
shared_image_gallery_destination {
subscription = "00000000-0000-0000-0000-00000000000"
@ -81,7 +75,8 @@
- `shared_image_gallery_timeout` (duration string | ex: "1h5m2s") - How long to wait for an image to be published to the shared image
gallery before timing out. If your Packer build is failing on the
Publishing to Shared Image Gallery step with the error `Original Error: context deadline exceeded`, but the image is present when you check your
Publishing to Shared Image Gallery step with the error `Original Error:
context deadline exceeded`, but the image is present when you check your
Azure dashboard, then you probably need to increase this timeout from
its default of "60m" (valid time units include `s` for seconds, `m` for
minutes, and `h` for hours.)
@ -101,7 +96,7 @@
across regions due to image synchronization latency. To ensure a consistent
version across regions set this value to one that is available in all
regions where you are deploying.
CLI example
`az vm image list --location westus --publisher Canonical --offer UbuntuServer --sku 16.04.0-LTS --all`
@ -111,7 +106,7 @@
VM from your VHD. See
[pricing](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/)
information. Defaults to `Standard_A1`.
CLI example `az vm list-sizes --location westus`
- `managed_image_resource_group_name` (string) - Specify the managed image resource group name where the result of the
@ -208,29 +203,29 @@
terms](https://aka.ms/azuremarketplaceapideployment) for more details.
Not all Marketplace images support programmatic deployment, and support
is controlled by the image publisher.
An example plan_info object is defined below.
An example plan\_info object is defined below.
```json
{
"plan_info": {
"plan_name": "rabbitmq",
"plan_product": "rabbitmq",
"plan_publisher": "bitnami"
"plan_name": "rabbitmq",
"plan_product": "rabbitmq",
"plan_publisher": "bitnami"
}
}
```
`plan_name` (string) - The plan name, required. `plan_product` (string) -
The plan product, required. `plan_publisher` (string) - The plan publisher,
required. `plan_promotion_code` (string) - Some images accept a promotion
code, optional.
Images created from the Marketplace with `plan_info` **must** specify
`plan_info` whenever the image is deployed. The builder automatically adds
tags to the image to ensure this information is not lost. The following
tags are added.
```text
1. PlanName
2. PlanProduct
@ -241,7 +236,8 @@
- `polling_duration_timeout` (duration string | ex: "1h5m2s") - The default PollingDuration for azure is 15mins, this property will override
that value. See [Azure DefaultPollingDuration](https://godoc.org/github.com/Azure/go-autorest/autorest#pkg-constants)
If your Packer build is failing on the
ARM deployment step with the error `Original Error: context deadline exceeded`, then you probably need to increase this timeout from
ARM deployment step with the error `Original Error:
context deadline exceeded`, then you probably need to increase this timeout from
its default of "15m" (valid time units include `s` for seconds, `m` for
minutes, and `h` for hours.)
@ -261,12 +257,12 @@
or
[Linux](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/about-disks-and-vhds)
for more information.
For VHD builds the final artifacts will be named
`PREFIX-dataDisk-<n>.UUID.vhd` and stored in the specified capture
container along side the OS disk. The additional disks are included in
the deployment template `PREFIX-vmTemplate.UUID`.
For Managed build the final artifacts are included in the managed image.
The additional disk will have the same storage account type as the OS
disk, as specified with the `managed_image_storage_account_type`

6
website/content/partials/builder/azure/arm/Config-required.mdx
View File

@ -3,20 +3,20 @@
- `image_publisher` (string) - Name of the publisher to use for your base image (Azure Marketplace Images only). See
[documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/)
for details.
CLI example `az vm image list-publishers --location westus`
- `image_offer` (string) - Name of the publisher's offer to use for your base image (Azure Marketplace Images only). See
[documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/)
for details.
CLI example
`az vm image list-offers --location westus --publisher Canonical`
- `image_sku` (string) - SKU of the image offer to use for your base image (Azure Marketplace Images only). See
[documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/)
for details.
CLI example
`az vm image list-skus --location westus --publisher Canonical --offer UbuntuServer`

32
website/content/partials/builder/azure/dtl/Config-not-required.mdx
View File

@ -6,9 +6,9 @@
- `shared_image_gallery` (SharedImageGallery) - Use a [Shared Gallery
image](https://azure.microsoft.com/en-us/blog/announcing-the-public-preview-of-shared-image-gallery/)
as the source for this build. _VHD targets are incompatible with this
build type_ - the target must be a _Managed Image_.
as the source for this build. *VHD targets are incompatible with this
build type* - the target must be a *Managed Image*.
```json
"shared_image_gallery": {
"subscription": "00000000-0000-0000-0000-00000000000",
@ -22,9 +22,9 @@
```
- `shared_image_gallery_destination` (SharedImageGalleryDestination) - The name of the Shared Image Gallery under which the managed image will be published as Shared Gallery Image version.
Following is an example.
```json
"shared_image_gallery_destination": {
"resource_group": "ResourceGroup",
@ -39,7 +39,8 @@
- `shared_image_gallery_timeout` (duration string | ex: "1h5m2s") - How long to wait for an image to be published to the shared image
gallery before timing out. If your Packer build is failing on the
Publishing to Shared Image Gallery step with the error `Original Error: context deadline exceeded`, but the image is present when you check your
Publishing to Shared Image Gallery step with the error `Original Error:
context deadline exceeded`, but the image is present when you check your
Azure dashboard, then you probably need to increase this timeout from
its default of "60m" (valid time units include `s` for seconds, `m` for
minutes, and `h` for hours.)
@ -47,20 +48,20 @@
- `image_publisher` (string) - PublisherName for your base image. See
[documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/)
for details.
CLI example `az vm image list-publishers --location westus`
- `image_offer` (string) - Offer for your base image. See
[documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/)
for details.
CLI example
`az vm image list-offers --location westus --publisher Canonical`
- `image_sku` (string) - SKU for your base image. See
[documentation](https://azure.microsoft.com/en-us/documentation/articles/resource-groups-vm-searching/)
for details.
CLI example
`az vm image list-skus --location westus --publisher Canonical --offer UbuntuServer`
@ -69,7 +70,7 @@
across regions due to image synchronization latency. To ensure a consistent
version across regions set this value to one that is available in all
regions where you are deploying.
CLI example
`az vm image list --location westus --publisher Canonical --offer UbuntuServer --sku 16.04.0-LTS --all`
@ -77,14 +78,14 @@
not set image_publisher, image_offer, image_sku, or image_version.
- `custom_managed_image_resource_group_name` (string) - Specify the source managed image's resource group used to use. If this
value is set, do not set image_publisher, image_offer, image_sku, or
image_version. If this value is set, the value
value is set, do not set image\_publisher, image\_offer, image\_sku, or
image\_version. If this value is set, the value
`custom_managed_image_name` must also be set. See
[documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images)
to learn more about managed images.
- `custom_managed_image_name` (string) - Specify the source managed image's name to use. If this value is set, do
not set image_publisher, image_offer, image_sku, or image_version.
not set image\_publisher, image\_offer, image\_sku, or image\_version.
If this value is set, the value
`custom_managed_image_resource_group_name` must also be set. See
[documentation](https://docs.microsoft.com/en-us/azure/storage/storage-managed-disks-overview#images)
@ -96,7 +97,7 @@
VM from your VHD. See
[pricing](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/)
information. Defaults to `Standard_A1`.
CLI example `az vm list-sizes --location westus`
- `managed_image_resource_group_name` (string) - Specify the managed image resource group name where the result of the
@ -130,7 +131,8 @@
- `polling_duration_timeout` (duration string | ex: "1h5m2s") - The default PollingDuration for azure is 15mins, this property will override
that value. See [Azure DefaultPollingDuration](https://godoc.org/github.com/Azure/go-autorest/autorest#pkg-constants)
If your Packer build is failing on the
ARM deployment step with the error `Original Error: context deadline exceeded`, then you probably need to increase this timeout from
ARM deployment step with the error `Original Error:
context deadline exceeded`, then you probably need to increase this timeout from
its default of "15m" (valid time units include `s` for seconds, `m` for
minutes, and `h` for hours.)

2
website/content/partials/builder/cloudstack/Config-not-required.mdx
View File

@ -104,6 +104,6 @@
contains tools to support dynamic scaling of VM cpu/memory. Defaults to
false.
- `template_tag` (string) -
- `template_tag` (string) -
- `tags` (map[string]string) - Tags

3
website/content/partials/builder/digitalocean/Config-not-required.mdx
View File

@ -26,7 +26,8 @@
- `snapshot_timeout` (duration string | ex: "1h5m2s") - How long to wait for an image to be published to the shared image
gallery before timing out. If your Packer build is failing on the
Publishing to Shared Image Gallery step with the error `Original Error: context deadline exceeded`, but the image is present when you check your
Publishing to Shared Image Gallery step with the error `Original Error:
context deadline exceeded`, but the image is present when you check your
Azure dashboard, then you probably need to increase this timeout from
its default of "60m" (valid time units include `s` for seconds, `m` for
minutes, and `h` for hours.)

10
website/content/partials/builder/docker/Config-not-required.mdx
View File

@ -33,13 +33,15 @@
used. This defaults to true if not set.
- `run_command` ([]string) - An array of arguments to pass to docker run in order to run the
container. By default this is set to `["-d", "-i", "-t", "--entrypoint=/bin/sh", "--", "{{.Image}}"]` if you are using a linux
container, and `["-d", "-i", "-t", "--entrypoint=powershell", "--", "{{.Image}}"]` if you are running a windows container. `{{.Image}}` is a
container. By default this is set to `["-d", "-i", "-t",
"--entrypoint=/bin/sh", "--", "{{.Image}}"]` if you are using a linux
container, and `["-d", "-i", "-t", "--entrypoint=powershell", "--",
"{{.Image}}"]` if you are running a windows container. `{{.Image}}` is a
template variable that corresponds to the image template option. Passing
the entrypoint option this way will make it the default entrypoint of
the resulting image, so running docker run -it --rm will start the
the resulting image, so running docker run -it --rm will start the
docker image from the /bin/sh shell interpreter; you could run a script
or another shell by running docker run -it --rm -c /bin/bash. If your
or another shell by running docker run -it --rm -c /bin/bash. If your
docker image embeds a binary intended to be run often, you should
consider changing the default entrypoint to point to it.

79
website/content/partials/builder/googlecompute/Config-not-required.mdx
View File

@ -50,23 +50,22 @@
- `image_description` (string) - The description of the resulting image.
- `image_encryption_key` (\*CustomerEncryptionKey) - Image encryption key to apply to the created image. Possible values:
- kmsKeyName - The name of the encryption key that is stored in Google Cloud KMS.
- RawKey: - A 256-bit customer-supplied encryption key, encodes in RFC 4648 base64.
* kmsKeyName - The name of the encryption key that is stored in Google Cloud KMS.
* RawKey: - A 256-bit customer-supplied encryption key, encodes in RFC 4648 base64.
examples:
```json
{
"kmsKeyName": "projects/${project}/locations/${region}/keyRings/computeEngine/cryptoKeys/computeEngine/cryptoKeyVersions/4"
}
```
```hcl
image_encryption_key {
kmsKeyName = "projects/${var.project}/locations/${var.region}/keyRings/computeEngine/cryptoKeys/computeEngine/cryptoKeyVersions/4"
```json
{
"kmsKeyName": "projects/${project}/locations/${region}/keyRings/computeEngine/cryptoKeys/computeEngine/cryptoKeyVersions/4"
}
```
```
```hcl
image_encryption_key {
kmsKeyName = "projects/${var.project}/locations/${var.region}/keyRings/computeEngine/cryptoKeys/computeEngine/cryptoKeyVersions/4"
}
```
- `image_family` (string) - The name of the image family to which the resulting image belongs. You
can create disks by specifying an image family instead of a specific
@ -80,22 +79,21 @@
- `image_storage_locations` ([]string) - Storage location, either regional or multi-regional, where snapshot
content is to be stored and only accepts 1 value. Always defaults to a nearby regional or multi-regional
location.
multi-regional example:
```json
{
"image_storage_locations": ["us"]
}
```
```json
{
"image_storage_locations": ["us"]
}
```
regional example:
```json
{
"image_storage_locations": ["us-east1"]
}
```
```json
{
"image_storage_locations": ["us-east1"]
}
```
- `instance_name` (string) - A name to give the launched instance. Beware that this must be unique.
Defaults to `packer-{{uuid}}`.
@ -107,7 +105,7 @@
- `metadata` (map[string]string) - Metadata applied to the launched instance.
All metadata configuration values are expected to be of type string.
Google metadata options that take a value of `TRUE` or `FALSE` should be
set as a string (i.e `"TRUE"` `"FALSE"` or `"true"` `"false"`).
set as a string (i.e `"TRUE"` `"FALSE"` or `"true"` `"false"`).
- `metadata_files` (map[string]string) - Metadata applied to the launched instance. Values are files.
@ -131,7 +129,7 @@
- `on_host_maintenance` (string) - Sets Host Maintenance Option. Valid choices are `MIGRATE` and
`TERMINATE`. Please see [GCE Instance Scheduling
Options](https://cloud.google.com/compute/docs/instances/setting-instance-scheduling-options),
as not all machine_types support `MIGRATE` (i.e. machines with GPUs).
as not all machine\_types support `MIGRATE` (i.e. machines with GPUs).
If preemptible is true this can only be `TERMINATE`. If preemptible is
false, it defaults to `MIGRATE`
@ -144,7 +142,7 @@
- `scopes` ([]string) - The service account scopes for launched
instance. Defaults to:
```json
[
"https://www.googleapis.com/auth/userinfo.email",
@ -163,9 +161,8 @@
- `startup_script_file` (string) - The path to a startup script to run on the launched instance from which the image will
be made. When set, the contents of the startup script file will be added to the instance metadata
under the `"startup_script"` metadata property. See [Providing startup script contents directly](https://cloud.google.com/compute/docs/startupscript#providing_startup_script_contents_directly) for more details.
When using `startup_script_file` the following rules apply:
- The contents of the script file will overwrite the value of the `"startup_script"` metadata property at runtime.
- The contents of the script file will be wrapped in Packer's startup script wrapper, unless `wrap_startup_script` is disabled. See `wrap_startup_script` for more details.
- Not supported by Windows instances. See [Startup Scripts for Windows](https://cloud.google.com/compute/docs/startupscript#providing_a_startup_script_for_windows_instances) for more details.
@ -174,9 +171,8 @@
If "true", the contents of `startup_script_file` or `"startup_script"` in the instance metadata
is wrapped in a Packer specific script that tracks the execution and completion of the provided
startup script. The wrapper ensures that the builder will not continue until the startup script has been executed.
- The use of the wrapped script file requires that the user or service account
running the build has the compute.instance.Metadata role.
running the build has the compute.instance.Metadata role.
- `subnetwork` (string) - The Google Compute subnetwork id or URL to use for the launched
instance. Only required if the network has been created with custom
@ -195,12 +191,12 @@
and setting the `enable-oslogin` to `TRUE` in the instance metadata.
Optionally, `use_os_login` can be used with an existing `ssh_username` and `ssh_private_key_file`
if a SSH key has already been added to the Google account's login profile - See [Adding SSH Keys](https://cloud.google.com/compute/docs/instances/managing-instance-access#add_oslogin_keys).
SSH keys can be added to an individual user account
```shell-session
$ gcloud compute os-login ssh-keys add --key-file=/home/user/.ssh/my-key.pub
$ gcloud compute os-login describe-profile
PosixAccounts:
- accountId: <project-id>
@ -214,13 +210,12 @@
000000000000000000000000000000000000000000000000000000000000000a:
fingerprint: 000000000000000000000000000000000000000000000000000000000000000a
```
Or SSH keys can be added to an associated service account
```shell-session
$ gcloud auth activate-service-account --key-file=<path to service account credentials file (e.g account.json)>
$ gcloud compute os-login ssh-keys add --key-file=/home/user/.ssh/my-key.pub
$ gcloud compute os-login describe-profile
PosixAccounts:
- accountId: <project-id>

3
website/content/partials/builder/googlecompute/IAPConfig-not-required.mdx
View File

@ -2,11 +2,10 @@
- `use_iap` (bool) - Whether to use an IAP proxy.
Prerequisites and limitations for using IAP:
- You must manually enable the IAP API in the Google Cloud console.
- You must have the gcloud sdk installed on the computer running Packer.
- You must be using a Service Account with a credentials file (using the
account_file option in the Packer template)
account_file option in the Packer template)
- You must add the given service account to project level IAP permissions
in https://console.cloud.google.com/security/iap. To do so, click
"project" > "SSH and TCP resoures" > "All Tunnel Resources" >

32
website/content/partials/builder/hyperv/common/CommonConfig-not-required.mdx
View File

@ -83,7 +83,7 @@
VM files and folders during the build. By default `%TEMP%` is used
which, for most systems, will evaluate to
`%USERPROFILE%/AppData/Local/Temp`.
The build directory housed under `temp_path` will have a name similar to
`packerhv1234567`. The seven digit number at the end of the name is
automatically generated by Packer to ensure the directory name is
@ -111,31 +111,29 @@
- `first_boot_device` (string) - When configured, determines the device or device type that is given preferential
treatment when choosing a boot device.
For Generation 1:
- `IDE`
- `CD` _or_ `DVD`
- `Floppy`
- `NET`
- `IDE`
- `CD` *or* `DVD`
- `Floppy`
- `NET`
For Generation 2:
- `IDE:x:y`
- `SCSI:x:y`
- `CD` _or_ `DVD`
- `NET`
- `IDE:x:y`
- `SCSI:x:y`
- `CD` *or* `DVD`
- `NET`
- `boot_order` ([]string) - When configured, the boot order determines the order of the devices
from which to boot.
The device name must be in the form of `SCSI:x:y`, for example,
to boot from the first scsi device use `SCSI:0:0`.
**NB** You should also set `first_boot_device` (e.g. `DVD`).
**NB** Although the VM will have this initial boot order, the OS can
change it, for example, Ubuntu 18.04 will modify the boot order to
include itself as the first boot option.
**NB** This only works for Generation 2 machines.

2
website/content/partials/builder/openstack/RunConfig-not-required.mdx
View File

@ -92,4 +92,4 @@
- `openstack_provider` (string) - Not really used, but here for BC
- `use_floating_ip` (bool) - _Deprecated_ use `floating_ip` or `floating_ip_pool` instead.
- `use_floating_ip` (bool) - *Deprecated* use `floating_ip` or `floating_ip_pool` instead.

68
website/content/partials/builder/openstack/RunConfig-required.mdx
View File

@ -12,48 +12,48 @@
providing source_image and only either of them can be specified.
- `source_image_filter` (ImageFilter) - Filters used to populate filter options. Example:
```json
{
"source_image_filter": {
"filters": {
"name": "ubuntu-16.04",
"visibility": "protected",
"owner": "d1a588cf4b0743344508dc145649372d1",
"tags": ["prod", "ready"],
"properties": {
"os_distro": "ubuntu"
}
},
"most_recent": true
}
"source_image_filter": {
"filters": {
"name": "ubuntu-16.04",
"visibility": "protected",
"owner": "d1a588cf4b0743344508dc145649372d1",
"tags": ["prod", "ready"],
"properties": {
"os_distro": "ubuntu"
}
},
"most_recent": true
}
}
```
This selects the most recent production Ubuntu 16.04 shared to you by
the given owner. NOTE: This will fail unless _exactly_ one image is
the given owner. NOTE: This will fail unless *exactly* one image is
returned, or `most_recent` is set to true. In the example of multiple
returned images, `most_recent` will cause this to succeed by selecting
the newest image of the returned images.
- `filters` (map of strings) - filters used to select a
`source_image`.
NOTE: This will fail unless _exactly_ one image is returned, or
`most_recent` is set to true. Of the filters described in
[ImageService](https://developer.openstack.org/api-ref/image/v2/), the
following are valid:
- name (string)
- owner (string)
- tags (array of strings)
- visibility (string)
- properties (map of strings to strings) (fields that can be set
with `openstack image set --property key=value`)
- `most_recent` (boolean) - Selects the newest created image when
true.
This is most useful for selecting a daily distro build.
- `filters` (map of strings) - filters used to select a
`source_image`.
NOTE: This will fail unless *exactly* one image is returned, or
`most_recent` is set to true. Of the filters described in
[ImageService](https://developer.openstack.org/api-ref/image/v2/), the
following are valid:
- name (string)
- owner (string)
- tags (array of strings)
- visibility (string)
- properties (map of strings to strings) (fields that can be set
with `openstack image set --property key=value`)
- `most_recent` (boolean) - Selects the newest created image when
true.
This is most useful for selecting a daily distro build.
You may set use this in place of `source_image` If `source_image_filter`
is provided alongside `source_image`, the `source_image` will override
the filter. The filter will not be used in this case.

89
website/content/partials/builder/qemu/Config-not-required.mdx
View File

@ -8,17 +8,17 @@
software must have already been installed on your build machine to use the
accelerator you specified. When no accelerator is specified, Packer will try
to use `kvm` if it is available but will default to `tcg` otherwise.
~> The `hax` accelerator has issues attaching CDROM ISOs. This is an
upstream issue which can be tracked
[here](https://github.com/intel/haxm/issues/20).
~> The `hvf` and `whpx` accelerator are new and experimental as of
[QEMU 2.12.0](https://wiki.qemu.org/ChangeLog/2.12#Host_support).
You may encounter issues unrelated to Packer when using these. You may need to
You may encounter issues unrelated to Packer when using these. You may need to
add [ "-global", "virtio-pci.disable-modern=on" ] to `qemuargs` depending on the
guest operating system.
~> For `whpx`, note that [Stefan Weil's QEMU for Windows distribution](https://qemu.weilnetz.de/w64/)
does not include WHPX support and users may need to compile or source a
build of QEMU for Windows themselves with WHPX support.
@ -28,22 +28,22 @@
is the default disk. Each string represents the disk image size in bytes.
Optional suffixes 'k' or 'K' (kilobyte, 1024), 'M' (megabyte, 1024k), 'G'
(gigabyte, 1024M), 'T' (terabyte, 1024G), 'P' (petabyte, 1024T) and 'E'
(exabyte, 1024P) are supported. 'b' is ignored. Per qemu-img documentation.
(exabyte, 1024P) are supported. 'b' is ignored. Per qemu-img documentation.
Each additional disk uses the same disk parameters as the default disk.
Unset by default.
- `cpus` (int) - The number of cpus to use when building the VM.
The default is `1` CPU.
The default is `1` CPU.
- `disk_interface` (string) - The interface to use for the disk. Allowed values include any of `ide`,
`scsi`, `virtio` or `virtio-scsi`^\*. Note also that any boot commands
or kickstart type scripts must have proper adjustments for resulting
device names. The Qemu builder uses `virtio` by default.
^\* Please be aware that use of the `scsi` disk interface has been
disabled by Red Hat due to a bug described
[here](https://bugzilla.redhat.com/show_bug.cgi?id=1019220). If you are
running Qemu on RHEL or a RHEL variant such as CentOS, you _must_ choose
running Qemu on RHEL or a RHEL variant such as CentOS, you *must* choose
one of the other listed interfaces. Using the `scsi` interface under
these circumstances will cause the build to fail.
@ -54,7 +54,7 @@
number is provided with no units, Packer will default to Megabytes.
- `skip_resize_disk` (bool) - Packer resizes the QCOW2 image using
qemu-img resize. Set this option to true to disable resizing.
qemu-img resize. Set this option to true to disable resizing.
Defaults to false.
- `disk_cache` (string) - The cache mode to use for disk. Allowed values include any of
@ -70,7 +70,7 @@
Packer still works with old versions of QEMU that don't have this option.
- `skip_compaction` (bool) - Packer compacts the QCOW2 image using
qemu-img convert. Set this option to true to disable compacting.
qemu-img convert. Set this option to true to disable compacting.
Defaults to false.
- `disk_compression` (bool) - Apply compression to the QCOW2 disk file
@ -87,7 +87,7 @@
- `headless` (bool) - Packer defaults to building QEMU virtual machines by
launching a GUI that shows the console of the machine being built. When this
value is set to `true`, the machine will start without a console.
You can still see the console if you make a note of the VNC display
number chosen, and then connect using `vncviewer -Shared <host>:<display>`
@ -121,12 +121,12 @@
- `net_bridge` (string) - Connects the network to this bridge instead of using the user mode
networking.
**NB** This bridge must already exist. You can use the `virbr0` bridge
as created by vagrant-libvirt.
**NB** This will automatically enable the QMP socket (see QMPEnable).
**NB** This only works in Linux based OSes.
- `output_directory` (string) - This is the path to the directory where the
@ -141,7 +141,7 @@
that overrides matching default switch/value pairs. Any value specified
as an empty string is ignored. All values after the switch are
concatenated with no separator.
~> **Warning:** The qemu command line allows extreme flexibility, so
beware of conflicting arguments causing failures of your run.
For instance adding a "--drive" or "--device" override will mean that
@ -152,16 +152,15 @@
you can use those arguments along with the template engines allowed
by qemu-args to set up a working configuration that includes both the
Packer defaults and your extra arguments.
Another pitfall could be setting arguments like --no-acpi, which could
break the ability to send power signal type commands
(e.g., shutdown -P now) to the virtual machine, thus preventing proper
shutdown.
The following shows a sample usage:
In JSON:
```json
"qemuargs": [
[ "-m", "1024M" ],
@ -175,9 +174,8 @@
[ "-device", "virtio-net,netdev=mynet0" ]
]
```
In HCL2:
```hcl
qemuargs = [
[ "-m", "1024M" ],
@ -191,66 +189,61 @@
[ "-device", "virtio-net,netdev=mynet0" ]
]
```
would produce the following (not including other defaults supplied by
the builder and not otherwise conflicting with the qemuargs):
```text
qemu-system-x86 -m 1024m --no-acpi -netdev
user,id=mynet0,hostfwd=hostip:hostport-guestip:guestport -device
virtio-net,netdev=mynet0"
```
~> **Windows Users:** [QEMU for Windows](https://qemu.weilnetz.de/)
builds are available though an environmental variable does need to be
set for QEMU for Windows to redirect stdout to the console instead of
stdout.txt.
The following shows the environment variable that needs to be set for
Windows QEMU support:
```text
setx SDL_STDIO_REDIRECT=0
```
You can also use the `SSHHostPort` template variable to produce a packer
template that can be invoked by `make` in parallel:
In JSON:
```json
"qemuargs": [
[ "-netdev", "user,hostfwd=tcp::{{ .SSHHostPort }}-:22,id=forward"],
[ "-device", "virtio-net,netdev=forward,id=net0"]
]
```
In HCL2:
```hcl
qemuargs = [
[ "-netdev", "user,hostfwd=tcp::{{ .SSHHostPort }}-:22,id=forward"],
[ "-device", "virtio-net,netdev=forward,id=net0"]
]
`make -j 3 my-awesome-packer-templates` spawns 3 packer processes, each
of which will bind to their own SSH port as determined by each process.
This will also work with WinRM, just change the port forward in
`qemuargs` to map to WinRM's default port of `5985` or whatever value
you have the service set to listen on.
This is a template engine and allows access to the following variables:
`{{ .HTTPIP }}`, `{{ .HTTPPort }}`, `{{ .HTTPDir }}`,
`{{ .OutputDir }}`, `{{ .Name }}`, and `{{ .SSHHostPort }}`
```
- `qemu_img_args` (QemuImgArgs) - A map of custom arguments to pass to qemu-img commands, where the key
is the subcommand, and the values are lists of strings for each flag.
Example:
In JSON:
```json
{
"qemu_img_args": {
@ -258,25 +251,23 @@
"resize": ["-foo", "bar"]
}
```
Please note
that unlike qemuargs, these commands are not split into switch-value
sub-arrays, because the basic elements in qemu-img calls are unlikely
sub-arrays, because the basic elements in qemu-img calls are unlikely
to need an actual override.
The arguments will be constructed as follows:
- Convert:
Default is `qemu-img convert -O $format $sourcepath $targetpath`. Adding
arguments ["-foo", "bar"] to qemu_img_args.convert will change this to
`qemu-img convert -foo bar -O $format $sourcepath $targetpath`
Default is `qemu-img convert -O $format $sourcepath $targetpath`. Adding
arguments ["-foo", "bar"] to qemu_img_args.convert will change this to
`qemu-img convert -foo bar -O $format $sourcepath $targetpath`
- Create:
Default is `create -f $format $targetpath $size`. Adding arguments
["-foo", "bar"] to qemu_img_args.create will change this to
"create -f qcow2 -foo bar target.qcow2 1234M"
Default is `create -f $format $targetpath $size`. Adding arguments
["-foo", "bar"] to qemu_img_args.create will change this to
"create -f qcow2 -foo bar target.qcow2 1234M"
- Resize:
Default is `qemu-img resize -f $format $sourcepath $size`. Adding
arguments ["-foo", "bar"] to qemu_img_args.resize will change this to
`qemu-img resize -f $format -foo bar $sourcepath $size`
Default is `qemu-img resize -f $format $sourcepath $size`. Adding
arguments ["-foo", "bar"] to qemu_img_args.resize will change this to
`qemu-img resize -f $format -foo bar $sourcepath $size`
- `qemu_binary` (string) - The name of the Qemu binary to look for. This
defaults to qemu-system-x86_64, but may need to be changed for

4
website/content/partials/builder/tencentcloud/cvm/TencentCloudAccessConfig-required.mdx
View File

@ -8,8 +8,8 @@
- `region` (string) - The region where your cvm will be launch. You should
reference Region and Zone
for parameter taking.
for parameter taking.
- `zone` (string) - The zone where your cvm will be launch. You should
reference Region and Zone
for parameter taking.
for parameter taking.

11
website/content/partials/builder/tencentcloud/cvm/TencentCloudRunConfig-not-required.mdx
View File

@ -24,10 +24,9 @@
type for all data disks, and each data disk size will use the origin
value in source image.
The data disks allow for the following argument:
- `disk_type` - Type of the data disk. Valid choices: `CLOUD_BASIC`, `CLOUD_PREMIUM` and `CLOUD_SSD`.
- `disk_size` - Size of the data disk.
- `disk_snapshot_id` - Id of the snapshot for a data disk.
- `disk_type` - Type of the data disk. Valid choices: `CLOUD_BASIC`, `CLOUD_PREMIUM` and `CLOUD_SSD`.
- `disk_size` - Size of the data disk.
- `disk_snapshot_id` - Id of the snapshot for a data disk.
- `vpc_id` (string) - Specify vpc your cvm will be launched by.
@ -61,8 +60,8 @@
- `host_name` (string) - host name.
- `run_tags` (map[string]string) - Key/value pair tags to apply to the instance that is _launched_ to
create the image. These tags are _not_ applied to the resulting image.
- `run_tags` (map[string]string) - Key/value pair tags to apply to the instance that is *launched* to
create the image. These tags are *not* applied to the resulting image.
- `run_tag` ([]{key string, value string}) - Same as [`run_tags`](#run_tags) but defined as a singular repeatable
block containing a `key` and a `value` field. In HCL2 mode the

2
website/content/partials/builder/tencentcloud/cvm/TencentCloudRunConfig-required.mdx
View File

@ -2,4 +2,4 @@
- `instance_type` (string) - The instance type your cvm will be launched by.
You should reference Instace Type
for parameter taking.
for parameter taking.

18
website/content/partials/builder/ucloud/common/ImageConfig-not-required.mdx
View File

@ -3,15 +3,15 @@
- `image_description` (string) - The description of the image.
- `image_copy_to_mappings` ([]ImageDestination) - The array of mappings regarding the copied images to the destination regions and projects.
- `project_id` (string) - The destination project id, where copying image in.
- `region` (string) - The destination region, where copying image in.
- `name` (string) - The copied image name. If not defined, builder will use `image_name` as default name.
- `description` (string) - The copied image description.
- `project_id` (string) - The destination project id, where copying image in.
- `region` (string) - The destination region, where copying image in.
- `name` (string) - The copied image name. If not defined, builder will use `image_name` as default name.
- `description` (string) - The copied image description.
```json
{
"image_copy_to_mappings": [

23
website/content/partials/builder/ucloud/common/RunConfig-not-required.mdx
View File

@ -7,7 +7,7 @@
Possible values are: `cloud_ssd` and `cloud_rssd` for cloud boot disk, `local_normal` and `local_ssd`
for local boot disk. (Default: `cloud_ssd`). The `cloud_ssd` and `local_ssd` are not fully supported
by all regions as boot disk type, please proceed to UCloud console for more details.
~> **Note:** It takes around 10 mins for boot disk initialization when `boot_disk_type` is `local_normal` or `local_ssd`.
- `vpc_id` (string) - The ID of VPC linked to the UHost instance. If not defined `vpc_id`, the instance will use the default VPC in the current region.
@ -39,17 +39,16 @@
- `min_cpu_platform` (string) - Specifies a minimum CPU platform for the the VM instance. (Default: `Intel/Auto`).
You may refer to [min_cpu_platform](https://docs.ucloud.cn/uhost/introduction/uhost/type_new)
- The Intel CPU platform:
- `Intel/Auto` as the Intel CPU platform version will be selected randomly by system;
- `Intel/IvyBridge` as Intel V2, the version of Intel CPU platform selected by system will be `Intel/IvyBridge` and above;
- `Intel/Haswell` as Intel V3, the version of Intel CPU platform selected by system will be `Intel/Haswell` and above;
- `Intel/Broadwell` as Intel V4, the version of Intel CPU platform selected by system will be `Intel/Broadwell` and above;
- `Intel/Skylake` as Intel V5, the version of Intel CPU platform selected by system will be `Intel/Skylake` and above;
- `Intel/Cascadelake` as Intel V6, the version of Intel CPU platform selected by system will be `Intel/Cascadelake`;
- The AMD CPU platform:
- `Amd/Auto` as the Amd CPU platform version will be selected randomly by system;
- `Amd/Epyc2` as the version of Amd CPU platform selected by system will be `Amd/Epyc2` and above;
- The Intel CPU platform:
- `Intel/Auto` as the Intel CPU platform version will be selected randomly by system;
- `Intel/IvyBridge` as Intel V2, the version of Intel CPU platform selected by system will be `Intel/IvyBridge` and above;
- `Intel/Haswell` as Intel V3, the version of Intel CPU platform selected by system will be `Intel/Haswell` and above;
- `Intel/Broadwell` as Intel V4, the version of Intel CPU platform selected by system will be `Intel/Broadwell` and above;
- `Intel/Skylake` as Intel V5, the version of Intel CPU platform selected by system will be `Intel/Skylake` and above;
- `Intel/Cascadelake` as Intel V6, the version of Intel CPU platform selected by system will be `Intel/Cascadelake`;
- The AMD CPU platform:
- `Amd/Auto` as the Amd CPU platform version will be selected randomly by system;
- `Amd/Epyc2` as the version of Amd CPU platform selected by system will be `Amd/Epyc2` and above;
- `use_ssh_private_ip` (bool) - If this value is true, packer will connect to the created UHost instance via a private ip
instead of allocating an EIP (elastic public ip).(Default: `false`).

31
website/content/partials/builder/vagrant/Config-not-required.mdx
View File

@ -11,23 +11,22 @@
"md5:{$checksum}", "sha1:{$checksum}", "sha256:{$checksum}",
"sha512:{$checksum}" or "file:{$path}". Here is a list of valid checksum
values:
* md5:090992ba9fd140077b0661cb75f7ce13
* 090992ba9fd140077b0661cb75f7ce13
* sha1:ebfb681885ddf1234c18094a45bbeafd91467911
* ebfb681885ddf1234c18094a45bbeafd91467911
* sha256:ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
* ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
* file:http://releases.ubuntu.com/20.04/MD5SUMS
* file:file://./local/path/file.sum
* file:./local/path/file.sum
* none
Although the checksum will not be verified when it is set to "none",
this is not recommended since these files can be very large and
corruption does happen from time to time.
- md5:090992ba9fd140077b0661cb75f7ce13
- 090992ba9fd140077b0661cb75f7ce13
- sha1:ebfb681885ddf1234c18094a45bbeafd91467911
- ebfb681885ddf1234c18094a45bbeafd91467911
- sha256:ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
- ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
- file:http://releases.ubuntu.com/20.04/MD5SUMS
- file:file://./local/path/file.sum
- file:./local/path/file.sum
- none
Although the checksum will not be verified when it is set to "none",
this is not recommended since these files can be very large and
corruption does happen from time to time.
- `box_name` (string) - if your source*box is a boxfile that we need to add to Vagrant, this is
the name to give it. If left blank, will default to "packer*" plus your
- `box_name` (string) - if your source_box is a boxfile that we need to add to Vagrant, this is
the name to give it. If left blank, will default to "packer_" plus your
buildname.
- `insert_key` (bool) - If true, Vagrant will automatically insert a keypair to use for SSH,

2
website/content/partials/builder/vagrant/Config-required.mdx
View File

@ -11,6 +11,6 @@
You can find the global id of your Vagrant boxes using the command
vagrant global-status; your global_id will be a 7-digit number and
letter comination that you'll find in the leftmost column of the
global-status output. If you choose to use global_id instead of
global-status output. If you choose to use global_id instead of
source_box, Packer will skip the Vagrant initialize and add steps, and
simply launch the box directly using the global id.

28
website/content/partials/builder/virtualbox/common/ExportConfig-not-required.mdx
View File

@ -7,27 +7,23 @@
export](https://www.virtualbox.org/manual/ch09.html#vboxmanage-export).
This can be useful for passing product information to include in the
resulting appliance file. Packer JSON configuration file example:
In JSON:
```json
{
"type": "virtualbox-iso",
"export_opts": [
"export_opts":
[
"--manifest",
"--vsys",
"0",
"--description",
"{{user `vm_description`}}",
"--version",
"{{user `vm_version`}}"
"--vsys", "0",
"--description", "{{user `vm_description`}}",
"--version", "{{user `vm_version`}}"
],
"format": "ova"
"format": "ova",
}
```
In HCL2:
```hcl
source "virtualbox-iso" "basic-example" {
export_opts = [
@ -39,7 +35,7 @@
format = "ova"
}
```
A VirtualBox [VM
description](https://www.virtualbox.org/manual/ch09.html#vboxmanage-export-ovf)
may contain arbitrary strings; the GUI interprets HTML formatting. However,
@ -47,14 +43,14 @@
multi-line description by preparing the string in the shell before the
packer call like this (shell `>` continuation character snipped for easier
copy & paste):
```shell
vm_description='some
multiline
description'
vm_version='0.2.0'
packer build \
-var "vm_description=${vm_description}" \
-var "vm_version=${vm_version}" \

24
website/content/partials/builder/virtualbox/common/GuestAdditionsConfig-not-required.mdx
View File

@ -14,19 +14,19 @@
iso_interface is not set. Options are "ide" and "sata".
- `guest_additions_path` (string) - The path on the guest virtual machine
where the VirtualBox guest additions ISO will be uploaded. By default this
is `VBoxGuestAdditions.iso` which should upload into the login directory of
the user. This is a [configuration
template](/docs/templates/engine) where the `Version`
variable is replaced with the VirtualBox version.
where the VirtualBox guest additions ISO will be uploaded. By default this
is `VBoxGuestAdditions.iso` which should upload into the login directory of
the user. This is a [configuration
template](/docs/templates/engine) where the `Version`
variable is replaced with the VirtualBox version.
- `guest_additions_sha256` (string) - The SHA256 checksum of the guest
additions ISO that will be uploaded to the guest VM. By default the
checksums will be downloaded from the VirtualBox website, so this only needs
to be set if you want to be explicit about the checksum.
additions ISO that will be uploaded to the guest VM. By default the
checksums will be downloaded from the VirtualBox website, so this only needs
to be set if you want to be explicit about the checksum.
- `guest_additions_url` (string) - The URL of the guest additions ISO
to upload. This can also be a file URL if the ISO is at a local path. By
default, the VirtualBox builder will attempt to find the guest additions ISO
on the local file system. If it is not available locally, the builder will
download the proper guest additions ISO from the internet.
to upload. This can also be a file URL if the ISO is at a local path. By
default, the VirtualBox builder will attempt to find the guest additions ISO
on the local file system. If it is not available locally, the builder will
download the proper guest additions ISO from the internet.

3
website/content/partials/builder/virtualbox/common/RunConfig-not-required.mdx
View File

@ -11,6 +11,7 @@
- `vrdp_port_min` (int) - The minimum and maximum port
to use for VRDP access to the virtual machine. Packer uses a randomly chosen
port in this range that appears available. By default this is 5900 to 6000. The minimum and maximum ports are inclusive.
port in this range that appears available. By default this is 5900 to
6000. The minimum and maximum ports are inclusive.
- `vrdp_port_max` (int) - VRDP Port Max

4
website/content/partials/builder/virtualbox/common/ShutdownConfig-not-required.mdx
View File

@ -19,8 +19,8 @@
or so. By default, the delay is 0s or disabled.
- `disable_shutdown` (bool) - Packer normally halts the virtual machine after all provisioners have
run when no `shutdown_command` is defined. If this is set to `true`, Packer
_will not_ halt the virtual machine but will assume that you will send the stop
run when no `shutdown_command` is defined. If this is set to `true`, Packer
*will not* halt the virtual machine but will assume that you will send the stop
signal yourself through the preseed.cfg or your final provisioner.
Packer will wait for a default of 5 minutes until the virtual machine is shutdown.
The timeout can be changed using `shutdown_timeout` option.

8
website/content/partials/builder/virtualbox/common/VBoxManageConfig-not-required.mdx
View File

@ -3,25 +3,23 @@
- `vboxmanage` ([][]string) - Custom `VBoxManage` commands to execute in order to further customize
the virtual machine being created. The example shown below sets the memory and number of CPUs
within the virtual machine:
In JSON:
```json
"vboxmanage": [
["modifyvm", "{{.Name}}", "--memory", "1024"],
["modifyvm", "{{.Name}}", "--cpus", "2"]
]
```
In HCL2:
```hcl
vboxmanage = [
["modifyvm", "{{.Name}}", "--memory", "1024"],
["modifyvm", "{{.Name}}", "--cpus", "2"],
]
```
The value of `vboxmanage` is an array of commands to execute. These commands are
executed in the order defined. So in the above example, the memory will be set
followed by the CPUs.

6
website/content/partials/builder/virtualbox/iso/Config-not-required.mdx
View File

@ -22,17 +22,15 @@
Virtualbox 6, install an [extension
pack](https://www.virtualbox.org/wiki/Downloads#VirtualBox6.0.14OracleVMVirtualBoxExtensionPack)
and you will need to enable EFI mode for nvme to work, ex:
In JSON:
```json
"vboxmanage": [
[ "modifyvm", "{{.Name}}", "--firmware", "EFI" ],
]
```
In HCL2:
```hcl
vboxmanage = [
[ "modifyvm", "{{.Name}}", "--firmware", "EFI" ],

27
website/content/partials/builder/virtualbox/ovf/Config-required.mdx
View File

@ -7,20 +7,19 @@
"md5:{$checksum}", "sha1:{$checksum}", "sha256:{$checksum}",
"sha512:{$checksum}" or "file:{$path}". Here is a list of valid checksum
values:
- md5:090992ba9fd140077b0661cb75f7ce13
- 090992ba9fd140077b0661cb75f7ce13
- sha1:ebfb681885ddf1234c18094a45bbeafd91467911
- ebfb681885ddf1234c18094a45bbeafd91467911
- sha256:ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
- ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
- file:http://releases.ubuntu.com/20.04/MD5SUMS
- file:file://./local/path/file.sum
- file:./local/path/file.sum
- none
Although the checksum will not be verified when it is set to "none",
this is not recommended since these files can be very large and
corruption does happen from time to time.
* md5:090992ba9fd140077b0661cb75f7ce13
* 090992ba9fd140077b0661cb75f7ce13
* sha1:ebfb681885ddf1234c18094a45bbeafd91467911
* ebfb681885ddf1234c18094a45bbeafd91467911
* sha256:ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
* ed363350696a726b7932db864dda019bd2017365c9e299627830f06954643f93
* file:http://releases.ubuntu.com/20.04/MD5SUMS
* file:file://./local/path/file.sum
* file:./local/path/file.sum
* none
Although the checksum will not be verified when it is set to "none",
this is not recommended since these files can be very large and
corruption does happen from time to time.
- `source_path` (string) - The filepath or URL to an OVF or OVA file that acts as the
source of this build.

32
website/content/partials/builder/virtualbox/vm/Config-not-required.mdx
View File

@ -1,27 +1,27 @@
<!-- Code generated from the comments of the Config struct in builder/virtualbox/vm/config.go; DO NOT EDIT MANUALLY -->
- `attach_snapshot` (string) - Default to `null/empty`. The name of an
**existing** snapshot to which the builder shall attach the VM before
starting it. If no snapshot is specified the builder will simply start the
VM from it's current state i.e. snapshot.
**existing** snapshot to which the builder shall attach the VM before
starting it. If no snapshot is specified the builder will simply start the
VM from it's current state i.e. snapshot.
- `target_snapshot` (string) - Default to `null/empty`. The name of the
snapshot which shall be created after all provisioners has been run by the
builder. If no target snapshot is specified and `keep_registered` is set to
`false` the builder will revert to the snapshot to which the VM was attached
before the builder has been executed, which will revert all changes applied
by the provisioners. This is handy if only an export shall be created and no
further snapshot is required.
snapshot which shall be created after all provisioners has been run by the
builder. If no target snapshot is specified and `keep_registered` is set to
`false` the builder will revert to the snapshot to which the VM was attached
before the builder has been executed, which will revert all changes applied
by the provisioners. This is handy if only an export shall be created and no
further snapshot is required.
- `force_delete_snapshot` (bool) - Defaults to `false`. If set to `true`,
overwrite an existing `target_snapshot`. Otherwise the builder will yield an
error if the specified target snapshot already exists.
overwrite an existing `target_snapshot`. Otherwise the builder will yield an
error if the specified target snapshot already exists.
- `keep_registered` (bool) - Set this to `true` if you would like to keep
the VM attached to the snapshot specified by `attach_snapshot`. Otherwise
the builder will reset the VM to the snapshot to which the VM was attached
before the builder started. Defaults to `false`.
the VM attached to the snapshot specified by `attach_snapshot`. Otherwise
the builder will reset the VM to the snapshot to which the VM was attached
before the builder started. Defaults to `false`.
- `skip_export` (bool) - Defaults to `false`. When enabled, Packer will
not export the VM. Useful if the builder should be applied again on the created
target snapshot.
not export the VM. Useful if the builder should be applied again on the created
target snapshot.

2
website/content/partials/builder/virtualbox/vm/Config-required.mdx
View File

@ -1,4 +1,4 @@
<!-- Code generated from the comments of the Config struct in builder/virtualbox/vm/config.go; DO NOT EDIT MANUALLY -->
- `vm_name` (string) - This is the name of the virtual machine to which the
builder shall attach.
builder shall attach.

44
website/content/partials/builder/vmware/common/DiskConfig-not-required.mdx
View File

@ -21,25 +21,25 @@
- `disk_type_id` (string) - The type of VMware virtual disk to create. This
option is for advanced usage.
For desktop VMware clients:
| Type ID | Description |
| ------- | ----------------------------------------------------------------------- |
| `0` | Growable virtual disk contained in a single file (monolithic sparse). |
| `1` | Growable virtual disk split into 2GB files (split sparse). |
| `2` | Preallocated virtual disk contained in a single file (monolithic flat). |
| `3` | Preallocated virtual disk split into 2GB files (split flat). |
| `4` | Preallocated virtual disk compatible with ESX server (VMFS flat). |
| `5` | Compressed disk optimized for streaming. |
The default is `1`.
For ESXi, this defaults to `zeroedthick`. The available options for ESXi
are: `zeroedthick`, `eagerzeroedthick`, `thin`. `rdm:dev`, `rdmp:dev`,
`2gbsparse` are not supported. Due to default disk compaction, when using
`zeroedthick` or `eagerzeroedthick` set `skip_compaction` to `true`.
For more information, please consult the [Virtual Disk Manager User's
Guide](https://www.vmware.com/pdf/VirtualDiskManager.pdf) for desktop
VMware clients. For ESXi, refer to the proper ESXi documentation.
For desktop VMware clients:
Type ID | Description
------- | ---
`0` | Growable virtual disk contained in a single file (monolithic sparse).
`1` | Growable virtual disk split into 2GB files (split sparse).
`2` | Preallocated virtual disk contained in a single file (monolithic flat).
`3` | Preallocated virtual disk split into 2GB files (split flat).
`4` | Preallocated virtual disk compatible with ESX server (VMFS flat).
`5` | Compressed disk optimized for streaming.
The default is `1`.
For ESXi, this defaults to `zeroedthick`. The available options for ESXi
are: `zeroedthick`, `eagerzeroedthick`, `thin`. `rdm:dev`, `rdmp:dev`,
`2gbsparse` are not supported. Due to default disk compaction, when using
`zeroedthick` or `eagerzeroedthick` set `skip_compaction` to `true`.
For more information, please consult the [Virtual Disk Manager User's
Guide](https://www.vmware.com/pdf/VirtualDiskManager.pdf) for desktop
VMware clients. For ESXi, refer to the proper ESXi documentation.

62
website/content/partials/builder/vmware/common/HWConfig-not-required.mdx
View File

@ -32,58 +32,58 @@
- `serial` (string) - This specifies a serial port to add to the VM. It has a format of
`Type:option1,option2,...`. The field `Type` can be one of the following
values: `FILE`, `DEVICE`, `PIPE`, `AUTO`, or `NONE`.
- `FILE:path(,yield)` - Specifies the path to the local file to be used
* `FILE:path(,yield)` - Specifies the path to the local file to be used
as the serial port.
- `yield` (bool) - This is an optional boolean that specifies
* `yield` (bool) - This is an optional boolean that specifies
whether the vm should yield the cpu when polling the port. By
default, the builder will assume this as `FALSE`.
- `DEVICE:path(,yield)` - Specifies the path to the local device to be
  used as the serial port. If `path` is empty, then default to the first
* `DEVICE:path(,yield)` - Specifies the path to the local device to be
  used as the serial port. If `path` is empty, then default to the first
serial port.
- `yield` (bool) - This is an optional boolean that specifies
* `yield` (bool) - This is an optional boolean that specifies
whether the vm should yield the cpu when polling the port. By
default, the builder will assume this as `FALSE`.
- `PIPE:path,endpoint,host(,yield)` - Specifies to use the named-pipe
* `PIPE:path,endpoint,host(,yield)` - Specifies to use the named-pipe
"path" as a serial port. This has a few options that determine how the
VM should use the named-pipe.
- `endpoint` (string) - Chooses the type of the VM-end, which can be
* `endpoint` (string) - Chooses the type of the VM-end, which can be
either a `client` or `server`.
- `host` (string) - Chooses the type of the host-end, which can
* `host` (string) - Chooses the type of the host-end, which can
be either `app` (application) or `vm` (another virtual-machine).
- `yield` (bool) - This is an optional boolean that specifies
* `yield` (bool) - This is an optional boolean that specifies
whether the vm should yield the cpu when polling the port. By
default, the builder will assume this as `FALSE`.
- `AUTO:(yield)` - Specifies to use auto-detection to determine the
* `AUTO:(yield)` - Specifies to use auto-detection to determine the
serial port to use. This has one option to determine how the VM should
support the serial port.
- `yield` (bool) - This is an optional boolean that specifies
* `yield` (bool) - This is an optional boolean that specifies
whether the vm should yield the cpu when polling the port. By
default, the builder will assume this as `FALSE`.
- `NONE` - Specifies to not use a serial port. (default)
* `NONE` - Specifies to not use a serial port. (default)
- `parallel` (string) - This specifies a parallel port to add to the VM. It has the format of
`Type:option1,option2,...`. Type can be one of the following values:
`FILE`, `DEVICE`, `AUTO`, or `NONE`.
- `FILE:path` - Specifies the path to the local file to be used
* `FILE:path` - Specifies the path to the local file to be used
for the parallel port.
- `DEVICE:path` - Specifies the path to the local device to be used
* `DEVICE:path` - Specifies the path to the local device to be used
for the parallel port.
- `AUTO:direction` - Specifies to use auto-detection to determine the
* `AUTO:direction` - Specifies to use auto-detection to determine the
parallel port. Direction can be `BI` to specify bidirectional
communication or `UNI` to specify unidirectional communication.
- `NONE` - Specifies to not use a parallel port. (default)
* `NONE` - Specifies to not use a parallel port. (default)

16
website/content/partials/builder/vmware/common/OutputConfig-not-required.mdx
View File

@ -4,31 +4,31 @@
directory where the resulting virtual machine will be created.
This may be relative or absolute. If relative, the path is relative to
the working directory when packer is executed.
If you are running a remote esx build, the output_dir is the path on your
local machine (the machine running Packer) to which Packer will export
the vm if you have `"skip_export": false`. If you want to manage the
virtual machine's path on the remote datastore, use `remote_output_dir`.
This directory must not exist or be empty prior to running
the builder.
By default this is output-BUILDNAME where "BUILDNAME" is the name of the
build.
- `remote_output_directory` (string) - This is the directoy on your remote esx host where you will save your
vm, relative to your remote_datastore.
This option's default value is your `vm_name`, and the final path of your
vm will be vmfs/volumes/$remote_datastore/$vm_name/$vm_name.vmx where
`$remote_datastore`and`$vm_name` match their corresponding template
`$remote_datastore` and `$vm_name` match their corresponding template
options
For example, setting `"remote_output_directory": "path/to/subdir`
will create a directory `/vmfs/volumes/remote_datastore/path/to/subdir`.
Packer will not create the remote datastore for you; it must already
exist. However, Packer will create all directories defined in the option
that do not currently exist.
This option will be ignored unless you are building on a remote esx host.

2
website/content/partials/builder/vmware/iso/Config-not-required.mdx
View File

@ -34,7 +34,7 @@
defines the contents of the virtual machine VMX file for VMware. The
engine has access to the template variables `{{ .DiskNumber }}` and
`{{ .DiskName }}`.
This is for **advanced users only** as this can render the virtual machine
non-functional. See below for more information. For basic VMX
modifications, try `vmx_data` first.

2
website/content/partials/builder/vmware/vmx/Config-not-required.mdx
View File

@ -3,7 +3,7 @@
- `linked` (bool) - By default Packer creates a 'full' clone of the virtual machine
specified in source_path. The resultant virtual machine is fully
independant from the parent it was cloned from.
Setting linked to true instead causes Packer to create the virtual
machine as a 'linked' clone. Linked clones use and require ongoing
access to the disks of the parent virtual machine. The benefit of a

2
website/content/partials/builder/vsphere/clone/vAppConfig-not-required.mdx
View File

@ -2,7 +2,7 @@
- `properties` (map[string]string) - Set values for the available vApp Properties to supply configuration parameters to a virtual machine cloned from
a template that came from an imported OVF or OVA file.
-> **Note:** The only supported usage path for vApp properties is for existing user-configurable keys.
These generally come from an existing template that was created from an imported OVF or OVA file.
You cannot set values for vApp properties on virtual machines created from scratch,

2
website/content/partials/builder/vsphere/common/ContentLibraryDestinationConfig-not-required.mdx
View File

@ -8,7 +8,7 @@
the default is [vm_name](#vm_name) + timestamp when not set. VM templates will be always imported to a new library item.
For OVF templates, the name defaults to [vm_name](#vm_name) when not set, and if an item with the same name already
exists it will be then updated with the new OVF template, otherwise a new item will be created.
~> **Note**: It's not possible to update existing library items with a new VM template. If updating an existing library
item is necessary, use an OVF template instead by setting the [ovf](#ovf) option as `true`.

5
website/content/partials/builder/vsphere/common/DiskConfig.mdx
View File

@ -5,7 +5,6 @@ Defines the disk storage for a VM.
Example that will create a 15GB and a 20GB disk on the VM. The second disk will be thin provisioned:
In JSON:
```json
"storage": [
{
@ -17,9 +16,7 @@ In JSON:
}
],
```
In HCL2:
```hcl
storage {
disk_size = 15000
@ -33,7 +30,6 @@ In HCL2:
Example that creates 2 pvscsi controllers and adds 2 disks to each one:
In JSON:
```json
"disk_controller_type": ["pvscsi", "pvscsi"],
"storage": [
@ -57,7 +53,6 @@ In JSON:
```
In HCL2:
```hcl
disk_controller_type = ["pvscsi", "pvscsi"]
storage {

16
website/content/partials/builder/vsphere/common/ExportConfig-not-required.mdx
View File

@ -9,25 +9,21 @@
- `manifest` (string) - generate manifest using sha1, sha256, sha512. Defaults to 'sha256'. Use 'none' for no manifest.
- `options` ([]string) - Advanced ovf export options. Options can include:
- mac - MAC address is exported for all ethernet devices
- uuid - UUID is exported for all virtual machines
- extraconfig - all extra configuration options are exported for a virtual machine
- nodevicesubtypes - resource subtypes for CD/DVD drives, floppy drives, and serial and parallel ports are not exported
* mac - MAC address is exported for all ethernet devices
* uuid - UUID is exported for all virtual machines
* extraconfig - all extra configuration options are exported for a virtual machine
* nodevicesubtypes - resource subtypes for CD/DVD drives, floppy drives, and serial and parallel ports are not exported
For example, adding the following export config option would output the mac addresses for all Ethernet devices in the ovf file:
In JSON:
```json
...
"export": {
"options": ["mac"]
},
```
In HCL2:
```hcl
...
export {

4
website/content/partials/builder/vsphere/common/ExportConfig.mdx
View File

@ -5,7 +5,6 @@ You may optionally export an ovf from VSphere to the instance running Packer.
Example usage:
In JSON:
```json
...
"vm_name": "example-ubuntu",
@ -15,9 +14,7 @@ In JSON:
"output_directory": "./output_vsphere"
},
```
In HCL2:
```hcl
# ...
vm_name = "example-ubuntu"
@ -27,7 +24,6 @@ In HCL2:
output_directory = "./output_vsphere"
}
```
The above configuration would create the following files:
```text

2
website/content/partials/builder/vsphere/common/OutputConfig-not-required.mdx
View File

@ -9,7 +9,7 @@
"output-BUILDNAME" where "BUILDNAME" is the name of the build.
- `directory_permission` (os.FileMode) - The permissions to apply to the "output_directory", and to any parent
directories that get created for output_directory. By default this is
directories that get created for output_directory. By default this is
"0750". You should express the permission as quoted string with a
leading zero such as "0755" in JSON file, because JSON does not support
octal value. In Unix-like OS, the actual permission may differ from

2
website/content/partials/builder/vsphere/common/ShutdownConfig-not-required.mdx
View File

@ -10,7 +10,7 @@
- `disable_shutdown` (bool) - Packer normally halts the virtual machine after all provisioners have
run when no `shutdown_command` is defined. If this is set to `true`, Packer
_will not_ halt the virtual machine but will assume that you will send the stop
*will not* halt the virtual machine but will assume that you will send the stop
signal yourself through a preseed.cfg, a script or the final provisioner.
Packer will wait for a default of five minutes until the virtual machine is shutdown.
The timeout can be changed using `shutdown_timeout` option.

10
website/content/partials/builder/vsphere/common/WaitIpConfig-not-required.mdx
View File

@ -10,11 +10,11 @@
parameter to apx. 2 minutes. Examples 45s and 10m. Defaults to
5s(5 seconds). See the Golang
[ParseDuration](https://golang.org/pkg/time/#ParseDuration) documentation
for full details.
for full details.
- `ip_wait_address` (\*string) - Set this to a CIDR address to cause the service to wait for an address that is contained in
this network range. Defaults to "0.0.0.0/0" for any ipv4 address. Examples include:
- empty string ("") - remove all filters
- `0:0:0:0:0:0:0:0/0` - allow only ipv6 addresses
- `192.168.1.0/24` - only allow ipv4 addresses from 192.168.1.1 to 192.168.1.254
* empty string ("") - remove all filters
* `0:0:0:0:0:0:0:0/0` - allow only ipv6 addresses
* `192.168.1.0/24` - only allow ipv4 addresses from 192.168.1.1 to 192.168.1.254

3
website/content/partials/builder/vsphere/iso/NIC.mdx
View File

@ -5,7 +5,6 @@ Defines a Network Adapter
Example that creates two network adapters:
In JSON:
```json
"network_adapters": [
{
@ -18,9 +17,7 @@ In JSON:
}
],
```
In HCL2:
```hcl
network_adapters {
network = "VM Network"

9
website/content/partials/post-processor/alicloud-import/Config-not-required.mdx
View File

@ -22,11 +22,10 @@
- `image_copy_regions` ([]string) - Alicloud Image Destination Regions
- `image_system_size` (string) - Size of the system disk, in GB, values
range:
- cloud - 5 \~ 2000
- cloud_efficiency - 20 \~ 2048
- cloud_ssd - 20 \~ 2048
range:
- cloud - 5 \~ 2000
- cloud_efficiency - 20 \~ 2048
- cloud_ssd - 20 \~ 2048
- `image_force_delete` (bool) - If this value is true, when the target image name is duplicated with an
existing image, it will delete the existing image and then create the

6
website/content/partials/post-processor/ucloud-import/Config-not-required.mdx
View File

@ -1,9 +1,9 @@
<!-- Code generated from the comments of the Config struct in post-processor/ucloud-import/post-processor.go; DO NOT EDIT MANUALLY -->
- `ufile_key_name` (string) - The name of the object key in
`ufile_bucket_name` where the RAW, VHD, VMDK, or qcow2 file will be copied
to import. This is a [template engine](/docs/templates/engine).
Therefore, you may use user variables and template functions in this field.
`ufile_bucket_name` where the RAW, VHD, VMDK, or qcow2 file will be copied
to import. This is a [template engine](/docs/templates/engine).
Therefore, you may use user variables and template functions in this field.
- `skip_clean` (bool) - Whether we should skip removing the RAW, VHD, VMDK, or qcow2 file uploaded to
UFile after the import process has completed. Possible values are: `true` to

2
website/content/partials/post-processor/ucloud-import/Config-required.mdx
View File

@ -1,7 +1,7 @@
<!-- Code generated from the comments of the Config struct in post-processor/ucloud-import/post-processor.go; DO NOT EDIT MANUALLY -->
- `ufile_bucket_name` (string) - The name of the UFile bucket where the RAW, VHD, VMDK, or qcow2 file will be copied to for import.
This bucket must exist when the post-processor is run.
This bucket must exist when the post-processor is run.
- `image_name` (string) - The name of the user-defined image, which contains 1-63 characters and only
supports Chinese, English, numbers, '-\_,.:[]'.

2
website/content/partials/post-processor/yandex-import/Config-not-required.mdx
View File

@ -2,7 +2,7 @@
- `bucket` (string) - The name of the bucket where the qcow2 file will be uploaded to for import.
This bucket must exist when the post-processor is run.
If import occurred after Yandex-Export post-processor, artifact already
in storage service and first paths (URL) is used to, so no need to set this param.

150
website/content/partials/provisioner/ansible/Config-not-required.mdx
View File

@ -1,26 +1,26 @@
<!-- Code generated from the comments of the Config struct in provisioner/ansible/provisioner.go; DO NOT EDIT MANUALLY -->
- `command` (string) - The command to invoke ansible. Defaults to
`ansible-playbook`. If you would like to provide a more complex command,
for example, something that sets up a virtual environment before calling
ansible, take a look at the ansible wrapper guide below for inspiration.
Please note that Packer expects Command to be a path to an executable.
Arbitrary bash scripting will not work and needs to go inside an
executable script.
`ansible-playbook`. If you would like to provide a more complex command,
for example, something that sets up a virtual environment before calling
ansible, take a look at the ansible wrapper guide below for inspiration.
Please note that Packer expects Command to be a path to an executable.
Arbitrary bash scripting will not work and needs to go inside an
executable script.
- `extra_arguments` ([]string) - Extra arguments to pass to Ansible.
These arguments _will not_ be passed through a shell and arguments should
not be quoted. Usage example:
```json
"extra_arguments": [ "--extra-vars", "Region={{user `Region`}} Stage={{user `Stage`}}" ]
```
If you are running a Windows build on AWS, Azure, Google Compute, or OpenStack
and would like to access the auto-generated password that Packer uses to
connect to a Windows instance via WinRM, you can use the template variable
`{{.WinRMPassword}}` in this option. For example:
```json
"extra_arguments": [
"--extra-vars", "winrm_password={{ .WinRMPassword }}"
@ -28,77 +28,77 @@
```
- `ansible_env_vars` ([]string) - Environment variables to set before
running Ansible. Usage example:
```json
"ansible_env_vars": [ "ANSIBLE_HOST_KEY_CHECKING=False", "ANSIBLE_SSH_ARGS='-o ForwardAgent=yes -o ControlMaster=auto -o ControlPersist=60s'", "ANSIBLE_NOCOLOR=True" ]
```
This is a [template engine](/docs/templates/engine). Therefore, you
may use user variables and template functions in this field.
For example, if you are running a Windows build on AWS, Azure,
Google Compute, or OpenStack and would like to access the auto-generated
password that Packer uses to connect to a Windows instance via WinRM, you
can use the template variable `{{.WinRMPassword}}` in this option. Example:
```json
"ansible_env_vars": [ "WINRM_PASSWORD={{.WinRMPassword}}" ],
```
running Ansible. Usage example:
```json
"ansible_env_vars": [ "ANSIBLE_HOST_KEY_CHECKING=False", "ANSIBLE_SSH_ARGS='-o ForwardAgent=yes -o ControlMaster=auto -o ControlPersist=60s'", "ANSIBLE_NOCOLOR=True" ]
```
This is a [template engine](/docs/templates/engine). Therefore, you
may use user variables and template functions in this field.
For example, if you are running a Windows build on AWS, Azure,
Google Compute, or OpenStack and would like to access the auto-generated
password that Packer uses to connect to a Windows instance via WinRM, you
can use the template variable `{{.WinRMPassword}}` in this option. Example:
```json
"ansible_env_vars": [ "WINRM_PASSWORD={{.WinRMPassword}}" ],
```
- `ansible_ssh_extra_args` ([]string) - Specifies --ssh-extra-args on command line defaults to -o IdentitiesOnly=yes
- `groups` ([]string) - The groups into which the Ansible host should
be placed. When unspecified, the host is not associated with any groups.
be placed. When unspecified, the host is not associated with any groups.
- `empty_groups` ([]string) - The groups which should be present in
inventory file but remain empty.
inventory file but remain empty.
- `host_alias` (string) - The alias by which the Ansible host should be
known. Defaults to `default`. This setting is ignored when using a custom
inventory file.
- `user` (string) - The `ansible_user` to use. Defaults to the user running
packer, NOT the user set for your communicator. If you want to use the same
user as the communicator, you will need to manually set it again in this
field.
packer, NOT the user set for your communicator. If you want to use the same
user as the communicator, you will need to manually set it again in this
field.
- `local_port` (int) - The port on which to attempt to listen for SSH
connections. This value is a starting point. The provisioner will attempt
listen for SSH connections on the first available of ten ports, starting at
`local_port`. A system-chosen port is used when `local_port` is missing or
empty.
connections. This value is a starting point. The provisioner will attempt
listen for SSH connections on the first available of ten ports, starting at
`local_port`. A system-chosen port is used when `local_port` is missing or
empty.
- `ssh_host_key_file` (string) - The SSH key that will be used to run the SSH
server on the host machine to forward commands to the target machine.
Ansible connects to this server and will validate the identity of the
server using the system known_hosts. The default behavior is to generate
and use a onetime key. Host key checking is disabled via the
`ANSIBLE_HOST_KEY_CHECKING` environment variable if the key is generated.
server on the host machine to forward commands to the target machine.
Ansible connects to this server and will validate the identity of the
server using the system known_hosts. The default behavior is to generate
and use a onetime key. Host key checking is disabled via the
`ANSIBLE_HOST_KEY_CHECKING` environment variable if the key is generated.
- `ssh_authorized_key_file` (string) - The SSH public key of the Ansible
`ssh_user`. The default behavior is to generate and use a onetime key. If
this key is generated, the corresponding private key is passed to
`ansible-playbook` with the `-e ansible_ssh_private_key_file` option.
`ssh_user`. The default behavior is to generate and use a onetime key. If
this key is generated, the corresponding private key is passed to
`ansible-playbook` with the `-e ansible_ssh_private_key_file` option.
- `sftp_command` (string) - The command to run on the machine being
provisioned by Packer to handle the SFTP protocol that Ansible will use to
transfer files. The command should read and write on stdin and stdout,
respectively. Defaults to `/usr/lib/sftp-server -e`.
provisioned by Packer to handle the SFTP protocol that Ansible will use to
transfer files. The command should read and write on stdin and stdout,
respectively. Defaults to `/usr/lib/sftp-server -e`.
- `skip_version_check` (bool) - Check if ansible is installed prior to
running. Set this to `true`, for example, if you're going to install
ansible during the packer run.
running. Set this to `true`, for example, if you're going to install
ansible during the packer run.
- `use_sftp` (bool) - Use SFTP
- `inventory_directory` (string) - The directory in which to place the
temporary generated Ansible inventory file. By default, this is the
system-specific temporary file location. The fully-qualified name of this
temporary file will be passed to the `-i` argument of the `ansible` command
when this provisioner runs ansible. Specify this if you have an existing
inventory directory with `host_vars` `group_vars` that you would like to
use in the playbook that this provisioner will run.
temporary generated Ansible inventory file. By default, this is the
system-specific temporary file location. The fully-qualified name of this
temporary file will be passed to the `-i` argument of the `ansible` command
when this provisioner runs ansible. Specify this if you have an existing
inventory directory with `host_vars` `group_vars` that you would like to
use in the playbook that this provisioner will run.
- `inventory_file_template` (string) - This template represents the format for the lines added to the temporary
inventory file that Packer will create to run Ansible against your image.
@ -110,36 +110,36 @@
"build" template engine.
- `inventory_file` (string) - The inventory file to use during provisioning.
When unspecified, Packer will create a temporary inventory file and will
use the `host_alias`.
When unspecified, Packer will create a temporary inventory file and will
use the `host_alias`.
- `keep_inventory_file` (bool) - If `true`, the Ansible provisioner will
not delete the temporary inventory file it creates in order to connect to
the instance. This is useful if you are trying to debug your ansible run
and using "--on-error=ask" in order to leave your instance running while you
test your playbook. this option is not used if you set an `inventory_file`.
not delete the temporary inventory file it creates in order to connect to
the instance. This is useful if you are trying to debug your ansible run
and using "--on-error=ask" in order to leave your instance running while you
test your playbook. this option is not used if you set an `inventory_file`.
- `galaxy_file` (string) - A requirements file which provides a way to
install roles or collections with the [ansible-galaxy
cli](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#the-ansible-galaxy-command-line-tool)
on the local machine before executing `ansible-playbook`. By default, this is empty.
install roles or collections with the [ansible-galaxy
cli](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#the-ansible-galaxy-command-line-tool)
on the local machine before executing `ansible-playbook`. By default, this is empty.
- `galaxy_command` (string) - The command to invoke ansible-galaxy. By default, this is
`ansible-galaxy`.
- `galaxy_force_install` (bool) - Force overwriting an existing role.
Adds `--force` option to `ansible-galaxy` command. By default, this is
`false`.
Adds `--force` option to `ansible-galaxy` command. By default, this is
`false`.
- `roles_path` (string) - The path to the directory on your local system in which to
install the roles. Adds `--roles-path /path/to/your/roles` to
`ansible-galaxy` command. By default, this is empty, and thus `--roles-path`
option is not added to the command.
install the roles. Adds `--roles-path /path/to/your/roles` to
`ansible-galaxy` command. By default, this is empty, and thus `--roles-path`
option is not added to the command.
- `collections_path` (string) - The path to the directory on your local system in which to
install the collections. Adds `--collections-path /path/to/your/collections` to
`ansible-galaxy` command. By default, this is empty, and thus `--collections-path`
option is not added to the command.
install the collections. Adds `--collections-path /path/to/your/collections` to
`ansible-galaxy` command. By default, this is empty, and thus `--collections-path`
option is not added to the command.
- `use_proxy` (boolean) - When `true`, set up a localhost proxy adapter
so that Ansible has an IP address to connect to, even if your guest does not
@ -147,15 +147,15 @@
to use the Ansible provisioner. If you set this option to `false`, but
Packer cannot find an IP address to connect Ansible to, it will
automatically set up the adapter anyway.
In order for Ansible to connect properly even when use_proxy is false, you
In order for Ansible to connect properly even when use_proxy is false, you
need to make sure that you are either providing a valid username and ssh key
to the ansible provisioner directly, or that the username and ssh key
being used by the ssh communicator will work for your needs. If you do not
provide a user to ansible, it will use the user associated with your
builder, not the user running Packer.
use_proxy=false is currently only supported for SSH and WinRM.
use_proxy=false is currently only supported for SSH and WinRM.
Currently, this defaults to `true` for all connection types. In the future,
this option will be changed to default to `false` for SSH and WinRM
connections where the provisioner has access to a host IP.