From b68168807aa249993dac9fc52b3978eb1b03a267 Mon Sep 17 00:00:00 2001 From: Josh Soref Date: Thu, 18 Oct 2018 19:09:49 -0400 Subject: [PATCH] Miscellaneous doc improvements backticks, spaces, commas In general, a list of items should have a space after each comma. While there are editorial styles that suggest commas inside quotations, they're horrible advice when the backticks are describing specific character for a user to enter. one off indent filters section singular backticks... word wrap long lines... spelling: macOS contributing: clarify closing case contributing: link to changelog contributing: point to git remote... contributing: split commands from descriptions contributing: grammar spelling: github grammar: comma after etc. spelling: macOS grammar: i.e. alicloud: use relative link alicloud: use backticks alicloud: bits alicloud: such as grammar: comma after etc. avoid linking periods grammar: period amazon-chroot: IOPS amazon-chroot: use backticks amazon-chroot: link to section amazon-chroot: whether-or-not; period amazon-ebs: period amazon-ebs: use relative link amazon-ebs: use backticks amazon-ebs: comma amazon-ebs: bold amazon-ebssurrogate: comma after etc. amazon-ebssurrogate: this builder amazon-instance: this builder amazon-ebssurrogate: set this amazon-ebssurrogate: whether-or-not amazon-ebssurrogate: period amazon-ebssurrogate: bold section reference amazon-ebssurrogate: backticks... amazon-ebssurrogate: commas around e.g. spelling: precedence spelling: i.e. amazon-ebssurrogate: backticks... --- .github/CONTRIBUTING.md | 38 ++++++++++----- .github/ISSUE_TEMPLATE.md | 2 +- README.md | 2 +- builder/azure/TODO.md | 2 +- test/README.md | 2 +- .../source/docs/builders/alicloud-ecs.html.md | 28 +++++------ .../docs/builders/amazon-chroot.html.md | 48 +++++++++---------- .../source/docs/builders/amazon-ebs.html.md | 38 +++++++-------- .../docs/builders/amazon-ebssurrogate.html.md | 42 ++++++++-------- .../docs/builders/amazon-ebsvolume.html.md | 4 +- .../docs/builders/amazon-instance.html.md | 12 ++--- .../docs/builders/googlecompute.html.md | 23 +++++---- website/source/docs/builders/lxd.html.md | 2 +- website/source/docs/builders/scaleway.html.md | 6 +-- .../post-processors/amazon-import.html.md | 2 +- .../intro/getting-started/build-image.html.md | 8 ++-- 16 files changed, 139 insertions(+), 120 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b94280a16..d871407c7 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -59,7 +59,7 @@ runtime in order to build packer. If/when you have go installed you can already `go get` packer and `make` in order to compile and test Packer. These instructions target -POSIX-like environments (Mac OS X, Linux, Cygwin, etc.) so you may need to +POSIX-like environments (macOS, Linux, Cygwin, etc.) so you may need to adjust them for Windows or other shells. The instructions below are for go 1.7. or later. @@ -107,6 +107,8 @@ From there, open your fork in your browser to open a new pull-request. will break if you `git clone` your fork instead of using `go get` on the main Packer project. +**Note:** See [Working on forks](#Working on forks) for a better way to use `git push ...`. + ### Pull Request Lifecycle 1. You are welcome to submit your pull request for commentary or review before @@ -124,11 +126,11 @@ Packer project. 1. Once all outstanding comments and checklist items have been addressed, your contribution will be merged! Merged PRs will be included in the next - Packer release. The core team takes care of updating the CHANGELOG as they - merge. + Packer release. The core team takes care of updating the + [CHANGELOG.md](../CHANGELOG.md) as they merge. -1. In rare cases, we might decide that a PR should be closed. We'll make sure to - provide clear reasoning when this happens. +1. In rare cases, we might decide that a PR should be closed without merging. + We'll make sure to provide clear reasoning when this happens. ### Tips for Working on Packer @@ -137,13 +139,25 @@ Packer project. The easiest way to work on a fork is to set it as a remote of the Packer project. After following the steps in "Setting up Go to work on Packer": -1. Navigate to `$GOPATH/src/github.com/hashicorp/packer` -2. Add the remote by running - `git remote add `. For example: - `git remote add mwhooker https://github.com/mwhooker/packer.git`. -3. Checkout a feature branch: `git checkout -b new-feature` -4. Make changes +1. Navigate to the code: + + `cd $GOPATH/src/github.com/hashicorp/packer` + +2. Add the remote by running: + + `git remote add ` + + For example: + + `git remote add mwhooker https://github.com/mwhooker/packer.git` + +3. Checkout a feature branch: + + `git checkout -b new-feature` + +4. Make changes. 5. (Optional) Push your changes to the fork: + `git push -u new-feature` This way you can push to your fork to create a PR, but the code on disk still @@ -180,7 +194,7 @@ Packer has [acceptance tests](https://en.wikipedia.org/wiki/Acceptance_testing) for various builders. These typically require an API key (AWS, GCE), or additional software to be installed on your computer (VirtualBox, VMware). -If you're working on a new builder or builder feature and want verify it is +If you're working on a new builder or builder feature and want to verify it is functioning (and also hasn't broken anything else), we recommend running the acceptance tests. diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 0f53bacaf..3b1eec808 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -2,7 +2,7 @@ _Please read these instructions before submitting_ **DELETE THIS TEMPLATE BEFORE SUBMITTING** -_Only use Github issues to report bugs or feature requests, see +_Only use GitHub issues to report bugs or feature requests, see https://www.packer.io/community.html_ For example, _Timeouts waiting for SSH/WinRM_ are generally not bugs within packer and are better addressed by the mailing list. Ask on the mailing list if you are unsure. diff --git a/README.md b/README.md index a3ec402a9..6b554993c 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ Packer will build an AMI according to the "quick-start" template. The AMI will be available in your AWS account. To delete the AMI, you must manually delete it using the [AWS console](https://console.aws.amazon.com/). Packer builds your images, it does not manage their lifecycle. Where they go, how -they're run, etc. is up to you. +they're run, etc., is up to you. ## Documentation diff --git a/builder/azure/TODO.md b/builder/azure/TODO.md index da9ce77a7..f35a4607b 100644 --- a/builder/azure/TODO.md +++ b/builder/azure/TODO.md @@ -4,7 +4,7 @@ Here's a list of things we like to get done in no particular order: - [ ] Blob/image rename post-processor - [ ] SSH to private ip through subnet - [ ] chroot builder -- [ ] support cross-storage account image source (ie. pre-build blob copy) +- [ ] support cross-storage account image source (i.e. pre-build blob copy) - [ ] look up object id when using device code (graph api /me ?) - [ ] device flow support for Windows - [x] look up tenant id in all cases (see device flow code) diff --git a/test/README.md b/test/README.md index e29fe9b24..a8a25243f 100644 --- a/test/README.md +++ b/test/README.md @@ -17,7 +17,7 @@ to running the tests. Additionally, many tests will leave left-over artifacts ### Required Software Before running the tests, you'll need the following installed. If you're -running on Mac OS X, most of these are available with `brew`: +running on macOS, most of these are available with `brew`: * [Bats](https://github.com/sstephenson/bats) diff --git a/website/source/docs/builders/alicloud-ecs.html.md b/website/source/docs/builders/alicloud-ecs.html.md index 7fd2bbd07..6ab254984 100644 --- a/website/source/docs/builders/alicloud-ecs.html.md +++ b/website/source/docs/builders/alicloud-ecs.html.md @@ -18,7 +18,7 @@ customized images based on an existing base images. The following configuration options are available for building Alicloud images. In addition to the options listed here, -a [communicator](/docs/templates/communicator.html) can be configured for this +a [communicator](../templates/communicator.html) can be configured for this builder. ### Required: @@ -77,9 +77,9 @@ builder. to the image. - `disk_category` (string) - Category of the data disk. Optional values are: - - cloud - general cloud disk - - cloud\_efficiency - efficiency cloud disk - - cloud\_ssd - cloud SSD + - `cloud` - general cloud disk + - `cloud_efficiency` - efficiency cloud disk + - `cloud_ssd` - cloud SSD Default value: cloud. @@ -98,9 +98,9 @@ builder. will appear on the console. It cannot begin with `http://` or `https://`. - `disk_size` (number) - Size of the system disk, in GB, values range: - - cloud - 5 ~ 2000 - - cloud\_efficiency - 20 ~ 2048 - - cloud\_ssd - 20 ~ 2048 + - `cloud` - 5 ~ 2000 + - `cloud_efficiency` - 20 ~ 2048 + - `cloud_ssd` - 20 ~ 2048 The value should be equal to or greater than the size of the specific SnapshotId. @@ -135,19 +135,19 @@ builder. - `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` (string) - Maximum outgoing bandwidth to the public - network, measured in Mbps (Mega bit per second). + 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. - `io_optimized` (boolean) - Whether an ECS instance is I/O optimized or not. The default value is `false`. @@ -165,7 +165,7 @@ builder. `_` or `-`. It cannot begin with `http://` or `https://`. - `security_token` (string) - STS access token, can be set through template or by exporting - as environment variable such "export SecurityToken=value". + as environment variable such as `export SecurityToken=value`. - `skip_region_validation` (boolean) - The region validation can be skipped if this value is true, the default value is false. @@ -175,7 +175,7 @@ builder. where `` is a 36 character unique identifier. - `TLSHandshakeTimeout` (int) - When happen "net/http: TLS handshake timeout" problem, set this environment variable - to a bigger such as "export TLSHandshakeTimeout=30", it will set the TLS handshake timeout value to 30s. + to a bigger such as `export TLSHandshakeTimeout=30`, it will set the TLS handshake timeout value to 30s. - `user_data` (string) - The UserData of an instance must be encoded in `Base64` format, and the maximum size of the raw data is `16 KB`. diff --git a/website/source/docs/builders/amazon-chroot.html.md b/website/source/docs/builders/amazon-chroot.html.md index 9bd5be7b1..572a44817 100644 --- a/website/source/docs/builders/amazon-chroot.html.md +++ b/website/source/docs/builders/amazon-chroot.html.md @@ -29,7 +29,7 @@ Packer, we recommend starting with the [amazon-ebs builder](/docs/builders/amazon-ebs.html), which is much easier to use. The builder does *not* manage AMIs. Once it creates an AMI and stores it in your -account, it is up to you to use, delete, etc. the AMI. +account, it is up to you to use, delete, etc., the AMI. ## How Does it Work? @@ -58,20 +58,20 @@ each category, the available configuration keys are alphabetized. ### Required: - `access_key` (string) - The access key used to communicate with AWS. [Learn - how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) + how to set this](/docs/builders/amazon.html#specifying-amazon-credentials) - `ami_name` (string) - The name of the resulting AMI that will appear when managing AMIs in the AWS console or via APIs. This must be unique. To help make this unique, use a function like `timestamp` (see [template - engine](/docs/templates/engine.html) for more info) + engine](/docs/templates/engine.html) for more info). - `secret_key` (string) - The secret key used to communicate with AWS. [Learn - how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) + how to set this](/docs/builders/amazon.html#specifying-amazon-credentials) - `source_ami` (string) - The source AMI whose root volume will be copied and provisioned on the currently running instance. This must be an EBS-backed AMI with a root volume snapshot that you have access to. Note: this is not used - when `from_scratch` is set to true. + when `from_scratch` is set to `true`. ### Optional: @@ -97,19 +97,19 @@ each category, the available configuration keys are alphabetized. - `ami_virtualization_type` (string) - The type of virtualization for the AMI you are building. This option is required to register HVM images. Can be - "paravirtual" (default) or "hvm". + `paravirtual` (default) or `hvm`. - `chroot_mounts` (array of array of strings) - This is a list of devices to mount into the chroot environment. This configuration parameter - requires some additional documentation which is in the "Chroot Mounts" - section below. Please read that section for more information on how to + requires some additional documentation which is in the [Chroot Mounts](#Chroot Mounts) + section. Please read that section for more information on how to use this. - `command_wrapper` (string) - How to run shell commands. This defaults to `{{.Command}}`. This may be useful to set if you want to set environmental variables or perhaps run it with `sudo` or so on. This is a configuration template where the `.Command` variable is replaced with the command to - be run. Defaults to "{{.Command}}". + be run. Defaults to `{{.Command}}`. - `copy_files` (array of strings) - Paths to files on the running EC2 instance that will be copied into the chroot environment prior to provisioning. Defaults @@ -131,7 +131,7 @@ each category, the available configuration keys are alphabetized. forces Packer to find an open device automatically. - `ena_support` (boolean) - Enable enhanced networking (ENA but not SriovNetSupport) - on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM policy. + on HVM-compatible AMIs. If `true`, 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). Default `false`. @@ -151,7 +151,7 @@ each category, the available configuration keys are alphabetized. will be encrypted by the default EBS KMS key. - `from_scratch` (boolean) - Build a new volume instead of starting from an - existing AMI root volume snapshot. Default `false`. If true, `source_ami` is + existing AMI root volume snapshot. Default `false`. If `true`, `source_ami` is no longer used and the following options become required: `ami_virtualization_type`, `pre_mount_commands` and `root_volume_size`. The below options are also required in this mode only: @@ -172,28 +172,28 @@ each category, the available configuration keys are alphabetized. example, `/dev/sdh` or `xvdh`). Required for every device in the block device mapping. - - `encrypted` (boolean) - Indicates whether to encrypt the volume or not + - `encrypted` (boolean) - Indicates whether or not to encrypt the volume. - `kms_key_id` (string) - The ARN for the KMS encryption key. When specifying `kms_key_id`, `encrypted` needs to be set to `true`. - `iops` (number) - The number of I/O operations per second (IOPS) that the volume supports. See the documentation on - [IOPs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) - for more information + [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) + for more information. - `no_device` (boolean) - Suppresses the specified device included in the - block device mapping of the AMI + block device mapping of the AMI. - - `snapshot_id` (string) - The ID of the snapshot + - `snapshot_id` (string) - The ID of the snapshot. - `virtual_name` (string) - The virtual device name. See the documentation on [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) - for more information + for more information. - `volume_size` (number) - The size of the volume, in GiB. Required if not - specifying a `snapshot_id` + specifying a `snapshot_id`. - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD) volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic @@ -229,7 +229,7 @@ each category, the available configuration keys are alphabetized. to the `mount` command ran by Packer. Because this command is ran in a shell, user discretion is advised. See [this manual page for the mount command](http://linuxcommand.org/man_pages/mount8.html) for valid file - system specific options + system specific options. - `nvme_device_path` (string) - When we call the mount command (by default `mount -o device dir`), the string provided in `nvme_mount_path` will @@ -262,7 +262,7 @@ each category, the available configuration keys are alphabetized. - `root_volume_type` (string) - The type of EBS volume for the chroot environment and resulting AMI. The default value is the type of the `source_ami`, unless - `from_scratch` is true, in which case the default value is `gp2`. You can only + `from_scratch` is `true`, in which case the default value is `gp2`. You can only specify `io1` if building based on top of a `source_ami` which is also `io1`. - `root_volume_tags` (object of key/value strings) - Tags to apply to the volumes @@ -270,7 +270,7 @@ each category, the available configuration keys are alphabetized. [template engine](/docs/templates/engine.html), see [Build template data](#build-template-data) for more information. -- `skip_region_validation` (boolean) - Set to true if you want to skip +- `skip_region_validation` (boolean) - Set to `true` if you want to skip validation of the `ami_regions` configuration option. Default `false`. - `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot. @@ -316,7 +316,7 @@ each category, the available configuration keys are alphabetized. for example, "amazon", "aws-marketplace", or "microsoft". This option is required for security reasons. - - `most_recent` (boolean) - Selects the newest created image when true. + - `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 @@ -326,7 +326,7 @@ each category, the available configuration keys are alphabetized. but will cause Packer to fail if the `source_ami` does not exist. - `sriov_support` (boolean) - Enable enhanced networking (SriovNetSupport but not ENA) - on HVM-compatible AMIs. If true, add `ec2:ModifyInstanceAttribute` to your AWS IAM + on HVM-compatible AMIs. If `true`, 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). Default `false`. @@ -470,7 +470,7 @@ A working example for mounting an NVMe device is below: ``` Note that in the `nvme_device_path` you must end with the `p`; if you try to -define the partition in this path (e.g. "nvme_device_path": `/dev/nvme1n1p1`) +define the partition in this path (e.g. `nvme_device_path`: `/dev/nvme1n1p1`) and haven't also set the `"mount_partition": 0`, a `1` will be appended to the `nvme_device_path` and Packer will fail. diff --git a/website/source/docs/builders/amazon-ebs.html.md b/website/source/docs/builders/amazon-ebs.html.md index 13d95865d..bdc9ea2cb 100644 --- a/website/source/docs/builders/amazon-ebs.html.md +++ b/website/source/docs/builders/amazon-ebs.html.md @@ -40,18 +40,18 @@ segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. In addition to the options listed here, a -[communicator](/docs/templates/communicator.html) can be configured for this +[communicator](../templates/communicator.html) can be configured for this builder. ### Required: - `access_key` (string) - The access key used to communicate with AWS. [Learn - how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) + how to set this](amazon.html#specifying-amazon-credentials) - `ami_name` (string) - The name of the resulting AMI that will appear when managing AMIs in the AWS console or via APIs. This must be unique. To help make this unique, use a function like `timestamp` (see [template - engine](/docs/templates/engine.html) for more info) + engine](../templates/engine.html) for more info). - `instance_type` (string) - The EC2 instance type to use while building the AMI, such as `t2.small`. @@ -60,7 +60,7 @@ builder. launch the EC2 instance to create the AMI. - `secret_key` (string) - The secret key used to communicate with AWS. [Learn - how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) + how to set this](amazon.html#specifying-amazon-credentials) - `source_ami` (string) - The initial AMI used as a base for the newly created machine. `source_ami_filter` may be used instead to populate this @@ -112,7 +112,7 @@ builder. - `ami_description` (string) - The description to set for the resulting AMI(s). By default this description is empty. This is a - [template engine](/docs/templates/engine.html), + [template engine](../templates/engine.html), see [Build template data](#build-template-data) for more information. - `ami_groups` (array of strings) - A list of groups that have access to @@ -160,7 +160,7 @@ builder. - `disable_stop_instance` (boolean) - Packer normally stops the build instance after all provisioners have 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* + which will stop the instance for you. If this is set to `true`, Packer *will not* stop the instance but will assume that you will send the stop signal yourself through your final provisioner. You can do this with a [windows-shell provisioner](https://www.packer.io/docs/provisioners/windows-shell.html). @@ -195,16 +195,16 @@ builder. instance to consume up to its available CPU Credits. See the AWS documentation for [T2 Unlimited] (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-unlimited.html) - and the 'T2 Unlimited Pricing' section of the [Amazon EC2 On-Demand + and the **T2 Unlimited Pricing** section of the [Amazon EC2 On-Demand Pricing](https://aws.amazon.com/ec2/pricing/on-demand/) document for more information. By default this option is disabled and Packer will set 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. + 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. + Instances, e.g., when the `spot_price` option has been configured. Attempting to do so will cause an error. !> **Warning!** Additional costs may be incurred by enabling T2 @@ -259,13 +259,13 @@ builder. - `run_tags` (object of key/value strings) - Tags to apply to the instance that is *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.html), + [template engine](../templates/engine.html), see [Build template data](#build-template-data) for more information. - `run_volume_tags` (object of key/value strings) - 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.html), + [template engine](../templates/engine.html), see [Build template data](#build-template-data) for more information. - `security_group_id` (string) - The ID (*not* the name) of the security group @@ -297,11 +297,11 @@ builder. 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 precendense over this. + `security_group_ids` take precedence over this. - `temporary_security_group_source_cidr` (string) - An IPv4 CIDR block to be authorized access to the instance, when packer is creating a temporary security group. - The default is `0.0.0.0/0` (ie, allow any IPv4 source). This is only used + 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. - `shutdown_behavior` (string) - Automatically terminate instances on shutdown @@ -321,7 +321,7 @@ builder. - `snapshot_tags` (object of key/value strings) - Tags to apply to snapshot. They will override AMI tags if already applied to snapshot. This is a - [template engine](/docs/templates/engine.html), + [template engine](../templates/engine.html), see [Build template data](#build-template-data) for more information. - `source_ami_filter` (object) - Filters used to populate the `source_ami` field. @@ -353,7 +353,7 @@ builder. - `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". + for example, `amazon`, `aws-marketplace`, or `microsoft`. This option is required for security reasons. - `most_recent` (boolean) - Selects the newest created image when true. @@ -392,8 +392,8 @@ builder. used for SSH with the machine. The key must match a key pair name loaded up into Amazon EC2. By default, this is blank, and Packer will generate a temporary keypair unless - [`ssh_password`](/docs/templates/communicator.html#ssh_password) is used. - [`ssh_private_key_file`](/docs/templates/communicator.html#ssh_private_key_file) + [`ssh_password`](../templates/communicator.html#ssh_password) is used. + [`ssh_private_key_file`](../templates/communicator.html#ssh_private_key_file) or `ssh_agent_auth` must be specified when `ssh_keypair_name` is utilized. - `ssh_agent_auth` (boolean) - If true, the local SSH agent will be used to @@ -408,7 +408,7 @@ builder. [`ssh_interface`](#ssh_interface). A fixer exists to migrate. - `ssh_interface` (string) - One of `public_ip`, `private_ip`, - `public_dns` or `private_dns`. If set, either the public IP address, + `public_dns`, or `private_dns`. If set, either the public IP address, private IP address, public DNS name or private DNS name will 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 @@ -457,7 +457,7 @@ builder. - `tags` (object of key/value strings) - Tags applied to the AMI and relevant snapshots. This is a - [template engine](/docs/templates/engine.html), + [template engine](../templates/engine.html), see [Build template data](#build-template-data) for more information. - `temporary_key_pair_name` (string) - The name of the temporary key pair diff --git a/website/source/docs/builders/amazon-ebssurrogate.html.md b/website/source/docs/builders/amazon-ebssurrogate.html.md index c3ec73da8..6956b02a7 100644 --- a/website/source/docs/builders/amazon-ebssurrogate.html.md +++ b/website/source/docs/builders/amazon-ebssurrogate.html.md @@ -19,13 +19,13 @@ then snapshotting and creating the AMI from that volume. This builder can therefore be used to bootstrap scratch-build images - for example FreeBSD or Ubuntu using ZFS as the root file system. -This is all done in your own AWS account. The builder will create temporary key -pairs, security group rules, etc. that provide it temporary access to the +This is all done in your own AWS account. This builder will create temporary key +pairs, security group rules, etc., that provide it temporary access to the instance while the image is being created. ## Configuration Reference -There are many configuration options available for the builder. They are +There are many configuration options available for this builder. They are segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. @@ -36,7 +36,7 @@ builder. ### Required: - `access_key` (string) - The access key used to communicate with AWS. [Learn - how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) + how to set this](/docs/builders/amazon.html#specifying-amazon-credentials) - `instance_type` (string) - The EC2 instance type to use while building the AMI, such as `m1.small`. @@ -45,7 +45,7 @@ builder. launch the EC2 instance to create the AMI. - `secret_key` (string) - The secret key used to communicate with AWS. [Learn - how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials) + how to set this](/docs/builders/amazon.html#specifying-amazon-credentials) - `source_ami` (string) - The initial AMI used as a base for the newly created machine. `source_ami_filter` may be used instead to populate this @@ -79,29 +79,29 @@ builder. example, `/dev/sdh` or `xvdh`). Required for every device in the block device mapping. - - `encrypted` (boolean) - Indicates whether to encrypt the volume or not + - `encrypted` (boolean) - Indicates whether or not to encrypt the volume. - `iops` (number) - The number of I/O operations per second (IOPS) that the volume supports. See the documentation on [IOPs](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html) - for more information + for more information. - `no_device` (boolean) - Suppresses the specified device included in the - block device mapping of the AMI + block device mapping of the AMI. - - `snapshot_id` (string) - The ID of the snapshot + - `snapshot_id` (string) - The ID of the snapshot. - `virtual_name` (string) - The virtual device name. See the documentation on [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html) - for more information + for more information. - `volume_size` (number) - The size of the volume, in GiB. Required if not - specifying a `snapshot_id` + specifying a `snapshot_id`. - - `volume_type` (string) - The volume type. `gp2` for General Purpose (SSD) + - `volume_type` (string) - The volume type. (`gp2` for General Purpose (SSD) volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic - volumes + volumes) - `ami_description` (string) - The description to set for the resulting AMI(s). By default this description is empty. This is a @@ -188,16 +188,16 @@ builder. instance to consume up to its available CPU Credits. See the AWS documentation for [T2 Unlimited] (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-unlimited.html) - and the 'T2 Unlimited Pricing' section of the [Amazon EC2 On-Demand + and the **T2 Unlimited Pricing** section of the [Amazon EC2 On-Demand Pricing](https://aws.amazon.com/ec2/pricing/on-demand/) document for more information. By default this option is disabled and Packer will set 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. + 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. + Instances, e.g., when the `spot_price` option has been configured. Attempting to do so will cause an error. !> **Warning!** Additional costs may be incurred by enabling T2 @@ -290,11 +290,11 @@ builder. 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 precendense over this. + `security_group_ids` take precedence over this. - `temporary_security_group_source_cidr` (string) - An IPv4 CIDR block to be authorized access to the instance, when packer is creating a temporary security group. - The default is `0.0.0.0/0` (ie, allow any IPv4 source). This is only used + 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. - `shutdown_behavior` (string) - Automatically terminate instances on shutdown @@ -344,9 +344,9 @@ builder. 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 + 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". + for example, `amazon`, `aws-marketplace`, or `microsoft`. This option is required for security reasons. @@ -543,7 +543,7 @@ or [for Windows](http://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/finding-a ## Accessing the Instance to Debug -If you need to access the instance to debug for some reason, run the builder +If you need to access the instance to debug for some reason, run this builder with the `-debug` flag. In debug mode, the Amazon builder will save the private key in the current directory and will output the DNS or IP information as well. You can use this information to access the instance as it is running. diff --git a/website/source/docs/builders/amazon-ebsvolume.html.md b/website/source/docs/builders/amazon-ebsvolume.html.md index 4042f1ab6..6c26167a6 100644 --- a/website/source/docs/builders/amazon-ebsvolume.html.md +++ b/website/source/docs/builders/amazon-ebsvolume.html.md @@ -223,11 +223,11 @@ builder. 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 precendense over this. + `security_group_ids` take precedence over this. - `temporary_security_group_source_cidr` (string) - An IPv4 CIDR block to be authorized access to the instance, when packer is creating a temporary security group. - The default is `0.0.0.0/0` (ie, allow any IPv4 source). This is only used + 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. - `shutdown_behavior` (string) - Automatically terminate instances on shutdown diff --git a/website/source/docs/builders/amazon-instance.html.md b/website/source/docs/builders/amazon-instance.html.md index 136af3cb9..8554f93fd 100644 --- a/website/source/docs/builders/amazon-instance.html.md +++ b/website/source/docs/builders/amazon-instance.html.md @@ -22,11 +22,11 @@ documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMI This builder builds an AMI by launching an EC2 instance from an existing instance-storage backed AMI, provisioning that running machine, and then bundling and creating a new AMI from that machine. This is all done in your own -AWS account. The builder will create temporary key pairs, security group rules, +AWS account. This builder will create temporary key pairs, security group rules, etc. that provide it temporary access to the instance while the image is being created. This simplifies configuration quite a bit. -The builder does *not* manage AMIs. Once it creates an AMI and stores it in +This builder does *not* manage AMIs. Once it creates an AMI and stores it in your account, it is up to you to use, delete, etc. the AMI. -> **Note:** Temporary resources are, by default, all created with the prefix @@ -42,7 +42,7 @@ builder finishes running. ## Configuration Reference -There are many configuration options available for the builder. They are +There are many configuration options available for this builder. They are segmented below into two categories: required and optional parameters. Within each category, the available configuration keys are alphabetized. @@ -299,11 +299,11 @@ builder. 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 precendense over this. + `security_group_ids` take precedence over this. - `temporary_security_group_source_cidr` (string) - An IPv4 CIDR block to be authorized access to the instance, when packer is creating a temporary security group. - The default is `0.0.0.0/0` (ie, allow any IPv4 source). This is only used + 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. - `skip_region_validation` (boolean) - Set to true if you want to skip @@ -536,7 +536,7 @@ for more information on what environmental variables Packer will look for. ## Accessing the Instance to Debug -If you need to access the instance to debug for some reason, run the builder +If you need to access the instance to debug for some reason, run this builder with the `-debug` flag. In debug mode, the Amazon builder will save the private key in the current directory and will output the DNS or IP information as well. You can use this information to access the instance as it is running. diff --git a/website/source/docs/builders/googlecompute.html.md b/website/source/docs/builders/googlecompute.html.md index c6333bbbe..52e152bff 100644 --- a/website/source/docs/builders/googlecompute.html.md +++ b/website/source/docs/builders/googlecompute.html.md @@ -79,13 +79,16 @@ straightforwarded, it is documented here. ### Precedence of Authentication Methods -Packer looks for credentials in the following places, preferring the first location found: +Packer looks for credentials in the following places, preferring the first +location found: 1. An `account_file` option in your packer file. -2. A JSON file (Service Account) whose path is specified by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. +2. A JSON file (Service Account) whose path is specified by the +`GOOGLE_APPLICATION_CREDENTIALS` environment variable. -3. A JSON file in a location known to the `gcloud` command-line tool. (`gcloud` creates it when it's configured) +3. A JSON file in a location known to the `gcloud` command-line tool. +(`gcloud` creates it when it's configured) On Windows, this is: @@ -95,7 +98,9 @@ Packer looks for credentials in the following places, preferring the first locat $HOME/.config/gcloud/application_default_credentials.json -4. On Google Compute Engine and Google App Engine Managed VMs, it fetches credentials from the metadata server. (Needs a correct VM authentication scope configuration, see above) +4. On Google Compute Engine and Google App Engine Managed VMs, it fetches +credentials from the metadata server. (Needs a correct VM authentication scope +configuration, see above.) ## Examples @@ -328,9 +333,9 @@ builder. Startup scripts can be a powerful tool for configuring the instance from which the image is made. The builder will wait for a startup script to terminate. A startup script can be provided via the -`startup_script_file` or 'startup-script' instance creation `metadata` field. Therefore, the build +`startup_script_file` or `startup-script` instance creation `metadata` field. Therefore, the build time will vary depending on the duration of the startup script. If `startup_script_file` is set, -the 'startup-script' `metadata` field will be overwritten. In other words,`startup_script_file` +the `startup-script` `metadata` field will be overwritten. In other words, `startup_script_file` takes precedence. The builder does not check for a pass/fail/error signal from the startup script, at this time. Until @@ -339,14 +344,14 @@ when a startup script fails. ### Windows -A Windows startup script can only be provided via the 'windows-startup-script-cmd' instance -creation `metadata` field. The builder will *not* wait for a Windows startup scripts to +A Windows startup script can only be provided via the `windows-startup-script-cmd` instance +creation `metadata` field. The builder will *not* wait for a Windows startup script to terminate. You have to ensure that it finishes before the instance shuts down. ### Logging Startup script logs can be copied to a Google Cloud Storage (GCS) location specified via the -'startup-script-log-dest' instance creation `metadata` field. The GCS location must be writeable by +`startup-script-log-dest` instance creation `metadata` field. The GCS location must be writeable by the credentials provided in the builder config's `account_file`. ## Gotchas diff --git a/website/source/docs/builders/lxd.html.md b/website/source/docs/builders/lxd.html.md index 94423c063..4e58cb4d0 100644 --- a/website/source/docs/builders/lxd.html.md +++ b/website/source/docs/builders/lxd.html.md @@ -46,7 +46,7 @@ Below is a fully functioning example. - `image` (string) - The source image to use when creating the build container. This can be a (local or remote) image (name or fingerprint). E.G. - `my-base-image,` `ubuntu-daily:x,` `08fababf6f27`, ... + `my-base-image`, `ubuntu-daily:x`, `08fababf6f27`, ... ~> Note: The builder may appear to pause if required to download a remote image, as they are usually 100-200MB. `/var/log/lxd/lxd.log` will diff --git a/website/source/docs/builders/scaleway.html.md b/website/source/docs/builders/scaleway.html.md index 4292e0826..8fe5e09f9 100644 --- a/website/source/docs/builders/scaleway.html.md +++ b/website/source/docs/builders/scaleway.html.md @@ -59,9 +59,9 @@ builder. available. - `commercial_type` (string) - The name of the server commercial type: - `ARM64-128GB`,`ARM64-16GB`,`ARM64-2GB`,`ARM64-32GB`,`ARM64-4GB`, `ARM64-64GB`, - `ARM64-8GB`,`C1`,`C2L`,`C2M`,`C2S`,`START1-L`,`START1-M`,`START1-S`,`START1-XS`, - `X64-120GB`,`X64-15GB`,`X64-30GB`,`X64-60GB` + `ARM64-128GB`, `ARM64-16GB`, `ARM64-2GB`, `ARM64-32GB`, `ARM64-4GB`, `ARM64-64GB`, + `ARM64-8GB`, `C1`, `C2L`, `C2M`, `C2S`, `START1-L`, `START1-M`, `START1-S`, + `START1-XS`, `X64-120GB`, `X64-15GB`, `X64-30GB`, `X64-60GB` ### Optional: diff --git a/website/source/docs/post-processors/amazon-import.html.md b/website/source/docs/post-processors/amazon-import.html.md index fc371e7c8..1153cd6ff 100644 --- a/website/source/docs/post-processors/amazon-import.html.md +++ b/website/source/docs/post-processors/amazon-import.html.md @@ -83,7 +83,7 @@ Optional: - `s3_key_name` (string) - The name of the key in `s3_bucket_name` where the OVA file will be copied to for import. If not specified, this will default - to "packer-import-{{timestamp}}.ova". This key (ie, the uploaded OVA) will + to "packer-import-{{timestamp}}.ova". This key (i.e., the uploaded OVA) will be removed after import, unless `skip_clean` is `true`. - `skip_clean` (boolean) - Whether we should skip removing the OVA file uploaded to S3 after the diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index a550cee18..cb84cabb6 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/website/source/intro/getting-started/build-image.html.md @@ -56,9 +56,9 @@ briefly. Create a file `example.json` and fill it with the following contents: "region": "us-east-1", "source_ami_filter": { "filters": { - "virtualization-type": "hvm", - "name": "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*", - "root-device-type": "ebs" + "virtualization-type": "hvm", + "name": "ubuntu/images/*ubuntu-xenial-16.04-amd64-server-*", + "root-device-type": "ebs" }, "owners": ["099720109477"], "most_recent": true @@ -274,7 +274,7 @@ Now save the following text in a file named `firstrun.json`: and to build, run `packer build firstrun.json` Note that if you wanted to use a `source_ami` instead of a `source_ami_filter` -it might look something like this: `"source_ami": "ami-fce3c696",` +it might look something like this: `"source_ami": "ami-fce3c696"`. Your output will look like this: