From d4a5555e52929c440ff5cfa1c422892a6cf54370 Mon Sep 17 00:00:00 2001 From: Rahman Syed Date: Tue, 19 Apr 2016 16:41:53 -0500 Subject: [PATCH] Improve python-designateclient docs * 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 --- doc/source/bindings.rst | 12 +- doc/source/conf.py | 2 +- doc/source/index.rst | 24 +++- doc/source/shell-examples.rst | 6 +- doc/source/shell-v2-examples.rst | 235 +++++++++++++++++++++++++++++++ doc/source/shell-v2.rst | 149 ++++++++++++++++---- doc/source/shell.rst | 6 +- tox.ini | 4 + 8 files changed, 395 insertions(+), 43 deletions(-) create mode 100644 doc/source/shell-v2-examples.rst diff --git a/doc/source/bindings.rst b/doc/source/bindings.rst index 6795d04c..739a5049 100644 --- a/doc/source/bindings.rst +++ b/doc/source/bindings.rst @@ -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 ========================== diff --git a/doc/source/conf.py b/doc/source/conf.py index 1629dbee..1b2a8a99 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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. diff --git a/doc/source/index.rst b/doc/source/index.rst index dd893588..df0b9ffc 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -2,12 +2,23 @@ python-designateclient ====================== -This is a client for Designate API. There's a :doc:`Python API -` (the :program:`designateclient` module), and a :doc:`command-line tool -` (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 ` 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 `. + +v1: the :program:`designate` command line tool. More information can be found +on the :doc:`designate v1 command line tool page `. + +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 diff --git a/doc/source/shell-examples.rst b/doc/source/shell-examples.rst index d7d71ea9..509ef627 100644 --- a/doc/source/shell-examples.rst +++ b/doc/source/shell-examples.rst @@ -1,6 +1,6 @@ -====================================== -designate command line tool - examples -====================================== +==================================== +Designate Command Line Tool Examples +==================================== Using the client against your dev environment --------------------------------------------- diff --git a/doc/source/shell-v2-examples.rst b/doc/source/shell-v2-examples.rst new file mode 100644 index 00000000..c440eafc --- /dev/null +++ b/doc/source/shell-v2-examples.rst @@ -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 diff --git a/doc/source/shell-v2.rst b/doc/source/shell-v2.rst index 86abdb4f..68262acb 100644 --- a/doc/source/shell-v2.rst +++ b/doc/source/shell-v2.rst @@ -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 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 diff --git a/doc/source/shell.rst b/doc/source/shell.rst index 1e9e8d39..85f7e5f6 100644 --- a/doc/source/shell.rst +++ b/doc/source/shell.rst @@ -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 diff --git a/tox.ini b/tox.ini index 379f0ad0..5d0ab423 100644 --- a/tox.ini +++ b/tox.ini @@ -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