ansible/network/cloudflare_dns.py

544 lines
21 KiB
Python
Raw Normal View History

#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
#
# This file is (intends to be) 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/>.
try:
import json
except ImportError:
try:
import simplejson as json
except ImportError:
# Let snippet from module_utils/basic.py return a proper error in this case
pass
import urllib
DOCUMENTATION = '''
---
module: cloudflare_dns
author: "Michael Gruener (@mgruener)"
version_added: "2.1"
short_description: manage Cloudflare DNS records
description:
- "Manages dns records via the Cloudflare API, see the docs: U(https://api.cloudflare.com/)"
options:
account_api_token:
description:
- "Account API token. You can obtain your API key from the bottom of the Cloudflare 'My Account' page, found here: U(https://www.cloudflare.com/a/account)"
required: true
account_email:
description:
- "Account email."
required: true
port:
description: Service port. Required for C(type=SRV)
required: false
default: null
priority:
description: Record priority. Required for C(type=MX) and C(type=SRV)
required: false
default: "1"
proto:
description: Service protocol. Required for C(type=SRV)
required: false
choices: [ 'tcp', 'udp' ]
default: null
record:
description:
- Record to add. Required if C(state=present). Default is C(@) (e.g. the zone name)
required: false
default: "@"
aliases: [ "name" ]
service:
description: Record service. Required for C(type=SRV)
required: false
default: null
solo:
description:
- Whether the record should be the only one for that record type and record name. Only use with C(state=present)
- This will delete all other records with the same record name and type.
required: false
default: null
state:
description:
- Whether the record(s) should exist or not
required: false
choices: [ 'present', 'absent' ]
default: present
timeout:
description:
- Timeout for Cloudflare API calls
required: false
default: 30
ttl:
description:
- The TTL to give the new record. Min 1 (automatic), max 2147483647
required: false
default: 1 (automatic)
type:
description:
- The type of DNS record to create. Required if C(state=present)
required: false
choices: [ 'A', 'AAAA', 'CNAME', 'TXT', 'SRV', 'MX', 'NS', 'SPF' ]
default: null
value:
description:
- The record value. Required for C(state=present)
required: false
default: null
aliases: [ "content" ]
weight:
description: Service weight. Required for C(type=SRV)
required: false
default: "1"
zone:
description:
- The name of the Zone to work with (e.g. "example.com"). The Zone must already exist.
required: true
aliases: ["domain"]
'''
EXAMPLES = '''
# create a test.my.com A record to point to 127.0.0.01
- cloudflare_dns:
zone: my.com
record: test
type: A
value: 127.0.0.1
account_email: test@example.com
account_api_token: dummyapitoken
register: record
# create a my.com CNAME record to example.com
- cloudflare_dns:
zone: my.com
type: CNAME
value: example.com
state: present
account_email: test@example.com
account_api_token: dummyapitoken
# change it's ttl
- cloudflare_dns:
zone: my.com
type: CNAME
value: example.com
ttl: 600
state: present
account_email: test@example.com
account_api_token: dummyapitoken
# and delete the record
- cloudflare_dns:
zone: my.com
type: CNAME
value: example.com
state: absent
account_email: test@example.com
account_api_token: dummyapitoken
# create TXT record "test.my.com" with value "unique value"
# delete all other TXT records named "test.my.com"
- cloudflare_dns:
domain: my.com
record: test
type: TXT
value: unique value
state: present
solo: true
account_email: test@example.com
account_api_token: dummyapitoken
# create a SRV record _foo._tcp.my.com
- cloudflare_dns:
domain: my.com
service: foo
proto: tcp
port: 3500
priority: 10
weight: 20
type: SRV
value: fooserver.my.com
'''
RETURN = '''
records:
description: >
List containing the records for a zone or the data for a newly created record.
For details see https://api.cloudflare.com/#dns-records-for-a-zone-properties.
returned: success/changed after record creation
type: list
'''
class CloudflareAPI(object):
cf_api_endpoint = 'https://api.cloudflare.com/client/v4'
changed = False
def __init__(self, module):
self.module = module
self.account_api_token = module.params['account_api_token']
self.account_email = module.params['account_email']
self.port = module.params['port']
self.priority = module.params['priority']
self.proto = module.params['proto']
self.record = module.params['record']
self.service = module.params['service']
self.is_solo = module.params['solo']
self.state = module.params['state']
self.timeout = module.params['timeout']
self.ttl = module.params['ttl']
self.type = module.params['type']
self.value = module.params['value']
self.weight = module.params['weight']
self.zone = module.params['zone']
if self.record == '@':
self.record = self.zone
if (self.type in ['CNAME','NS','MX','SRV']) and (self.value is not None):
self.value = self.value.rstrip('.')
if (self.type == 'SRV'):
if (self.proto is not None) and (not self.proto.startswith('_')):
self.proto = '_' + self.proto
if (self.service is not None) and (not self.service.startswith('_')):
self.service = '_' + self.service
if not self.record.endswith(self.zone):
self.record = self.record + '.' + self.zone
def _cf_simple_api_call(self,api_call,method='GET',payload=None):
headers = { 'X-Auth-Email': self.account_email,
'X-Auth-Key': self.account_api_token,
'Content-Type': 'application/json' }
data = None
if payload:
try:
data = json.dumps(payload)
except Exception, e:
self.module.fail_json(msg="Failed to encode payload as JSON: {0}".format(e))
resp, info = fetch_url(self.module,
self.cf_api_endpoint + api_call,
headers=headers,
data=data,
method=method,
timeout=self.timeout)
if info['status'] not in [200,304,400,401,403,429,405,415]:
self.module.fail_json(msg="Failed API call {0}; got unexpected HTTP code {1}".format(api_call,info['status']))
error_msg = ''
if info['status'] == 401:
# Unauthorized
error_msg = "API user does not have permission; Status: {0}; Method: {1}: Call: {2}".format(info['status'],method,api_call)
elif info['status'] == 403:
# Forbidden
error_msg = "API request not authenticated; Status: {0}; Method: {1}: Call: {2}".format(info['status'],method,api_call)
elif info['status'] == 429:
# Too many requests
error_msg = "API client is rate limited; Status: {0}; Method: {1}: Call: {2}".format(info['status'],method,api_call)
elif info['status'] == 405:
# Method not allowed
error_msg = "API incorrect HTTP method provided; Status: {0}; Method: {1}: Call: {2}".format(info['status'],method,api_call)
elif info['status'] == 415:
# Unsupported Media Type
error_msg = "API request is not valid JSON; Status: {0}; Method: {1}: Call: {2}".format(info['status'],method,api_call)
elif info ['status'] == 400:
# Bad Request
error_msg = "API bad request; Status: {0}; Method: {1}: Call: {2}".format(info['status'],method,api_call)
result = None
try:
content = resp.read()
result = json.loads(content)
except AttributeError:
error_msg += "; The API response was empty"
except json.JSONDecodeError:
error_msg += "; Failed to parse API response: {0}".format(content)
# received an error status but no data with details on what failed
if (info['status'] not in [200,304]) and (result is None):
self.module.fail_json(msg=error_msg)
if not result['success']:
error_msg += "; Error details: "
for error in result['errors']:
error_msg += "code: {0}, error: {1}; ".format(error['code'],error['message'])
if 'error_chain' in error:
for chain_error in error['error_chain']:
error_msg += "code: {0}, error: {1}; ".format(chain_error['code'],chain_error['message'])
self.module.fail_json(msg=error_msg)
return result, info['status']
def _cf_api_call(self,api_call,method='GET',payload=None):
result, status = self._cf_simple_api_call(api_call,method,payload)
data = result['result']
if 'result_info' in result:
pagination = result['result_info']
if pagination['total_pages'] > 1:
next_page = int(pagination['page']) + 1
parameters = ['page={0}'.format(next_page)]
# strip "page" parameter from call parameters (if there are any)
if '?' in api_call:
raw_api_call,query = api_call.split('?',1)
parameters += [param for param in query.split('&') if not param.startswith('page')]
else:
raw_api_call = api_call
while next_page <= pagination['total_pages']:
raw_api_call += '?' + '&'.join(parameters)
result, status = self._cf_simple_api_call(raw_api_call,method,payload)
data += result['result']
next_page += 1
return data, status
def _get_zone_id(self,zone=None):
if not zone:
zone = self.zone
zones = self.get_zones(zone)
if len(zones) > 1:
self.module.fail_json(msg="More than one zone matches {0}".format(zone))
if len(zones) < 1:
self.module.fail_json(msg="No zone found with name {0}".format(zone))
return zones[0]['id']
def get_zones(self,name=None):
if not name:
name = self.zone
param = ''
if name:
param = '?' + urllib.urlencode({'name' : name})
zones,status = self._cf_api_call('/zones' + param)
return zones
def get_dns_records(self,zone_name=None,type=None,record=None,value=''):
if not zone_name:
zone_name = self.zone
if not type:
type = self.type
if not record:
record = self.record
# necessary because None as value means to override user
# set module value
if (not value) and (value is not None):
value = self.value
zone_id = self._get_zone_id()
api_call = '/zones/{0}/dns_records'.format(zone_id)
query = {}
if type:
query['type'] = type
if record:
query['name'] = record
if value:
query['content'] = value
if query:
api_call += '?' + urllib.urlencode(query)
records,status = self._cf_api_call(api_call)
return records
def delete_dns_records(self,**kwargs):
params = {}
for param in ['port','proto','service','solo','type','record','value','weight','zone']:
if param in kwargs:
params[param] = kwargs[param]
else:
params[param] = getattr(self,param)
records = []
search_value = params['value']
search_record = params['record']
if params['type'] == 'SRV':
search_value = str(params['weight']) + '\t' + str(params['port']) + '\t' + params['value']
search_record = params['service'] + '.' + params['proto'] + '.' + params['record']
if solo:
search_value = None
records = self.get_dns_records(params['zone'],params['type'],search_record,search_value)
for rr in records:
if solo:
if not ((rr['type'] == params['type']) and (rr['name'] == params['record']) and (rr['content'] == params['value'])):
self.changed = True
if not self.module.check_mode:
result, info = self._cf_api_call('/zones/{0}/dns_records/{1}'.format(rr['zone_id'],rr['id']),'DELETE')
else:
self.changed = True
if not self.module.check_mode:
result, info = self._cf_api_call('/zones/{0}/dns_records/{1}'.format(rr['zone_id'],rr['id']),'DELETE')
return self.changed
def ensure_dns_record(self,**kwargs):
params = {}
for param in ['port','priority','proto','service','ttl','type','record','value','weight','zone']:
if param in kwargs:
params[param] = kwargs[param]
else:
params[param] = getattr(self,param)
search_value = params['value']
search_record = params['record']
new_record = None
if (params['type'] is None) or (params['record'] is None):
self.module.fail_json(msg="You must provide a type and a record to create a new record")
if (params['type'] in [ 'A','AAAA','CNAME','TXT','MX','NS','SPF']):
if not params['value']:
self.module.fail_json(msg="You must provide a non-empty value to create this record type")
new_record = {
"type": params['type'],
"name": params['record'],
"content": params['value'],
"ttl": params['ttl']
}
if params['type'] == 'MX':
for attr in [params['priority'],params['value']]:
if (attr is None) or (attr == ''):
self.module.fail_json(msg="You must provide priority and a value to create this record type")
new_record = {
"type": params['type'],
"name": params['record'],
"content": params['value'],
"priority": params['priority'],
"ttl": params['ttl']
}
if params['type'] == 'SRV':
for attr in [params['port'],params['priority'],params['proto'],params['service'],params['weight'],params['value']]:
if (attr is None) or (attr == ''):
self.module.fail_json(msg="You must provide port, priority, proto, service, weight and a value to create this record type")
srv_data = {
"target": params['value'],
"port": params['port'],
"weight": params['weight'],
"priority": params['priority'],
"name": params['record'],
"proto": params['proto'],
"service": params['service']
}
new_record = { "type": params['type'], "ttl": params['ttl'], 'data': srv_data }
search_value = str(params['weight']) + '\t' + str(params['port']) + '\t' + params['value']
search_record = params['service'] + '.' + params['proto'] + '.' + params['record']
zone_id = self._get_zone_id(params['zone'])
records = self.get_dns_records(params['zone'],params['type'],search_record,search_value)
# in theory this should be impossible as cloudflare does not allow
# the creation of duplicate records but lets cover it anyways
if len(records) > 1:
return records,self.changed
# record already exists, check if ttl must be updated
if len(records) == 1:
cur_record = records[0]
do_update = False
if (params['ttl'] is not None) and (cur_record['ttl'] != params['ttl'] ):
cur_record['ttl'] = params['ttl']
do_update = True
if (params['priority'] is not None) and ('priority' in cur_record) and (cur_record['priority'] != params['priority']):
cur_record['priority'] = params['priority']
do_update = True
if ('data' in new_record) and ('data' in cur_record):
if (cur_record['data'] > new_record['data']) - (cur_record['data'] < new_record['data']):
cur_record['data'] = new_record['data']
do_update = True
if do_update:
if not self.module.check_mode:
result, info = self._cf_api_call('/zones/{0}/dns_records/{1}'.format(zone_id,records[0]['id']),'PUT',new_record)
self.changed = True
return result,self.changed
else:
return records,self.changed
if not self.module.check_mode:
result, info = self._cf_api_call('/zones/{0}/dns_records'.format(zone_id),'POST',new_record)
self.changed = True
return result,self.changed
def main():
module = AnsibleModule(
argument_spec = dict(
account_api_token = dict(required=True, no_log=True, type='str'),
account_email = dict(required=True, type='str'),
port = dict(required=False, default=None, type='int'),
priority = dict(required=False, default=1, type='int'),
proto = dict(required=False, default=None, choices=[ 'tcp', 'udp' ], type='str'),
record = dict(required=False, default='@', aliases=['name'], type='str'),
service = dict(required=False, default=None, type='str'),
solo = dict(required=False, default=None, type='bool'),
state = dict(required=False, default='present', choices=['present', 'absent'], type='str'),
timeout = dict(required=False, default=30, type='int'),
ttl = dict(required=False, default=1, type='int'),
type = dict(required=False, default=None, choices=[ 'A', 'AAAA', 'CNAME', 'TXT', 'SRV', 'MX', 'NS', 'SPF' ], type='str'),
value = dict(required=False, default=None, aliases=['content'], type='str'),
weight = dict(required=False, default=1, type='int'),
zone = dict(required=True, default=None, aliases=['domain'], type='str'),
),
supports_check_mode = True,
required_if = ([
('state','present',['record','type']),
('type','MX',['priority','value']),
('type','SRV',['port','priority','proto','service','value','weight']),
('type','A',['value']),
('type','AAAA',['value']),
('type','CNAME',['value']),
('type','TXT',['value']),
('type','NS',['value']),
('type','SPF',['value'])
]
),
required_one_of = (
[['record','value','type']]
)
)
changed = False
cf_api = CloudflareAPI(module)
# sanity checks
if cf_api.is_solo and cf_api.state == 'absent':
module.fail_json(msg="solo=true can only be used with state=present")
# perform add, delete or update (only the TTL can be updated) of one or
# more records
if cf_api.state == 'present':
# delete all records matching record name + type
if cf_api.is_solo:
changed = cf_api.delete_dns_records(solo=cf_api.is_solo)
result,changed = cf_api.ensure_dns_record()
module.exit_json(changed=changed,result={'records': result})
else:
# force solo to False, just to be sure
changed = cf_api.delete_dns_records(solo=False)
module.exit_json(changed=changed)
# import module snippets
from ansible.module_utils.basic import *
from ansible.module_utils.urls import *
if __name__ == '__main__':
main()