class Aws::IAM::Policy

Public Class Methods

new(*args) click to toggle source

@overload def initialize(arn, options = {})

@param [String] arn
@option options [Client] :client

@overload def initialize(options = {})

@option options [required, String] :arn
@option options [Client] :client
# File lib/aws-sdk-iam/policy.rb, line 22
def initialize(*args)
  options = Hash === args.last ? args.pop.dup : {}
  @arn = extract_arn(args, options)
  @data = options.delete(:data)
  @client = options.delete(:client) || Client.new(options)
  @waiter_block_warned = false
end

Public Instance Methods

arn() click to toggle source

@return [String]

# File lib/aws-sdk-iam/policy.rb, line 33
def arn
  @arn
end
attach_group(options = {}) click to toggle source

@example Request syntax with placeholder values

policy.attach_group({
  group_name: "groupNameType", # required
})

@param [Hash] options ({}) @option options [required, String] :group_name

The name (friendly name, not ARN) of the group to attach the policy
to.

This parameter allows (through its [regex pattern][1]) a string of
characters consisting of upper and lowercase alphanumeric characters
with no spaces. You can also include any of the following characters:
\_+=,.@-

[1]: http://wikipedia.org/wiki/regex

@return [EmptyStructure]

# File lib/aws-sdk-iam/policy.rb, line 305
def attach_group(options = {})
  options = options.merge(policy_arn: @arn)
  resp = @client.attach_group_policy(options)
  resp.data
end
attach_role(options = {}) click to toggle source

@example Request syntax with placeholder values

policy.attach_role({
  role_name: "roleNameType", # required
})

@param [Hash] options ({}) @option options [required, String] :role_name

The name (friendly name, not ARN) of the role to attach the policy to.

This parameter allows (through its [regex pattern][1]) a string of
characters consisting of upper and lowercase alphanumeric characters
with no spaces. You can also include any of the following characters:
\_+=,.@-

[1]: http://wikipedia.org/wiki/regex

@return [EmptyStructure]

# File lib/aws-sdk-iam/policy.rb, line 329
def attach_role(options = {})
  options = options.merge(policy_arn: @arn)
  resp = @client.attach_role_policy(options)
  resp.data
end
attach_user(options = {}) click to toggle source

@example Request syntax with placeholder values

policy.attach_user({
  user_name: "userNameType", # required
})

@param [Hash] options ({}) @option options [required, String] :user_name

The name (friendly name, not ARN) of the IAM user to attach the policy
to.

This parameter allows (through its [regex pattern][1]) a string of
characters consisting of upper and lowercase alphanumeric characters
with no spaces. You can also include any of the following characters:
\_+=,.@-

[1]: http://wikipedia.org/wiki/regex

@return [EmptyStructure]

# File lib/aws-sdk-iam/policy.rb, line 354
def attach_user(options = {})
  options = options.merge(policy_arn: @arn)
  resp = @client.attach_user_policy(options)
  resp.data
end
attached_groups(options = {}) click to toggle source

@example Request syntax with placeholder values

attached_groups = policy.attached_groups({
  path_prefix: "pathType",
  policy_usage_filter: "PermissionsPolicy", # accepts PermissionsPolicy, PermissionsBoundary
})

@param [Hash] options ({}) @option options [String] :path_prefix

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

This parameter allows (through its [regex pattern][1]) 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.

[1]: http://wikipedia.org/wiki/regex

@option options [String] :policy_usage_filter

The policy usage method to use for filtering the results.

To list only permissions policies,
set `PolicyUsageFilter` to `PermissionsPolicy`. To list only the
policies used to set permissions boundaries, set the value
to `PermissionsBoundary`.

This parameter is optional. If it is not included, all policies are
returned.

@return [Group::Collection]

# File lib/aws-sdk-iam/policy.rb, line 543
def attached_groups(options = {})
  batches = Enumerator.new do |y|
    options = options.merge(
      policy_arn: @arn,
      entity_filter: "Group"
    )
    resp = @client.list_entities_for_policy(options)
    resp.each_page do |page|
      batch = []
      page.data.policy_groups.each do |p|
        batch << Group.new(
          name: p.group_name,
          data: p,
          client: @client
        )
      end
      y.yield(batch)
    end
  end
  Group::Collection.new(batches)
end
attached_roles(options = {}) click to toggle source

@example Request syntax with placeholder values

attached_roles = policy.attached_roles({
  path_prefix: "pathType",
  policy_usage_filter: "PermissionsPolicy", # accepts PermissionsPolicy, PermissionsBoundary
})

@param [Hash] options ({}) @option options [String] :path_prefix

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

This parameter allows (through its [regex pattern][1]) 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.

[1]: http://wikipedia.org/wiki/regex

@option options [String] :policy_usage_filter

The policy usage method to use for filtering the results.

To list only permissions policies,
set `PolicyUsageFilter` to `PermissionsPolicy`. To list only the
policies used to set permissions boundaries, set the value
to `PermissionsBoundary`.

This parameter is optional. If it is not included, all policies are
returned.

@return [Role::Collection]

# File lib/aws-sdk-iam/policy.rb, line 598
def attached_roles(options = {})
  batches = Enumerator.new do |y|
    options = options.merge(
      policy_arn: @arn,
      entity_filter: "Role"
    )
    resp = @client.list_entities_for_policy(options)
    resp.each_page do |page|
      batch = []
      page.data.policy_roles.each do |p|
        batch << Role.new(
          name: p.role_name,
          data: p,
          client: @client
        )
      end
      y.yield(batch)
    end
  end
  Role::Collection.new(batches)
end
attached_users(options = {}) click to toggle source

@example Request syntax with placeholder values

attached_users = policy.attached_users({
  path_prefix: "pathType",
  policy_usage_filter: "PermissionsPolicy", # accepts PermissionsPolicy, PermissionsBoundary
})

@param [Hash] options ({}) @option options [String] :path_prefix

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

This parameter allows (through its [regex pattern][1]) 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.

[1]: http://wikipedia.org/wiki/regex

@option options [String] :policy_usage_filter

The policy usage method to use for filtering the results.

To list only permissions policies,
set `PolicyUsageFilter` to `PermissionsPolicy`. To list only the
policies used to set permissions boundaries, set the value
to `PermissionsBoundary`.

This parameter is optional. If it is not included, all policies are
returned.

@return [User::Collection]

# File lib/aws-sdk-iam/policy.rb, line 653
def attached_users(options = {})
  batches = Enumerator.new do |y|
    options = options.merge(
      policy_arn: @arn,
      entity_filter: "User"
    )
    resp = @client.list_entities_for_policy(options)
    resp.each_page do |page|
      batch = []
      page.data.policy_users.each do |p|
        batch << User.new(
          name: p.user_name,
          data: p,
          client: @client
        )
      end
      y.yield(batch)
    end
  end
  User::Collection.new(batches)
end
attachment_count() click to toggle source

The number of entities (users, groups, and roles) that the policy is attached to. @return [Integer]

# File lib/aws-sdk-iam/policy.rb, line 79
def attachment_count
  data[:attachment_count]
end
client() click to toggle source

@return [Client]

# File lib/aws-sdk-iam/policy.rb, line 155
def client
  @client
end
create_date() click to toggle source

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

[1]: www.iso.org/iso/iso8601 @return [Time]

# File lib/aws-sdk-iam/policy.rb, line 120
def create_date
  data[:create_date]
end
create_version(options = {}) click to toggle source

@example Request syntax with placeholder values

policyversion = policy.create_version({
  policy_document: "policyDocumentType", # required
  set_as_default: false,
})

@param [Hash] options ({}) @option options [required, String] :policy_document

The JSON policy document that you want to use as the content for this
new version of the policy.

You must provide policies in JSON format in IAM. 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 maximum length of the policy document that you can pass in this
operation, including whitespace, is listed below. To view the maximum
character counts of a managed policy with no whitespaces, see [IAM and
STS character quotas][1].

The [regex pattern][2] 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`)

[1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html#reference_iam-quotas-entity-length
[2]: http://wikipedia.org/wiki/regex

@option options [Boolean] :set_as_default

Specifies whether to set this version as the policy's default
version.

When this parameter is `true`, the new policy version becomes the
operative version. That is, it becomes the version that is in effect
for the IAM users, groups, and roles that the policy is attached to.

For more information about managed policy versions, see [Versioning
for managed policies][1] in the *IAM User Guide*.

[1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/policies-managed-versions.html

@return [PolicyVersion]

# File lib/aws-sdk-iam/policy.rb, line 412
def create_version(options = {})
  options = options.merge(policy_arn: @arn)
  resp = @client.create_policy_version(options)
  PolicyVersion.new(
    arn: @arn,
    version_id: resp.data.policy_version.version_id,
    client: @client
  )
end
data() click to toggle source

@return [Types::Policy]

Returns the data for this {Policy}. Calls
{Client#get_policy} if {#data_loaded?} is `false`.
# File lib/aws-sdk-iam/policy.rb, line 175
def data
  load unless @data
  @data
end
data_loaded?() click to toggle source

@return [Boolean]

Returns `true` if this resource is loaded.  Accessing attributes or
{#data} on an unloaded resource will trigger a call to {#load}.
# File lib/aws-sdk-iam/policy.rb, line 183
def data_loaded?
  !!@data
end
default_version() click to toggle source

@return [PolicyVersion, nil]

# File lib/aws-sdk-iam/policy.rb, line 676
def default_version
  if data[:default_version_id]
    PolicyVersion.new(
      arn: @arn,
      version_id: data[:default_version_id],
      client: @client
    )
  else
    nil
  end
end
default_version_id() click to toggle source

The identifier for the version of the policy that is set as the default version. @return [String]

# File lib/aws-sdk-iam/policy.rb, line 72
def default_version_id
  data[:default_version_id]
end
delete(options = {}) click to toggle source

@example Request syntax with placeholder values

policy.delete()

@param [Hash] options ({}) @return [EmptyStructure]

# File lib/aws-sdk-iam/policy.rb, line 427
def delete(options = {})
  options = options.merge(policy_arn: @arn)
  resp = @client.delete_policy(options)
  resp.data
end
description() click to toggle source

A friendly description of the policy.

This element is included in the response to the GetPolicy operation. It is not included in the response to the ListPolicies operation. @return [String]

# File lib/aws-sdk-iam/policy.rb, line 109
def description
  data[:description]
end
detach_group(options = {}) click to toggle source

@example Request syntax with placeholder values

policy.detach_group({
  group_name: "groupNameType", # required
})

@param [Hash] options ({}) @option options [required, String] :group_name

The name (friendly name, not ARN) of the IAM group to detach the
policy from.

This parameter allows (through its [regex pattern][1]) a string of
characters consisting of upper and lowercase alphanumeric characters
with no spaces. You can also include any of the following characters:
\_+=,.@-

[1]: http://wikipedia.org/wiki/regex

@return [EmptyStructure]

# File lib/aws-sdk-iam/policy.rb, line 452
def detach_group(options = {})
  options = options.merge(policy_arn: @arn)
  resp = @client.detach_group_policy(options)
  resp.data
end
detach_role(options = {}) click to toggle source

@example Request syntax with placeholder values

policy.detach_role({
  role_name: "roleNameType", # required
})

@param [Hash] options ({}) @option options [required, String] :role_name

The name (friendly name, not ARN) of the IAM role to detach the policy
from.

This parameter allows (through its [regex pattern][1]) a string of
characters consisting of upper and lowercase alphanumeric characters
with no spaces. You can also include any of the following characters:
\_+=,.@-

[1]: http://wikipedia.org/wiki/regex

@return [EmptyStructure]

# File lib/aws-sdk-iam/policy.rb, line 477
def detach_role(options = {})
  options = options.merge(policy_arn: @arn)
  resp = @client.detach_role_policy(options)
  resp.data
end
detach_user(options = {}) click to toggle source

@example Request syntax with placeholder values

policy.detach_user({
  user_name: "userNameType", # required
})

@param [Hash] options ({}) @option options [required, String] :user_name

The name (friendly name, not ARN) of the IAM user to detach the policy
from.

This parameter allows (through its [regex pattern][1]) a string of
characters consisting of upper and lowercase alphanumeric characters
with no spaces. You can also include any of the following characters:
\_+=,.@-

[1]: http://wikipedia.org/wiki/regex

@return [EmptyStructure]

# File lib/aws-sdk-iam/policy.rb, line 502
def detach_user(options = {})
  options = options.merge(policy_arn: @arn)
  resp = @client.detach_user_policy(options)
  resp.data
end
identifiers() click to toggle source

@deprecated @api private

# File lib/aws-sdk-iam/policy.rb, line 715
def identifiers
  { arn: @arn }
end
is_attachable() click to toggle source

Specifies whether the policy can be attached to an IAM user, group, or role. @return [Boolean]

# File lib/aws-sdk-iam/policy.rb, line 100
def is_attachable
  data[:is_attachable]
end
load() click to toggle source

Loads, or reloads {#data} for the current {Policy}. Returns `self` making it possible to chain methods.

policy.reload.data

@return [self]

# File lib/aws-sdk-iam/policy.rb, line 165
def load
  resp = @client.get_policy(policy_arn: @arn)
  @data = resp.policy
  self
end
Also aliased as: reload
path() click to toggle source

The path to the policy.

For more information about paths, see [IAM identifiers] in the *IAM User Guide*.

[1]: docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html @return [String]

# File lib/aws-sdk-iam/policy.rb, line 65
def path
  data[:path]
end
permissions_boundary_usage_count() click to toggle source

The number of entities (users and roles) for which the policy is used to set the permissions boundary.

For more information about permissions boundaries, see [Permissions boundaries for IAM identities ][1] in the *IAM User Guide*.

[1]: docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html @return [Integer]

# File lib/aws-sdk-iam/policy.rb, line 93
def permissions_boundary_usage_count
  data[:permissions_boundary_usage_count]
end
policy_id() click to toggle source

The stable and unique string identifying the policy.

For more information about IDs, see [IAM identifiers] in the *IAM User Guide*.

[1]: docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html @return [String]

# File lib/aws-sdk-iam/policy.rb, line 52
def policy_id
  data[:policy_id]
end
policy_name() click to toggle source

The friendly name (not ARN) identifying the policy. @return [String]

# File lib/aws-sdk-iam/policy.rb, line 39
def policy_name
  data[:policy_name]
end
reload()
Alias for: load
tags() click to toggle source

A list of tags that are attached to the instance profile. For more information about tagging, see [Tagging IAM resources] in the *IAM User Guide*.

[1]: docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html @return [Array<Types::Tag>]

# File lib/aws-sdk-iam/policy.rb, line 148
def tags
  data[:tags]
end
update_date() click to toggle source

The date and time, in [ISO 8601 date-time format], when the policy was last updated.

When a policy has only one version, this field contains the date and time when the policy was created. When a policy has more than one version, this field contains the date and time when the most recent policy version was created.

[1]: www.iso.org/iso/iso8601 @return [Time]

# File lib/aws-sdk-iam/policy.rb, line 136
def update_date
  data[:update_date]
end
versions(options = {}) click to toggle source

@example Request syntax with placeholder values

policy.versions()

@param [Hash] options ({}) @return [PolicyVersion::Collection]

# File lib/aws-sdk-iam/policy.rb, line 693
def versions(options = {})
  batches = Enumerator.new do |y|
    options = options.merge(policy_arn: @arn)
    resp = @client.list_policy_versions(options)
    resp.each_page do |page|
      batch = []
      page.data.versions.each do |v|
        batch << PolicyVersion.new(
          arn: @arn,
          version_id: v.version_id,
          data: v,
          client: @client
        )
      end
      y.yield(batch)
    end
  end
  PolicyVersion::Collection.new(batches)
end
wait_until(options = {}, &block) click to toggle source

@deprecated Use [Aws::IAM::Client] wait_until instead

Waiter polls an API operation until a resource enters a desired state.

@note The waiting operation is performed on a copy. The original resource

remains unchanged.

## Basic Usage

Waiter will polls until it is successful, it fails by entering a terminal state, or until a maximum number of attempts are made.

# polls in a loop until condition is true
resource.wait_until(options) {|resource| condition}

## Example

instance.wait_until(max_attempts:10, delay:5) do |instance|
  instance.state.name == 'running'
end

## Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. The waiting condition is set by passing a block to {#wait_until}:

# poll for ~25 seconds
resource.wait_until(max_attempts:5,delay:5) {|resource|...}

## Callbacks

You can be notified before each polling attempt and before each delay. If you throw `:success` or `:failure` from these callbacks, it will terminate the waiter.

started_at = Time.now
# poll for 1 hour, instead of a number of attempts
proc = Proc.new do |attempts, response|
  throw :failure if Time.now - started_at > 3600
end

  # disable max attempts
instance.wait_until(before_wait:proc, max_attempts:nil) {...}

## Handling Errors

When a waiter is successful, it returns the Resource. When a waiter fails, it raises an error.

begin
  resource.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

@yieldparam [Resource] resource to be used in the waiting condition.

@raise [Aws::Waiters::Errors::FailureStateError] Raised when the waiter

terminates because the waiter has entered a state that it will not
transition out of, preventing success.

yet successful.

@raise [Aws::Waiters::Errors::UnexpectedError] Raised when an error is

encountered while polling for a resource that is not expected.

@raise [NotImplementedError] Raised when the resource does not

@option options [Integer] :max_attempts (10) Maximum number of attempts @option options [Integer] :delay (10) Delay between each attempt in seconds @option options [Proc] :before_attempt (nil) Callback invoked before each attempt @option options [Proc] :before_wait (nil) Callback invoked before each wait @return [Resource] if the waiter was successful

# File lib/aws-sdk-iam/policy.rb, line 267
def wait_until(options = {}, &block)
  self_copy = self.dup
  attempts = 0
  options[:max_attempts] = 10 unless options.key?(:max_attempts)
  options[:delay] ||= 10
  options[:poller] = Proc.new do
    attempts += 1
    if block.call(self_copy)
      [:success, self_copy]
    else
      self_copy.reload unless attempts == options[:max_attempts]
      :retry
    end
  end
  Aws::Waiters::Waiter.new(options).wait({})
end

Private Instance Methods

extract_arn(args, options) click to toggle source
# File lib/aws-sdk-iam/policy.rb, line 722
def extract_arn(args, options)
  value = args[0] || options.delete(:arn)
  case value
  when String then value
  when nil then raise ArgumentError, "missing required option :arn"
  else
    msg = "expected :arn to be a String, got #{value.class}"
    raise ArgumentError, msg
  end
end