first drop of python-designateclient docs
Change-Id: Iecad349608bdc391b1c8613bac55b37f2719be19
This commit is contained in:
Simon McCartney
parent
76a37fa37c
commit
472ec278d4
5
doc/source/api-examples.rst
Normal file
5
doc/source/api-examples.rst
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
========================================
|
||||||
|
designateclient python module - examples
|
||||||
|
========================================
|
||||||
|
|
||||||
|
TODO
|
||||||
4
doc/source/api.rst
Normal file
4
doc/source/api.rst
Normal file
@ -0,0 +1,4 @@
|
|||||||
|
designateclient python module
|
||||||
|
=============================
|
||||||
|
|
||||||
|
TODO
|
||||||
33
doc/source/contributing.rst
Normal file
33
doc/source/contributing.rst
Normal 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
|
||||||
|
|
||||||
@ -1,16 +1,26 @@
|
|||||||
.. designate documentation master file, created by
|
======================
|
||||||
sphinx-quickstart on Wed Oct 31 18:58:17 2012.
|
python-designateclient
|
||||||
You can adapt this file completely to your liking, but it should at least
|
======================
|
||||||
contain the root `toctree` directive.
|
|
||||||
|
|
||||||
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::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 1
|
||||||
|
|
||||||
|
installation
|
||||||
|
api
|
||||||
|
api-examples
|
||||||
|
shell
|
||||||
|
shell-examples
|
||||||
|
contributing
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
@ -19,3 +29,4 @@ Indices and tables
|
|||||||
* :ref:`modindex`
|
* :ref:`modindex`
|
||||||
* :ref:`search`
|
* :ref:`search`
|
||||||
|
|
||||||
|
.. _Cloud DNS: http://www.hpcloud.com/products-services/dns
|
||||||
|
|||||||
45
doc/source/installation.rst
Normal file
45
doc/source/installation.rst
Normal 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
34
doc/source/shell-examples.rst
Normal 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
191
doc/source/shell.rst
Normal 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
|
||||||
Loading…
x
Reference in New Issue
Block a user