x/python-tatuclient
Code Issues Proposed changes

Improve python-designateclient docs

Browse Source 
* Improve index page to explain the difference between v1 and v2
  CLI support.
* Add a v2 examples page
* Add all supported commands to v2 shell page
* Add a tox task to build the docs
* Fix a bug building the docs with an invalid html_static_path
  config

Change-Id: Ie1e65c2d0cc8ad1b8b258e03114e19a943d1d19c
Closes-Bug: 1572217
This commit is contained in:
Rahman Syed
2016-04-19 16:41:53 -05:00
parent df20e40405
commit d4a5555e52
8 changed files with 395 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
doc/source/bindings.rst
View File

@@ -1,10 +1,10 @@
===============
Python Bindings
===============
===========================
Python Bindings - v1 and v2
===========================
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.
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
==========================

2
doc/source/conf.py
View File

@@ -121,7 +121,7 @@ html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_static_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.

24
doc/source/index.rst
View File

@@ -2,12 +2,23 @@
python-designateclient
======================
This is a client for Designate API. There's a :doc:`Python API
<api>` (the :program:`designateclient` module), and a :doc:`command-line tool
<shell>` (installed as :program:`designate`).
python-designateclient provides python bindings and command line tools for both
Designate v1 and v2 APIs.
You'll need credentials for an OpenStack cloud that is implementing the Designate API ,
such as HP's `Cloud DNS`_, in order to use the designate client.
The :doc:`Python API bindings <bindings>` are provided by the
:program:`designateclient` module.
There are two separate command line interfaces to work with the two API
versions:
v2: the designate plugin for the :program:`openstack` command line tool. More information can be
found on the :doc:`designate v2 command line tool page <shell-v2>`.
v1: the :program:`designate` command line tool. More information can be found
on the :doc:`designate v1 command line tool page <shell>`.
You'll need credentials for an OpenStack cloud that implements the Designate
API in order to use the client.
Contents
======================
@@ -17,9 +28,10 @@ Contents
installation
bindings
shell-v2
shell-v2-examples
shell
shell-examples
shell-v2
contributing
functional-tests

6
doc/source/shell-examples.rst
View File

@@ -1,6 +1,6 @@
======================================
designate command line tool - examples
======================================
====================================
Designate Command Line Tool Examples
====================================
Using the client against your dev environment
---------------------------------------------

235
doc/source/shell-v2-examples.rst Normal file
View File

@@ -0,0 +1,235 @@
====================================
Openstack Command Line Tool Examples
====================================
Because command output would make this document long, much of it will be
omitted from the examples.
Working with Zones
------------------
Create a zone with the following command:
.. code-block:: shell-session
$ openstack zone create --email admin@example.com example.com.
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | CREATE |
| created_at | 2016-04-19T17:44:04.000000 |
| description | None |
| email | admin@example.com |
| id | 388814ef-3c5d-415e-a866-5b1d13d78dae |
| masters | |
| name | example.com. |
| pool_id | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
| project_id | 123456 |
| serial | 1461087844 |
| status | PENDING |
| transferred_at | None |
| ttl | 3600 |
| type | PRIMARY |
| updated_at | None |
| version | 1 |
+----------------+--------------------------------------+
See the new zone in your list of zones with the following command:
.. code-block:: shell-session
$ openstack zone list
Display a specific zone with either of these commands; most zone commands
accept either the zone_id or name attribute:
.. code-block:: shell-session
$ openstack zone show example.com.
$ openstack zone show 388814ef-3c5d-415e-a866-5b1d13d78dae
Update the zone with this command:
.. code-block:: shell-session
$ openstack zone set --description "Description" example.com.
Delete the zone with this command:
.. code-block:: shell-session
$ openstack zone delete example.com.
Working with Recordsets
-----------------------
Using the zone above, create a recordset with the following command:
.. code-block:: shell-session
$ openstack recordset create example.com. --type A www --records 192.0.2.20
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | CREATE |
| created_at | 2016-04-19T17:51:12.000000 |
| description | None |
| id | 180d3574-3c29-4ea2-b6ff-df904bd3f126 |
| name | www.example.com. |
| records | 192.0.2.20 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | None |
| version | 1 |
| zone_id | 388814ef-3c5d-415e-a866-5b1d13d78dae |
+-------------+--------------------------------------+
Multiple records can be provided for a specific recordset type:
.. code-block:: shell-session
$ openstack recordset create example.com. --type A www --records 192.0.2.20 192.0.2.21
See the new recordset in the list of recordsets with the following command:
.. code-block:: shell-session
$ openstack recordset list example.com.
Display a specific recordset:
.. code-block:: shell-session
$ openstack recordset show example.com. www.example.com.
Update a specific recordset:
.. code-block:: shell-session
$ openstack recordset set example.com. www.example.com. --ttl 10000 --records 192.0.2.20 192.0.2.21
Delete a recordset:
.. code-block:: shell-session
$ openstack recordset delete example.com. www.example.com.
Working with PTR Records
------------------------
Reverse DNS for Neutron Floating IPs can be managed with the "ptr" subcommand.
List all PTR records:
.. code-block:: shell-session
$ openstack ptr record list
Show a PTR record:
.. code-block:: shell-session
$ openstack ptr record show RegionOne:5c02c519-4928-4a38-bd10-c748c200912f
Create a PTR record:
.. code-block:: shell-session
$ openstack ptr record set RegionOne:5c02c519-4928-4a38-bd10-c748c200912f mail.example.com.
Delete a PTR record:
.. code-block:: shell-session
$ openstack ptr record delete RegionOne:5c02c519-4928-4a38-bd10-c748c200912f
Working with Zone Exports
-------------------------
Zone exports enable you to save Designate zone information offline.
Create a zone export:
.. code-block:: shell-session
$ openstack zone export create example.com.
+------------+--------------------------------------+
| Field | Value |
+------------+--------------------------------------+
| created_at | 2016-04-19T20:42:16.000000 |
| id | 6d5acb9d-f3d6-4ed4-96e1-03bc0e405bb5 |
| location | None |
| message | None |
| project_id | 123456 |
| status | PENDING |
| updated_at | None |
| version | 1 |
| zone_id | 388814ef-3c5d-415e-a866-5b1d13d78dae |
+------------+--------------------------------------+
List zone exports:
.. code-block:: shell-session
$ openstack zone export list
Show zone export:
.. code-block:: shell-session
$ openstack zone export show 6d5acb9d-f3d6-4ed4-96e1-03bc0e405bb5
Show the zone file for the Zone Export:
.. code-block:: shell-session
$ openstack zone export showfile 6d5acb9d-f3d6-4ed4-96e1-03bc0e405bb5 -f value
$ORIGIN example.com.
$TTL 3600
example.com. IN NS ns2.exampleprovider.com.
example.com. IN NS ns1.exampleprovider.com.
example.com. IN SOA ns.exampleprovider.com. admin@example.com 1458678636 7200 300 604800 300
Delete zone export:
.. code-block:: shell-session
$ openstack zone export delete 6d5acb9d-f3d6-4ed4-96e1-03bc0e405bb5
Working with Zone Imports
-------------------------
Zone imports enable you to import a zone into Designate from a file on the filesystem.
Create a zone import from a file:
.. code-block:: shell-session
$ openstack zone import create zonefile.txt
+------------+--------------------------------------+
| Field | Value |
+------------+--------------------------------------+
| created_at | 2016-04-19T20:59:38.000000 |
| id | bab6e152-da9f-4dfc-8a59-3f9710fe4894 |
| message | None |
| project_id | 123456 |
| status | PENDING |
| updated_at | None |
| version | 1 |
| zone_id | None |
+------------+--------------------------------------+
List zone imports:
.. code-block:: shell-session
$ openstack zone import list
Show zone import:
.. code-block:: shell-session
$ openstack zone import show 839d8041-1960-4d74-8533-118d52218074
Delete zone import:
.. code-block:: shell-session
$ openstack zone import delete 839d8041-1960-4d74-8533-118d52218074

149
doc/source/shell-v2.rst
View File

@@ -1,43 +1,144 @@
=============================
designate v2 cli and examples
=============================
=========================================================
Openstack Command Line Tool (compatible with v2 API only)
=========================================================
In order to use the v2 you need *python-openstackclient* available.
The python-designateclient package comes with a plugin for the openstack
command line tool (installed as :program:`openstack`). This can be used to
access a Designate API without having to manipulate JSON by hand, it can also
produce the output in a variety of formats (JSON, CSV) and allow you to select
columns to be displayed.
Installation
------------
Both *python-openstackclient* and *python-designateclient* must be installed:
::
$ pip install python-openstackclient
$ pip install python-openstackclient python-designateclient
Using the client
----------------
Configuration
-------------
Source credentials first
:program:`openstack` requires certain information to talk to the REST API. An
in-depth explanation is covered in the
`Openstack Client configuration documentation`_.
::
Using the Command Line Tool
---------------------------
$ source ~/openrc
Or you can use the ~/.config/openstack/clouds.yaml approach.
.. note::
This required you to pass in --os-cloud <cloudname> after the "openstack" part.
We can now try to create a primary zone
With enough details now in the environment, you can use the
:program:`openstack` to create a zone and populate it with some records:
.. code-block:: shell-session
$ openstack zone create example.net. --email foo@example.org
$ openstack zone create --email admin@example.com example.com.
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | CREATE |
| created_at | 2016-04-19T17:44:04.000000 |
| description | None |
| email | admin@example.com |
| id | 388814ef-3c5d-415e-a866-5b1d13d78dae |
| masters | |
| name | example.com. |
| pool_id | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
| project_id | 123456 |
| serial | 1461087844 |
| status | PENDING |
| transferred_at | None |
| ttl | 3600 |
| type | PRIMARY |
| updated_at | None |
| version | 1 |
+----------------+--------------------------------------+
Create a A type recordset with some records in it.
Now that the zone has been created, we can start adding records.
You'll note that the zone name (example.com) has a trailing ``.``, as per
the DNS standard, and we didn't set a TTL.
.. code-block:: shell-session
$ openstack recordset create example.net --type A www --records 10.0.0.1 10.0.0.2
$ openstack recordset create --type A --records 192.0.2.20 example.com. www
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | CREATE |
| created_at | 2016-04-19T17:51:12.000000 |
| description | None |
| id | 180d3574-3c29-4ea2-b6ff-df904bd3f126 |
| name | www.example.com. |
| records | 192.0.2.20 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | None |
| version | 1 |
| zone_id | 388814ef-3c5d-415e-a866-5b1d13d78dae |
+-------------+--------------------------------------+
Set a PTR record for a Floating IP
Designate-specific Subcommands
------------------------------
.. code-block:: shell-session
Aside from the ``zone create`` and ``recordset create`` subcommands, this is
the full list of subcommands that enable Designate V2 support:
$ openstack ptr record set RegionOne:5c02c519-4928-4a38-bd10-c748c200912f mail.example.net.
============================ ====================================================== ===============
subcommand Notes Admin Required
============================ ====================================================== ===============
zone create Create new zone
zone list List zones
zone show Show zone details
zone set Set zone properties
zone delete Delete zone
recordset create Create new recordset
recordset list List recordsets
recordset show Show recordset details
recordset set Set recordset properties
recordset delete Delete recordset
ptr record list List floatingip ptr records
ptr record show Show floatingip ptr record details
ptr record set Set floatingip ptr record
ptr record unset Unset floatingip ptr record
zone export create Export a Zone
zone export list List Zone Exports
zone export show Show a Zone Export
zone export delete Delete a Zone Export
zone export showfile Show the zone file for the Zone Export
zone import create Import a Zone from a file on the filesystem
zone import list List Zone Imports
zone import show Show a Zone Import
zone import delete Delete a Zone Import
zone transfer request create Create new zone transfer request
zone transfer request list List Zone Transfer Requests
zone transfer request show Show Zone Transfer Request Details
zone transfer request set Set a Zone Transfer Request
zone transfer request delete Delete a Zone Transfer Request
zone transfer accept request Accept a Zone Transfer Request
zone transfer accept show Show Zone Transfer Accept
zone abandon Abandon a zone
zone axfr AXFR a zone
zone blacklist create Create new blacklist Yes
zone blacklist list List blacklists Yes
zone blacklist show Show blacklist details Yes
zone blacklist set Set blacklist properties Yes
zone blacklist delete Delete blacklist Yes
tld create Create new tld Yes
tld list List tlds Yes
tld show Show tld details Yes
tld set Set tld properties Yes
tld delete Delete tld Yes
============================ ====================================================== ===============
Built-in Designate Documentation
--------------------------------
You'll find complete documentation on the shell by running:
``openstack --help``
For a specific command, you can execute: ``openstack subcommand help``
.. _Openstack Client configuration documentation: http://docs.openstack.org/developer/python-openstackclient/configuration.html

6
doc/source/shell.rst
View File

@@ -1,6 +1,6 @@
===========================
designate command line tool
===========================
=========================================================
Designate Command Line Tool (compatible with v1 API only)
=========================================================
The python-designateclient package comes with a command line tool (installed as :program:`designate`), this can be used to access a Designate API
without having to manipulate JSON by hand, it can also produce the output in a variety of formats (JSON, CSV) and allow you to select columns to be

4
tox.ini
View File

@@ -21,6 +21,10 @@ commands =
sh tools/pretty_tox.sh '{posargs}'
passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY
[testenv:docs]
commands = rm -rf doc/build
sphinx-build -E -W -b html doc/source doc/build/html
[testenv:flake8]
commands = flake8