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