Skip to main content

roles

Creates, updates, deletes, gets or lists a roles resource.

Overview​

Nameroles
TypeResource
Idaws.iam.roles

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
arnstringThe Amazon Resource Name (ARN) specifying the role. For more information about ARNs and how to use them in policies, see IAM identifiers in the IAM User Guide guide.
assume_role_policy_documentstringThe policy that grants an entity permission to assume the role.
create_datestringThe date and time, in ISO 8601 date-time format, when the role was created.
descriptionstringA description of the role that you provide.
max_session_durationintegerThe maximum session duration (in seconds) for the specified role. Anyone who uses the CLI, or API to assume the role can specify the duration using the optional DurationSeconds API parameter or duration-seconds CLI parameter.
pathstringThe path to the role. For more information about paths, see IAM identifiers in the IAM User Guide.
permissions_boundarystringThe ARN of the policy used to set the permissions boundary for the role. For more information about permissions boundaries, see Permissions boundaries for IAM identities in the IAM User Guide.
role_idstringThe stable and unique string identifying the role. For more information about IDs, see IAM identifiers in the IAM User Guide.
role_last_usedstringContains information about the last time that an IAM role was used. This includes the date and time and the Region in which the role was last used. Activity is only reported for the trailing 400 days. This period can be shorter if your Region began supporting these features within the last year. The role might have been used more than 400 days ago. For more information, see Regions where data is tracked in the IAM user Guide.
role_namestringThe friendly name that identifies the role.
source_role_templatestringContains information about the role template that this role was created from. This member is present only for roles created with AcquireRole.
tagsstringA list of tags that are attached to the role. For more information about tagging, see Tagging IAM resources in the IAM User Guide.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
get_roleselectRoleName, regionRetrieves information about the specified role, including the role's path, GUID, ARN, and the role's trust policy that grants permission to assume the role. For more information about roles, see IAM roles in the IAM User Guide. Policies returned by this operation are URL-encoded compliant with RFC 3986. You can use a URL decoding method to convert the policy back to plain JSON text. For example, if you use Java, you can use the decode method of the java.net.URLDecoder utility class in the Java SDK. Other languages and SDKs provide similar functionality, and some SDKs do this decoding automatically.
list_rolesselectregionPathPrefix, Marker, MaxItemsLists the IAM roles that have the specified path prefix. If there are none, the operation returns an empty list. For more information about roles, see IAM roles in the IAM User Guide. IAM resource-listing operations return a subset of the available attributes for the resource. This operation does not return the following attributes, even though they are an attribute of the returned object: PermissionsBoundary RoleLastUsed Tags To view all of the information for a role, see GetRole. You can paginate the results using the MaxItems and Marker parameters.
create_roleinsertRoleName, AssumeRolePolicyDocument, regionPath, Description, MaxSessionDuration, PermissionsBoundary, TagsCreates a new role for your Amazon Web Services account. For more information about roles, see IAM roles in the IAM User Guide. For information about quotas for role names and the number of roles you can create, see IAM and STS quotas in the IAM User Guide.
create_service_linked_roleinsertAWSServiceName, regionDescription, CustomSuffixCreates an IAM role that is linked to a specific Amazon Web Services service. The service controls the attached policies and when the role can be deleted. This helps ensure that the service is not broken by an unexpectedly changed or deleted role, which could put your Amazon Web Services resources into an unknown state. Allowing the service to control the role helps improve service stability and proper cleanup when a service and its role are no longer needed. For more information, see Using service-linked roles in the IAM User Guide. To attach a policy to this service-linked role, you must make the request using the Amazon Web Services service that depends on this role.
update_roleupdateRoleName, regionDescription, MaxSessionDurationUpdates the description or maximum session duration setting of a role.
put_role_permissions_boundaryreplaceRoleName, PermissionsBoundary, regionAdds or updates the policy that is specified as the IAM role's permissions boundary. You can use an Amazon Web Services managed policy or a customer managed policy to set the boundary for a role. Use the boundary to control the maximum permissions that the role can have. Setting a permissions boundary is an advanced feature that can affect the permissions for the role. You cannot set the boundary for a service-linked role. Policies used as permissions boundaries do not provide permissions. You must also attach a permissions policy to the role. To learn how the effective permissions for a role are evaluated, see IAM JSON policy evaluation logic in the IAM User Guide.
delete_roledeleteRoleName, regionDeletes the specified role. Unlike the Amazon Web Services Management Console, when you delete a role programmatically, you must delete the items attached to the role manually, or the deletion fails. For more information, see Deleting an IAM role. Before attempting to delete a role, remove the following attached items: Inline policies (DeleteRolePolicy) Attached managed policies (DetachRolePolicy) Instance profile (RemoveRoleFromInstanceProfile) Optional – Delete instance profile after detaching from role for resource clean up (DeleteInstanceProfile) Make sure that you do not have any Amazon EC2 instances running with the role you are about to delete. Deleting a role or instance profile that is associated with a running instance will break any applications running on the instance.
delete_role_permissions_boundaryexecRoleName, regionDeletes the permissions boundary for the specified IAM role. You cannot set the boundary for a service-linked role. Deleting the permissions boundary for a role might increase its permissions. For example, it might allow anyone who assumes the role to perform all the actions granted in its permissions policies.
delete_service_linked_roleexecRoleName, regionSubmits a service-linked role deletion request and returns a DeletionTaskId, which you can use to check the status of the deletion. Before you call this operation, confirm that the role has no active sessions and that any resources used by the role in the linked service are deleted. If you call this operation more than once for the same service-linked role and an earlier deletion task is not complete, then the DeletionTaskId of the earlier request is returned. If you submit a deletion request for a service-linked role whose linked service is still accessing a resource, then the deletion task fails. If it fails, the GetServiceLinkedRoleDeletionStatus operation returns the reason for the failure, usually including the resources that must be deleted. To delete the service-linked role, you must first remove those resources from the linked service and then submit the deletion request again. Resources are specific to the service that is linked to the role. For more information about removing resources from a service, see the Amazon Web Services documentation for your service. For more information about service-linked roles, see Roles terms and concepts: Amazon Web Services service-linked role in the IAM User Guide.
update_role_descriptionexecRoleName, regionDescriptionUse UpdateRole instead. Modifies only the description of a role. This operation performs the same function as the Description parameter in the UpdateRole operation.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
AWSServiceNamestringThe service principal for the Amazon Web Services service to which this role is attached. You use a string similar to a URL but without the http:​// in front. For example: elasticbeanstalk.amazonaws.com. Service principals are unique and case-sensitive. To find the exact service principal for your service-linked role, see Amazon Web Services services that work with IAM in the IAM User Guide. Look for the services that have Yes in the Service-Linked Role column. Choose the Yes link to view the service-linked role documentation for that service.
AssumeRolePolicyDocumentstringThe trust relationship policy document that grants an entity permission to assume the role. In IAM, you must provide a JSON policy that has been converted to a string. However, for CloudFormation templates formatted in YAML, you can provide the policy in JSON or YAML format. CloudFormation always converts a YAML policy to JSON format before submitting it to IAM. The regex pattern used to validate this parameter is a string of characters consisting of the following: Any printable ASCII character ranging from the space character (\u0020) through the end of the ASCII character range The printable characters in the Basic Latin and Latin-1 Supplement character set (through \u00FF) The special characters tab (\u0009), line feed (\u000A), and carriage return (\u000D) Upon success, the response includes the same trust policy in JSON format.
PermissionsBoundarystringThe ARN of the managed policy that is used to set the permissions boundary for the role. A permissions boundary policy defines the maximum permissions that identity-based policies can grant to an entity, but does not grant permissions. Permissions boundaries do not define the maximum permissions that a resource-based policy can grant to an entity. To learn more, see Permissions boundaries for IAM entities in the IAM User Guide. For more information about policy types, see Policy types in the IAM User Guide.
RoleNamestringThe name of the role that you want to modify.
regionstringAWS region (default: us-east-1)
CustomSuffixstringA string that you provide, which is combined with the service-provided prefix to form the complete role name. If you make multiple requests for the same service, then you must supply a different CustomSuffix for each request. Otherwise the request fails with a duplicate role name error. For example, you could add -1 or -debug to the suffix. Some services do not support the CustomSuffix parameter. If you provide an optional suffix and the operation fails, try the operation again without the suffix.
DescriptionstringThe new description that you want to apply to the specified role.
MarkerstringUse this parameter only when paginating results and only after you receive a response indicating that the results are truncated. Set it to the value of the Marker element in the response that you received to indicate where the next call should start.
MaxItemsintegerUse this only when paginating results to indicate the maximum number of items you want in the response. If additional items exist beyond the maximum you specify, the IsTruncated response element is true. If you do not include this parameter, the number of items defaults to 100. Note that IAM might return fewer results, even when there are more results available. In that case, the IsTruncated response element returns true, and Marker contains a value to include in the subsequent call that tells the service where to continue from.
MaxSessionDurationintegerThe maximum session duration (in seconds) that you want to set for the specified role. If you do not specify a value for this setting, the default value of one hour is applied. This setting can have a value from 1 hour to 12 hours. Anyone who assumes the role from the CLI or API can use the DurationSeconds API parameter or the duration-seconds CLI parameter to request a longer session. The MaxSessionDuration setting determines the maximum duration that can be requested using the DurationSeconds parameter. If users don't specify a value for the DurationSeconds parameter, their security credentials are valid for one hour by default. This applies when you use the AssumeRole* API operations or the assume-role* CLI operations but does not apply when you use those operations to create a console URL. For more information, see Using IAM roles in the IAM User Guide. IAM role credentials provided by Amazon EC2 instances assigned to the role are not subject to the specified maximum session duration.
PathstringThe path to the role. For more information about paths, see IAM Identifiers in the IAM User Guide. This parameter is optional. If it is not included, it defaults to a slash (/). This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.
PathPrefixstringThe path prefix for filtering the results. For example, the prefix /application_abc/component_xyz/ gets all roles whose path starts with /application_abc/component_xyz/. This parameter is optional. If it is not included, it defaults to a slash (/), listing all roles. This parameter allows (through its regex pattern) a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. In addition, it can contain any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercased letters.
PermissionsBoundarystringThe ARN of the managed policy that is used to set the permissions boundary for the role. A permissions boundary policy defines the maximum permissions that identity-based policies can grant to an entity, but does not grant permissions. Permissions boundaries do not define the maximum permissions that a resource-based policy can grant to an entity. To learn more, see Permissions boundaries for IAM entities in the IAM User Guide. For more information about policy types, see Policy types in the IAM User Guide.
TagsarrayA list of tags that you want to attach to the new role. Each tag consists of a key name and an associated value. For more information about tagging, see Tagging IAM resources in the IAM User Guide. If any one of the tags is invalid or if you exceed the allowed maximum number of tags, then the entire request fails and the resource is not created.

SELECT examples​

Retrieves information about the specified role, including the role's path, GUID, ARN, and the role's trust policy that grants permission to assume the role. For more information about roles, see IAM roles in the IAM User Guide. Policies returned by this operation are URL-encoded compliant with RFC 3986. You can use a URL decoding method to convert the policy back to plain JSON text. For example, if you use Java, you can use the decode method of the java.net.URLDecoder utility class in the Java SDK. Other languages and SDKs provide similar functionality, and some SDKs do this decoding automatically.

SELECT
arn,
assume_role_policy_document,
create_date,
description,
max_session_duration,
path,
permissions_boundary,
role_id,
role_last_used,
role_name,
source_role_template,
tags
FROM aws.iam.roles
WHERE RoleName = '{{ RoleName }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new role for your Amazon Web Services account. For more information about roles, see IAM roles in the IAM User Guide. For information about quotas for role names and the number of roles you can create, see IAM and STS quotas in the IAM User Guide.

INSERT INTO aws.iam.roles (
RoleName,
AssumeRolePolicyDocument,
region,
Path,
Description,
MaxSessionDuration,
PermissionsBoundary,
Tags
)
SELECT 
'{{ RoleName }}',
'{{ AssumeRolePolicyDocument }}',
'{{ region }}',
'{{ Path }}',
'{{ Description }}',
'{{ MaxSessionDuration }}',
'{{ PermissionsBoundary }}',
'{{ Tags }}'
RETURNING
arn,
assume_role_policy_document,
create_date,
description,
max_session_duration,
path,
permissions_boundary,
role_id,
role_last_used,
role_name,
source_role_template,
tags
;

UPDATE examples​

Updates the description or maximum session duration setting of a role.

UPDATE aws.iam.roles
SET 
-- No updatable properties
WHERE 
RoleName = '{{ RoleName }}' --required
AND region = '{{ region }}' --required
AND Description = '{{ Description}}'
AND MaxSessionDuration = '{{ MaxSessionDuration}}';

REPLACE examples​

Adds or updates the policy that is specified as the IAM role's permissions boundary. You can use an Amazon Web Services managed policy or a customer managed policy to set the boundary for a role. Use the boundary to control the maximum permissions that the role can have. Setting a permissions boundary is an advanced feature that can affect the permissions for the role. You cannot set the boundary for a service-linked role. Policies used as permissions boundaries do not provide permissions. You must also attach a permissions policy to the role. To learn how the effective permissions for a role are evaluated, see IAM JSON policy evaluation logic in the IAM User Guide.

REPLACE aws.iam.roles
SET 
-- No updatable properties
WHERE 
RoleName = '{{ RoleName }}' --required
AND PermissionsBoundary = '{{ PermissionsBoundary }}' --required
AND region = '{{ region }}' --required;

DELETE examples​

Deletes the specified role. Unlike the Amazon Web Services Management Console, when you delete a role programmatically, you must delete the items attached to the role manually, or the deletion fails. For more information, see Deleting an IAM role. Before attempting to delete a role, remove the following attached items: Inline policies (DeleteRolePolicy) Attached managed policies (DetachRolePolicy) Instance profile (RemoveRoleFromInstanceProfile) Optional – Delete instance profile after detaching from role for resource clean up (DeleteInstanceProfile) Make sure that you do not have any Amazon EC2 instances running with the role you are about to delete. Deleting a role or instance profile that is associated with a running instance will break any applications running on the instance.

DELETE FROM aws.iam.roles
WHERE RoleName = '{{ RoleName }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods​

Deletes the permissions boundary for the specified IAM role. You cannot set the boundary for a service-linked role. Deleting the permissions boundary for a role might increase its permissions. For example, it might allow anyone who assumes the role to perform all the actions granted in its permissions policies.

EXEC aws.iam.roles.delete_role_permissions_boundary 
@RoleName='{{ RoleName }}' --required, 
@region='{{ region }}' --required
;
Last updated on