Merge pull request #2500 from mitchellh/docs-amazon-creds

Updated docs on how AWS credentials are resolved
This commit is contained in:
Chris Bednarski 2015-07-24 20:48:55 -07:00
commit 40f2173c6e
4 changed files with 35 additions and 18 deletions

View File

@ -57,10 +57,7 @@ can be configured for this builder.
### Required: ### Required:
* `access_key` (string) - The access key used to communicate with AWS. * `access_key` (string) - The access key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
If not specified, Packer will search the standard [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file using environment variable `AWS_PROFILE` as the profile name, will use the `[default]` entry,
or will fall back to environment variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY`.
Finally, if Packer is running on an EC2 instance it will check the instance metadata for IAM role keys.
* `ami_name` (string) - The name of the resulting AMI that will appear * `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. when managing AMIs in the AWS console or via APIs. This must be unique.
@ -68,7 +65,7 @@ can be configured for this builder.
[configuration templates](/docs/templates/configuration-templates.html) for more info) [configuration templates](/docs/templates/configuration-templates.html) for more info)
* `secret_key` (string) - The secret key used to communicate with AWS. * `secret_key` (string) - The secret key used to communicate with AWS.
Lookup behavior is as above for `access_key` except the variables are `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY`. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
* `source_ami` (string) - The source AMI whose root volume will be copied * `source_ami` (string) - The source AMI whose root volume will be copied
and provisioned on the currently running instance. This must be an and provisioned on the currently running instance. This must be an

View File

@ -37,10 +37,7 @@ can be configured for this builder.
### Required: ### Required:
* `access_key` (string) - The access key used to communicate with AWS. * `access_key` (string) - The access key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
If not specified, Packer will search the standard [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file using environment variable `AWS_PROFILE` as the profile name, will use the `[default]` entry,
or will fall back to environment variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY`.
Finally, if Packer is running on an EC2 instance it will check the instance metadata for IAM role keys.
* `ami_name` (string) - The name of the resulting AMI that will appear * `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. when managing AMIs in the AWS console or via APIs. This must be unique.
@ -53,8 +50,7 @@ can be configured for this builder.
* `region` (string) - The name of the region, such as "us-east-1", in which * `region` (string) - The name of the region, such as "us-east-1", in which
to launch the EC2 instance to create the AMI. to launch the EC2 instance to create the AMI.
* `secret_key` (string) - The secret key used to communicate with AWS. * `secret_key` (string) - The secret key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
Lookup behavior is as above for `access_key` except the variables are `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY`
* `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.

View File

@ -42,10 +42,7 @@ can be configured for this builder.
### Required: ### Required:
* `access_key` (string) - The access key used to communicate with AWS. * `access_key` (string) - The access key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
If not specified, Packer will search the standard [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file using environment variable `AWS_PROFILE` as the profile name, will use the `[default]` entry,
or will fall back to environment variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY`.
Finally, if Packer is running on an EC2 instance it will check the instance metadata for IAM role keys.
* `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 the AMI. This is _not the same_ as the access key. You can find your
@ -65,9 +62,7 @@ can be configured for this builder.
* `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. * `s3_bucket` (string) - The name of the S3 bucket to upload the AMI.
This 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. * `secret_key` (string) - The secret key used to communicate with AWS. [Learn how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
Lookup behavior is as above for `access_key` except the variables are `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY`
* `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.

View File

@ -31,6 +31,35 @@ AMI. Packer supports the following builders at the moment:
[amazon-ebs builder](/docs/builders/amazon-ebs.html). It is [amazon-ebs builder](/docs/builders/amazon-ebs.html). It is
much easier to use and Amazon 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
If AWS keys are not specified in the template, Packer will consult the [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file, try the standard AWS environment variables, and then If AWS keys are not specified in the template, Packer will consult the [credentials](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files) file, try the standard AWS environment variables, and then