Add role_last_used attribute to iam_role resource

.changelog/30750.txt

@@ -0,0 +1,7 @@
+```release-note:enhancement
+resource/aws_iam_role: Add `role_last_used` attribute
+```
+
+```release-note:enhancement
+data-source/aws_iam_role: Add `role_last_used` attribute
+```

internal/service/iam/role.go

@@ -160,6 +160,22 @@ func ResourceRole() *schema.Resource {
 				Optional:     true,
 				ValidateFunc: verify.ValidARN,
 			},
+			"role_last_used": {
+				Type:     schema.TypeList,
+				Computed: true,
+				Elem: &schema.Resource{
+					Schema: map[string]*schema.Schema{
+						"region": {
+							Type:     schema.TypeString,
+							Computed: true,
+						},
+						"last_used_date": {
+							Type:     schema.TypeString,
+							Computed: true,
+						},
+					},
+				},
+			},
 			names.AttrTags:    tftags.TagsSchema(),
 			names.AttrTagsAll: tftags.TagsSchemaComputed(),
 			"unique_id": {
@@ -311,6 +327,10 @@ func resourceRoleRead(ctx context.Context, d *schema.ResourceData, meta interfac
 		return sdkdiag.AppendErrorf(diags, "reading inline policies for IAM role %s, error: %s", d.Id(), err)
 	}
 
+	if err := d.Set("role_last_used", flattenRoleLastUsed(role.RoleLastUsed)); err != nil {
+		return sdkdiag.AppendErrorf(diags, "setting role_last_used: %s", err)
+	}
+
 	var configPoliciesList []*iam.PutRolePolicyInput
 	if v := d.Get("inline_policy").(*schema.Set); v.Len() > 0 {
 		configPoliciesList = expandRoleInlinePolicies(aws.StringValue(role.RoleName), v.List())
@@ -713,6 +733,21 @@ func deleteRoleInlinePolicies(ctx context.Context, conn *iam.IAM, roleName strin
 	return nil
 }
 
+func flattenRoleLastUsed(apiObject *iam.RoleLastUsed) []interface{} {
+	if apiObject == nil {
+		return nil
+	}
+
+	tfMap := map[string]interface{}{
+		"region": aws.StringValue(apiObject.Region),
+	}
+
+	if apiObject.LastUsedDate != nil {
+		tfMap["last_used_date"] = apiObject.LastUsedDate.Format(time.RFC3339)
+	}
+	return []interface{}{tfMap}
+}
+
 func flattenRoleInlinePolicy(apiObject *iam.PutRolePolicyInput) map[string]interface{} {
 	if apiObject == nil {
 		return nil

internal/service/iam/role_data_source.go

@@ -28,35 +28,51 @@ func DataSourceRole() *schema.Resource {
 				Type:     schema.TypeString,
 				Computed: true,
 			},
-			"path": {
-				Type:     schema.TypeString,
-				Computed: true,
-			},
-			"permissions_boundary": {
+			"create_date": {
 				Type:     schema.TypeString,
 				Computed: true,
 			},
-			"unique_id": {
+			"description": {
 				Type:     schema.TypeString,
 				Computed: true,
 			},
-			"description": {
-				Type:     schema.TypeString,
+			"max_session_duration": {
+				Type:     schema.TypeInt,
 				Computed: true,
 			},
 			"name": {
 				Type:     schema.TypeString,
 				Required: true,
 			},
-			"create_date": {
+			"path": {
 				Type:     schema.TypeString,
 				Computed: true,
 			},
-			"max_session_duration": {
-				Type:     schema.TypeInt,
+			"permissions_boundary": {
+				Type:     schema.TypeString,
 				Computed: true,
 			},
+			"role_last_used": {
+				Type:     schema.TypeList,
+				Computed: true,
+				Elem: &schema.Resource{
+					Schema: map[string]*schema.Schema{
+						"region": {
+							Type:     schema.TypeString,
+							Computed: true,
+						},
+						"last_used_date": {
+							Type:     schema.TypeString,
+							Computed: true,
+						},
+					},
+				},
+			},
 			"tags": tftags.TagsSchemaComputed(),
+			"unique_id": {
+				Type:     schema.TypeString,
+				Computed: true,
+			},
 		},
 	}
 }
@@ -81,6 +97,11 @@ func dataSourceRoleRead(ctx context.Context, d *schema.ResourceData, meta interf
 	if err := d.Set("create_date", output.Role.CreateDate.Format(time.RFC3339)); err != nil {
 		return sdkdiag.AppendErrorf(diags, "setting create_date: %s", err)
 	}
+
+	if err := d.Set("role_last_used", flattenRoleLastUsed(output.Role.RoleLastUsed)); err != nil {
+		return sdkdiag.AppendErrorf(diags, "setting role_last_used: %s", err)
+	}
+
 	d.Set("description", output.Role.Description)
 	d.Set("max_session_duration", output.Role.MaxSessionDuration)
 	d.Set("name", output.Role.RoleName)

website/docs/d/iam_role.html.markdown

@@ -34,5 +34,11 @@ data "aws_iam_role" "example" {
 * `max_session_duration` - Maximum session duration.
 * `path` - Path to the role.
 * `permissions_boundary` - The ARN of the policy that is used to set the permissions boundary for the role.
+* `role_last_used` - Contains information about the last time that an IAM role was used. See [`role_last_used`](#role_last_used) for details.
 * `unique_id` - Stable and unique string identifying the role.
 * `tags` - Tags attached to the role.
+
+### role_last_used
+
+* `region` - The name of the AWS Region in which the role was last used.
+* `last_used_time` - The date and time, in RFC 3339 format, that the role was last used.

website/docs/r/iam_role.html.markdown

@@ -208,9 +208,15 @@ In addition to all arguments above, the following attributes are exported:
 * `create_date` - Creation date of the IAM role.
 * `id` - Name of the role.
 * `name` - Name of the role.
+* `role_last_used` - Contains information about the last time that an IAM role was used. See [`role_last_used`](#role_last_used) for details.
 * `tags_all` - A map of tags assigned to the resource, including those inherited from the provider [`default_tags` configuration block](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#default_tags-configuration-block).
 * `unique_id` - Stable and unique string identifying the role.
 
+### role_last_used
+
+* `region` - The name of the AWS Region in which the role was last used.
+* `last_used_time` - The date and time, in RFC 3339 format, that the role was last used.
+
 ## Import
 
 IAM Roles can be imported using the `name`, e.g.,