ansible/test/support/integration/plugins/modules/iam_role.py
Felix Fontein a862ff2d43
Deprecation revisited (#69926)
* Allow to specify collection_name separately for deprecation.

* Use new functionality in Ansible.

* Use new functionality in tests.

* Update tagging/untagging functions.

* Update pylint deprecated sanity test.

* Update validate-modules. Missing are basic checks for version_added (validate semantic version format for collections).

* Improve version validation. Re-add version_added validation.

* Make sure collection names are added to return docs before schema validation.

* Extra checks to avoid crashes on bad data.

* Make C# module utils code work, and update/extend tests.

* Add changelog fragment.

* Stop extracting collection name from potentially tagged versions/dates.

* Simplify C# code.

* Update Windows modules docs.

* Forgot semicolons.
2020-06-09 15:21:19 -07:00

674 lines
26 KiB
Python

#!/usr/bin/python
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = '''
---
module: iam_role
short_description: Manage AWS IAM roles
description:
- Manage AWS IAM roles.
version_added: "2.3"
author: "Rob White (@wimnat)"
options:
path:
description:
- The path to the role. For more information about paths, see U(https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html).
default: "/"
type: str
name:
description:
- The name of the role to create.
required: true
type: str
description:
description:
- Provides a description of the role.
version_added: "2.5"
type: str
boundary:
description:
- The ARN of an IAM managed policy to use to restrict the permissions this role can pass on to IAM roles/users that it creates.
- Boundaries cannot be set on Instance Profiles, as such if this option is specified then I(create_instance_profile) must be C(false).
- This is intended for roles/users that have permissions to create new IAM objects.
- For more information on boundaries, see U(https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html).
- Requires botocore 1.10.57 or above.
aliases: [boundary_policy_arn]
version_added: "2.7"
type: str
assume_role_policy_document:
description:
- The trust relationship policy document that grants an entity permission to assume the role.
- This parameter is required when I(state=present).
type: json
managed_policies:
description:
- A list of managed policy ARNs or, since Ansible 2.4, a list of either managed policy ARNs or friendly names.
- To remove all policies set I(purge_polices=true) and I(managed_policies=[None]).
- To embed an inline policy, use M(iam_policy).
aliases: ['managed_policy']
type: list
max_session_duration:
description:
- The maximum duration (in seconds) of a session when assuming the role.
- Valid values are between 1 and 12 hours (3600 and 43200 seconds).
version_added: "2.10"
type: int
purge_policies:
description:
- When I(purge_policies=true) any managed policies not listed in I(managed_policies) will be detatched.
- By default I(purge_policies=true). In Ansible 2.14 this will be changed to I(purge_policies=false).
version_added: "2.5"
type: bool
aliases: ['purge_policy', 'purge_managed_policies']
state:
description:
- Create or remove the IAM role.
default: present
choices: [ present, absent ]
type: str
create_instance_profile:
description:
- Creates an IAM instance profile along with the role.
default: true
version_added: "2.5"
type: bool
delete_instance_profile:
description:
- When I(delete_instance_profile=true) and I(state=absent) deleting a role will also delete the instance
profile created with the same I(name) as the role.
- Only applies when I(state=absent).
default: false
version_added: "2.10"
type: bool
tags:
description:
- Tag dict to apply to the queue.
- Requires botocore 1.12.46 or above.
version_added: "2.10"
type: dict
purge_tags:
description:
- Remove tags not listed in I(tags) when tags is specified.
default: true
version_added: "2.10"
type: bool
requirements: [ botocore, boto3 ]
extends_documentation_fragment:
- aws
- ec2
'''
EXAMPLES = '''
# Note: These examples do not set authentication details, see the AWS Guide for details.
- name: Create a role with description and tags
iam_role:
name: mynewrole
assume_role_policy_document: "{{ lookup('file','policy.json') }}"
description: This is My New Role
tags:
env: dev
- name: "Create a role and attach a managed policy called 'PowerUserAccess'"
iam_role:
name: mynewrole
assume_role_policy_document: "{{ lookup('file','policy.json') }}"
managed_policies:
- arn:aws:iam::aws:policy/PowerUserAccess
- name: Keep the role created above but remove all managed policies
iam_role:
name: mynewrole
assume_role_policy_document: "{{ lookup('file','policy.json') }}"
managed_policies: []
- name: Delete the role
iam_role:
name: mynewrole
assume_role_policy_document: "{{ lookup('file', 'policy.json') }}"
state: absent
'''
RETURN = '''
iam_role:
description: dictionary containing the IAM Role data
returned: success
type: complex
contains:
path:
description: the path to the role
type: str
returned: always
sample: /
role_name:
description: the friendly name that identifies the role
type: str
returned: always
sample: myrole
role_id:
description: the stable and unique string identifying the role
type: str
returned: always
sample: ABCDEFF4EZ4ABCDEFV4ZC
arn:
description: the Amazon Resource Name (ARN) specifying the role
type: str
returned: always
sample: "arn:aws:iam::1234567890:role/mynewrole"
create_date:
description: the date and time, in ISO 8601 date-time format, when the role was created
type: str
returned: always
sample: "2016-08-14T04:36:28+00:00"
assume_role_policy_document:
description: the policy that grants an entity permission to assume the role
type: str
returned: always
sample: {
'statement': [
{
'action': 'sts:AssumeRole',
'effect': 'Allow',
'principal': {
'service': 'ec2.amazonaws.com'
},
'sid': ''
}
],
'version': '2012-10-17'
}
attached_policies:
description: a list of dicts containing the name and ARN of the managed IAM policies attached to the role
type: list
returned: always
sample: [
{
'policy_arn': 'arn:aws:iam::aws:policy/PowerUserAccess',
'policy_name': 'PowerUserAccess'
}
]
tags:
description: role tags
type: dict
returned: always
sample: '{"Env": "Prod"}'
'''
import json
from ansible.module_utils.aws.core import AnsibleAWSModule
from ansible.module_utils.ec2 import camel_dict_to_snake_dict, compare_policies
from ansible.module_utils.ec2 import AWSRetry, ansible_dict_to_boto3_tag_list, boto3_tag_list_to_ansible_dict, compare_aws_tags
try:
from botocore.exceptions import ClientError, BotoCoreError
except ImportError:
pass # caught by AnsibleAWSModule
def compare_assume_role_policy_doc(current_policy_doc, new_policy_doc):
if not compare_policies(current_policy_doc, json.loads(new_policy_doc)):
return True
else:
return False
@AWSRetry.jittered_backoff()
def _list_policies(connection):
paginator = connection.get_paginator('list_policies')
return paginator.paginate().build_full_result()['Policies']
def convert_friendly_names_to_arns(connection, module, policy_names):
if not any([not policy.startswith('arn:') for policy in policy_names]):
return policy_names
allpolicies = {}
policies = _list_policies(connection)
for policy in policies:
allpolicies[policy['PolicyName']] = policy['Arn']
allpolicies[policy['Arn']] = policy['Arn']
try:
return [allpolicies[policy] for policy in policy_names]
except KeyError as e:
module.fail_json_aws(e, msg="Couldn't find policy")
def attach_policies(connection, module, policies_to_attach, params):
changed = False
for policy_arn in policies_to_attach:
try:
if not module.check_mode:
connection.attach_role_policy(RoleName=params['RoleName'], PolicyArn=policy_arn, aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to attach policy {0} to role {1}".format(policy_arn, params['RoleName']))
changed = True
return changed
def remove_policies(connection, module, policies_to_remove, params):
changed = False
for policy in policies_to_remove:
try:
if not module.check_mode:
connection.detach_role_policy(RoleName=params['RoleName'], PolicyArn=policy, aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to detach policy {0} from {1}".format(policy, params['RoleName']))
changed = True
return changed
def generate_create_params(module):
params = dict()
params['Path'] = module.params.get('path')
params['RoleName'] = module.params.get('name')
params['AssumeRolePolicyDocument'] = module.params.get('assume_role_policy_document')
if module.params.get('description') is not None:
params['Description'] = module.params.get('description')
if module.params.get('max_session_duration') is not None:
params['MaxSessionDuration'] = module.params.get('max_session_duration')
if module.params.get('boundary') is not None:
params['PermissionsBoundary'] = module.params.get('boundary')
if module.params.get('tags') is not None:
params['Tags'] = ansible_dict_to_boto3_tag_list(module.params.get('tags'))
return params
def create_basic_role(connection, module, params):
"""
Perform the Role creation.
Assumes tests for the role existing have already been performed.
"""
try:
if not module.check_mode:
role = connection.create_role(aws_retry=True, **params)
# 'Description' is documented as key of the role returned by create_role
# but appears to be an AWS bug (the value is not returned using the AWS CLI either).
# Get the role after creating it.
role = get_role_with_backoff(connection, module, params['RoleName'])
else:
role = {'MadeInCheckMode': True}
role['AssumeRolePolicyDocument'] = json.loads(params['AssumeRolePolicyDocument'])
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to create role")
return role
def update_role_assumed_policy(connection, module, params, role):
# Check Assumed Policy document
if compare_assume_role_policy_doc(role['AssumeRolePolicyDocument'], params['AssumeRolePolicyDocument']):
return False
if module.check_mode:
return True
try:
connection.update_assume_role_policy(
RoleName=params['RoleName'],
PolicyDocument=json.dumps(json.loads(params['AssumeRolePolicyDocument'])),
aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to update assume role policy for role {0}".format(params['RoleName']))
return True
def update_role_description(connection, module, params, role):
# Check Description update
if params.get('Description') is None:
return False
if role.get('Description') == params['Description']:
return False
if module.check_mode:
return True
try:
connection.update_role_description(RoleName=params['RoleName'], Description=params['Description'], aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to update description for role {0}".format(params['RoleName']))
return True
def update_role_max_session_duration(connection, module, params, role):
# Check MaxSessionDuration update
if params.get('MaxSessionDuration') is None:
return False
if role.get('MaxSessionDuration') == params['MaxSessionDuration']:
return False
if module.check_mode:
return True
try:
connection.update_role(RoleName=params['RoleName'], MaxSessionDuration=params['MaxSessionDuration'], aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to update maximum session duration for role {0}".format(params['RoleName']))
return True
def update_role_permissions_boundary(connection, module, params, role):
# Check PermissionsBoundary
if params.get('PermissionsBoundary') is None:
return False
if params.get('PermissionsBoundary') == role.get('PermissionsBoundary', {}).get('PermissionsBoundaryArn', ''):
return False
if module.check_mode:
return True
if params.get('PermissionsBoundary') == '':
try:
connection.delete_role_permissions_boundary(RoleName=params['RoleName'], aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to remove permission boundary for role {0}".format(params['RoleName']))
else:
try:
connection.put_role_permissions_boundary(RoleName=params['RoleName'], PermissionsBoundary=params['PermissionsBoundary'], aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to update permission boundary for role {0}".format(params['RoleName']))
return True
def update_managed_policies(connection, module, params, role, managed_policies, purge_policies):
# Check Managed Policies
if managed_policies is None:
return False
# If we're manipulating a fake role
if role.get('MadeInCheckMode', False):
role['AttachedPolicies'] = list(map(lambda x: {'PolicyArn': x, 'PolicyName': x.split(':')[5]}, managed_policies))
return True
# Get list of current attached managed policies
current_attached_policies = get_attached_policy_list(connection, module, params['RoleName'])
current_attached_policies_arn_list = [policy['PolicyArn'] for policy in current_attached_policies]
if len(managed_policies) == 1 and managed_policies[0] is None:
managed_policies = []
policies_to_remove = set(current_attached_policies_arn_list) - set(managed_policies)
policies_to_attach = set(managed_policies) - set(current_attached_policies_arn_list)
changed = False
if purge_policies:
changed |= remove_policies(connection, module, policies_to_remove, params)
changed |= attach_policies(connection, module, policies_to_attach, params)
return changed
def create_or_update_role(connection, module):
params = generate_create_params(module)
role_name = params['RoleName']
create_instance_profile = module.params.get('create_instance_profile')
purge_policies = module.params.get('purge_policies')
if purge_policies is None:
purge_policies = True
managed_policies = module.params.get('managed_policies')
if managed_policies:
# Attempt to list the policies early so we don't leave things behind if we can't find them.
managed_policies = convert_friendly_names_to_arns(connection, module, managed_policies)
changed = False
# Get role
role = get_role(connection, module, role_name)
# If role is None, create it
if role is None:
role = create_basic_role(connection, module, params)
changed = True
else:
changed |= update_role_tags(connection, module, params, role)
changed |= update_role_assumed_policy(connection, module, params, role)
changed |= update_role_description(connection, module, params, role)
changed |= update_role_max_session_duration(connection, module, params, role)
changed |= update_role_permissions_boundary(connection, module, params, role)
if create_instance_profile:
changed |= create_instance_profiles(connection, module, params, role)
changed |= update_managed_policies(connection, module, params, role, managed_policies, purge_policies)
# Get the role again
if not role.get('MadeInCheckMode', False):
role = get_role(connection, module, params['RoleName'])
role['AttachedPolicies'] = get_attached_policy_list(connection, module, params['RoleName'])
role['tags'] = get_role_tags(connection, module)
module.exit_json(
changed=changed, iam_role=camel_dict_to_snake_dict(role, ignore_list=['tags']),
**camel_dict_to_snake_dict(role, ignore_list=['tags']))
def create_instance_profiles(connection, module, params, role):
if role.get('MadeInCheckMode', False):
return False
# Fetch existing Profiles
try:
instance_profiles = connection.list_instance_profiles_for_role(RoleName=params['RoleName'], aws_retry=True)['InstanceProfiles']
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to list instance profiles for role {0}".format(params['RoleName']))
# Profile already exists
if any(p['InstanceProfileName'] == params['RoleName'] for p in instance_profiles):
return False
if module.check_mode:
return True
# Make sure an instance profile is created
try:
connection.create_instance_profile(InstanceProfileName=params['RoleName'], Path=params['Path'], aws_retry=True)
except ClientError as e:
# If the profile already exists, no problem, move on.
# Implies someone's changing things at the same time...
if e.response['Error']['Code'] == 'EntityAlreadyExists':
return False
else:
module.fail_json_aws(e, msg="Unable to create instance profile for role {0}".format(params['RoleName']))
except BotoCoreError as e:
module.fail_json_aws(e, msg="Unable to create instance profile for role {0}".format(params['RoleName']))
# And attach the role to the profile
try:
connection.add_role_to_instance_profile(InstanceProfileName=params['RoleName'], RoleName=params['RoleName'], aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to attach role {0} to instance profile {0}".format(params['RoleName']))
return True
def remove_instance_profiles(connection, module, role_params, role):
role_name = module.params.get('name')
delete_profiles = module.params.get("delete_instance_profile")
try:
instance_profiles = connection.list_instance_profiles_for_role(aws_retry=True, **role_params)['InstanceProfiles']
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to list instance profiles for role {0}".format(role_name))
# Remove the role from the instance profile(s)
for profile in instance_profiles:
profile_name = profile['InstanceProfileName']
try:
if not module.check_mode:
connection.remove_role_from_instance_profile(aws_retry=True, InstanceProfileName=profile_name, **role_params)
if profile_name == role_name:
if delete_profiles:
try:
connection.delete_instance_profile(InstanceProfileName=profile_name, aws_retry=True)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to remove instance profile {0}".format(profile_name))
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to remove role {0} from instance profile {1}".format(role_name, profile_name))
def destroy_role(connection, module):
role_name = module.params.get('name')
role = get_role(connection, module, role_name)
role_params = dict()
role_params['RoleName'] = role_name
boundary_params = dict(role_params)
boundary_params['PermissionsBoundary'] = ''
if role is None:
module.exit_json(changed=False)
# Before we try to delete the role we need to remove any
# - attached instance profiles
# - attached managed policies
# - permissions boundary
remove_instance_profiles(connection, module, role_params, role)
update_managed_policies(connection, module, role_params, role, [], True)
update_role_permissions_boundary(connection, module, boundary_params, role)
try:
if not module.check_mode:
connection.delete_role(aws_retry=True, **role_params)
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to delete role")
module.exit_json(changed=True)
def get_role_with_backoff(connection, module, name):
try:
return AWSRetry.jittered_backoff(catch_extra_error_codes=['NoSuchEntity'])(connection.get_role)(RoleName=name)['Role']
except (BotoCoreError, ClientError) as e:
module.fail_json_aws(e, msg="Unable to get role {0}".format(name))
def get_role(connection, module, name):
try:
return connection.get_role(RoleName=name, aws_retry=True)['Role']
except ClientError as e:
if e.response['Error']['Code'] == 'NoSuchEntity':
return None
else:
module.fail_json_aws(e, msg="Unable to get role {0}".format(name))
except BotoCoreError as e:
module.fail_json_aws(e, msg="Unable to get role {0}".format(name))
def get_attached_policy_list(connection, module, name):
try:
return connection.list_attached_role_policies(RoleName=name, aws_retry=True)['AttachedPolicies']
except (ClientError, BotoCoreError) as e:
module.fail_json_aws(e, msg="Unable to list attached policies for role {0}".format(name))
def get_role_tags(connection, module):
role_name = module.params.get('name')
if not hasattr(connection, 'list_role_tags'):
return {}
try:
return boto3_tag_list_to_ansible_dict(connection.list_role_tags(RoleName=role_name, aws_retry=True)['Tags'])
except (ClientError, BotoCoreError) as e:
module.fail_json_aws(e, msg="Unable to list tags for role {0}".format(role_name))
def update_role_tags(connection, module, params, role):
new_tags = params.get('Tags')
if new_tags is None:
return False
new_tags = boto3_tag_list_to_ansible_dict(new_tags)
role_name = module.params.get('name')
purge_tags = module.params.get('purge_tags')
try:
existing_tags = boto3_tag_list_to_ansible_dict(connection.list_role_tags(RoleName=role_name, aws_retry=True)['Tags'])
except (ClientError, KeyError):
existing_tags = {}
tags_to_add, tags_to_remove = compare_aws_tags(existing_tags, new_tags, purge_tags=purge_tags)
if not module.check_mode:
try:
if tags_to_remove:
connection.untag_role(RoleName=role_name, TagKeys=tags_to_remove, aws_retry=True)
if tags_to_add:
connection.tag_role(RoleName=role_name, Tags=ansible_dict_to_boto3_tag_list(tags_to_add), aws_retry=True)
except (ClientError, BotoCoreError) as e:
module.fail_json_aws(e, msg='Unable to set tags for role %s' % role_name)
changed = bool(tags_to_add) or bool(tags_to_remove)
return changed
def main():
argument_spec = dict(
name=dict(type='str', required=True),
path=dict(type='str', default="/"),
assume_role_policy_document=dict(type='json'),
managed_policies=dict(type='list', aliases=['managed_policy']),
max_session_duration=dict(type='int'),
state=dict(type='str', choices=['present', 'absent'], default='present'),
description=dict(type='str'),
boundary=dict(type='str', aliases=['boundary_policy_arn']),
create_instance_profile=dict(type='bool', default=True),
delete_instance_profile=dict(type='bool', default=False),
purge_policies=dict(type='bool', aliases=['purge_policy', 'purge_managed_policies']),
tags=dict(type='dict'),
purge_tags=dict(type='bool', default=True),
)
module = AnsibleAWSModule(argument_spec=argument_spec,
required_if=[('state', 'present', ['assume_role_policy_document'])],
supports_check_mode=True)
if module.params.get('purge_policies') is None:
module.deprecate('In Ansible 2.14 the default value of purge_policies will change from true to false.'
' To maintain the existing behaviour explicity set purge_policies=true',
version='2.14', collection_name='ansible.builtin')
if module.params.get('boundary'):
if module.params.get('create_instance_profile'):
module.fail_json(msg="When using a boundary policy, `create_instance_profile` must be set to `false`.")
if not module.params.get('boundary').startswith('arn:aws:iam'):
module.fail_json(msg="Boundary policy must be an ARN")
if module.params.get('tags') is not None and not module.botocore_at_least('1.12.46'):
module.fail_json(msg="When managing tags botocore must be at least v1.12.46. "
"Current versions: boto3-{boto3_version} botocore-{botocore_version}".format(**module._gather_versions()))
if module.params.get('boundary') is not None and not module.botocore_at_least('1.10.57'):
module.fail_json(msg="When using a boundary policy, botocore must be at least v1.10.57. "
"Current versions: boto3-{boto3_version} botocore-{botocore_version}".format(**module._gather_versions()))
if module.params.get('max_session_duration'):
max_session_duration = module.params.get('max_session_duration')
if max_session_duration < 3600 or max_session_duration > 43200:
module.fail_json(msg="max_session_duration must be between 1 and 12 hours (3600 and 43200 seconds)")
if module.params.get('path'):
path = module.params.get('path')
if not path.endswith('/') or not path.startswith('/'):
module.fail_json(msg="path must begin and end with /")
connection = module.client('iam', retry_decorator=AWSRetry.jittered_backoff())
state = module.params.get("state")
if state == 'present':
create_or_update_role(connection, module)
else:
destroy_role(connection, module)
if __name__ == '__main__':
main()