Commit 99061b96 authored by Chris Bednarski's avatar Chris Bednarski

Merge branch 'master' into docs-revamp

parents d8e8f98b 40f2173c
...@@ -64,7 +64,7 @@ type TestT interface { ...@@ -64,7 +64,7 @@ type TestT interface {
// Test performs an acceptance test on a backend with the given test case. // Test performs an acceptance test on a backend with the given test case.
// //
// Tests are not run unless an environmental variable "TF_ACC" is // Tests are not run unless an environmental variable "PACKER_ACC" is
// set to some non-empty value. This is to avoid test cases surprising // set to some non-empty value. This is to avoid test cases surprising
// a user by creating real resources. // a user by creating real resources.
// //
......
...@@ -35,7 +35,7 @@ type Config struct { ...@@ -35,7 +35,7 @@ type Config struct {
TypeOverride bool `mapstructure:"artifact_type_override"` TypeOverride bool `mapstructure:"artifact_type_override"`
Metadata map[string]string Metadata map[string]string
ServerAddr string `mapstructure:"server_address"` ServerAddr string `mapstructure:"atlas_url"`
Token string Token string
// This shouldn't ever be set outside of unit tests. // This shouldn't ever be set outside of unit tests.
......
...@@ -60,30 +60,19 @@ builder. ...@@ -60,30 +60,19 @@ builder.
### Required: ### Required:
- `access_key` (string) - The access key used to communicate with AWS. If not * `access_key` (string) - The access key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
specified, Packer will use the key from any
[credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) * `ami_name` (string) - The name of the resulting AMI that will appear
file or fall back to environment variables `AWS_ACCESS_KEY_ID` or when managing AMIs in the AWS console or via APIs. This must be unique.
`AWS_ACCESS_KEY` (in that order), if set. If the environmental variables To help make this unique, use a function like `timestamp` (see
aren't set and Packer is running on an EC2 instance, Packer will check the [configuration templates](/docs/templates/configuration-templates.html) for more info)
instance metadata for IAM role keys.
* `secret_key` (string) - The secret key used to communicate with AWS.
- `ami_name` (string) - The name of the resulting AMI that will appear when [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
managing AMIs in the AWS console or via APIs. This must be unique. To help
make this unique, use a function like `timestamp` (see [configuration * `source_ami` (string) - The source AMI whose root volume will be copied
templates](/docs/templates/configuration-templates.html) for more info) and provisioned on the currently running instance. This must be an
EBS-backed AMI with a root volume snapshot that you have access to.
- `secret_key` (string) - The secret key used to communicate with AWS. If not
specified, Packer will use the secret from any
[credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files)
file or fall back to environment variables `AWS_SECRET_ACCESS_KEY` or
`AWS_SECRET_KEY` (in that order), if set. If the environmental variables
aren't set and Packer is running on an EC2 instance, Packer will check the
instance metadata for IAM role keys.
- `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.
### Optional: ### Optional:
......
...@@ -40,34 +40,26 @@ builder. ...@@ -40,34 +40,26 @@ builder.
### Required: ### Required:
- `access_key` (string) - The access key used to communicate with AWS. If not * `access_key` (string) - The access key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
specified, Packer will use the key from any
[credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) * `ami_name` (string) - The name of the resulting AMI that will appear
file or fall back to environment variables `AWS_ACCESS_KEY_ID` or when managing AMIs in the AWS console or via APIs. This must be unique.
`AWS_ACCESS_KEY` (in that order), if set. To help make this unique, use a function like `timestamp` (see
[configuration templates](/docs/templates/configuration-templates.html) for more info)
- `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 * `instance_type` (string) - The EC2 instance type to use while building
make this unique, use a function like `timestamp` (see [configuration the AMI, such as "m1.small".
templates](/docs/templates/configuration-templates.html) for more info)
* `region` (string) - The name of the region, such as "us-east-1", in which
- `instance_type` (string) - The EC2 instance type to use while building the to launch the EC2 instance to create the AMI.
AMI, such as "m1.small".
* `secret_key` (string) - The secret key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
- `region` (string) - The name of the region, such as "us-east-1", in which to
launch the EC2 instance to create the AMI. * `source_ami` (string) - The initial AMI used as a base for the newly
created machine.
- `secret_key` (string) - The secret key used to communicate with AWS. If not
specified, Packer will use the secret from any * `ssh_username` (string) - The username to use in order to communicate
[credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) over SSH to the running machine.
file or fall back to environment variables `AWS_SECRET_ACCESS_KEY` or
`AWS_SECRET_KEY` (in that order), if set.
- `source_ami` (string) - The initial AMI used as a base for the newly
created machine.
- `ssh_username` (string) - The username to use in order to communicate over
SSH to the running machine.
### Optional: ### Optional:
......
...@@ -45,50 +45,41 @@ builder. ...@@ -45,50 +45,41 @@ builder.
### Required: ### Required:
- `access_key` (string) - The access key used to communicate with AWS. If not * `access_key` (string) - The access key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
specified, Packer will use the key from any
[credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files)
file or fall back to environment variables `AWS_ACCESS_KEY_ID` or
`AWS_ACCESS_KEY` (in that order), if set.
- `account_id` (string) - Your AWS account ID. This is required for bundling * `account_id` (string) - Your AWS account ID. This is required for bundling
the AMI. This is *not the same* as the access key. You can find your account the AMI. This is _not the same_ as the access key. You can find your
ID in the security credentials page of your AWS account. account ID in the security credentials page of your AWS account.
- `ami_name` (string) - The name of the resulting AMI that will appear when * `ami_name` (string) - The name of the resulting AMI that will appear
managing AMIs in the AWS console or via APIs. This must be unique. To help when managing AMIs in the AWS console or via APIs. This must be unique.
make this unique, use a function like `timestamp` (see [configuration To help make this unique, use a function like `timestamp` (see
templates](/docs/templates/configuration-templates.html) for more info) [configuration templates](/docs/templates/configuration-templates.html) for more info)
- `instance_type` (string) - The EC2 instance type to use while building the * `instance_type` (string) - The EC2 instance type to use while building
AMI, such as "m1.small". the AMI, such as "m1.small".
- `region` (string) - The name of the region, such as "us-east-1", in which to * `region` (string) - The name of the region, such as "us-east-1", in which
launch the EC2 instance to create the AMI. to launch the EC2 instance to create the AMI.
- `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. This * `s3_bucket` (string) - The name of the S3 bucket to upload the AMI.
bucket will be created if it doesn't exist. This bucket will be created if it doesn't exist.
- `secret_key` (string) - The secret key used to communicate with AWS. If not * `secret_key` (string) - The secret key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
specified, Packer will use the secret from any
[credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files)
file or fall back to environment variables `AWS_SECRET_ACCESS_KEY` or
`AWS_SECRET_KEY` (in that order), if set.
- `source_ami` (string) - The initial AMI used as a base for the newly * `source_ami` (string) - The initial AMI used as a base for the newly
created machine. created machine.
- `ssh_username` (string) - The username to use in order to communicate over * `ssh_username` (string) - The username to use in order to communicate
SSH to the running machine. over SSH to the running machine.
- `x509_cert_path` (string) - The local path to a valid X509 certificate for * `x509_cert_path` (string) - The local path to a valid X509 certificate for
your AWS account. This is used for bundling the AMI. This X509 certificate your AWS account. This is used for bundling the AMI. This X509 certificate
must be registered with your account from the security credentials page in must be registered with your account from the security credentials page
the AWS console. in the AWS console.
- `x509_key_path` (string) - The local path to the private key for the X509 * `x509_key_path` (string) - The local path to the private key for the X509
certificate specified by `x509_cert_path`. This is used for bundling certificate specified by `x509_cert_path`. This is used for bundling the AMI.
the AMI.
### Optional: ### Optional:
......
...@@ -9,28 +9,57 @@ page_title: Amazon AMI Builder ...@@ -9,28 +9,57 @@ page_title: Amazon AMI Builder
# Amazon AMI Builder # Amazon AMI Builder
Packer is able to create Amazon AMIs. To achieve this, Packer comes with Packer is able to create Amazon AMIs. To achieve this, Packer comes with
multiple builders depending on the strategy you want to use to build the AMI. multiple builders depending on the strategy you want to use to build the
Packer supports the following builders at the moment: AMI. Packer supports the following builders at the moment:
- [amazon-ebs](/docs/builders/amazon-ebs.html) - Create EBS-backed AMIs by * [amazon-ebs](/docs/builders/amazon-ebs.html) - Create EBS-backed AMIs
launching a source AMI and re-packaging it into a new AMI by launching a source AMI and re-packaging it into a new AMI after
after provisioning. If in doubt, use this builder, which is the easiest to provisioning. If in doubt, use this builder, which is the easiest to get
get started with. started with.
- [amazon-instance](/docs/builders/amazon-instance.html) - Create * [amazon-instance](/docs/builders/amazon-instance.html) - Create
instance-store AMIs by launching and provisioning a source instance, then instance-store AMIs by launching and provisioning a source instance, then
rebundling it and uploading it to S3. rebundling it and uploading it to S3.
- [amazon-chroot](/docs/builders/amazon-chroot.html) - Create EBS-backed AMIs * [amazon-chroot](/docs/builders/amazon-chroot.html) - Create EBS-backed AMIs
from an existing EC2 instance by mounting the root device and using a from an existing EC2 instance by mounting the root device and using a
[Chroot](http://en.wikipedia.org/wiki/Chroot) environment to provision [Chroot](http://en.wikipedia.org/wiki/Chroot) environment to provision
that device. This is an **advanced builder and should not be used by that device. This is an **advanced builder and should not be used by
newcomers**. However, it is also the fastest way to build an EBS-backed AMI newcomers**. However, it is also the fastest way to build an EBS-backed
since no new EC2 instance needs to be launched. AMI since no new EC2 instance needs to be launched.
-> **Don't know which builder to use?** If in doubt, use the [amazon-ebs -> **Don't know which builder to use?** If in doubt, use the
builder](/docs/builders/amazon-ebs.html). It is much easier to use and Amazon [amazon-ebs builder](/docs/builders/amazon-ebs.html). It is
generally recommends EBS-backed images nowadays. much easier to use and Amazon generally recommends EBS-backed images nowadays.
<div id="specifying-amazon-credentials">## Specifying Amazon Credentials</div>
When you use any of the amazon builders, you must provide credentials to the API in the form of an access key id and secret. These look like:
access key id: AKIAIOSFODNN7EXAMPLE
secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
If you use other AWS tools you may already have these configured. If so, packer will try to use them, *unless* they are specified in your packer template. Credentials are resolved in the following order:
1. Values hard-coded in the packer template are always authoritative.
2. *Variables* in the packer template may be resolved from command-line flags or from environment variables. Please read about [User Variables](https://packer.io/docs/templates/user-variables.html) for details.
3. If no credentials are found, packer falls back to automatic lookup.
### Automatic Lookup
If no AWS credentials are found in a packer template, we proceed on to the following steps:
1. Lookup via environment variables.
- First `AWS_ACCESS_KEY_ID`, then `AWS_ACCESS_KEY`
- First `AWS_SECRET_ACCESS_KEY`, then `AWS_SECRET_KEY`
2. Look for [local AWS configuration files](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files)
- First `~/.aws/credentials`
- Next based on `AWS_PROFILE`
3. Lookup an IAM role for the current EC2 instance (if you're running in EC2)
~> **Subtle details of automatic lookup may change over time.** The most reliable way to specify your configuration is by setting them in template variables (directly or indirectly), or by using the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.
Environment variables provide the best portability, allowing you to run your packer build on your workstation, in Atlas, or on another build server.
## Using an IAM Instance Profile ## Using an IAM Instance Profile
...@@ -74,3 +103,24 @@ Packer to work: ...@@ -74,3 +103,24 @@ Packer to work:
}] }]
} }
``` ```
## Troubleshooting
### Attaching IAM Policies to Roles
IAM policies can be associated with user or roles. If you use packer with IAM roles, you may encounter an error like this one:
==> amazon-ebs: Error launching source instance: You are not authorized to perform this operation.
You can read more about why this happens on the [Amazon Security Blog](http://blogs.aws.amazon.com/security/post/Tx3M0IFB5XBOCQX/Granting-Permission-to-Launch-EC2-Instances-with-IAM-Roles-PassRole-Permission). The example policy below may help packer work with IAM roles. Note that this example provides more than the minimal set of permissions needed for packer to work, but specifics will depend on your use-case.
```json
{
"Sid": "PackerIAMPassRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": [
"*"
]
}
```
...@@ -73,6 +73,14 @@ alternatives available. ...@@ -73,6 +73,14 @@ alternatives available.
If you're using OS X and [Homebrew](http://brew.sh), you can install Packer: If you're using OS X and [Homebrew](http://brew.sh), you can install Packer:
``` {.text} $ brew install packer
$ brew install packer
``` ## Troubleshooting
On some RedHat-based Linux distributions there is another tool named `packer` installed by default. You can check for this using `which -a packer`. If you get an error like this it indicates there is a name conflict.
$ packer
/usr/share/cracklib/pw_dict.pwd: Permission denied
/usr/share/cracklib/pw_dict: Permission denied
To fix this, you can create a symlink to packer that uses a different name like `packer.io`, or invoke the `packer` binary you want using its absolute path, e.g. `/usr/local/packer`.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment