Add Amazon Elastic File System Facts (efs_facts) module

Also switch EFS module to using boto3_conn from boto3.Session
pull/18777/head
Ryan Sydnor 8 years ago committed by Matt Clay
parent dfec3d3c4c
commit 3c6ae0063b

@ -29,21 +29,25 @@ options:
state: state:
description: description:
- Allows to create, search and destroy Amazon EFS file system - Allows to create, search and destroy Amazon EFS file system
required: true required: false
default: 'present'
choices: ['present', 'absent'] choices: ['present', 'absent']
aliases: []
name: name:
description: description:
- Creation Token of Amazon EFS file system. Required for create. Either name or ID required for delete. It can be omitted for 'list' (unless you want to find EFS with certain name). - Creation Token of Amazon EFS file system. Required for create. Either name or ID required for delete.
required: false required: false
default: None default: None
aliases: []
id: id:
description: description:
- ID of Amazon EFS. Either name or ID required for delete. - ID of Amazon EFS. Either name or ID required for delete.
required: false required: false
default: None default: None
aliases: [] performance_mode:
description:
- File system's performance mode to use. Only takes effect during creation.
required: false
default: 'general_purpose'
choices: ['general_purpose', 'max_io']
tags: tags:
description: description:
- | - |
@ -51,18 +55,16 @@ options:
In case of 'present' state with list of tags and existing EFS (matched by 'name'), tags of EFS will be replaced with provided data. In case of 'present' state with list of tags and existing EFS (matched by 'name'), tags of EFS will be replaced with provided data.
required: false required: false
default: None default: None
aliases: []
targets: targets:
description: description:
- | - |
List of mounted targets. It should be a list of dictionaries, every dictionary should include next attributes: List of mounted targets. It should be a list of dictionaries, every dictionary should include next attributes:
- SubnetId - Mandatory. The ID of the subnet to add the mount target in. - subnet_id - Mandatory. The ID of the subnet to add the mount target in.
- IpAddress - Optional. A valid IPv4 address within the address range of the specified subnet. - ip_address - Optional. A valid IPv4 address within the address range of the specified subnet.
- SecurityGroups - Optional. List of security group IDs, of the form "sg-xxxxxxxx". These must be for the same VPC as subnet specified - security_groups - Optional. List of security group IDs, of the form "sg-xxxxxxxx". These must be for the same VPC as subnet specified
This data may be modified for existing EFS using state 'present' and new list of mount targets. This data may be modified for existing EFS using state 'present' and new list of mount targets.
required: false required: false
default: None default: None
aliases: []
wait: wait:
description: description:
- | - |
@ -71,13 +73,11 @@ options:
required: false required: false
default: "no" default: "no"
choices: ["yes", "no"] choices: ["yes", "no"]
aliases: []
wait_timeout: wait_timeout:
description: description:
- How long the module should wait (in seconds) for desired state before returning. Zero means wait as long as necessary. - How long the module should wait (in seconds) for desired state before returning. Zero means wait as long as necessary.
required: false required: false
default: 0 default: 0
aliases: []
extends_documentation_fragment: extends_documentation_fragment:
- aws - aws
''' '''
@ -88,116 +88,111 @@ EXAMPLES = '''
state: present state: present
name: myTestEFS name: myTestEFS
tags: tags:
Name: myTestNameTag name: myTestNameTag
Purpose: file-storage purpose: file-storage
targets: targets:
- SubnetId: subnet-748c5d03 - subnet_id: subnet-748c5d03
SecurityGroups: [ "sg-1a2b3c4d" ] security_groups: [ "sg-1a2b3c4d" ]
# Modifying EFS data # Modifying EFS data
- efs: - efs:
state: present state: present
name: myTestEFS name: myTestEFS
tags: tags:
Name: myAnotherTestTag name: myAnotherTestTag
targets: targets:
- SubnetId: subnet-7654fdca - subnet_id: subnet-7654fdca
SecurityGroups: [ "sg-4c5d6f7a" ] security_groups: [ "sg-4c5d6f7a" ]
# Deleting EFS # Deleting EFS
- efs: - efs:
state: absent state: absent
name: myTestEFS name: myTestEFS
# Searching all EFS instances with tag Name = 'myTestNameTag', in subnet 'subnet-1a2b3c4d' and with security group 'sg-4d3c2b1a'
- efs:
state: list
tags:
Name: myTestNameTag
targets:
- subnet-1a2b3c4d
- sg-4d3c2b1a
''' '''
RETURN = ''' RETURN = '''
CreationTime: creation_time:
description: timestamp of creation date description: timestamp of creation date
returned: returned:
type: datetime type: datetime
sample: 2015-11-16 07:30:57-05:00 sample: 2015-11-16 07:30:57-05:00
CreationToken: creation_token:
description: EFS creation token description: EFS creation token
returned: returned:
type: UUID type: UUID
sample: console-88609e04-9a0e-4a2e-912c-feaa99509961 sample: console-88609e04-9a0e-4a2e-912c-feaa99509961
FileSystemId: file_system_id:
description: ID of the file system description: ID of the file system
returned: returned:
type: unique ID type: unique ID
sample: fs-xxxxxxxx sample: fs-xxxxxxxx
LifeCycleState: life_cycle_state:
description: state of the EFS file system description: state of the EFS file system
returned: returned:
type: str type: str
sample: creating, available, deleting, deleted sample: creating, available, deleting, deleted
MountPoint: mount_point:
description: url of file system description: url of file system
returned: returned:
type: str type: str
sample: .fs-xxxxxxxx.efs.us-west-2.amazonaws.com:/ sample: .fs-xxxxxxxx.efs.us-west-2.amazonaws.com:/
MountTargets: mount_targets:
description: list of mount targets description: list of mount targets
returned: returned:
type: list of dicts type: list of dicts
sample: sample:
[ [
{ {
"FileSystemId": "fs-a7ad440e", "file_system_id": "fs-a7ad440e",
"IpAddress": "172.31.17.173", "ip_address": "172.31.17.173",
"LifeCycleState": "available", "life_cycle_state": "available",
"MountTargetId": "fsmt-d8907871", "mount_target_id": "fsmt-d8907871",
"NetworkInterfaceId": "eni-6e387e26", "network_interface_id": "eni-6e387e26",
"OwnerId": "740748460359", "owner_id": "740748460359",
"SecurityGroups": [ "security_groups": [
"sg-a30b22c6" "sg-a30b22c6"
], ],
"SubnetId": "subnet-e265c895" "subnet_id": "subnet-e265c895"
}, },
... ...
] ]
Name: name:
description: name of the file system description: name of the file system
returned: returned:
type: str type: str
sample: my-efs sample: my-efs
NumberOfMountTargets: number_of_mount_targets:
description: the number of targets mounted description: the number of targets mounted
returned: returned:
type: int type: int
sample: 3 sample: 3
OwnerId: owner_id:
description: AWS account ID of EFS owner description: AWS account ID of EFS owner
returned: returned:
type: str type: str
sample: XXXXXXXXXXXX sample: XXXXXXXXXXXX
SizeInBytes: size_in_bytes:
description: size of the file system in bytes as of a timestamp description: size of the file system in bytes as of a timestamp
returned: returned:
type: dict type: dict
sample: sample:
{ {
"Timestamp": "2015-12-21 13:59:59-05:00", "timestamp": "2015-12-21 13:59:59-05:00",
"Value": 12288 "value": 12288
} }
Tags: performance_mode:
description: performance mode of the file system
returned:
type: str
sample: "generalPurpose"
tags:
description: tags on the efs instance description: tags on the efs instance
returned: returned:
type: dict type: dict
sample: sample:
{ {
"Name": "my-efs", "name": "my-efs",
"Key": "Value" "key": "Value"
} }
''' '''
@ -209,7 +204,7 @@ from collections import defaultdict
try: try:
from botocore.exceptions import ClientError from botocore.exceptions import ClientError
from boto3.session import Session import boto3
HAS_BOTO3 = True HAS_BOTO3 = True
except ImportError as e: except ImportError as e:
HAS_BOTO3 = False HAS_BOTO3 = False
@ -226,15 +221,11 @@ class EFSConnection(object):
def __init__(self, module, region, **aws_connect_params): def __init__(self, module, region, **aws_connect_params):
try: try:
session = Session( self.connection = boto3_conn(module, conn_type='client',
aws_access_key_id=aws_connect_params['aws_access_key_id'], resource='efs', region=region,
aws_secret_access_key=aws_connect_params['aws_secret_access_key'], **aws_connect_params)
aws_session_token=aws_connect_params['aws_session_token'],
region_name=region
)
self.connection = session.client('efs')
except Exception as e: except Exception as e:
module.fail_json(msg=repr(e)) module.fail_json(msg="Failed to connect to AWS: %s" % str(e))
self.region = region self.region = region
self.wait = module.params.get('wait') self.wait = module.params.get('wait')
@ -345,7 +336,7 @@ class EFSConnection(object):
return list(targets) return list(targets)
def create_file_system(self, name): def create_file_system(self, name, performance_mode):
""" """
Creates new filesystem with selected name Creates new filesystem with selected name
""" """
@ -356,7 +347,7 @@ class EFSConnection(object):
lambda: self.get_file_system_state(name), lambda: self.get_file_system_state(name),
self.STATE_DELETED self.STATE_DELETED
) )
self.connection.create_file_system(CreationToken=name) self.connection.create_file_system(CreationToken=name, PerformanceMode=performance_mode)
changed = True changed = True
# we always wait for the state to be available when creating. # we always wait for the state to be available when creating.
@ -507,7 +498,7 @@ def iterate_all(attr, map_method, **kwargs):
""" """
Method creates iterator from boto result set Method creates iterator from boto result set
""" """
args = dict((key, value) for (key, value) in kwargs.iteritems() if value is not None) args = dict((key, value) for (key, value) in kwargs.items() if value is not None)
wait = 1 wait = 1
while True: while True:
try: try:
@ -539,44 +530,14 @@ def dict_diff(dict1, dict2, by_key=False):
""" """
Helper method to calculate difference of two dictionaries Helper method to calculate difference of two dictionaries
""" """
keys1 = set(dict1.keys() if by_key else dict1.iteritems()) keys1 = set(dict1.keys() if by_key else dict1.items())
keys2 = set(dict2.keys() if by_key else dict2.iteritems()) keys2 = set(dict2.keys() if by_key else dict2.items())
intersection = keys1 & keys2 intersection = keys1 & keys2
return keys2 ^ intersection, intersection, keys1 ^ intersection return keys2 ^ intersection, intersection, keys1 ^ intersection
def group_list_of_dict(array):
"""
Helper method to group list of dict to dict with all possible values
"""
result = defaultdict(list)
for item in array:
for key, value in item.iteritems():
result[key] += value if isinstance(value, list) else [value]
return result
def prefix_to_attr(attr_id):
"""
Helper method to convert ID prefix to mount target attribute
"""
attr_by_prefix = {
'fsmt-': 'MountTargetId',
'subnet-': 'SubnetId',
'eni-': 'NetworkInterfaceId',
'sg-': 'SecurityGroups'
}
prefix = first_or_default(filter(
lambda pref: str(attr_id).startswith(pref),
attr_by_prefix.keys()
))
if prefix:
return attr_by_prefix[prefix]
return 'IpAddress'
def first_or_default(items, default=None): def first_or_default(items, default=None):
""" """
Helper method to fetch first element of list (if exists) Helper method to fetch first element of list (if exists)
@ -586,27 +547,6 @@ def first_or_default(items, default=None):
return default return default
def has_tags(available, required):
"""
Helper method to determine if tag requested already exists
"""
for key, value in required.iteritems():
if key not in available or value != available[key]:
return False
return True
def has_targets(available, required):
"""
Helper method to determine if mount tager requested already exists
"""
grouped = group_list_of_dict(available)
for (value, field) in required:
if field not in grouped or value not in grouped[field]:
return False
return True
def wait_for(callback, value, timeout=EFSConnection.DEFAULT_WAIT_TIMEOUT_SECONDS): def wait_for(callback, value, timeout=EFSConnection.DEFAULT_WAIT_TIMEOUT_SECONDS):
""" """
Helper method to wait for desired value returned by callback method Helper method to wait for desired value returned by callback method
@ -628,11 +568,12 @@ def main():
""" """
argument_spec = ec2_argument_spec() argument_spec = ec2_argument_spec()
argument_spec.update(dict( argument_spec.update(dict(
state=dict(required=True, type='str', choices=["present", "absent"]), state=dict(required=False, type='str', choices=["present", "absent"], default="present"),
id=dict(required=False, type='str', default=None), id=dict(required=False, type='str', default=None),
name=dict(required=False, type='str', default=None), name=dict(required=False, type='str', default=None),
tags=dict(required=False, type="dict", default={}), tags=dict(required=False, type="dict", default={}),
targets=dict(required=False, type="list", default=[]), targets=dict(required=False, type="list", default=[]),
performance_mode=dict(required=False, type='str', choices=["general_purpose", "max_io"], default="general_purpose"),
wait=dict(required=False, type="bool", default=False), wait=dict(required=False, type="bool", default=False),
wait_timeout=dict(required=False, type="int", default=0) wait_timeout=dict(required=False, type="int", default=0)
)) ))
@ -648,7 +589,17 @@ def main():
name = module.params.get('name') name = module.params.get('name')
fs_id = module.params.get('id') fs_id = module.params.get('id')
tags = module.params.get('tags') tags = module.params.get('tags')
targets = module.params.get('targets') target_translations = {
'ip_address': 'IpAddress',
'security_groups': 'SecurityGroups',
'subnet_id': 'SubnetId'
}
targets = [dict((target_translations[key], value) for (key, value) in x.items()) for x in module.params.get('targets')]
performance_mode_translations = {
'general_purpose': 'generalPurpose',
'max_io': 'maxIO'
}
performance_mode = performance_mode_translations[module.params.get('performance_mode')]
changed = False changed = False
state = str(module.params.get('state')).lower() state = str(module.params.get('state')).lower()
@ -657,7 +608,7 @@ def main():
if not name: if not name:
module.fail_json(msg='Name parameter is required for create') module.fail_json(msg='Name parameter is required for create')
changed = connection.create_file_system(name) changed = connection.create_file_system(name, performance_mode)
changed = connection.converge_file_system(name=name, tags=tags, targets=targets) or changed changed = connection.converge_file_system(name=name, tags=tags, targets=targets) or changed
result = first_or_default(connection.get_file_systems(CreationToken=name)) result = first_or_default(connection.get_file_systems(CreationToken=name))
@ -667,7 +618,8 @@ def main():
changed = connection.delete_file_system(name, fs_id) changed = connection.delete_file_system(name, fs_id)
result = None result = None
if result:
result = camel_dict_to_snake_dict(result)
module.exit_json(changed=changed, efs=result) module.exit_json(changed=changed, efs=result)
from ansible.module_utils.basic import * from ansible.module_utils.basic import *

@ -0,0 +1,377 @@
#!/usr/bin/python
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
DOCUMENTATION = '''
---
module: efs_facts
short_description: Get information about Amazon EFS file systems
description:
- Module searches Amazon EFS file systems
version_added: "2.2"
requirements: [ boto3 ]
author:
- "Ryan Sydnor (@ryansydnor)"
options:
name:
description:
- Creation Token of Amazon EFS file system.
required: false
default: None
id:
description:
- ID of Amazon EFS.
required: false
default: None
tags:
description:
- |
List of tags of Amazon EFS. Should be defined as dictionary
required: false
default: None
targets:
description:
- |
List of mounted targets. It should be a list of dictionaries, every dictionary should include next attributes:
- SubnetId - Mandatory. The ID of the subnet to add the mount target in.
- IpAddress - Optional. A valid IPv4 address within the address range of the specified subnet.
- SecurityGroups - Optional. List of security group IDs, of the form "sg-xxxxxxxx". These must be for the same VPC as subnet specified.
required: false
default: None
extends_documentation_fragment:
- aws
'''
EXAMPLES = '''
# find all existing efs
- efs_facts:
register: result
- efs_facts:
name: myTestNameTag
- efs_facts:
id: fs-1234abcd
# Searching all EFS instances with tag Name = 'myTestNameTag', in subnet 'subnet-1a2b3c4d' and with security group 'sg-4d3c2b1a'
- efs_facts:
tags:
name: myTestNameTag
targets:
- subnet-1a2b3c4d
- sg-4d3c2b1a
'''
RETURN = '''
creation_time:
description: timestamp of creation date
returned:
type: datetime
sample: 2015-11-16 07:30:57-05:00
creation_token:
description: EFS creation token
returned:
type: UUID
sample: console-88609e04-9a0e-4a2e-912c-feaa99509961
file_system_id:
description: ID of the file system
returned:
type: unique ID
sample: fs-xxxxxxxx
life_cycle_state:
description: state of the EFS file system
returned:
type: str
sample: creating, available, deleting, deleted
mount_point:
description: url of file system
returned:
type: str
sample: .fs-xxxxxxxx.efs.us-west-2.amazonaws.com:/
mount_targets:
description: list of mount targets
returned:
type: list of dicts
sample:
[
{
"file_system_id": "fs-a7ad440e",
"ip_address": "172.31.17.173",
"life_cycle_state": "available",
"mount_target_id": "fsmt-d8907871",
"network_interface_id": "eni-6e387e26",
"owner_id": "740748460359",
"security_groups": [
"sg-a30b22c6"
],
"subnet_id": "subnet-e265c895"
},
...
]
name:
description: name of the file system
returned:
type: str
sample: my-efs
number_of_mount_targets:
description: the number of targets mounted
returned:
type: int
sample: 3
owner_id:
description: AWS account ID of EFS owner
returned:
type: str
sample: XXXXXXXXXXXX
size_in_bytes:
description: size of the file system in bytes as of a timestamp
returned:
type: dict
sample:
{
"timestamp": "2015-12-21 13:59:59-05:00",
"value": 12288
}
performance_mode:
description: performance mode of the file system
returned:
type: str
sample: "generalPurpose"
tags:
description: tags on the efs instance
returned:
type: dict
sample:
{
"name": "my-efs",
"key": "Value"
}
'''
from time import sleep
from collections import defaultdict
try:
from botocore.exceptions import ClientError
import boto3
HAS_BOTO3 = True
except ImportError as e:
HAS_BOTO3 = False
class EFSConnection(object):
STATE_CREATING = 'creating'
STATE_AVAILABLE = 'available'
STATE_DELETING = 'deleting'
STATE_DELETED = 'deleted'
def __init__(self, module, region, **aws_connect_params):
try:
self.connection = boto3_conn(module, conn_type='client',
resource='efs', region=region,
**aws_connect_params)
except Exception as e:
module.fail_json(msg="Failed to connect to AWS: %s" % str(e))
self.region = region
def get_file_systems(self, **kwargs):
"""
Returns generator of file systems including all attributes of FS
"""
items = iterate_all(
'FileSystems',
self.connection.describe_file_systems,
**kwargs
)
for item in items:
item['CreationTime'] = str(item['CreationTime'])
"""
Suffix of network path to be used as NFS device for mount. More detail here:
http://docs.aws.amazon.com/efs/latest/ug/gs-step-three-connect-to-ec2-instance.html
"""
item['MountPoint'] = '.%s.efs.%s.amazonaws.com:/' % (item['FileSystemId'], self.region)
if 'Timestamp' in item['SizeInBytes']:
item['SizeInBytes']['Timestamp'] = str(item['SizeInBytes']['Timestamp'])
if item['LifeCycleState'] == self.STATE_AVAILABLE:
item['Tags'] = self.get_tags(FileSystemId=item['FileSystemId'])
item['MountTargets'] = list(self.get_mount_targets(FileSystemId=item['FileSystemId']))
else:
item['Tags'] = {}
item['MountTargets'] = []
yield item
def get_tags(self, **kwargs):
"""
Returns tag list for selected instance of EFS
"""
tags = iterate_all(
'Tags',
self.connection.describe_tags,
**kwargs
)
return dict((tag['Key'], tag['Value']) for tag in tags)
def get_mount_targets(self, **kwargs):
"""
Returns mount targets for selected instance of EFS
"""
targets = iterate_all(
'MountTargets',
self.connection.describe_mount_targets,
**kwargs
)
for target in targets:
if target['LifeCycleState'] == self.STATE_AVAILABLE:
target['SecurityGroups'] = list(self.get_security_groups(
MountTargetId=target['MountTargetId']
))
else:
target['SecurityGroups'] = []
yield target
def get_security_groups(self, **kwargs):
"""
Returns security groups for selected instance of EFS
"""
return iterate_all(
'SecurityGroups',
self.connection.describe_mount_target_security_groups,
**kwargs
)
def iterate_all(attr, map_method, **kwargs):
"""
Method creates iterator from boto result set
"""
args = dict((key, value) for (key, value) in kwargs.items() if value is not None)
wait = 1
while True:
try:
data = map_method(**args)
for elm in data[attr]:
yield elm
if 'NextMarker' in data:
args['Marker'] = data['Nextmarker']
continue
break
except ClientError as e:
if e.response['Error']['Code'] == "ThrottlingException" and wait < 600:
sleep(wait)
wait = wait * 2
continue
def prefix_to_attr(attr_id):
"""
Helper method to convert ID prefix to mount target attribute
"""
attr_by_prefix = {
'fsmt-': 'MountTargetId',
'subnet-': 'SubnetId',
'eni-': 'NetworkInterfaceId',
'sg-': 'SecurityGroups'
}
prefix = first_or_default(filter(
lambda pref: str(attr_id).startswith(pref),
attr_by_prefix.keys()
))
if prefix:
return attr_by_prefix[prefix]
return 'IpAddress'
def first_or_default(items, default=None):
"""
Helper method to fetch first element of list (if exists)
"""
for item in items:
return item
return default
def has_tags(available, required):
"""
Helper method to determine if tag requested already exists
"""
for key, value in required.items():
if key not in available or value != available[key]:
return False
return True
def has_targets(available, required):
"""
Helper method to determine if mount tager requested already exists
"""
grouped = group_list_of_dict(available)
for (value, field) in required:
if field not in grouped or value not in grouped[field]:
return False
return True
def group_list_of_dict(array):
"""
Helper method to group list of dict to dict with all possible values
"""
result = defaultdict(list)
for item in array:
for key, value in item.items():
result[key] += value if isinstance(value, list) else [value]
return result
def main():
"""
Module action handler
"""
argument_spec = ec2_argument_spec()
argument_spec.update(dict(
id=dict(required=False, type='str', default=None),
name=dict(required=False, type='str', default=None),
tags=dict(required=False, type="dict", default={}),
targets=dict(required=False, type="list", default=[])
))
module = AnsibleModule(argument_spec=argument_spec)
if not HAS_BOTO3:
module.fail_json(msg='boto3 required for this module')
region, _, aws_connect_params = get_aws_connection_info(module, boto3=True)
connection = EFSConnection(module, region, **aws_connect_params)
name = module.params.get('name')
fs_id = module.params.get('id')
tags = module.params.get('tags')
targets = module.params.get('targets')
file_systems_info = connection.get_file_systems(FileSystemId=fs_id, CreationToken=name)
if tags:
file_systems_info = filter(lambda item: has_tags(item['Tags'], tags), file_systems_info)
if targets:
targets = [(item, prefix_to_attr(item)) for item in targets]
file_systems_info = filter(lambda item:
has_targets(item['MountTargets'], targets), file_systems_info)
file_systems_info = [camel_dict_to_snake_dict(x) for x in file_systems_info]
module.exit_json(changed=False, ansible_facts={'efs': file_systems_info})
from ansible.module_utils.basic import *
from ansible.module_utils.ec2 import *
if __name__ == '__main__':
main()
Loading…
Cancel
Save