69f4597bf1
As keystoneclient's Session and auth plugins have been deprecated in favor of keystoneauth, the documentation examples must reflect that. This patch updates all examples in order to show keystoneauth Session usage instead of deprecated keystoneclient Session. Also, the python API bindings were updated too. Change-Id: I4b64fee4f526cc5b4a5e36cc8edb61164ceded51
538 lines
13 KiB
ReStructuredText
538 lines
13 KiB
ReStructuredText
===========================
|
|
Python Bindings - v1 and v2
|
|
===========================
|
|
|
|
The python-designateclient package comes with python bindings for both versions
|
|
of the Designate API: v1 and v2. These can be used to interact with the Designate
|
|
API from any python program.
|
|
|
|
Introduction - Bindings v2
|
|
==========================
|
|
|
|
To view examples of usage please checkout the *doc/examples* folder, basic usage is:
|
|
|
|
.. code-block:: python
|
|
|
|
#!/usr/bin/env python
|
|
from designateclient.v2 import client
|
|
from designateclient import shell
|
|
|
|
from keystoneauth1.identity import generic
|
|
from keystoneauth1 import session as keystone_session
|
|
|
|
|
|
auth = generic.Password(
|
|
auth_url=shell.env('OS_AUTH_URL'),
|
|
username=shell.env('OS_USERNAME'),
|
|
password=shell.env('OS_PASSWORD'),
|
|
project_name=shell.env('OS_PROJECT_NAME'),
|
|
project_domain_id='default',
|
|
user_domain_id='default')
|
|
|
|
session = keystone_session.Session(auth=auth)
|
|
|
|
client = client.Client(session=session)
|
|
|
|
zone = client.zones.create('i.io.', email='i@i.io')
|
|
|
|
rs = client.recordsets.create(zone['id'], 'www', 'A', ['10.0.0.1'])
|
|
|
|
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 __future__ import print_function
|
|
from designateclient.v1 import Client
|
|
|
|
|
|
# Create an instance of the client, providing the necessary credentials
|
|
client = Client(
|
|
auth_url="https://example.com:5000/v3/",
|
|
username="openstack",
|
|
password="yadayada",
|
|
project_name="myproject",
|
|
project_domain_id='default',
|
|
user_domain_id='default')
|
|
|
|
# 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 using keystoneauth
|
|
Sessions. For more information on keystoneauth API, see `Using Sessions`_.
|
|
|
|
.. _Using Sessions: http://docs.openstack.org/developer/keystoneauth/using-sessions.html
|
|
|
|
.. code-block:: python
|
|
|
|
#!/usr/bin/env python
|
|
|
|
from designateclient.v1 import Client
|
|
|
|
from keystoneauth1.identity import generic
|
|
from keystoneauth1 import session as keystone_session
|
|
|
|
|
|
# Create an authentication plugin providing the necessary credentials
|
|
auth = generic.Password(
|
|
auth_url="https://example.com:5000/v3/",
|
|
username="openstack",
|
|
password="yadayada",
|
|
project_name="myproject",
|
|
project_domain_id='default',
|
|
user_domain_id='default'
|
|
)
|
|
|
|
session = keystone_session.Session(auth=auth)
|
|
|
|
# Create an instance of the client, providing a keystoneauth Session
|
|
client = Client(session=session)
|
|
|
|
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
|
|
|
|
from keystoneauth1.identity import generic
|
|
from keystoneauth1 import session as keystone_session
|
|
|
|
|
|
# Create an authentication plugin providing the necessary credentials
|
|
auth = generic.Password(
|
|
auth_url="https://example.com:5000/v3/",
|
|
username="openstack",
|
|
password="yadayada",
|
|
project_name="myproject",
|
|
project_domain_id='default',
|
|
user_domain_id='default')
|
|
|
|
session = keystone_session.Session(auth=auth)
|
|
|
|
# Create an instance of the client, providing a keystoneauth Session
|
|
client = Client(
|
|
session=session,
|
|
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
|
|
description Domain Description
|
|
======================= =======================================================
|
|
|
|
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
|
|
description Record Description
|
|
======================= =======================================================
|
|
|
|
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", data="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(domain_id, 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(domain_id, 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)
|