Add Python bindings docs
Change-Id: I95a098190917017b010a323403ca43108f078958
This commit is contained in:
Kiall Mac Innes
parent
472ec278d4
commit
1416ffa87e
@ -1,5 +0,0 @@
|
||||
========================================
|
||||
designateclient python module - examples
|
||||
========================================
|
||||
|
||||
TODO
|
||||
@ -1,4 +0,0 @@
|
||||
designateclient python module
|
||||
=============================
|
||||
|
||||
TODO
|
||||
476
doc/source/bindings.rst
Normal file
476
doc/source/bindings.rst
Normal file
@ -0,0 +1,476 @@
|
||||
===============
|
||||
Python Bindings
|
||||
===============
|
||||
|
||||
The python-designateclient package comes with python bindings for the Designate
|
||||
API. This can be used to interact with the Designate API from any python
|
||||
program.
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
Below is a simple example of how to instantiate and perform basic tasks using
|
||||
the bindings.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client, providing the necessary credentials
|
||||
client = Client(
|
||||
auth_url="https://example.com:5000/v2.0/",
|
||||
username="openstack",
|
||||
password="yadayada",
|
||||
tenant_id="123456789"
|
||||
)
|
||||
|
||||
# Fetch a list of the domains this user/tenant has access to
|
||||
domains = client.domains.list()
|
||||
|
||||
# Iterate the list, printing some useful information
|
||||
for domain in domains:
|
||||
print "Domain ID: %s, Name: %s" % (domain.id, domain.name)
|
||||
|
||||
And the output this program might produce:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ python /tmp/example.py
|
||||
Domain ID: 467f97b4-f074-4839-ae85-1a61fccfb83d, Name: example-one.com.
|
||||
Domain ID: 6d3bf479-8a93-47ae-8c65-3dff8dba1b0d, Name: example-two.com.
|
||||
|
||||
|
||||
Authentication
|
||||
==============
|
||||
|
||||
Designate supports either Keystone authentication, or no authentication at all.
|
||||
|
||||
Keystone Authentication
|
||||
-----------------------
|
||||
|
||||
Below is a sample of standard authentication with keystone:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client, providing the necessary credentials
|
||||
client = Client(
|
||||
auth_url="https://example.com:5000/v2.0/",
|
||||
username="openstack",
|
||||
password="yadayada",
|
||||
tenant_id="123456789"
|
||||
)
|
||||
|
||||
Below is a sample of standard authentication with keystone, but also explicitly
|
||||
providing the endpoint to use:
|
||||
|
||||
.. note:: This is useful when a development Designate instances authenticates
|
||||
against a production Keystone.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client, providing the necessary credentials
|
||||
client = Client(
|
||||
auth_url="https://example.com:5000/v2.0/",
|
||||
username="openstack",
|
||||
password="yadayada",
|
||||
tenant_id="123456789",
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
No Authentication
|
||||
-----------------
|
||||
|
||||
Below is a sample of interaction with a non authenticated designate:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client, providing the endpoint directly
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
Working with Domains
|
||||
====================
|
||||
|
||||
The Domain Object
|
||||
-----------------
|
||||
|
||||
Object Properties:
|
||||
|
||||
======================= =======================================================
|
||||
Property Description
|
||||
======================= =======================================================
|
||||
id Domain ID
|
||||
name Domain Name (e.g. example.com.)
|
||||
email Domain Responsible Person Email (e.g. fred@example.com)
|
||||
ttl Default TTL for records
|
||||
serial Domain Server Number
|
||||
created_at Date and time this domain was created at
|
||||
updated_at Date and time this domain was last updated
|
||||
======================= =======================================================
|
||||
|
||||
Listing Domains
|
||||
---------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
# List All Domains
|
||||
domains = client.domains.list()
|
||||
|
||||
Fetching a Domain by ID
|
||||
-----------------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the domain
|
||||
domain = client.domains.get(domain_id)
|
||||
|
||||
|
||||
Creating a Domain
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
from designateclient.v1.domains import Domain
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
# Create a new Domain object
|
||||
domain = Domain(name="example.com.", email="fred@example.com")
|
||||
|
||||
# Send the Create Domain API call
|
||||
domain = client.domains.create(domain)
|
||||
|
||||
Updating a Domain
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the domain
|
||||
domain = client.domains.get(domain_id)
|
||||
|
||||
# Update a value on the Domain
|
||||
domain.ttl = 300
|
||||
|
||||
# Send the Update Domain API call
|
||||
domain = client.domains.update(domain)
|
||||
|
||||
Deleting a Domain
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the domain
|
||||
domains = client.domains.delete(domain_id)
|
||||
|
||||
Working with Records
|
||||
====================
|
||||
|
||||
The Record Object
|
||||
-----------------
|
||||
|
||||
Object Properties:
|
||||
|
||||
======================= =======================================================
|
||||
Property Description
|
||||
======================= =======================================================
|
||||
id Record ID
|
||||
domain_id Domain ID
|
||||
name Record Name (e.g. example.com.)
|
||||
type Record Type (e.g. A, AAAA, CNAME, MX, SRV etc)
|
||||
data Record Data (e.g. 127.0.0.1)
|
||||
priority Rercord Priority (Valid only for MX and SRV records)
|
||||
ttl Record TTL
|
||||
created_at Date and time this record was created at
|
||||
updated_at Date and time this record was last updated
|
||||
======================= =======================================================
|
||||
|
||||
Listing Records
|
||||
---------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
|
||||
# List All Records
|
||||
records = client.records.list(domain_id)
|
||||
|
||||
Fetching a Record by ID
|
||||
-----------------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
record_id = 'bd3e8520-25e0-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the record
|
||||
records = client.records.get(domain_id, record_id)
|
||||
|
||||
|
||||
Creating a Record
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
from designateclient.v1.records import Record
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
|
||||
# Create a new Record object
|
||||
record = Record(name="www.example.com.", type="A", content="127.0.0.1")
|
||||
|
||||
# Send the Create Record API call
|
||||
record = client.records.create(domain_id, record)
|
||||
|
||||
Updating a Record
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
record_id = 'bd3e8520-25e0-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the record
|
||||
record = client.records.get(record_id)
|
||||
|
||||
# Update a value on the Record
|
||||
record.ttl = 300
|
||||
|
||||
# Send the Update Record API call
|
||||
record = client.records.update(record)
|
||||
|
||||
Deleting a Record
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
record_id = 'bd3e8520-25e0-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the record
|
||||
records = client.records.delete(record_id)
|
||||
|
||||
Working with Servers
|
||||
====================
|
||||
|
||||
The Server Object
|
||||
-----------------
|
||||
|
||||
Object Properties:
|
||||
|
||||
======================= =======================================================
|
||||
Property Description
|
||||
======================= =======================================================
|
||||
id Server ID
|
||||
name Server Name (e.g. example.com.)
|
||||
created_at Date and time this server was created at
|
||||
updated_at Date and time this server was last updated
|
||||
======================= =======================================================
|
||||
|
||||
Listing Servers
|
||||
---------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
# List All Servers
|
||||
servers = client.servers.list()
|
||||
|
||||
Fetching a Server by ID
|
||||
-----------------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
server_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the server
|
||||
server = client.servers.get(server_id)
|
||||
|
||||
|
||||
Creating a Server
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
from designateclient.v1.servers import Server
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
# Create a new Server object
|
||||
server = Server(name="ns1.example.com.")
|
||||
|
||||
# Send the Create Server API call
|
||||
server = client.servers.create(server)
|
||||
|
||||
Updating a Server
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
server_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the server
|
||||
server = client.servers.get(server_id)
|
||||
|
||||
# Update a value on the Server
|
||||
server.name = "ns2.example.com"
|
||||
|
||||
# Send the Update Server API call
|
||||
server = client.servers.update(server)
|
||||
|
||||
Deleting a Server
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from designateclient.v1 import Client
|
||||
|
||||
# Create an instance of the client
|
||||
client = Client(
|
||||
endpoint="https://127.0.0.1:9001/v1/"
|
||||
)
|
||||
|
||||
server_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
|
||||
|
||||
# Fetch the server
|
||||
servers = client.servers.delete(server_id)
|
||||
@ -213,10 +213,7 @@ latex_documents = [
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
('index', 'designateclient', u'Designate Client Documentation',
|
||||
[u'Managed I.T.'], 1)
|
||||
]
|
||||
#man_pages = []
|
||||
|
||||
# If true, show URL addresses after external links.
|
||||
#man_show_urls = False
|
||||
|
||||
@ -16,8 +16,7 @@ Contents
|
||||
:maxdepth: 1
|
||||
|
||||
installation
|
||||
api
|
||||
api-examples
|
||||
bindings
|
||||
shell
|
||||
shell-examples
|
||||
contributing
|
||||
|
||||
@ -25,7 +25,7 @@ params, but it's easier to just set them as environment variables::
|
||||
You will also need to define the authentication url with ``--os-auth-url``
|
||||
or set is as an environment variable as well::
|
||||
|
||||
export OS_AUTH_URL=http://example.com:5000/v2.0/
|
||||
export OS_AUTH_URL=https://example.com:5000/v2.0/
|
||||
|
||||
Since Keystone can return multiple regions in the Service Catalog, you
|
||||
can specify the one you want with ``--os-region-name`` (or
|
||||
|
||||
Loading…
Reference in New Issue
Block a user