openstack/python-designateclient
Code Issues Proposed changes

Update cli docs

Browse Source 
Marked V1 API docs as deprecated
Moved to "example.(org|net|com). domains
Removed servers cli examples (as they are now dangerous with v2 API)

Change-Id: I3e1fa170dc189cc5dac608a9aecacd9127a2233e
This commit is contained in:
Graham Hayes 2017-07-10 11:52:28 +01:00
parent 3bb401758c
commit 4e7b853e30
2 changed files with 36 additions and 67 deletions

67
doc/source/shell-examples.rst

@ -2,37 +2,39 @@
Designate Command Line Tool Examples Designate Command Line Tool Examples
==================================== ====================================
.. warning:: This page refers to command that use the V1 API, which is currently disabled, and will be removed in a future release
Using the client against your dev environment 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. 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 .. code-block:: shell-session
$ designate --os-endpoint http://127.0.0.1:9001/v1 server-create --name ns.foo.com. $ designate --os-endpoint http://127.0.0.1:9001/v1 server-create --name ns.example.com.
+------------+--------------------------------------+ +------------+--------------------------------------+
| Field | Value | | Field | Value |
+------------+--------------------------------------+ +------------+--------------------------------------+
| id | 3dee78df-c6b8-4fbd-8e89-3186c1a4734f | | id | 3dee78df-c6b8-4fbd-8e89-3186c1a4734f |
| created_at | 2015-11-04T08:47:12.000000 | | created_at | 2015-11-04T08:47:12.000000 |
| updated_at | None | | updated_at | None |
| name | ns.foo.com. | | name | ns.example.com. |
+------------+--------------------------------------+ +------------+--------------------------------------+
$ designate --os-endpoint http://127.0.0.1:9001/v1 domain-create --name testing123.net. --email me@mydomain.com $ designate --os-endpoint http://127.0.0.1:9001/v1 domain-create --name example.net. --email me@example.org
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| Field | Value | | Field | Value |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| description | None | | description | None |
| created_at | 2015-11-04T08:49:53.000000 | | created_at | 2015-11-04T08:49:53.000000 |
| updated_at | None | | updated_at | None |
| email | me@mydomain.com | | email | me@example.org |
| ttl | 3600 | | ttl | 3600 |
| serial | 1446626993 | | serial | 1446626993 |
| id | f98c3d91-f514-4956-a955-20eefb413a64 | | id | f98c3d91-f514-4956-a955-20eefb413a64 |
| name | testing123.net. | | name | example.net. |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
$ designate --os-endpoint http://127.0.0.1:9001/v1 record-create --name myhost.testing123.net. --type A --data 1.2.3.4 f98c3d91-f514-4956-a955-20eefb413a64 (domain_id) $ designate --os-endpoint http://127.0.0.1:9001/v1 record-create --name myhost.example.net. --type A --data 1.2.3.4 f98c3d91-f514-4956-a955-20eefb413a64 (domain_id)
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| Field | Value | | Field | Value |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
@ -45,29 +47,29 @@ Typically the designate client talks to Keystone (or a Keystone like service) vi
| ttl | None | | ttl | None |
| data | 1.2.3.4 | | data | 1.2.3.4 |
| id | b5a74471-8062-4395-be70-968805a0d832 | | id | b5a74471-8062-4395-be70-968805a0d832 |
| name | myhost.testing123.net. | | name | myhost.example.net. |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
$ designate domain-list $ designate domain-list
+--------------------------------------+-------------+------------+ +--------------------------------------+--------------+------------+
| id | name | serial | | id | name | serial |
+--------------------------------------+-------------+------------+ +--------------------------------------+--------------+------------+
| 88c14ecf-b034-424c-b081-ca42494dcdf9 | sample.com. | 1462372104 | | 88c14ecf-b034-424c-b081-ca42494dcdf9 | example.com. | 1462372104 |
+--------------------------------------+-------------+------------+ +--------------------------------------+--------------+------------+
$ designate domain-update --email sample@example.com 88c14ecf-b034-424c-b081-ca42494dcdf9 (domain_id) $ designate domain-update --email example@example.com 88c14ecf-b034-424c-b081-ca42494dcdf9 (domain_id)
+-------------+--------------------------------------+ +-------------+---------------------------------------+
| Field | Value | | Field | Value |
+-------------+--------------------------------------+ +-------------+---------------------------------------+
| description | None | | description | None |
| created_at | 2016-05-04T14:28:24.000000 | | created_at | 2016-05-04T14:28:24.000000 |
| updated_at | 2016-05-04T14:29:48.000000 | | updated_at | 2016-05-04T14:29:48.000000 |
| email | sample@example.com | | email | example@example.com |
| ttl | 3600 | | ttl | 3600 |
| serial | 1462372188 | | serial | 1462372188 |
| id | 88c14ecf-b034-424c-b081-ca42494dcdf9 | | id | 88c14ecf-b034-424c-b081-ca42494dcdf9 |
| name | sample.com. | | name | example.com. |
+-------------+--------------------------------------+ +-------------+---------------------------------------+
$ designate domain-delete 88c14ecf-b034-424c-b081-ca42494dcdf9 (domain_id) $ designate domain-delete 88c14ecf-b034-424c-b081-ca42494dcdf9 (domain_id)
@ -99,37 +101,6 @@ Typically the designate client talks to Keystone (or a Keystone like service) vi
$ designate record-delete 66584cdd-f7a6-4f0e-acf0-3dd5ad04830d (domain-id) 7e80531d-bd65-49bc-a316-a6a06cd7fe26 (record_id) $ designate record-delete 66584cdd-f7a6-4f0e-acf0-3dd5ad04830d (domain-id) 7e80531d-bd65-49bc-a316-a6a06cd7fe26 (record_id)
$ designate server-update --name abc.org. 3d9d220d-d111-436a-b9bb-e7bc0e275803 (server_id)
+------------+--------------------------------------+
| Field | Value |
+------------+--------------------------------------+
| updated_at | None |
| created_at | 2016-05-04T16:17:16.000000 |
| id | 3d9d220d-d111-436a-b9bb-e7bc0e275803 |
| name | abc.org. |
+------------+--------------------------------------+
$ designate server-list
+--------------------------------------+------------------+
| id | name |
+--------------------------------------+------------------+
| 4f6f0cbe-ea38-453e-97c5-091617a06b41 | ns1.example.org. |
| 326de09b-691e-4e4e-bf1c-5a1bf7e7f44d | xyz.com. |
| 3d9d220d-d111-436a-b9bb-e7bc0e275803 | abc.org. |
+--------------------------------------+------------------+
$ designate server-get 3d9d220d-d111-436a-b9bb-e7bc0e275803 (server_id)
+------------+--------------------------------------+
| Field | Value |
+------------+--------------------------------------+
| updated_at | 2016-05-04T16:18:06.000000 |
| created_at | 2016-05-04T16:17:16.000000 |
| id | 3d9d220d-d111-436a-b9bb-e7bc0e275803 |
| name | abc.org. |
+------------+--------------------------------------+
$ designate server-delete 3d9d220d-d111-436a-b9bb-e7bc0e275803 (server_id)
$ designate quota-get 70a4596c9974429db5fb6fe240ab87b9 (tenant_id) $ designate quota-get 70a4596c9974429db5fb6fe240ab87b9 (tenant_id)
+-------------------+-------+ +-------------------+-------+
| Field | Value | | Field | Value |

18
doc/source/shell.rst

@ -2,6 +2,8 @@
Designate Command Line Tool (compatible with v1 API only) Designate Command Line Tool (compatible with v1 API only)
========================================================= =========================================================
.. warning:: This page refers to command that use the V1 API, which is currently disabled, and will be removed in a future release
The python-designateclient package comes with a command line tool (installed as :program:`designate`), this can be used to access a Designate API 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 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. displayed.
@ -38,34 +40,32 @@ With enough details now in the environment, you can use the designate client to
.. code-block:: shell-session .. code-block:: shell-session
$ designate domain-create --name doctestdomain.eu. --email admin@doctestdomain.eu $ designate domain-create --name example.com. --email admin@example.com
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| Field | Value | | Field | Value |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| description | None | | description | None |
| created_at | 2013-09-19T11:45:25.295355 | | created_at | 2013-09-19T11:45:25.295355 |
| updated_at | None | | updated_at | None |
| email | admin@doctestdomain.eu | | email | admin@example.com |
| ttl | 3600 | | ttl | 3600 |
| serial | 1379591125 | | serial | 1379591125 |
| id | eacbe2a5-95f1-4a9f-89f5-b9c58009b163 | | id | eacbe2a5-95f1-4a9f-89f5-b9c58009b163 |
| name | doctestdomain.eu. | | name | example.com. |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
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. 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 You'll note that the name (www.example.com) 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``. zone/domain by domain_id ``eacbe2a5-95f1-4a9f-89f5-b9c58009b163``.
.. code-block:: shell-session .. code-block:: shell-session
$ designate record-create eacbe2a5-95f1-4a9f-89f5-b9c58009b163 --name www.doctestdomain.eu. --type A --data 1.2.3.4 $ designate record-create eacbe2a5-95f1-4a9f-89f5-b9c58009b163 --name www.example.com. --type A --data 1.2.3.4
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| Field | Value | | Field | Value |
+-------------+--------------------------------------+ +-------------+--------------------------------------+
| name | www.doctestdomain.eu. | | name | www.example.com. |
| data | 1.2.3.4 | | data | 1.2.3.4 |
| created_at | 2013-09-19T13:44:42.295428 | | created_at | 2013-09-19T13:44:42.295428 |
| updated_at | None | | updated_at | None |
@ -244,5 +244,3 @@ Commands:
sync-domain Sync a single Domain sync-domain Sync a single Domain
sync-record Sync a single Record sync-record Sync a single Record
touch-domain Touch a single Domain touch-domain Touch a single Domain
.. _REST API create-domain: https://designate.readthedocs.org/en/latest/rest/domains.html#create-domain