python-designateclient/doc/source/bindings.rst

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:

#!/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.

#!/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:

$ 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.

#!/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.

#!/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:

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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

#!/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)