python-route53¶
Amazon’s Route 53 is an excellent DNS service, with great stability and performance world-wide. The entire feature set is exposed through a web-based API. However, said API is somewhat difficult to work with in some cases.
python-route53 aims to provide the simplest possible API for Route 53. It is also currently the only publicly available module with support for Python 3 (also supports 2.7).
License: | BSD License |
---|
Assorted Info¶
- Issue tracker - Report bugs here.
- GitHub project - Source code lives here.
- @gctaylor Twitter - Tweets from the maintainer.
- AWS’s Official Route 53 Documentation - Behaviors, specifics, more details.
User Guide¶
Installation¶
Before installing python-route53, make sure that you have Python 2.7 or Python 3.x installed. If you do not have either of these, you’ll need to use another module (boto is highly recommended).
If you’re all set with Python 2.7 or Python 3, there are a few ways to install python-route.
Distribute & Pip¶
Installing python-route53 is simple with pip:
pip install route53
easy_install works, too:
easy_install route53
Get the source¶
python-route53 is developed on GitHub in the python-route53 project.
You can either clone the repository:
git clone git://github.com/gtaylor/python-route53.git
Download the tarball:
curl -OL https://github.com/gtaylor/python-route53/tarball/master
Or download the zip:
curl -OL https://github.com/gtaylor/python-route53/zipball/master
Quickstart¶
This section goes over how to get up and running quickly. We’ll assume that you have already followed the Installation instructions, and are ready to go.
Tip
It’s best to combine our documentation with the Route 53 Documentation. While we’ll do our best to make this as simple as possible, it may be necessary to look at what they’ve got for more details on behavior and how things work.
AWS credentials¶
Before you can make your first query to Route 53, you’ll need obtain your API credentials. Visit your security credentials page and note your Access Key ID and Secret Access Key.
Instantiate the API client¶
Next, you’ll want to import the module:
import route53
You can then instantiate a connection to Route53 via route53.connect()
:
conn = route53.connect(
aws_access_key_id='YOURACCESSKEYHERE',
aws_secret_access_key='YOURSECRETACCESSKEYHERE',
)
You are now ready to roll. Continue reading to see how much fun there is to be had (hooray!).
Listing Hosted Zones¶
Let’s say you want to retrieve a representation of all of your currently existing hosted zones. These roughly correspond to domains, ala angry-squirrel.com, or python.org.
The Route53Connection.list_hosted_zones
method returns a generator of
HostedZone
instances:
# This is a generator.
for zone in conn.list_hosted_zones():
# You can then do various things to the zone.
print(zone.name)
# Perhaps you want to see the record sets under this zone
for record_set in zone.record_sets:
print(record_set)
# Or maybe you don't like this zone, and want to blow it away.
zone.delete()
Creating a Hosted Zone¶
The Route53Connection.create_hosted_zone
method creates hosted zones, and returns a tuple that contains a
HostedZone
instance, and some details about the pending change from the API:
new_zone, change_info = conn.create_hosted_zone(
'some-domain.com.', comment='An optional comment.'
)
# You can then manipulate the HostedZone.
print("Zone ID", new_zone.id)
# This has some details about the change from the API.
print(change_info)
Note
Notice that we passed in a fully-qualified domain name,
some-domain.com.
, ending in a period.
In this case, new_zone
is a new HostedZone
instance, and change_info
is a dict with some details about the changes
pending (from the Route 53 API).
Retrieving a Hosted Zone¶
The
Route53Connection.get_hosted_zone_by_id
method retrieves a specific hosted zone, by Zone ID:
zone = conn.get_hosted_zone_by_id('ZONE-ID-HERE')
Note
A Zone ID is not the same thing as the domain name. The Zone ID is a unique string identifier for the hosted zone, as per Route 53’s records.
Deleting a Hosted Zone¶
Simply call the HostedZone.delete
method on a HostedZone
to delete
it:
zone = conn.get_hosted_zone_by_id('ZONE-ID-HERE')
zone.delete()
If you have record sets under the hosted zone, you’ll need to delete those
first, or an exception will be raised. Alternatively, you can
call delete()
with force=True
to delete the record sets and the
hosted zones:
zone.delete(force=True)
Creating a record set¶
Depending on which kind of record set you’d like to create, choose the
appropriate create_*_record
method on
HostedZone
. The methods
return one of the ResourceRecordSet
sub-classes:
new_record, change_info = zone.create_a_record(
# Notice that this is a full-qualified name.
name='test.some-domain.com.',
# A list of IP address entries, in the case fo an A record.
values=['8.8.8.8'],
)
# Or maybe we want a weighted round-robin set.
wrr_record1, change_info = zone.create_a_record(
name='wrrtest.some-domain.com.',
values=['8.8.8.8'],
weight=1
set_identifier='set123,
)
wrr_record2, change_info = zone.create_a_record(
name='wrrtest.some-domain.com.',
values=['6.6.6.6'],
weight=2
set_identifier='set123,
)
Listing record sets¶
In order to list record sets, use the
HostedZone.record_sets
property on HostedZone
.
Note that we don’t currently implement any convenience
methods for finding record sets, so this is the way to go:
# Note that this is a fully-qualified domain name.
name_to_match = 'fuzzy.bunny.com.'
for record_set in zone.record_sets:
if record_set.name == name_to_match:
print(record_set)
# Stopping early may save some additional HTTP requests,
# since zone.record_sets is a generator.
break
While it may seem like extra work to craft these filters yourself, it does prevent needless additional iteration, and keeps the API more concise.
Changing a record set¶
Simply change one of the attributes on the various ResourceRecordSet
sub-classed instances and call its save()
method:
record_set.values = ['8.8.8.7']
record_set.save()
Reference¶
route53 API Reference¶
Below you will find the entire publicly exposed API for python-route53 documented in its entirety. If you find anything missing, lacking detail, or incorrect, please file an issue on the issue tracker.
route53¶
The top-level route53 module is used as the default entry point to
python-route53’s functionality. You’ll want to go through the connect()
function to get a
Route53Connection
instance to work with the Route 53 API.
-
route53.
connect
(aws_access_key_id=None, aws_secret_access_key=None, **kwargs)¶ Instantiates and returns a
route53.connection.Route53Connection
instance, which is how you’ll start your interactions with the Route 53 API.Parameters: Return type: Returns: A connection to Amazon’s Route 53
route53.connection¶
-
class
route53.connection.
Route53Connection
(aws_access_key_id, aws_secret_access_key)¶ Instances of this class are instantiated by the top-level
route53.connect()
function, and serve as a high level gateway to the Route 53 API. The majority of your interaction with these instances will probably be creating, deleting, and retrievingHostedZone
instances.Warning
Do not instantiate instances of this class yourself.
-
create_hosted_zone
(name, caller_reference=None, comment=None)¶ Creates and returns a new hosted zone. Once a hosted zone is created, its details can’t be changed.
Parameters: - name (str) – The name of the hosted zone to create.
- caller_reference (str) – A unique string that identifies the request and that allows failed create_hosted_zone requests to be retried without the risk of executing the operation twice. If no value is given, we’ll generate a Type 4 UUID for you.
- comment (str) – An optional comment to attach to the zone.
Return type: Returns: A tuple in the form of
(hosted_zone, change_info)
. Thehosted_zone
variable contains aHostedZone
instance matching the newly created zone, andchange_info
is a dict with some details about the API request.
-
delete_hosted_zone_by_id
(id)¶ Deletes a hosted zone, by hosted zone ID (not name).
Tip
For most cases, we recommend deleting hosted zones via a
HostedZone
instance’sHostedZone.delete
method, but this saves an HTTP request if you already know the zone’s ID.Note
Unlike
HostedZone.delete
, this method has no optionalforce
kwarg.Parameters: id (str) – The hosted zone’s ID (a short hash string). Return type: dict Returns: A dict of change info, which contains some details about the request.
-
endpoint_version
= '2012-02-29'¶
-
get_hosted_zone_by_id
(id)¶ Retrieves a hosted zone, by hosted zone ID (not name).
Parameters: id (str) – The hosted zone’s ID (a short hash string). Return type: HostedZone
Returns: An HostedZone
instance representing the requested hosted zone.
-
list_hosted_zones
(page_chunks=100)¶ List all hosted zones associated with this connection’s account. Since this method returns a generator, you can pull as many or as few entries as you’d like, without having to query and receive every hosted zone you may have.
Parameters: page_chunks (int) – This API call is “paginated” behind-the-scenes in order to break up large result sets. This number determines the maximum number of HostedZone
instances to retrieve per request. The default is fine for almost everyone.Return type: generator Returns: A generator of HostedZone
instances.
-
route53.hosted_zone¶
-
class
route53.hosted_zone.
HostedZone
(connection, id, name, caller_reference, resource_record_set_count, comment)¶ A hosted zone is a collection of resource record sets hosted by Route 53. Like a traditional DNS zone file, a hosted zone represents a collection of resource record sets that are managed together under a single domain name. Each hosted zone has its own metadata and configuration information.
Warning
Do not instantiate this directly yourself. Go through one of the methods on
route53.connection.Route53Connection
.-
create_a_record
(name, values, ttl=60, weight=None, region=None, set_identifier=None, alias_hosted_zone_id=None, alias_dns_name=None)¶ Creates and returns an A record attached to this hosted zone.
Parameters: - name (str) – The fully qualified name of the record to add.
- values (list) – A list of value strings for the record.
- ttl (int) – The time-to-live of the record (in seconds).
- weight (int) – For weighted record sets only. Among resource record sets that have the same combination of DNS name and type, a value that determines what portion of traffic for the current resource record set is routed to the associated location. Ranges from 0-255.
- region (str) – For latency-based record sets. The Amazon EC2 region where the resource that is specified in this resource record set resides.
- set_identifier (str) – For weighted and latency resource record sets only. An identifier that differentiates among multiple resource record sets that have the same combination of DNS name and type. 1-128 chars.
- alias_hosted_zone_id (str) – Alias A records have this specified. It appears to be the hosted zone ID for the ELB the Alias points at.
- alias_dns_name (str) – Alias A records have this specified. It is the DNS name for the ELB that the Alias points to.
Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly createdAResourceRecordSet
instance.
-
create_aaaa_record
(name, values, ttl=60, weight=None, region=None, set_identifier=None)¶ Creates an AAAA record attached to this hosted zone.
Parameters: - name (str) – The fully qualified name of the record to add.
- values (list) – A list of value strings for the record.
- ttl (int) – The time-to-live of the record (in seconds).
- weight (int) – For weighted record sets only. Among resource record sets that have the same combination of DNS name and type, a value that determines what portion of traffic for the current resource record set is routed to the associated location. Ranges from 0-255.
- region (str) – For latency-based record sets. The Amazon EC2 region where the resource that is specified in this resource record set resides.
- set_identifier (str) – For weighted and latency resource record sets only. An identifier that differentiates among multiple resource record sets that have the same combination of DNS name and type. 1-128 chars.
Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly created AAAAResourceRecordSet instance.
-
create_cname_record
(name, values, ttl=60, weight=None, region=None, set_identifier=None)¶ Creates a CNAME record attached to this hosted zone.
Parameters: - name (str) – The fully qualified name of the record to add.
- values (list) – A list of value strings for the record.
- ttl (int) – The time-to-live of the record (in seconds).
- weight (int) – For weighted record sets only. Among resource record sets that have the same combination of DNS name and type, a value that determines what portion of traffic for the current resource record set is routed to the associated location. Ranges from 0-255.
- region (str) – For latency-based record sets. The Amazon EC2 region where the resource that is specified in this resource record set resides.
- set_identifier (str) – For weighted and latency resource record sets only. An identifier that differentiates among multiple resource record sets that have the same combination of DNS name and type. 1-128 chars.
Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly created CNAMEResourceRecordSet instance.
-
create_mx_record
(name, values, ttl=60)¶ Creates a MX record attached to this hosted zone.
Parameters: Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly created MXResourceRecordSet instance.
-
create_ns_record
(name, values, ttl=60)¶ Creates a NS record attached to this hosted zone.
Parameters: Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly created NSResourceRecordSet instance.
-
create_ptr_record
(name, values, ttl=60)¶ Creates a PTR record attached to this hosted zone.
Parameters: Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly created PTRResourceRecordSet instance.
-
create_spf_record
(name, values, ttl=60)¶ Creates a SPF record attached to this hosted zone.
Parameters: Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly created SPFResourceRecordSet instance.
-
create_srv_record
(name, values, ttl=60)¶ Creates a SRV record attached to this hosted zone.
Parameters: Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly created SRVResourceRecordSet instance.
-
create_txt_record
(name, values, ttl=60, weight=None, region=None, set_identifier=None)¶ Creates a TXT record attached to this hosted zone.
Parameters: - name (str) – The fully qualified name of the record to add.
- values (list) – A list of value strings for the record.
- ttl (int) – The time-to-live of the record (in seconds).
- weight (int) – For weighted record sets only. Among resource record sets that have the same combination of DNS name and type, a value that determines what portion of traffic for the current resource record set is routed to the associated location. Ranges from 0-255.
- region (str) – For latency-based record sets. The Amazon EC2 region where the resource that is specified in this resource record set resides.
- set_identifier (str) – For weighted and latency resource record sets only. An identifier that differentiates among multiple resource record sets that have the same combination of DNS name and type. 1-128 chars.
Return type: Returns: A tuple in the form of
(rrset, change_info)
, whererrset
is the newly created TXTResourceRecordSet instance.
-
delete
(force=False)¶ Deletes this hosted zone. After this method is ran, you won’t be able to add records, or do anything else with the zone. You’d need to re-create it, as zones are read-only after creation.
Parameters: force (bool) – If True
, delete theHostedZone
, even if it means nuking all associated record sets. IfFalse
, an exception is raised if thisHostedZone
has record sets.Return type: dict Returns: A dict of change info, which contains some details about the request.
-
record_sets
¶ Queries for the Resource Record Sets that are under this HostedZone. This is typically the way to go to find specific record sets, or to list them all.
We don’t currently implement any filtering convenience method, since it is very easy to do this yourself, catered to your own needs. For example, if you find your match, you may choose to stop iterating on the generator, potentially saving yourself extra API queries (behind the scenes).
Warning
This result set can get pretty large if you have a ton of records.
Return type: generator Returns: A generator of ResourceRecordSet sub-classes.
-
route53.resource_record_set¶
-
class
route53.resource_record_set.
AResourceRecordSet
(alias_hosted_zone_id=None, alias_dns_name=None, *args, **kwargs)¶ Specific A record class. There are two kinds of A records:
- Regular A records.
- Alias A records. These point at an ELB instance instead of an IP.
Create these via
HostedZone.create_a_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'A'¶
-
save
()¶ Saves any changes to this record set.
-
class
route53.resource_record_set.
AAAAResourceRecordSet
(alias_hosted_zone_id=None, alias_dns_name=None, *args, **kwargs)¶ Specific AAAA record class. Create these via
HostedZone.create_aaaa_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'AAAA'¶
-
save
()¶ Saves any changes to this record set.
-
-
class
route53.resource_record_set.
CNAMEResourceRecordSet
(alias_hosted_zone_id=None, alias_dns_name=None, *args, **kwargs)¶ Specific CNAME record class. Create these via
HostedZone.create_cname_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'CNAME'¶
-
save
()¶ Saves any changes to this record set.
-
-
class
route53.resource_record_set.
MXResourceRecordSet
(connection, zone_id, name, ttl, records, weight=None, region=None, set_identifier=None)¶ Specific MX record class. Create these via
HostedZone.create_mx_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'MX'¶
-
save
()¶ Saves any changes to this record set.
-
-
class
route53.resource_record_set.
NSResourceRecordSet
(connection, zone_id, name, ttl, records, weight=None, region=None, set_identifier=None)¶ Specific NS record class. Create these via
HostedZone.create_ns_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'NS'¶
-
save
()¶ Saves any changes to this record set.
-
-
class
route53.resource_record_set.
PTRResourceRecordSet
(connection, zone_id, name, ttl, records, weight=None, region=None, set_identifier=None)¶ Specific PTR record class. Create these via
HostedZone.create_ptr_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'PTR'¶
-
save
()¶ Saves any changes to this record set.
-
-
class
route53.resource_record_set.
SOAResourceRecordSet
(connection, zone_id, name, ttl, records, weight=None, region=None, set_identifier=None)¶ Specific SOA record class. Retrieve these via
HostedZone.record_sets
. They can’t be created.-
delete
()¶ SOA records can’t be created or deleted.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'SOA'¶
-
save
()¶ Saves any changes to this record set.
-
-
class
route53.resource_record_set.
SPFResourceRecordSet
(connection, zone_id, name, ttl, records, weight=None, region=None, set_identifier=None)¶ Specific SPF record class. Create these via
HostedZone.create_spf_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'SPF'¶
-
save
()¶ Saves any changes to this record set.
-
-
class
route53.resource_record_set.
SRVResourceRecordSet
(connection, zone_id, name, ttl, records, weight=None, region=None, set_identifier=None)¶ Specific SRV record class. Create these via
HostedZone.create_srv_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'SRV'¶
-
save
()¶ Saves any changes to this record set.
-
-
class
route53.resource_record_set.
TXTResourceRecordSet
(connection, zone_id, name, ttl, records, weight=None, region=None, set_identifier=None)¶ Specific TXT record class. Create these via
HostedZone.create_txt_record
. Retrieve them viaHostedZone.record_sets
.-
delete
()¶ Deletes this record set.
-
hosted_zone
¶ Queries for this record set’s HostedZone.
Note
This is not cached, it will always return the latest data from the Route 53 API.
Return type: HostedZone
Returns: The matching HostedZone
for this record set.
-
is_alias_record_set
()¶ Checks whether this is an A record in Alias mode.
Return type: bool Returns: True
if this is an A record in Alias mode, andFalse
otherwise.
-
is_modified
()¶ Determines whether this record set has been modified since the last retrieval or save.
Return type: bool Returns: True` if the record set has been modified, and ``False
if not.
-
rrset_type
= 'TXT'¶
-
save
()¶ Saves any changes to this record set.
-
route53.exceptions¶
-
exception
route53.exceptions.
AlreadyDeletedError
¶ Raised when the user tries to modify something on a hosted zone that has been deleted in Route53.
-
exception
route53.exceptions.
Route53Error
¶ Base class for all Route53 API exceptions. Mostly here to allow end users to catch all Route53 exceptions.