From 3df130af12d098f5cf17a62f29b6d10eb9244159 Mon Sep 17 00:00:00 2001 From: Michael Chapman Date: Thu, 10 Jun 2021 17:33:03 +1000 Subject: [PATCH] TLD Doc update Add some more detail to the TLD admin doc. Replace API calls with cli. Change-Id: If9e7d1ac3a8d518ed445ad76ce5175f40408a02a --- doc/source/admin/tlds.rst | 126 +++++++++++++------------------------- 1 file changed, 42 insertions(+), 84 deletions(-) diff --git a/doc/source/admin/tlds.rst b/doc/source/admin/tlds.rst index 278923def..4ca6a8fe1 100644 --- a/doc/source/admin/tlds.rst +++ b/doc/source/admin/tlds.rst @@ -18,108 +18,66 @@ Managing Top Level Domain Names =============================== -Designate allows management of the Top-Level Domains (TLDs) that users are -allowed to create zones within. +`System Administrators`_ can use top level domains (TLDs) to restrict the +domains under which users can create zones. While in the Domain Name System +the term "TLD" refers specifically to the set of domains that lie directly +below the root, such as ``.org``, in Designate a TLD can be any domain. -For example, it's simple to only allow users to create zones that end in -``.com.`` TLD. - -By default, all TLDs are allowed in Designate, this is ok for most scenarios. - -If for example you wanted to restrict to only ``.com.`` though, you could make -the following API call. - -.. code-block:: http - - POST /v2/tlds HTTP/1.1 - Accept: application/json - Content-Type: application/json - - { - "name": "com" - } - -Response: - -.. code-block:: http - - HTTP/1.1 201 CREATED - Content-Type: application/json - X-Openstack-Request-Id: req-432e72b4-f4e1-4f9c-8e35-53decc752260 - - { - "id": "2f8bc76d-1701-4323-a101-248e09471342", - "name": "com", - "description": null, - "created_at": "2020-06-01T16:25:44.000000", - "updated_at": null, - "links": { - "self": "http://127.0.0.1:9001/v2/tlds/2f8bc76d-1701-4323-a101-248e09471342" - } - } - -Using the command line client: +For example, if you want to require that users create zones ending in +``.org.``, this can be achieved by creating a single ``.org`` TLD: .. code-block:: console - $ openstack tld create --name com + $ openstack tld create --name org +-------------+--------------------------------------+ | Field | Value | +-------------+--------------------------------------+ - | created_at | 2020-06-01T16:25:44.000000 | + | created_at | 2021-06-10T05:20:16.000000 | | description | None | - | id | 2f8bc76d-1701-4323-a101-248e09471342 | - | name | com | + | id | 9fd0a12d-511e-4024-bf76-6ec2e3e71edd | + | name | org | | updated_at | None | +-------------+--------------------------------------+ -Now, if someone were to try and create ``example.net.``, they would encounter -an error: +.. note:: When using the `openstack tld` command, ensure that the FQDN that + you enter has no trailing dot (`example.net.`). -.. code-block:: http - - POST /v2/zones HTTP/1.1 - Accept: application/json - Content-Type: application/json - - { - "name": "example.net.", - "type": "PRIMARY", - "email": "admin@example.net" - } - -.. code-block:: http - - HTTP/1.1 400 BAD REQUEST - Content-Type: application/json - X-Openstack-Request-Id: req-3a8985fd-0155-4dd4-a7fb-584b140f1f59 - - { - "code": 400, - "type": "invalid_zone_name", - "message": "Invalid TLD", - "request_id": "req-3a8985fd-0155-4dd4-a7fb-584b140f1f59" - } - -Using the command line client: +If you now attempt to create a zone that does not lie within the ``.org`` TLD, +it will fail: .. code-block:: console - $ openstack zone create --email admin@example.net example.net. + $ openstack zone create --email admin@test.net test.net. Invalid TLD -TLDs can be deleted, just like many other resources in the API, using -``DELETE /v2/tlds/``: +TLDs are much like an allowlist: if there are many TLDs then the +zone must exist within one of the TLDs. If no TLDs have been created in +Designate, then users can create any zone. Unlike the blacklists feature, TLDs +do not have a policy that allows priviliged users to create zones outside the +allowed TLDs. -.. code-block:: http - - DELETE /v2/tlds/2f8bc76d-1701-4323-a101-248e09471342 HTTP/1.1 - Accept: application/json - Content-Type: application/json - -Or by using the command line client: +You can modify the values for a TLD using the `set` command. You can use either +the name or the ID to specify which TLD to set: .. code-block:: console - $ openstack tld delete com - TLD com was deleted + $ openstack tld set org --name example.net + +-------------+--------------------------------------+ + | Field | Value | + +-------------+--------------------------------------+ + | created_at | 2021-06-10T05:20:16.000000 | + | description | | + | id | 9fd0a12d-511e-4024-bf76-6ec2e3e71edd | + | name | example.net | + | updated_at | 2021-06-10T07:09:45.000000 | + +-------------+--------------------------------------+ + +You can delete a TLD by providing either the ID or the current name: + +.. code-block:: console + + $ openstack tld delete org + +This command has no output when completed successfully. + +.. _System Administrators: https://docs.openstack.org/keystone/latest/admin/service-api-protection.html#system-personas