diff --git a/doc/source/api-examples.rst b/doc/source/api-examples.rst new file mode 100644 index 0000000..1ef4985 --- /dev/null +++ b/doc/source/api-examples.rst @@ -0,0 +1,5 @@ +======================================== +designateclient python module - examples +======================================== + +TODO diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000..986c0e7 --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,4 @@ +designateclient python module +============================= + +TODO diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000..87665cd --- /dev/null +++ b/doc/source/contributing.rst @@ -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 + diff --git a/doc/source/index.rst b/doc/source/index.rst index e201836..7d0a1c0 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000..41b47ca --- /dev/null +++ b/doc/source/installation.rst @@ -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/ diff --git a/doc/source/shell-examples.rst b/doc/source/shell-examples.rst new file mode 100644 index 0000000..cee605b --- /dev/null +++ b/doc/source/shell-examples.rst @@ -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 diff --git a/doc/source/shell.rst b/doc/source/shell.rst new file mode 100644 index 0000000..7368935 --- /dev/null +++ b/doc/source/shell.rst @@ -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