resource/aws_backup_selection: IAM retries, test fix, documenta… (#9298)

* resource/aws_backup_selection: Retry creation for IAM eventual consistency error

Reference: #9297

Output from acceptance testing (failure present on master):

```
--- FAIL: TestAccAwsBackupSelection_withResources (12.00s)
    testing.go:568: Step 0 error: errors during apply:

        Error: error creating Backup Selection: InvalidParameterValueException: Invalid ARN: arn:aws:elasticfilesystem:us-west-2:--OMITTED--:file-system/. Specified resource is not supported
        	status code: 400, request id: 2f845d03-51d3-48df-b853-46c077f85780

          on /var/folders/v0/_d108fkx1pbbg4_sh864_7740000gn/T/tf-test308326165/main.tf line 22:
          (source code not available)

--- PASS: TestAccAwsBackupSelection_disappears (17.20s)
--- PASS: TestAccAwsBackupSelection_basic (18.44s)
--- PASS: TestAccAwsBackupSelection_withTags (18.47s)
--- PASS: TestAccAwsBackupSelection_updateTag (28.73s)
```

* tests/resource/aws_backup_selection: Remove wildcard usage in withResources acceptance test

The usage of wildcards differs between AWS Regions while ARNs are supported everywhere.

Previously from acceptance testing:

```
--- FAIL: TestAccAwsBackupSelection_withResources (12.00s)
    testing.go:568: Step 0 error: errors during apply:

        Error: error creating Backup Selection: InvalidParameterValueException: Invalid ARN: arn:aws:elasticfilesystem:us-west-2:--OMITTED--:file-system/. Specified resource is not supported
```

Output from acceptance testing:

```
--- PASS: TestAccAwsBackupSelection_withResources (29.35s)
```

* docs/resource/aws_backup_selection: Expand example documentation to show IAM Role creation and show using resource ARNs

The support for wildcard resource selection does not work in all AWS Regions while ARN support is consistent.

Reference: #9269

aws/resource_aws_backup_selection.go

@@ -5,9 +5,11 @@ import (
 	"log"
 	"regexp"
 	"strings"
+	"time"
 
 	"github.com/aws/aws-sdk-go/aws"
 	"github.com/aws/aws-sdk-go/service/backup"
+	"github.com/hashicorp/terraform/helper/resource"
 	"github.com/hashicorp/terraform/helper/schema"
 	"github.com/hashicorp/terraform/helper/validation"
 )
@@ -94,12 +96,34 @@ func resourceAwsBackupSelectionCreate(d *schema.ResourceData, meta interface{})
 		BackupSelection: selection,
 	}
 
-	resp, err := conn.CreateBackupSelection(input)
+	// Retry for IAM eventual consistency
+	var output *backup.CreateBackupSelectionOutput
+	err := resource.Retry(1*time.Minute, func() *resource.RetryError {
+		var err error
+		output, err = conn.CreateBackupSelection(input)
+
+		// Retry on the following error:
+		// InvalidParameterValueException: IAM Role arn:aws:iam::123456789012:role/XXX cannot be assumed by AWS Backup
+		if isAWSErr(err, backup.ErrCodeInvalidParameterValueException, "cannot be assumed") {
+			return resource.RetryableError(err)
+		}
+
+		if err != nil {
+			return resource.NonRetryableError(err)
+		}
+
+		return nil
+	})
+
+	if isResourceTimeoutError(err) {
+		output, err = conn.CreateBackupSelection(input)
+	}
+
 	if err != nil {
 		return fmt.Errorf("error creating Backup Selection: %s", err)
 	}
 
-	d.SetId(*resp.SelectionId)
+	d.SetId(aws.StringValue(output.SelectionId))
 
 	return resourceAwsBackupSelectionRead(d, meta)
 }

aws/resource_aws_backup_selection_test.go

@@ -304,6 +304,17 @@ resource "aws_backup_selection" "test" {
 
 func testAccBackupSelectionConfigWithResources(rInt int) string {
 	return testAccBackupSelectionConfigBase(rInt) + fmt.Sprintf(`
+data "aws_availability_zones" "available" {
+  state = "available"
+}
+
+resource "aws_ebs_volume" "test" {
+  count = 2
+
+  availability_zone = "${data.aws_availability_zones.available.names[0]}"
+  size              = 1
+}
+
 resource "aws_backup_selection" "test" {
   plan_id      = "${aws_backup_plan.test.id}"
 
@@ -317,8 +328,8 @@ resource "aws_backup_selection" "test" {
   }
 
   resources = [
-    "arn:${data.aws_partition.current.partition}:elasticfilesystem:${data.aws_region.current.name}:${data.aws_caller_identity.current.account_id}:file-system/",
-    "arn:${data.aws_partition.current.partition}:ec2:${data.aws_region.current.name}:${data.aws_caller_identity.current.account_id}:volume/"
+    "${aws_ebs_volume.test.0.arn}",
+    "${aws_ebs_volume.test.1.arn}",
   ]
 }
 `, rInt)

website/docs/r/backup_selection.html.markdown

@@ -12,21 +12,71 @@ Manages selection conditions for AWS Backup plan resources.
 
 ## Example Usage
 
+### IAM Role
+
+-> For more information about creating and managing IAM Roles for backups and restores, see the [AWS Backup Developer Guide](https://docs.aws.amazon.com/aws-backup/latest/devguide/iam-service-roles.html).
+
+The below example creates an IAM role with the default managed IAM Policy for allowing AWS Backup to create backups.
+
 ```hcl
+resource "aws_iam_role" "example" {
+  name               = "example"
+  assume_role_policy = <<POLICY
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": ["sts:AssumeRole"],
+      "Effect": "allow",
+      "Principal": {
+        "Service": ["backup.amazonaws.com"]
+      }
+    }
+  ]
+}
+POLICY
+}
+
+resource "aws_iam_role_policy_attachment" "example" {
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSBackupServiceRolePolicyForBackup"
+  role       = "${aws_iam_role.example.name}"
+}
+
 resource "aws_backup_selection" "example" {
-  plan_id = "${aws_backup_plan.example.id}"
+  # ... other configuration ...
+
+  iam_role_arn = "${aws_iam_role.example.arn}"
+}
+```
+
+### Selecting Backups By Tag
 
+```hcl
+resource "aws_backup_selection" "example" {
+  iam_role_arn = "${aws_iam_role.example.arn}"
   name         = "tf_example_backup_selection"
-  iam_role_arn = "arn:aws:iam::123456789012:role/service-role/AWSBackupDefaultServiceRole"
+  plan_id      = "${aws_backup_plan.example.id}"
 
   selection_tag {
     type  = "STRINGEQUALS"
     key   = "foo"
     value = "bar"
   }
+}
+```
+
+### Selecting Backups By Resource
+
+```hcl
+resource "aws_backup_selection" "example" {
+  iam_role_arn = "${aws_iam_role.example.arn}"
+  name         = "tf_example_backup_selection"
+  plan_id      = "${aws_backup_plan.example.id}"
 
   resources = [
-    "arn:aws:ec2:us-east-1:123456789012:volume/",
+    "${aws_db_instance.example.arn}",
+    "${aws_ebs_volume.example.arn}",
+    "${aws_efs_file_system.example.arn}",
   ]
 }
 ```