Merge branch 'docs-revamp' into docs-revamp-content

helper/builder/testing/testing.go

@@ -64,7 +64,7 @@ type TestT interface {
 
 // 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
 // a user by creating real resources.
 //

post-processor/atlas/post-processor.go

@@ -35,7 +35,7 @@ type Config struct {
 	TypeOverride bool   `mapstructure:"artifact_type_override"`
 	Metadata     map[string]string
 
-	ServerAddr string `mapstructure:"server_address"`
+	ServerAddr string `mapstructure:"atlas_url"`
 	Token      string
 
 	// This shouldn't ever be set outside of unit tests.

website/source/docs/builders/amazon-chroot.html.markdown

@@ -60,26 +60,16 @@ builder.
 
 ### Required:
 
--   `access_key` (string) - The access key used to communicate with AWS. If not
-    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. 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.
+-   `access_key` (string) - The access key used to communicate with AWS. [Learn
+    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 [configuration
     templates](/docs/templates/configuration-templates.html) for more info)
 
--   `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.
+-   `secret_key` (string) - The secret key used to communicate with AWS. [Learn
+    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

website/source/docs/builders/amazon-ebs.html.markdown

@@ -40,11 +40,8 @@ builder.
 
 ### Required:
 
--   `access_key` (string) - The access key used to communicate with AWS. If not
-    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.
+-   `access_key` (string) - The access key used to communicate with AWS. [Learn
+    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
@@ -57,11 +54,8 @@ builder.
 -   `region` (string) - The name of the region, such as "us-east-1", in which to
     launch the EC2 instance to create the AMI.
 
--   `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.
+-   `secret_key` (string) - The secret key used to communicate with AWS. [Learn
+    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.

website/source/docs/builders/amazon-instance.html.markdown

@@ -45,11 +45,8 @@ builder.
 
 ### Required:
 
--   `access_key` (string) - The access key used to communicate with AWS. If not
-    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.
+-   `access_key` (string) - The access key used to communicate with AWS. [Learn
+    how to set this.](/docs/builders/amazon.html#specifying-amazon-credentials)
 
 -   `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
@@ -69,11 +66,8 @@ builder.
 -   `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. This
     bucket will be created if it doesn't exist.
 
--   `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.
+-   `secret_key` (string) - The secret key used to communicate with AWS. [Learn
+    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.

website/source/docs/builders/amazon.html.markdown

@@ -32,6 +32,53 @@ Packer supports the following builders at the moment:
 builder](/docs/builders/amazon-ebs.html). It is 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)
+
+\~&gt; **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
 
 If AWS keys are not specified in the template, a
@@ -74,3 +121,29 @@ 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": [
+        "*"
+    ]
+}
+```

website/source/intro/getting-started/setup.html.markdown

@@ -73,6 +73,18 @@ alternatives available.
 
 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`.