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

Merge pull request #9607 from hashicorp/amazon_hcl_docs 

Amazon hcl docs
This commit is contained in:
Megan Marsh 2020-07-20 18:11:51 -07:00 committed by GitHub
parent ea4aa67f78 3897865f3f
commit 6077a9174a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 446 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

215
website/pages/docs/builders/amazon/chroot.mdx
View File

@ -127,24 +127,35 @@ Here is a basic example. It is completely valid except for the access keys:
<Tab heading="HCL2"> <Tab heading="HCL2">
```hcl ```hcl
// To make Packer read these variables from the environment into the var object,
// set the environment variables to have the same name as the declared
// variables, with the prefix PKR_VAR_.
// You could also hardcode them into the file, but we recommend against that.
// export PKR_VAR_aws_access_key=$YOURKEY
variable "aws_access_key" { variable "aws_access_key" {
type = string type = string
// default = "hardcoded_key" // Not recommended !
} }
// export PKR_VAR_aws_secret_key=$YOURSECRETKEY
variable "aws_secret_key" { variable "aws_secret_key" {
type = string type = string
// default = "hardcoded_secret_key" // Not recommended !
} }
source "amazon-chroot" "basic-example" { source "amazon-chroot" "basic-example" {
access_key = var.aws_access_key access_key = var.aws_access_key
secret_key = var.aws_secret_key secret_key = var.aws_secret_key
ami_name = "example-chroot"
source_ami = "ami-e81d5881" source_ami = "ami-e81d5881"
} }
build { build {
source "sources.amazon-chroot.basic-example" { sources = [
ami_name = "packer-amazon-chroot {{timestamp}}" "source.amazon-chroot.basic-example"
} ]
} }
``` ```
@ -163,20 +174,42 @@ chroot by Packer:
- `/dev/pts` (devpts) - `/dev/pts` (devpts)
- `/proc/sys/fs/binfmt_misc` (binfmt_misc) - `/proc/sys/fs/binfmt_misc` (binfmt_misc)
These default mounts are usually good enough for anyone and are sane defaults. These default mounts are usually good enough for anyone and are reasonable
However, if you want to change or add the mount points, you may using the defaults. However, if you want to change or add the mount points, you may using
`chroot_mounts` configuration. Here is an example configuration which only the `chroot_mounts` configuration. Here is an example configuration which only
mounts `/proc` and `/dev`: mounts `/proc` and `/dev`:
<Tabs>
<Tab heading="JSON">
```json ```json
{ ...
"builders": [{
"type": "amazon-chroot"
...
"chroot_mounts": [ "chroot_mounts": [
["proc", "proc", "/proc"], ["proc", "proc", "/proc"],
["bind", "/dev", "/dev"] ["bind", "/dev", "/dev"]
] ]
}]
```
</Tab>
<Tab heading="HCL2">
```hcl
source "amazon-chroot" "basic-example" {
// ... other builder options
chroot_mounts = [
["proc", "proc", "/proc"],
["bind", "/dev", "/dev"]
]
} }
``` ```
</Tab>
</Tabs>
`chroot_mounts` is a list of a 3-tuples of strings. The three components of the `chroot_mounts` is a list of a 3-tuples of strings. The three components of the
3-tuple, in order, are: 3-tuple, in order, are:
@ -210,23 +243,56 @@ For debian based distributions you can setup a
file which will prevent packages installed by your provisioners from starting file which will prevent packages installed by your provisioners from starting
services: services:
```json
({
"type": "shell",
"inline": [
"echo '#!/bin/sh' > /usr/sbin/policy-rc.d",
"echo 'exit 101' >> /usr/sbin/policy-rc.d",
"chmod a+x /usr/sbin/policy-rc.d"
]
},
// ...
{ <Tabs>
"type": "shell", <Tab heading="JSON">
"inline": ["rm -f /usr/sbin/policy-rc.d"]
}) ```json
"provisioners": [
{
"type": "shell",
"inline": [
"echo '#!/bin/sh' > /usr/sbin/policy-rc.d",
"echo 'exit 101' >> /usr/sbin/policy-rc.d",
"chmod a+x /usr/sbin/policy-rc.d"
]
},
{
"type": "shell",
"inline": ["rm -f /usr/sbin/policy-rc.d"]
}
]
``` ```
</Tab>
<Tab heading="HCL2">
```hcl
// ...
build {
sources = [
"source.amazon-chroot.basic-example"
]
// Set policy
provisioner "shell" {
inline = [
"echo '#!/bin/sh' > /usr/sbin/policy-rc.d",
"echo 'exit 101' >> /usr/sbin/policy-rc.d",
"chmod a+x /usr/sbin/policy-rc.d"
]
}
// Un-set policy
provisioner "shell" {
inline = ["rm -f /usr/sbin/policy-rc.d"]
}
}
```
</Tab>
</Tabs>
### Ansible provisioner ### Ansible provisioner
Running ansible against `amazon-chroot` requires changing the Ansible Running ansible against `amazon-chroot` requires changing the Ansible
@ -242,6 +308,9 @@ involving the `nvme_device_path` option above. Read that for more information.
A working example for mounting an NVMe device is below: A working example for mounting an NVMe device is below:
<Tabs>
<Tab heading="JSON">
```json ```json
{ {
"variables": { "variables": {
@ -276,6 +345,60 @@ A working example for mounting an NVMe device is below:
} }
``` ```
</Tab>
<Tab heading="HCL2">
```hcl
// export PKR_VAR_aws_access_key=$YOURKEY
variable "aws_access_key" {
type = string
}
// export PKR_VAR_aws_secret_key=$YOURSECRETKEY
variable "aws_secret_key" {
type = string
}
source "amazon-chroot" "basic-example" {
access_key = var.aws_access_key
secret_key = var.aws_secret_key
region = "us-east-1"
source_ami_filter {
filter {
key = "virtualization-type"
value = "hvm"
}
filter {
key = "name"
value = "amzn-ami-hvm-*"
}
filter {
key = "root-device-type"
value = "ebs"
}
owners = ["137112412989"]
most_recent = true
}
ena_support = true
ami_name = "amazon-chroot-test-{{timestamp}}"
nvme_device_path = "/dev/nvme1n1p"
device_path = "/dev/sdf"
}
build {
sources = [
"source.amazon-chroot.basic-example"
]
provisioner "shell" {
inline = ["echo Test > /tmp/test.txt"]
}
}
```
</Tab>
</Tabs>
Note that in the `nvme_device_path` you must end with the `p`; if you try to 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 and haven't also set the `"mount_partition": 0`, a `1` will be appended to the
@ -289,6 +412,9 @@ The device setup commands partition the device with one partition for use as an
HVM image and format it ext4. This builder block should be followed by HVM image and format it ext4. This builder block should be followed by
provisioning commands to install the os and bootloader. provisioning commands to install the os and bootloader.
<Tabs>
<Tab heading="JSON">
```json ```json
{ {
"type": "amazon-chroot", "type": "amazon-chroot",
@ -311,6 +437,53 @@ provisioning commands to install the os and bootloader.
} }
``` ```
</Tab>
<Tab heading="HCL2">
```hcl
// This example assumes that AWS_SECRET_ACCESS_KEY and AWS_ACCESS_KEY_ID are
// set in your environment, or a ~/.aws/credentials file is configured.
source "amazon-chroot" "basic-example" {
region = "us-east-1"
ami_name = "packer-from-scratch {{timestamp}}"
from_scratch = true
ami_virtualization_type = "hvm"
pre_mount_commands = [
"parted {{.Device}} mklabel msdos mkpart primary 1M 100% set 1 boot on print",
"mkfs.ext4 {{.Device}}1"
]
root_volume_size = 15
root_device_name = "xvda"
ami_block_device_mappings {
device_name = "xvda"
delete_on_termination = true
volume_type = "gp2"
}
}
build {
sources = [
"source.amazon-chroot.basic-example"
]
provisioner "shell" {
inline = [
"echo '#!/bin/sh' > /usr/sbin/policy-rc.d",
"echo 'exit 101' >> /usr/sbin/policy-rc.d",
"chmod a+x /usr/sbin/policy-rc.d"
]
}
provisioner "shell" {
inline = ["rm -f /usr/sbin/policy-rc.d"]
}
}
```
</Tab>
</Tabs>
## Build template data ## Build template data
In configuration directives marked as a template engine above, the following In configuration directives marked as a template engine above, the following

266
website/pages/docs/builders/amazon/ebs.mdx
View File

@ -143,12 +143,22 @@ run:
<Tab heading="HCL2"> <Tab heading="HCL2">
```hcl ```hcl
// To make Packer read these variables from the environment into the var object,
// set the environment variables to have the same name as the declared
// variables, with the prefix PKR_VAR_.
// You could also hardcode them into the file, but we recommend against that.
// export PKR_VAR_aws_access_key=$YOURKEY
variable "aws_access_key" { variable "aws_access_key" {
type = string type = string
// default = "hardcoded_key"
} }
// export PKR_VAR_aws_secret_key=$YOURSECRETKEY
variable "aws_secret_key" { variable "aws_secret_key" {
type = string type = string
// default = "hardcoded_secret_key"
} }
source "amazon-ebs" "basic-example" { source "amazon-ebs" "basic-example" {
@ -158,21 +168,23 @@ source "amazon-ebs" "basic-example" {
source_ami = "ami-fce3c696" source_ami = "ami-fce3c696"
instance_type = "t2.micro" instance_type = "t2.micro"
ssh_username = "ubuntu" ssh_username = "ubuntu"
ami_name = "packer_AWS {{timestamp}}"
} }
build { build {
source "sources.amazon-ebs.basic-example" { sources = [
ami_name = "packer_AWS {{timestamp}}" "source.amazon-ebs.basic-example"
} ]
} }
``` ```
</Tab> </Tab>
</Tabs> </Tabs>
-> **Note:** Packer can also read the access key and secret access key from -> **Note:** Packer can also read the access key and secret access key directly
environmental variables. See the configuration reference in the section above from environmental variables instead of being set as user variables. See the
for more information on what environmental variables Packer will look for. configuration reference in the section above for more information on what
environmental variables Packer will look for.
Further information on locating AMI IDs and their relationship to instance Further information on locating AMI IDs and their relationship to instance
types and regions can be found in the AWS EC2 Documentation [for types and regions can be found in the AWS EC2 Documentation [for
@ -195,37 +207,91 @@ configuration of `launch_block_device_mappings` will expand the root volume
`ami_block_device_mappings` AWS will attach additional volumes `/dev/sdb` and `ami_block_device_mappings` AWS will attach additional volumes `/dev/sdb` and
`/dev/sdc` when we boot a new instance of our AMI. `/dev/sdc` when we boot a new instance of our AMI.
<Tabs>
<Tab heading="JSON">
```json ```json
{ {
"type": "amazon-ebs", "builders": [
"access_key": "YOUR KEY HERE", {
"secret_key": "YOUR SECRET KEY HERE", "type": "amazon-ebs",
"region": "us-east-1", "region": "us-east-1",
"source_ami": "ami-fce3c696", "source_ami": "ami-fce3c696",
"instance_type": "t2.micro", "instance_type": "t2.micro",
"ssh_username": "ubuntu", "ssh_username": "ubuntu",
"ami_name": "packer-quick-start {{timestamp}}", "ami_name": "packer-quick-start {{timestamp}}",
"launch_block_device_mappings": [ "launch_block_device_mappings": [
{ {
"device_name": "/dev/sda1", "device_name": "/dev/sda1",
"volume_size": 40, "volume_size": 40,
"volume_type": "gp2", "volume_type": "gp2",
"delete_on_termination": true "delete_on_termination": true
} }
], ],
"ami_block_device_mappings": [ "ami_block_device_mappings": [
{ {
"device_name": "/dev/sdb", "device_name": "/dev/sdb",
"virtual_name": "ephemeral0" "virtual_name": "ephemeral0"
}, },
{ {
"device_name": "/dev/sdc", "device_name": "/dev/sdc",
"virtual_name": "ephemeral1" "virtual_name": "ephemeral1"
}
]
} }
] ]
} }
``` ```
</Tab>
<Tab heading="HCL2">
```hcl
source "amazon-ebs" "basic-example" {
region = "us-east-1"
source_ami = "ami-fce3c696"
instance_type = "t2.micro"
ssh_username = "ubuntu"
ami_name = "packer_AWS_example_{{timestamp}}"
launch_block_device_mappings {
device_name = "/dev/sda1"
volume_size = 40
volume_type = "gp2"
delete_on_termination = true
}
// Notice that instead of providing a list of mappings, you are just providing
// multiple mappings in a row. This diverges from the JSON template format.
ami_block_device_mappings {
device_name = "/dev/sdb"
virtual_name = "ephemeral0"
}
ami_block_device_mappings {
device_name = "/dev/sdc"
virtual_name = "ephemeral1"
}
}
build {
sources = [
"source.amazon-ebs.basic-example"
]
}
```
</Tab>
</Tabs>
The above build template is functional assuming you have set the environment
variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
-> **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. Packer will attempt to
clean up all residual volumes that are not designated by the user to remain
after termination. If you need to preserve those source volumes, you can
overwrite the termination setting by setting `delete_on_termination` to `false`
in the `launch_block_device_mappings` block for the device.
## Build template data ## Build template data
In configuration directives marked as a template engine above, the following In configuration directives marked as a template engine above, the following
@ -294,32 +360,57 @@ Here is an example using the optional AMI tags. This will add the tags
provide your access keys, and may need to change the source AMI ID based on provide your access keys, and may need to change the source AMI ID based on
what images exist when this template is run: what images exist when this template is run:
<Tabs>
<Tab heading="JSON">
```json ```json
{ {
"type": "amazon-ebs", "builders": [
"access_key": "YOUR KEY HERE", {
"secret_key": "YOUR SECRET KEY HERE", "type": "amazon-ebs",
"region": "us-east-1", "region": "us-east-1",
"source_ami": "ami-fce3c696", "source_ami": "ami-fce3c696",
"instance_type": "t2.micro", "instance_type": "t2.micro",
"ssh_username": "ubuntu", "ssh_username": "ubuntu",
"ami_name": "packer-quick-start {{timestamp}}", "ami_name": "packer-tag-example {{timestamp}}",
"tags": { "tags": {
"OS_Version": "Ubuntu", "OS_Version": "Ubuntu",
"Release": "Latest", "Release": "Latest",
"Base_AMI_Name": "{{ .SourceAMIName }}", "Base_AMI_Name": "{{ .SourceAMIName }}",
"Extra": "{{ .SourceAMITags.TagName }}" "Extra": "{{ .SourceAMITags.TagName }}"
} }
}
]
} }
``` ```
-> **Note:** Packer uses pre-built AMIs as the source for building images. </Tab>
These source AMIs may include volumes that are not flagged to be destroyed on <Tab heading="HCL2">
termination of the instance building the new image. Packer will attempt to
clean up all residual volumes that are not designated by the user to remain ```hcl
after termination. If you need to preserve those source volumes, you can source "amazon-ebs" "basic-example" {
overwrite the termination setting by specifying `delete_on_termination=false` region = "us-east-1"
in the `launch_block_device_mappings` block for the device. source_ami = "ami-fce3c696"
instance_type = "t2.micro"
ssh_username = "ubuntu"
ami_name = "packer_tag_example {{timestamp}}"
tags = {
OS_Version = "Ubuntu"
Release = "Latest"
Base_AMI_Name = "{{ .SourceAMIName }}"
Extra = "{{ .SourceAMITags.TagName }}"
}
}
build {
sources = [
"source.amazon-ebs.basic-example"
]
}
```
</Tab>
</Tabs>
## Connecting to Windows instances using WinRM ## Connecting to Windows instances using WinRM
@ -387,6 +478,9 @@ You'll notice that this config does not define a user or password; instead,
Packer will ask AWS to provide a random password that it generates Packer will ask AWS to provide a random password that it generates
automatically. The following config will work with the above template: automatically. The following config will work with the above template:
<Tabs>
<Tab heading="JSON">
```json ```json
{ {
"builders": [ "builders": [
@ -404,7 +498,7 @@ automatically. The following config will work with the above template:
"owners": "amazon" "owners": "amazon"
}, },
"ami_name": "default-packer", "ami_name": "default-packer",
"user_data_file": "winrm_bootstrap.txt", "user_data_file": "./boot_config/winrm_bootstrap.txt",
"communicator": "winrm", "communicator": "winrm",
"force_deregister": true, "force_deregister": true,
"winrm_insecure": true, "winrm_insecure": true,
@ -415,11 +509,63 @@ automatically. The following config will work with the above template:
} }
``` ```
</Tab>
<Tab heading="HCL2">
```hcl
source "amazon-ebs" "winrm-example" {
region = "us-east-1"
// This example uses a source_ami_filter rather than a specific AMI.
// this allows us to use the same filter regardless of what region we're in,
// among other benefits.
source_ami_filter {
filter {
key = "virtualization-type"
value = "hvm"
}
filter {
key = "name"
value = "*Windows_Server-2012*English-64Bit-Base*"
}
filter {
key = "root-device-type"
value = "ebs"
}
most_recent = true
owners = ["amazon"]
}
instance_type = "t2.micro"
ami_name = "packer_winrm_example {{timestamp}}"
// This user data file sets up winrm and configures it so that the connection
// from Packer is allowed. Without this file being set, Packer will not
// connect to the instance.
user_data_file = "../boot_config/winrm_bootstrap.txt"
communicator = "winrm"
force_deregister = true
winrm_insecure = true
winrm_username = "Administrator"
winrm_use_ssl = true
}
build {
sources = [
"source.amazon-ebs.winrm-example"
]
}
```
</Tab>
</Tabs>
## Windows 2016 Sysprep Commands - For Amazon Windows AMIs Only ## Windows 2016 Sysprep Commands - For Amazon Windows AMIs Only
For Amazon Windows 2016 AMIs it is necessary to run Sysprep commands which can For Amazon Windows 2016 AMIs it is necessary to run Sysprep commands which can
be easily added to the provisioner section. be easily added to the provisioner section.
<Tabs>
<Tab heading="JSON">
```json ```json
{ {
"type": "powershell", "type": "powershell",
@ -430,4 +576,20 @@ be easily added to the provisioner section.
} }
``` ```
</Tab>
<Tab heading="HCL2">
```hcl
provisioner "powershell" {
inline = [
"C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/InitializeInstance.ps1 -Schedule",
"C:/ProgramData/Amazon/EC2-Windows/Launch/Scripts/SysprepInstance.ps1 -NoShutdown"
]
}
```
</Tab>
</Tabs>
@include 'builders/aws-ssh-differentiation-table.mdx' @include 'builders/aws-ssh-differentiation-table.mdx'

42
website/pages/docs/builders/amazon/index.mdx
View File

@ -67,15 +67,32 @@ explained below:
Static credentials can be provided in the form of an access key id and secret. Static credentials can be provided in the form of an access key id and secret.
These look like: These look like:
<Tabs>
<Tab heading="JSON">
```json ```json
{ "builders": {
"type": "amazon-ebs"
"access_key": "AKIAIOSFODNN7EXAMPLE", "access_key": "AKIAIOSFODNN7EXAMPLE",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"region": "us-east-1", "region": "us-east-1",
"type": "amazon-ebs"
} }
``` ```
</Tab>
<Tab heading="HCL2">
```hcl
source "amazon-ebs" "basic-example" {
access_key = "AKIAIOSFODNN7EXAMPLE"
secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
region = "us-east-1"
}
```
</Tab>
</Tabs>
### Environment variables ### Environment variables
You can provide your credentials via the `AWS_ACCESS_KEY_ID` and You can provide your credentials via the `AWS_ACCESS_KEY_ID` and
@ -110,14 +127,31 @@ The format for the credentials file is like so
You may also configure the profile to use by setting the `profile` You may also configure the profile to use by setting the `profile`
configuration option, or setting the `AWS_PROFILE` environment variable: configuration option, or setting the `AWS_PROFILE` environment variable:
<Tabs>
<Tab heading="JSON">
```json ```json
{ "builders": {
"type": "amazon-ebs"
"profile": "customprofile", "profile": "customprofile",
"region": "us-east-1", "region": "us-east-1",
"type": "amazon-ebs"
} }
``` ```
</Tab>
<Tab heading="HCL2">
```hcl
source "amazon-ebs" "basic-example" {
profile = "customprofile"
region = "us-east-1"
}
```
</Tab>
</Tabs>
### IAM Task or Instance Role ### IAM Task or Instance Role
Finally, Packer will use credentials provided by the task's or instance's IAM Finally, Packer will use credentials provided by the task's or instance's IAM