make error messaging around ResourceNotReady better, update docs with other possible issues (#8349)

builder/amazon/common/state.go

@@ -5,6 +5,7 @@ import (
 	"log"
 	"os"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/aws/aws-sdk-go/aws"
@@ -52,6 +53,16 @@ func WaitUntilAMIAvailable(ctx aws.Context, conn ec2iface.EC2API, imageId string
 		ctx,
 		&imageInput,
 		waitOpts...)
+	if err != nil {
+		if strings.Contains(err.Error(), request.WaiterResourceNotReadyErrorCode) {
+			err = fmt.Errorf("Failed with ResourceNotReady error, which can "+
+				"have a variety of causes. For help troubleshooting, check "+
+				"our docs: "+
+				"https://www.packer.io/docs/builders/amazon.html#resourcenotready-error\n"+
+				"original error: %s", err.Error())
+		}
+	}
+
 	return err
 }
 

builder/amazon/common/step_cleanup_volumes.go

@@ -60,7 +60,7 @@ func (s *StepCleanupVolumes) Cleanup(state multistep.StateBag) {
 	})
 
 	if err != nil {
-		ui.Say(fmt.Sprintf("Error describing volumes: %s", err))
+		ui.Error(fmt.Sprintf("Error describing volumes: %s", err))
 		return
 	}
 

builder/amazon/common/step_security_group.go

@@ -183,7 +183,8 @@ func (s *StepSecurityGroup) Cleanup(state multistep.StateBag) {
 
 	if err != nil {
 		ui.Error(fmt.Sprintf(
-			"Error cleaning up security group. Please delete the group manually: %s", s.createdGroupId))
+			"Error cleaning up security group. Please delete the group manually:"+
+				" err: %s; security group ID: %s", err, s.createdGroupId))
 	}
 }
 

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

@@ -262,34 +262,47 @@ If you suspect your system's date is wrong, you can compare it against
 Linux/OS X, you can run the `date` command to get the current time. If you're
 on Linux, you can try setting the time with ntp by running `sudo ntpd -q`.
 
-### `exceeded wait attempts` while waiting for tasks to complete
-
-We use the AWS SDK's built-in waiters to wait for longer-running tasks to
-complete. These waiters have default delays between queries and maximum number
-of queries that don't always work for our users.
-
-If you find that you are being rate-limited or have exceeded your max wait
-attempts, you can override the defaults by setting the following packer
-environment variables (note that these will apply to all aws tasks that we have
-to wait for):
-
-`AWS_MAX_ATTEMPTS` - This is how many times to re-send a status update request.
-Excepting tasks that we know can take an extremely long time, this defaults to
-40tries.
-
-`AWS_POLL_DELAY_SECONDS` - How many seconds to wait in between status update
-requests. Generally defaults to 2 or 5 seconds, depending on the task.
-
-### `ResourceNotReady: failed waiting for successful resource state`
-
-This error message can appear for several reasons, generally during image
-copy/encryption. It is often the result of a KMS misconfiguration. Examples of
-possible misconfigurations are:
-
-- You provided an invalid kms_key_id.
-- The kms key you provided is a valid key, but not in the region you've said to
-  use it in.
-- The kms key you provided is a valid key, but does not have all of the
-  necessary policy permissions for an image copy. (see above for the necessary
-  kms policies)
-- You are using STS credentials that expired during a long-running call.
+### ResourceNotReady Error
+This error generally appears as either `ResourceNotReady: exceeded wait
+attempts` or `ResourceNotReady: failed waiting for successful resource state`.
+
+This opaque error gets returned from AWS's API for a number of reasons,
+generally during image copy/encryption. Possible reasons for the error include:
+
+- You aren't waiting long enough. This is where you'll see the `exceeded wait
+  attempts` variety of this error message:
+  We use the AWS SDK's built-in waiters to wait for longer-running tasks to
+    complete. These waiters have default delays between queries and maximum
+    number of queries that don't always work for our users.
+
+    If you find that you are being rate-limited or have exceeded your max wait
+    attempts, you can override the defaults by setting the following packer
+    environment variables (note that these will apply to all AWS tasks that we
+    have to wait for):
+
+    - `AWS_MAX_ATTEMPTS` - This is how many times to re-send a status update
+    request. Excepting tasks that we know can take an extremely long time, this
+    defaults to 40 tries.
+
+    - `AWS_POLL_DELAY_SECONDS` - How many seconds to wait in between status update
+    requests. Generally defaults to 2 or 5 seconds, depending on the task.
+
+- You are using short-lived credentials that expired during the build. If this
+    is the problem, you may also see `RequestExpired: Request has expired.`
+    errors displayed in the Packer output:
+
+    - If you are using STS credentials, make sure that they expire only after the
+    build has completed
+
+    - If you are chaining roles, make sure your build doesn't last more than an
+    hour, since when you chain roles the maximum length of time your credentials
+    will last is an hour:
+    https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html
+
+- Something is wrong with your KMS key. This is where you'll see the
+  `ResourceNotReady: failed waiting for successful resource state` variety of
+  this error message. Issues we've seen include:
+    - Your KMS key is invalid, possibly because of a typo
+    - Your KMS key is valid but does not have the necessary permissions (see
+      above for the necessary key permissions)
+    - Your KMS key is valid, but not in the region you've told us to use it in.