openstack/python-designateclient
Code Issues Proposed changes

first drop of python-designateclient docs

Browse Source 
Change-Id: Iecad349608bdc391b1c8613bac55b37f2719be19
This commit is contained in:
Simon McCartney
2013-09-19 16:17:12 +01:00
parent 76a37fa37c
commit 472ec278d4
7 changed files with 331 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/source/api-examples.rst Normal file
View File

@@ -0,0 +1,5 @@
========================================
designateclient python module - examples
========================================
TODO

4
doc/source/api.rst Normal file
View File

@@ -0,0 +1,4 @@
designateclient python module
=============================
TODO

33
doc/source/contributing.rst Normal file
View File

@@ -0,0 +1,33 @@
Contributing
============
Code is hosted `on GitHub`_. Submit bugs to the Designate project on
`Launchpad`_. Submit code to the stackforge/python-designateclient project using
`Gerrit`_.
.. _on GitHub: https://github.com/stackforge/python-designateclient
.. _Launchpad: https://launchpad.net/designate
.. _Gerrit: http://wiki.openstack.org/GerritWorkflow
Here's a quick summary:
Install the git-review package to make life easier
.. code-block:: shell-session
pip install git-review
Branch, work, & submit:
.. code-block:: shell-session
# cut a new branch, tracking master
git checkout --track -b bug/id origin/master
# work work work
git add stuff
git commit
# rebase/squash to a single commit before submitting
git rebase -i
# submit
git-review

27
doc/source/index.rst
View File

@@ -1,16 +1,26 @@
.. designate documentation master file, created by
sphinx-quickstart on Wed Oct 31 18:58:17 2012.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
======================
python-designateclient
======================
Welcome to designateclients's documentation!
===================================
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`).
Contents:
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.
Contents
======================
.. toctree::
:maxdepth: 2
:maxdepth: 1
installation
api
api-examples
shell
shell-examples
contributing
Indices and tables
==================
@@ -19,3 +29,4 @@ Indices and tables
* :ref:`modindex`
* :ref:`search`
.. _Cloud DNS: http://www.hpcloud.com/products-services/dns

45
doc/source/installation.rst Normal file
View File

@@ -0,0 +1,45 @@
============
Installation
============
Install the client from PyPI
----------------------------
The :program:`python-designateclient` package is published on `PyPI`_ and so can be installed using the pip tool, which will manage installing all
python dependencies:
.. code-block:: shell-session
pip install python-designateclient
*Warning: the packages on PyPI may lag behind the git repo in functionality.*
Setup the client from source
----------------------------
If you want the latest version, straight from github:
.. code-block:: shell-session
git clone git@github.com:stackforge/python-designateclient.git
cd python-designateclient
virtualenv .venv
. .venv/bin/activate
pip install -r requirements.txt -r test-requirements.txt
python setup.py install
Setup the client in development mode
------------------------------------
Installing in development mode allows your to make changes to the source code & test directly without having to re-run the "python setup.py install"
step. You can find out more about `Development Mode`_
.. code-block:: shell-session
git clone git@github.com:stackforge/python-designateclient.git
cd python-designateclient
virtualenv .venv
. .venv/bin/activate
pip install -r requirements.txt -r test-requirements.txt
python setup.py develop
.. _Development Mode: http://pythonhosted.org/distribute/setuptools.html#development-mode
.. _PyPI: https://pypi.python.org/pypi/python-designateclient/

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

@@ -0,0 +1,34 @@
======================================
designate command line tool - examples
======================================
Using the client against your dev environment
---------------------------------------------
Typically the designate client talks to Keystone (or a Keystone like service) via the OS_AUTH_URL setting & retrives the designate endpoint from the returned service catalog. Using ``--os-endpoint`` or ``OS_ENDPOINT`` you can specify the end point directly, this is useful if you want to point the client at a test environment that's running without a full Keystone service.
.. code-block:: shell-session
$ designate --os-endpoint http://127.0.0.1:9001/v1 server-create --name ns.foo.com.
+------------+--------------------------------------+
| Field | Value |
+------------+--------------------------------------+
| created_at | 2013-07-09T13:20:23.664811 |
| id | 1af2d561-b802-44d7-8208-46475dcd45f9 |
| name | ns.foo.com. |
| updated_at | None |
+------------+--------------------------------------+
$ designate --os-endpoint http://127.0.0.1:9001/v1 domain-create --name testing123.net. --email simon@mccartney.ie
+------------+--------------------------------------+
| Field | Value |
+------------+--------------------------------------+
| name | testing123.net. |
| created_at | 2013-07-09T13:20:30.826155 |
| updated_at | None |
| id | 5c02c519-4928-4a38-bd10-c748c200912f |
| ttl | 3600 |
| serial | 1373376030 |
| email | simon@mccartney.ie |
+------------+--------------------------------------+
$ designate --os-endpoint http://127.0.0.1:9001/v1 record-create --name myhost.testing123.net. --type A --data 1.2.3.4 5c02c519-4928-4a38-bd10-c748c200912f

191
doc/source/shell.rst Normal file
View File

@@ -0,0 +1,191 @@
===========================
designate command line tool
===========================
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
displayed.
Credentials
-----------
As with any OpenStack utility, :program:`designate` requires certain information to
talk to the REST API, username, password, auth url (from where the other required
endpoints are retrieved once you are authenticated).
To provide your access credentials (username, password, tenant name or tenant id)
you can pass them on the command line with the ``--os-username``, ``--os-password``, ``--os-tenant-name`` or ``--os-tenant-id``
params, but it's easier to just set them as environment variables::
export OS_USERNAME=openstack
export OS_PASSWORD=yadayada
export OS_TENANT_NAME=myproject
export OS_TENANT_ID=123456789
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/
Since Keystone can return multiple regions in the Service Catalog, you
can specify the one you want with ``--os-region-name`` (or
``export OS_REGION_NAME``). It defaults to the first in the list returned.
Using the command line tool
---------------------------
With enough details now in environment, you can use the designate client to create a domain & populate it with some records:
.. code-block:: shell-session
$ designate domain-create --name doctestdomain.eu. --email admin@doctestdomain.eu
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| description | None |
| created_at | 2013-09-19T11:45:25.295355 |
| updated_at | None |
| email | admin@doctestdomain.eu |
| ttl | 3600 |
| serial | 1379591125 |
| id | eacbe2a5-95f1-4a9f-89f5-b9c58009b163 |
| name | doctestdomain.eu. |
+-------------+--------------------------------------+
You can see more details on the arguments domain-create accepts at the `REST API create-domain`_.
Now that the domain has been created, we can start adding records.
You'll note that the name (www.doctestdomain.eu) has a trailing ``.``, as per the DNS standard, we didn't set a TTL and we had to specify the parent
zone/domain by domain_id ``eacbe2a5-95f1-4a9f-89f5-b9c58009b163``.
.. code-block:: shell-session
$ designate record-create eacbe2a5-95f1-4a9f-89f5-b9c58009b163 --name www.doctestdomain.eu. --type A --data 1.2.3.4
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| name | www.doctestdomain.eu. |
| data | 1.2.3.4 |
| created_at | 2013-09-19T13:44:42.295428 |
| updated_at | None |
| id | 147f6082-8466-4951-8d13-37a10e92b11e |
| priority | None |
| ttl | None |
| type | A |
| domain_id | eacbe2a5-95f1-4a9f-89f5-b9c58009b163 |
| description | None |
+-------------+--------------------------------------+
subcommands
-----------
We've already seen the ``domain-create`` and ``record-create`` subcommands, here the full list of subcommands:
======================= ====================================================== ===============
subcommand Notes Admin Required
======================= ====================================================== ===============
diagnostics-ping Ping a service on a given host
diagnostics-sync-all Sync Everything
diagnostics-sync-domain Sync a single Domain
diagnostics-sync-record Sync a single Record
domain-create Create Domain
domain-delete Delete Domain
domain-get Get Domain
domain-list List Domains
domain-servers-list List Domain Servers
domain-update Update Domain
help print detailed help for another command
record-create Create Record
record-delete Delete Record
record-get Get Record
record-list List Records
record-update Update Record
report-count-all Get count totals for all tenants, domains and records
report-count-domains Get counts for total domains
report-count-records Get counts for total records
report-count-tenants Get counts for total tenants
report-tenant-domains Get a list of domains for given tenant
report-tenants-all Get list of tenants and domain count for each
server-create Create Server
server-delete Delete Server
server-get Get Server
server-list List Servers
server-update Update Server
======================= ====================================================== ===============
Builtin designate documentation
-------------------------------
You'll find complete documentation on the shell by running
``designate --help``::
usage: designate [--version] [-v] [--log-file LOG_FILE] [-q] [-h] [--debug]
[--os-endpoint OS_ENDPOINT] [--os-auth-url OS_AUTH_URL]
[--os-username OS_USERNAME] [--os-password OS_PASSWORD]
[--os-tenant-id OS_TENANT_ID]
[--os-tenant-name OS_TENANT_NAME] [--os-token OS_TOKEN]
[--os-service-type OS_SERVICE_TYPE]
[--os-region-name OS_REGION_NAME]
[--sudo-tenant-id SUDO_TENANT_ID] [--insecure]
Designate Client
optional arguments:
--version show program's version number and exit
-v, --verbose Increase verbosity of output. Can be repeated.
--log-file LOG_FILE Specify a file to log output. Disabled by default.
-q, --quiet suppress output except warnings and errors
-h, --help show this help message and exit
--debug show tracebacks on errors
--os-endpoint OS_ENDPOINT
Defaults to env[OS_DNS_ENDPOINT]
--os-auth-url OS_AUTH_URL
Defaults to env[OS_AUTH_URL]
--os-username OS_USERNAME
Defaults to env[OS_USERNAME]
--os-password OS_PASSWORD
Defaults to env[OS_PASSWORD]
--os-tenant-id OS_TENANT_ID
Defaults to env[OS_TENANT_ID]
--os-tenant-name OS_TENANT_NAME
Defaults to env[OS_TENANT_NAME]
--os-token OS_TOKEN Defaults to env[OS_SERVICE_TOKEN]
--os-service-type OS_SERVICE_TYPE
Defaults to env[OS_DNS_SERVICE_TYPE], or 'dns'
--os-region-name OS_REGION_NAME
Defaults to env[OS_REGION_NAME]
--sudo-tenant-id SUDO_TENANT_ID
Defaults to env[DESIGNATE_SUDO_TENANT_ID]
--insecure Explicitly allow 'insecure' SSL requests
Commands:
diagnostics-ping Ping a service on a given host
diagnostics-sync-all Sync Everything
diagnostics-sync-domain Sync a single Domain
diagnostics-sync-record Sync a single Record
domain-create Create Domain
domain-delete Delete Domain
domain-get Get Domain
domain-list List Domains
domain-servers-list List Domain Servers
domain-update Update Domain
help print detailed help for another command
record-create Create Record
record-delete Delete Record
record-get Get Record
record-list List Records
record-update Update Record
report-count-all Get count totals for all tenants, domains and records
report-count-domains Get counts for total domains
report-count-records Get counts for total records
report-count-tenants Get counts for total tenants
report-tenant-domains Get a list of domains for given tenant
report-tenants-all Get list of tenants and domain count for each
server-create Create Server
server-delete Delete Server
server-get Get Server
server-list List Servers
server-update Update Server
.. _REST API create-domain: https://designate.readthedocs.org/en/latest/rest/domains.html#create-domain