From 5b7e058d0a8278e4a2c76d98034de76266dcd120 Mon Sep 17 00:00:00 2001 From: Anthony Dong Date: Mon, 2 Apr 2018 19:32:14 +0200 Subject: [PATCH] Add documentation for template variables available for tagging --- .../docs/builders/amazon-chroot.html.md | 27 +++++++------ .../source/docs/builders/amazon-ebs.html.md | 38 +++++++++++-------- .../docs/builders/amazon-ebssurrogate.html.md | 35 +++++++++-------- .../docs/builders/amazon-ebsvolume.html.md | 21 ++++++---- .../docs/builders/amazon-instance.html.md | 24 +++++++----- 5 files changed, 86 insertions(+), 59 deletions(-) diff --git a/website/source/docs/builders/amazon-chroot.html.md b/website/source/docs/builders/amazon-chroot.html.md index c9612d3b8..3738d4e7d 100644 --- a/website/source/docs/builders/amazon-chroot.html.md +++ b/website/source/docs/builders/amazon-chroot.html.md @@ -77,10 +77,8 @@ each category, the available configuration keys are alphabetized. - `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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with name of the region where this - is built. + [template engine](/docs/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 launch the resulting AMI(s). By default no groups have permission to launch @@ -251,10 +249,8 @@ each category, the available configuration keys are alphabetized. - `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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with name of the region where this - is built. + [template engine](/docs/templates/engine.html), + see [Build template data](#build-template-data) for more information. - `snapshot_groups` (array of strings) - A list of groups that have access to create volumes from the snapshot(s). By default no groups have permission to create @@ -307,10 +303,8 @@ each category, the available configuration keys are alphabetized. Default `false`. - `tags` (object of key/value strings) - Tags applied to the AMI. This is a - [template engine](/docs/templates/engine.html) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with name of the region where this - is built. + [template engine](/docs/templates/engine.html), + see [Build template data](#build-template-data) for more information. ## Basic Example @@ -432,3 +426,12 @@ provisioning commands to install the os and bootloader. ] } ``` + +## Build template data + +The available variables are: + +- `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI. +- `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI. +- `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI. +- `SourceAMITags` - The source AMI Tags, as a `map[string]string` object. diff --git a/website/source/docs/builders/amazon-ebs.html.md b/website/source/docs/builders/amazon-ebs.html.md index 400eb7ecb..fce12b678 100644 --- a/website/source/docs/builders/amazon-ebs.html.md +++ b/website/source/docs/builders/amazon-ebs.html.md @@ -114,9 +114,8 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 launch the resulting AMI(s). By default no groups have permission to launch @@ -221,16 +220,14 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 to assign to the instance. By default this is not set and Packer will @@ -264,9 +261,8 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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. Example: @@ -361,9 +357,8 @@ builder. - `tags` (object of key/value strings) - Tags applied to the AMI and relevant snapshots. This is a - [template engine](/docs/templates/engine.html) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 to generate. By default, Packer generates a name that looks like @@ -462,6 +457,15 @@ configuration of `launch_block_device_mappings` will expand the root volume } ``` +## Build template data + +The available variables are: + +- `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI. +- `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI. +- `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI. +- `SourceAMITags` - The source AMI Tags, as a `map[string]string` object. + ## Tag Example Here is an example using the optional AMI tags. This will add the tags @@ -481,7 +485,9 @@ images exist when this template is run: "ami_name": "packer-quick-start {{timestamp}}", "tags": { "OS_Version": "Ubuntu", - "Release": "Latest" + "Release": "Latest", + "Base_AMI_Name": "{{ .SourceAMIName }}", + "Extra": "{{ .SourceAMITags.TagName }}" } } ``` diff --git a/website/source/docs/builders/amazon-ebssurrogate.html.md b/website/source/docs/builders/amazon-ebssurrogate.html.md index 1d3724533..98781a94d 100644 --- a/website/source/docs/builders/amazon-ebssurrogate.html.md +++ b/website/source/docs/builders/amazon-ebssurrogate.html.md @@ -107,9 +107,8 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 launch the resulting AMI(s). By default no groups have permission to launch @@ -214,16 +213,14 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 to assign to the instance. By default this is not set and Packer will @@ -257,9 +254,8 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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. Example: @@ -354,9 +350,8 @@ builder. - `tags` (object of key/value strings) - Tags applied to the AMI and relevant snapshots. This is a - [template engine](/docs/templates/engine.html) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/templates/engine.html), + see [Build template data](#build-template-data) for more information. - `temporary_key_pair_name` (string) - The name of the temporary keypair to generate. By default, Packer generates a name with a UUID. @@ -426,6 +421,16 @@ 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. +## Build template data + +The available variables are: + +- `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI. +- `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI. +- `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI. +- `SourceAMITags` - The source AMI Tags, as a `map[string]string` object. + + -> **Note:** Packer uses pre-built AMIs as the source for building images. These source AMIs may include volumes that are not flagged to be destroyed on termination of the instance building the new image. In addition to those volumes diff --git a/website/source/docs/builders/amazon-ebsvolume.html.md b/website/source/docs/builders/amazon-ebsvolume.html.md index 5a3ee9830..3c277920f 100644 --- a/website/source/docs/builders/amazon-ebsvolume.html.md +++ b/website/source/docs/builders/amazon-ebsvolume.html.md @@ -86,10 +86,9 @@ builder. volumes, `io1` for Provisioned IOPS (SSD) volumes, and `standard` for Magnetic volumes - `tags` (map) - Tags to apply to the volume. These are retained after the - builder completes. This is a \[template engine\] - (/docs/templates/engine.html) where the `SourceAMI` - variable is replaced with the source AMI ID and `BuildRegion` variable - is replaced with the value of `region`. + builder completes. This is a + [template engine](/docs/templates/engine.html), + see [Build template data](#build-template-data) for more information. - `associate_public_ip_address` (boolean) - If using a non-default VPC, public IP addresses are not provided by default. If this is toggled, your new @@ -126,9 +125,8 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 to assign to the instance. By default this is not set and Packer will @@ -328,6 +326,15 @@ 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. +## Build template data + +The available variables are: + +- `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI. +- `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI. +- `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI. +- `SourceAMITags` - The source AMI Tags, as a `map[string]string` object. + -> **Note:** Packer uses pre-built AMIs as the source for building images. These source AMIs may include volumes that are not flagged to be destroyed on termination of the instance building the new image. In addition to those volumes diff --git a/website/source/docs/builders/amazon-instance.html.md b/website/source/docs/builders/amazon-instance.html.md index 58ac7088b..e6e40535c 100644 --- a/website/source/docs/builders/amazon-instance.html.md +++ b/website/source/docs/builders/amazon-instance.html.md @@ -136,9 +136,8 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 launch the resulting AMI(s). By default no groups have permission to launch @@ -236,9 +235,8 @@ 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) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 to assign to the instance. By default this is not set and Packer will @@ -361,9 +359,8 @@ builder. required if you are using an non-default VPC. - `tags` (object of key/value strings) - Tags applied to the AMI. This is a - [template engine](/docs/templates/engine.html) - where the `SourceAMI` variable is replaced with the source AMI ID and - `BuildRegion` variable is replaced with the value of `region`. + [template engine](/docs/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 to generate. By default, Packer generates a name that looks like @@ -425,6 +422,15 @@ 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. +## Build template data + +The available variables are: + +- `BuildRegion` - The region (for example `eu-central-1`) where Packer is building the AMI. +- `SourceAMI` - The source AMI ID (for example `ami-a2412fcd`) used to build the AMI. +- `SourceAMIName` - The source AMI Name (for example `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to build the AMI. +- `SourceAMITags` - The source AMI Tags, as a `map[string]string` object. + ## Custom Bundle Commands A lot of the process required for creating an instance-store backed AMI involves