You are viewing documentation for version 2 of the AWS SDK for Ruby. Version 3 documentation can be found here.

Class: Aws::IAM::Role

Inherits:
Resources::Resource show all
Defined in:
(unknown)

Instance Attribute Summary collapse

Attributes inherited from Resources::Resource

#client, #identifiers

Instance Method Summary collapse

Methods inherited from Resources::Resource

add_data_attribute, add_identifier, #data, data_attributes, #data_loaded?, identifiers, #load, #wait_until

Methods included from Resources::OperationMethods

#add_batch_operation, #add_operation, #batch_operation, #batch_operation_names, #batch_operations, #operation, #operation_names, #operations

Constructor Details

#initialize(name, options = {}) ⇒ Object #initialize(options = {}) ⇒ Object

Overloads:

  • #initialize(name, options = {}) ⇒ Object

    Parameters:

    • name (String)

    Options Hash (options):

    • :client (Client) —

      When `:client is not given, the options hash is used to construct a new Client object.

  • #initialize(options = {}) ⇒ Object

    Options Hash (options):

    • :name (required, String)
    • :client (Client) —

      When `:client is not given, the options hash is used to construct a new Client object.

Instance Attribute Details

#arn ⇒ String (readonly)

The 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.

Returns:

  • (String) —

    The Amazon Resource Name (ARN) specifying the role.

#assume_role_policy_document ⇒ String (readonly)

The policy that grants an entity permission to assume the role.

Returns:

  • (String) —

    The policy that grants an entity permission to assume the role.

#create_date ⇒ Time (readonly)

The date and time, in ISO 8601 date-time format, when the role was created.

Returns:

  • (Time) —

    The date and time, in [ISO 8601 date-time format][1], when the role was created.

#description ⇒ String (readonly)

A description of the role that you provide.

Returns:

  • (String) —

    A description of the role that you provide.

#max_session_duration ⇒ Integer (readonly)

The maximum session duration (in seconds) for the specified role. Anyone who uses the AWS CLI, or API to assume the role can specify the duration using the optional DurationSeconds API parameter or duration-seconds CLI parameter.

Returns:

  • (Integer) —

    The maximum session duration (in seconds) for the specified role.

#name ⇒ String (readonly)

Returns:

  • (String)

#path ⇒ String (readonly)

The path to the role. For more information about paths, see IAM Identifiers in the IAM User Guide.

Returns:

  • (String) —

    The path to the role.

#permissions_boundary ⇒ Types::AttachedPermissionsBoundary (readonly)

The 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.

Returns:

#role_id ⇒ String (readonly)

The stable and unique string identifying the role. For more information about IDs, see IAM Identifiers in the IAM User Guide.

Returns:

  • (String) —

    The stable and unique string identifying the role.

#role_last_used ⇒ Types::RoleLastUsed (readonly)

Contains 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.

Returns:

  • (Types::RoleLastUsed) —

    Contains information about the last time that an IAM role was used.

#role_name ⇒ String (readonly)

The friendly name that identifies the role.

Returns:

  • (String) —

    The friendly name that identifies the role.

#tags ⇒ Array<Types::Tag> (readonly)

A list of tags that are attached to the specified role. For more information about tagging, see Tagging IAM Identities in the IAM User Guide.

Returns:

  • (Array<Types::Tag>) —

    A list of tags that are attached to the specified role.

Instance Method Details

#assume_role_policy ⇒ AssumeRolePolicy

Returns:

#attach_policy(options = {}) ⇒ Struct

Attaches the specified managed policy to the specified IAM role. When you attach a managed policy to a role, the managed policy becomes part of the role's permission (access) policy.

You cannot use a managed policy as the role's trust policy. The role's trust policy is created at the same time as the role, using CreateRole. You can update a role's trust policy using UpdateAssumeRolePolicy.

Use this API to attach a managed policy to a role. To embed an inline policy in a role, use PutRolePolicy. For more information about policies, see Managed Policies and Inline Policies in the IAM User Guide.

Examples:

Request syntax example with placeholder values


role.attach_policy({
  policy_arn: "arnType", # required
})

Options Hash (options):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#attached_policies(options = {}) ⇒ Collection<Policy>

Returns a Collection of Policy resources. No API requests are made until you call an enumerable method on the collection. Client#list_attached_role_policies will be called multiple times until every Policy has been yielded.

Examples:

Request syntax example with placeholder values


role.attached_policies({
  path_prefix: "policyPathType",
  marker: "markerType",
  max_items: 1,
})

Enumerating Policy resources.

role.attached_policies.each do |policy|
  # yields each policy
end

Enumerating Policy resources with a limit.

role.attached_policies.limit(10).each do |policy|
  # yields at most 10 attached_policies
end

Options Hash (options):

  • :path_prefix (String) —

    The path prefix for filtering the results. This parameter is optional. If it is not included, it defaults to a slash (/), listing all policies.

    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.

  • :marker (String) —

    Use 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.

  • :max_items (Integer) —

    Use 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.

Returns:

See Also:

#delete ⇒ Struct

Deletes the specified role. The role must not have any policies attached. For more information about roles, go to Working with Roles.

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.

Examples:

Request syntax example with placeholder values


role.delete()

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#detach_policy(options = {}) ⇒ Struct

Removes the specified managed policy from the specified role.

A role can also have inline policies embedded with it. To delete an inline policy, use the DeleteRolePolicy API. For information about policies, see Managed Policies and Inline Policies in the IAM User Guide.

Examples:

Request syntax example with placeholder values


role.detach_policy({
  policy_arn: "arnType", # required
})

Options Hash (options):

Returns:

  • (Struct) —

    Returns an empty response.

See Also:

#instance_profiles(options = {}) ⇒ Collection<InstanceProfile>

Returns a Collection of InstanceProfile resources. No API requests are made until you call an enumerable method on the collection. Client#list_instance_profiles_for_role will be called multiple times until every InstanceProfile has been yielded.

Examples:

Request syntax example with placeholder values


role.instance_profiles({
  marker: "markerType",
  max_items: 1,
})

Enumerating InstanceProfile resources.

role.instance_profiles.each do |instanceprofile|
  # yields each instanceprofile
end

Enumerating InstanceProfile resources with a limit.

role.instance_profiles.limit(10).each do |instanceprofile|
  # yields at most 10 instance_profiles
end

Options Hash (options):

  • :marker (String) —

    Use 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.

  • :max_items (Integer) —

    Use 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.

Returns:

See Also:

#policies(options = {}) ⇒ Collection<RolePolicy>

Returns a Collection of Aws::IAM::RolePolicy resources. No API requests are made until you call an enumerable method on the collection. Client#list_role_policies will be called multiple times until every Aws::IAM::RolePolicy has been yielded.

Examples:

Request syntax example with placeholder values


role.policies({
  marker: "markerType",
  max_items: 1,
})

Enumerating Aws::IAM::RolePolicy resources.

role.policies.each do |rolepolicy|
  # yields each rolepolicy
end

Enumerating Aws::IAM::RolePolicy resources with a limit.

role.policies.limit(10).each do |rolepolicy|
  # yields at most 10 policies
end

Options Hash (options):

  • :marker (String) —

    Use 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.

  • :max_items (Integer) —

    Use 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.

Returns:

See Also:

#policy(name) ⇒ RolePolicy

Parameters:

Returns:

See Also: