1.. _route53_tut.rst:
2
3===========================================
4An Introduction to boto's Route53 interface
5===========================================
6
7This tutorial focuses on the boto interface to Route53 from Amazon Web
8Services.  This tutorial assumes that you have already downloaded and installed
9boto.
10
11Route53 is a Domain Name System (DNS) web service. It can be used to route
12requests to services running on AWS such as EC2 instances or load balancers, as
13well as to external services. Route53 also allows you to have automated checks
14to send requests where you require them.
15
16In this tutorial, we will be setting up our services for *example.com*.
17
18Creating a connection
19---------------------
20
21To start using Route53 you will need to create a connection to the service as
22normal:
23
24>>> import boto.route53
25>>> conn = boto.route53.connect_to_region('us-west-2')
26
27You will be using this conn object for the remainder of the tutorial to send
28commands to Route53.
29
30Working with domain names
31-------------------------
32
33You can manipulate domains through a zone object. For example, you can create a
34domain name:
35
36>>> zone = conn.create_zone("example.com.")
37
38Note that trailing dot on that domain name is significant. This is known as a
39fully qualified domain name (`FQDN <http://en.wikipedia.org/wiki/Fully_qualified_domain_name>`_).
40
41>>> zone
42<Zone:example.com.>
43
44You can also retrieve all your domain names:
45
46>>> conn.get_zones()
47[<Zone:example.com.>]
48
49Or you can retrieve a single domain:
50
51>>> conn.get_zone("example.com.")
52<Zone:example.com.>
53
54Finally, you can retrieve the list of nameservers that AWS has setup for this
55domain name as follows:
56
57>>> zone.get_nameservers()
58[u'ns-1000.awsdns-42.org.', u'ns-1001.awsdns-30.com.', u'ns-1002.awsdns-59.net.', u'ns-1003.awsdns-09.co.uk.']
59
60Once you have finished configuring your domain name, you will need to change
61your nameservers at your registrar to point to those nameservers for Route53 to
62work.
63
64Setting up dumb records
65-----------------------
66
67You can also add, update and delete records on a zone:
68
69>>> status = a.add_record("MX", "example.com.", "10 mail.isp.com")
70
71When you send a change request through, the status of the update will be
72*PENDING*:
73
74>>> status
75<Status:PENDING>
76
77You can call the API again and ask for the current status as follows:
78
79>>> status.update()
80'INSYNC'
81
82>>> status
83<Status:INSYNC>
84
85When the status has changed to *INSYNC*, the change has been propagated to
86remote servers
87
88Updating a record
89-----------------
90
91You can create, upsert or delete a single record like this
92
93>>> zone = conn.get_zone("example.com.")
94>>> change_set = ResourceRecordSets(conn, zone.id)
95>>> changes1 = change_set.add_change("UPSERT", "www" + ".example.com", type="CNAME", ttl=3600)
96>>> changes1.add_value("webserver.example.com")
97>>> change_set.commit()
98
99In this example we create or update, depending on the existence of the record, the
100CNAME www.example.com to webserver.example.com.
101
102Working with Change Sets
103------------------------
104
105You can also do bulk updates using ResourceRecordSets. For example updating the TTL
106
107>>> zone = conn.get_zone('example.com')
108>>> change_set = boto.route53.record.ResourceRecordSets(conn, zone.id)
109>>> for rrset in conn.get_all_rrsets(zone.id):
110...     u = change_set.add_change("UPSERT", rrset.name, rrset.type, ttl=3600)
111...     u.add_value(rrset.resource_records[0])
112... results = change_set.commit()
113Done
114
115In this example we update the TTL to 1hr (3600 seconds) for all records recursed from
116example.com.
117Note: this will also change the SOA and NS records which may not be ideal for many users.
118