openstack/designate
Code Issues Proposed changes

Merge "Add docs guide updates for multi-pools"

Browse Source
This commit is contained in:
Zuul 2025-01-28 11:27:06 +00:00 committed by Gerrit Code Review
commit 4d29f0b90b
6 changed files with 424 additions and 296 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

298
doc/source/admin/multiple-pools.rst
View File

@ -13,175 +13,213 @@
License for the specific language governing permissions and limitations
under the License.
.. _configpools:
===============================
How To Configure Multiple Pools
===============================
==========================
Configuring Multiple Pools
==========================
Designate supports "pools" of nameservers. A pool is a collection of
nameservers and targets that Designate will write to and read from to
confirm changes are successful. In some cases you might have multiple
pools that you need to manage differently. For example, you might use
separate pools to distribute tenants across some subset of your DNS
infrastructure.
Administrators can group DNS namespace servers into multiple pools to help
them manage their DNS environments. See :ref:`pools` to learn more about what
pools are and how you can use them.
Read the section on :ref:`pools` to learn more about what pools are
and what they can do.
Configuring Designate to use multiple pools consists of:
Pools Configuration
===================
#. Defining new pools and loading their definitions into the database.
Pools are configured by a `pools.yml` file. This file describes the
pools and can be used to update Designate via `designate-manage`
commands.
#. Configuring the pool scheduler with filters that you have created or with
filters provided by Designate.
Here is an example `pools.yml` that configures two different
pools. The idea is that we'll configure our pools to support different
usage levels. We'll define a `gold` and `standard` level and put zones
in each based on the tenant.
#. Supplying the required pool information to users to specify when they
create zones.
Our `gold` level will provide 6 nameservers that users have access to
where our `standard` will only provide 2. Both pools will have one
master target we write to.
Defining New Pools
==================
.. code-block:: yaml
In Designate, you define a new pool in a pool definition file, and then load
the definition into the Designate database by running the ``designate-manage``
command.
---
#. Add the pool to the pool definition file, by following the required key
value pairs in YAML format that are documented under "Pool Definition File"
in :ref:`pools`.
- name: golden_pool
description: The golden pool!
Here is an example of a pool definition file, ``pools.yaml``, that
configures two different pools. Each pool supports a different usage level,
`gold` and `standard`, and each contains zones that reflect their
respective usage levels.
attributes:
service_tier: gold
The `gold` level provides 6 nameservers that users have access to. The
`standard` level provides only 2 nameservers. Both pools have one target
that is written to.
ns_records:
- hostname: ns1-gold.example.org
priority: 1
.. code-block:: yaml
- hostname: ns2-gold.example.org
priority: 2
---
- hostname: ns3-gold.example.net
priority: 3
- name: golden_pool
description: The golden pool!
- hostname: ns4-gold.example.net
priority: 4
attributes:
service_tier: gold
- hostname: ns5-gold.example.net
priority: 5
ns_records:
- hostname: ns1-gold.example.org
priority: 1
- hostname: ns6-gold.example.net
priority: 6
- hostname: ns2-gold.example.org
priority: 2
nameservers:
- host: ns1-gold.example.net
port: 53
- hostname: ns3-gold.example.net
priority: 3
- host: ns2-gold.example.net
port: 53
- hostname: ns4-gold.example.net
priority: 4
- host: ns3-gold.example.net
port: 53
- hostname: ns5-gold.example.net
priority: 5
- host: ns4-gold.example.net
port: 53
- hostname: ns6-gold.example.net
priority: 6
- host: ns5-gold.example.net
port: 53
nameservers:
- host: ns1-gold.example.net
port: 53
- host: ns6-gold.example.net
port: 53
- host: ns2-gold.example.net
port: 53
targets:
- type: bind9
description: bind9 golden master
- host: ns3-gold.example.net
port: 53
masters:
- host: mdns.designate.example.com.
port: 5354
- host: ns4-gold.example.net
port: 53
options:
host: ns-master-gold.example.org
port: 53
rndc_host: ns-master-gold.example.org
rndc_port: 953
rndc_key_file: /etc/designate.rndc.key
- host: ns5-gold.example.net
port: 53
- host: ns6-gold.example.net
port: 53
targets:
- type: bind9
description: bind9 golden master
masters:
- host: mdns.designate.example.com
port: 5354
options:
host: ns-master-gold.example.org
port: 53
rndc_host: ns-master-gold.example.org
rndc_port: 953
rndc_key_file: /etc/designate.rndc.key
- name: standard_pool
description: The standard pool
- name: standard_pool
description: The standard pool
attributes:
service_tier: standard
attributes:
service_tier: standard
ns_records:
- hostname: ns1-std.example.org
priority: 1
ns_records:
- hostname: ns1-std.example.org
priority: 1
- hostname: ns2-std.example.org
priority: 2
- hostname: ns2-std.example.org
priority: 2
nameservers:
- host: ns1-std.example.net
port: 53
nameservers:
- host: ns1-std.example.net
port: 53
- host: ns2-std.example.net
port: 53
- host: ns2-std.example.net
port: 53
targets:
- type: bind9
description: bind9 golden master
targets:
- type: bind9
description: bind9 golden master
masters:
- host: mdns.designate.example.com.
port: 5354
masters:
- host: mdns.designate.example.com
port: 5354
options:
host: ns-master-std.example.org
port: 53
rndc_host: ns-master-std.example.org
rndc_port: 953
rndc_key_file: /etc/designate.rndc.key
options:
host: ns-master-std.example.org
port: 53
rndc_host: ns-master-std.example.org
rndc_port: 953
rndc_key_file: /etc/designate.rndc.key
With our configuration in place, we can then update Designate to use
the pool configuration.
#. Load the definitions into the Designate database using the
``designate-manage pool update`` command:
.. code-block:: bash
.. code-block:: bash
# Do a dry run
$ designate-manage pool update --file pools.yml --dry-run
$ designate-manage pool update --file pools.yml
# Do a dry run
$ designate-manage pool update --file pools.yaml --dry-run
$ designate-manage pool update --file pools.yaml
Designate now has two pools to work with. The next step will be to
configure the scheduler to use the attributes when choosing what pool
to store the zone on.
Designate now has two pools to work with. The next step is to configure the
pool scheduler to use the attributes--provided through filters--when
choosing the pool to store the zone on.
Showing the configured pools
============================
Pool Scheduler
==============
In Designate, you can show the current configured default pool by running the
``designate-manage pool show_config`` command.
You can either see a different pool by adding --pool_id <POOL_ID>, or you can
see all the configured pools by adding ``--all_pools`` or just ``--all``.
The pool scheduler allows selecting a pool when a zone is
created. Each scheduler acts as a filter, selecting or negating each
pool based on some attributes. Designate comes with some simple
schedulers to support common patterns:
Configuring the Pool Scheduler
==============================
- default_pool
- fallback
- random
- pool_id_attribute
- attribute
When a user creates a zone, the pool scheduler uses filters to assign the zone
to a particular DNS server pool. As the administrator, you choose an ordered
list of filters that runs on each ``zone create`` API request. You configure
the scheduler to use filters that are provided with Designate or create
your own.
These are configured in the `service:central` section of the
config.
#. Do one of the following:
- Write one or more custom filters.
See :ref:`poolsched`.
- Choose one or more of the filters that Designate provides:
- ``attribute``--assigns the zone to the pool whose attribute is
specified.
- ``pool_id_attribute``--if the user is a member of the specified role
assigns the zone to the pool whose ID is specified.
- ``default_pool``--assigns the zone to the default pool specified in the
Designate configuration file.
- ``fallback``--if there are no pools available, assigns the zone to the
default pool.
- ``random``--if multiple pools have been specified, randomly assigns the
zone to a pool.
- ``in_doubt_default_pool``--if none of the specified pools are
available, and the default pool has not been specified, assigns the
zone to the default pool.
#. Add the filters that you want the scheduler to use in the
``service:central`` section of the ``designate.conf`` file. See
:ref:`poolsched` for more information.
Schedule by Pool ID Example
---------------------------
For example, if we wanted to allow a user to select a specific pool by
id or fallback to using a default, we could use the following
configuration.
For example, to allow a user to select a pool by specifying an ID or
fallback to using a default, you could use the following configuration:
.. code-block:: ini
@ -189,16 +227,16 @@ configuration.
default_pool_id = 794ccc2c-d751-44fe-b57f-8894c9f5c842
scheduler_filters = pool_id_attribute, fallback
The filters are applied from left to right. If the zone body doesn't
contain an `attributes` object with a `pool_id` set to a valid pool
id, the fallback filter is then called, returning the default pool as
the scheduled pool for that zone.
The pool scheduler applies filters from left to right. If the zone body
doesn't contain an `attributes` object with a `pool_id` set to a valid pool
ID, the fallback filter is then called, returning the default pool as the
scheduled pool for that zone.
Schedule by Tier Example
------------------------
In our tiered example, we'll use the `attribute` filter to select the
In this tier example, the `attribute` filter is used to select the
correct pool.
.. code-block:: ini
@ -207,8 +245,8 @@ correct pool.
default_pool_id = 794ccc2c-d751-44fe-b57f-8894c9f5c842 # the std pool
scheduler_filters = attribute, fallback
When a user needs the zone to go to the `gold` pool, the user needs to
provide the appropriate attribute in the zone.
When a user wants to assign a zone to the `gold` pool, the user must provide
the appropriate attribute in the zone.
.. code-block:: http
@ -224,10 +262,6 @@ provide the appropriate attribute in the zone.
"name": "example.net."
}
This ensures the zone ends up on the correct pool.
In this example, we've allowed the user to define what pool should be
scheduled. If we wanted to schedule the zone based on the tenant, we
could write a custom filter that looked up the appropriate group and
adds the appropriate pool.
In this example, the user defines which pool is scheduled. If the zone should
be scheduled based on the tenant, a custom filter could be written that looks
up the appropriate group and adds the appropriate pool.

92
doc/source/admin/pool-scheduler.rst
View File

@ -13,54 +13,26 @@
License for the specific language governing permissions and limitations
under the License.
.. _pool_scheduler:
.. _poolsched:
==============
Pool Scheduler
==============
======================
Pool Scheduler Filters
======================
In designate we have a pluggable scheduler filter interface.
About Filters
=============
You can set an ordered list of filters to run on each zone create api request.
We provide a few basic filters below, and creating custom filters follows a
similar pattern to schedulers.
You can create your own by extending
:class:`designate.scheduler.filters.base.Filter`
and registering a new entry point in the ``designate.scheduler.filters``
namespace like so in your ``setup.cfg`` file:
.. code-block:: ini
[entry_points]
designate.scheduler.filters =
my_custom_filter = my_extension.filters.my_custom_filter:MyCustomFilter
The new filter can be added to the
``scheduler_filters`` list in the ``[service:central]`` section like so:
.. code-block:: ini
[service:central]
scheduler_filters = attribute, pool_id_attribute, fallback, random, my_custom_filter
The filters list is ran from left to right, so if the list is set to:
.. code-block:: ini
[service:central]
scheduler_filters = attribute, random
There will be two filters ran,
the :class:`designate.scheduler.filters.attribute_filter.AttributeFilter`
followed by :class:`designate.scheduler.filters.random_filter.RandomFilter`
When a user creates a zone, the pool scheduler uses filters to assign the zone
to a particular DNS server pool. As the administrator, you choose an ordered
list of filters that runs on each ``zone create`` API request. You configure
the scheduler to use filters that are provided with Designate or create
your own.
Default Provided Filters
========================
Filters Provided with Designate
===============================
Designate provides several filters that represent common use cases.
Base Class - Filter
-------------------
@ -111,3 +83,37 @@ In Doubt Default Pool Filter
.. autoclass:: designate.scheduler.filters.in_doubt_default_pool_filter.InDoubtDefaultPoolFilter
:members: name
:show-inheritance:
Creating Custom Filters
=======================
You can create your own filters by extending
:class:`designate.scheduler.filters.base.Filter`
and registering a new entry point in the ``designate.scheduler.filters``
namespace in ``designate.conf``:
.. code-block:: ini
[entry_points]
designate.scheduler.filters =
my_custom_filter = my_extension.filters.my_custom_filter:MyCustomFilter
Configuring Filters in the Scheduler
====================================
After you have decided whether to use the filters provided with Designate or
create custom filters you must configure the filters in the pool scheduler.
Inside the ``designate.conf`` file under the ``[service:central]`` section,
add the filters that you want the scheduler to use to the
``scheduler_filters`` parameter:
.. code-block:: ini
[service:central]
scheduler_filters = attribute, pool_id_attribute, fallback, random, my_custom_filter
.. important::
The scheduler runs the filters list from left to right.

158
doc/source/admin/pools.rst
View File

@ -19,71 +19,61 @@
DNS Server Pools
================
Overview
========
About Pools
===========
In designate we support the concept of multiple "pools" of DNS Servers.
Administrators can group DNS namespace servers into multiple pools to help
them manage their DNS environments. You can provide users with tiers of
service, by configuring pools to offer more capacity and better geographical
proximity. Administrators of private clouds can leverage multiple pools to
separate internal and external facing zones.
This allows operators to scale out their DNS Service by adding more pools,
avoiding the scaling problems that some DNS servers have for number of zones,
and the total number of records hosted by a single server.
By default, Designate contains only one DNS server pool called ``default``.
When users create a zone in a multi-pool environment, the pool scheduler must
select a pool to host the new zone. Administrators control pool selection
through the use of filters, that the scheduler uses to select a pool for the
new zone.
This also allows providers to have tiers of service (i.e. the difference
between GOLD vs SILVER tiers may be the number of DNS Servers, and how they
are distributed around the world.)
The filter interface consists of pool attributes that are key-value pairs that
the scheduler attaches to the zone during creation.
Administrators can update pool attributes later, but none of the updates will
trigger zones to move to another pool.
Zones can be moved manually to a different pool, as mentioned in the
`API Reference <https://docs.openstack.org/api-ref/dns/dns-api-v2-index.html#pool-move-zone>`_.
In a private cloud situation, it allows operators to separate internal and
external facing zones.
Designate provides a set of filters that reflect some common use cases and
also a simple interface that administrators can use to create custom filters.
To help users create zones on the correct pool we have a "scheduler" that is
responsible for examining the zone being created and the pools that are
available for use, and matching the zone to a pool.
The filters are pluggable (i.e. operator replaceable) and all follow a simple
interface.
Process Overview for Configuring Multiple Pools
===============================================
The zones are matched using "zone attributes" and "pool attributes". These are
key: value pairs that are attached to the zone when it is being created, and
the pool. The pool attributes can be updated by the operator in the future,
but it will **not** trigger zones to be moved from one pool to another.
The process of configuring multiple DNS server pools in Designate, consists
of the following steps:
.. note::
#. Define the new pool in the pool definition file.
Currently the only zone attribute that is accepted is the `pool_id` attribute.
As more filters are merged there will be support for dynamic filters.
#. Load the new pool definition into the Designate database by running the
``designate-manage`` command.
Target vs. Nameserver
=====================
#. Configure the pool scheduler to use one or more filters to match any
new zones that users create with the appropriate pool. You can choose
filters that are provided with Designate, or create new filters.
One thing that can be confusing about pools is the differentiation
between a target and a nameserver. The target is where Designate will
try to write the change, while a namserver is where Designate checks
that the change exists.
#. Supply the required pool information to users to specify when they create
zones.
A great example of this is `bind's stealth master system
<http://www.zytrax.com/books/dns/ch4/#stealth>`_. In this
configuration, there could be a stealth master that you configure as
your target and a set of slaves pointed to that master as your
nameservers. Designate will write to the master and then look for the
changes on the slaves before considering the change active.
Another example would be where Designate uses an API backend such as
DynDNS or even another Designate instance. In this situation, you will
typically have a single target with a set of nameservers to test that
meet your requirements.
Managing Pools
==============
In mitaka we moved the method of updating pools to a CLI in `designate-manage`
There is a YAML file that defines the pool, and is used to load
this information into the database.
Pool Definition File
====================
A pool definition file is required when you create a DNS server pool in
Designate. The required key value pairs in YAML format are documented here:
.. literalinclude:: ../../../etc/designate/pools.yaml.sample
:language: yaml
.. _catalog_zones:
Catalog zones
@ -119,53 +109,69 @@ details on how to use catalog zones with TSIG.
| catalog zones with TSIG.
Designate Manage Pools Command Reference
----------------------------------------
designate-manage pool Command Reference
=======================================
Update Pools Information
^^^^^^^^^^^^^^^^^^^^^^^^
You manage pools in Designate with the ``designate-manage pool`` commands.
.. note::
Control plane does not need to be restarted after designate-manage pool command changes.
Pool update
-----------
You manage can modify the current deployed pools with the
``designate-manage pool update`` command.
.. code-block:: console
designate-manage pool update [options]
designate-manage pool update [options]
Options:
""""""""
Pool update options
^^^^^^^^^^^^^^^^^^^
``--file <file>``
Input file. When a file is not specified, ``/etc/designate/pools.yaml`` is
used by default.
``--dry-run``
Simulates what happens when you run this command.
``--delete``
Removes all pools not listed in the config file.
--file Input file (Default: ``/etc/designate/pools.yaml``)
--dry-run This will simulate what will happen when you run this command
--delete Any Pools not listed in the config file will be deleted
.. warning::
| Running with ``--delete`` can be **extremely** dangerous.
| It will delete any pools that are not in the supplied YAML file, and any
| zones that are in that Pool.
| Before running with ``--delete`` we recommend operators run with
| ``--delete --dry-run`` to view the outcome.
Using ``--delete`` can be **extremely** dangerous, because ``designate-manage`` removes any pools that are not in the supplied YAML file, **including the default one** and any zones that are in those pools. Before using ``--delete``, use ``--delete --dry-run`` to view the outcome.
Generate YAML File
^^^^^^^^^^^^^^^^^^
Generating a Copy of the Pool Configuration
-------------------------------------------
.. code-block:: console
designate-manage pool generate_file [options]
designate-manage pool generate_file [options]
Options:
""""""""
--file YAML file output too (Default: ``/etc/designate/pools.yaml``)
Options
^^^^^^^
Generate YAML File from Liberty Config
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``--file <file>``
The YAML file where ``designate-manage`` writes its output. When a file is
not specified, ``designate-manage`` writes to ``/etc/designate/pools.yaml``.
Showing the current Pools Configuration
---------------------------------------
.. code-block:: console
designate-manage pool export_from_config [options]
designate-manage pool show_config [options]
Options:
""""""""
--file YAML file output too (Default: ``/etc/designate/pools.yaml``)
Options
^^^^^^^
``--pool_id <pool_id>``
ID of the pool to be examined.
``--all_pools``
Show the config of all the pools.

30
doc/source/cli/designate-manage.rst
View File

@ -127,6 +127,13 @@ designate optional arguments
designate-manage pool
=====================
.. code-block:: console
usage: designate pool [-h] {generate_file,show_config,update} ...
positional arguments:
{generate_file,show_config,update}
.. _designate_manage_pool_generate_file:
designate-manage pool generate_file
@ -177,6 +184,29 @@ Update the running pool config from a YAML file
``--dry-run``
This will simulate what will happen when you run this command
.. _designate_manage_pool_show:
designate-manage pool show
--------------------------
.. code-block:: console
usage: designate-manage pool show_config [-h] [--pool_id POOL_ID]
[--all_pools]
Show the deployed pools configuration
**Optional arguments:**
``-h, --help``
show this help message and exit
``--pool_id POOL_ID``
ID of the pool to be examined
``--all_pools``
show the config of all the pools
.. _designate_manage_database:

138
doc/source/user/manage-zones.rst
View File

@ -15,7 +15,7 @@
================
Managing Zones
Managing Zones
================
In the Domain Name System, `zones` are used to break up the namespace into more
@ -169,50 +169,6 @@ managed by designate as part of the default pool.
In the ``AUTHORITY`` section, the numeric value between the name and `IN` is
the TTL, which has updated to the new value of 3000.
Multiple Pools Zone Creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When Multipools is configured, if you want to create a zone and attach it to a
different pool than the default one, you must indicate to which pool your zone
will be attached to. This is done via the attributes options during the zone
creation.
See the following example:
.. code-block:: console
$ openstack zone create --email dnsmaster@example.com example.com. --attributes pool_level:secondary
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | CREATE |
| attributes | pool_level:secondary |
| | |
| created_at | 2023-01-24T18:30:45.000000 |
| description | None |
| email | dnsmaster@example.com |
| id | d106e7b0-9973-41a1-b3db-0fb34b6d952c |
| masters | |
| name | example.com. |
| pool_id | 10cec123-43f0-4b60-98a8-1204dd826c67 |
| project_id | 5160768b59524fd283a4fa82d7327644 |
| serial | 1674585045 |
| status | PENDING |
| transferred_at | None |
| ttl | 3600 |
| type | PRIMARY |
| updated_at | None |
| version | 1 |
+----------------+--------------------------------------+
$ openstack zone list
+--------------------------------------+---------------+---------+------------+--------+--------+
| id | name | type | serial | status | action |
+--------------------------------------+---------------+---------+------------+--------+--------+
| d106e7b0-9973-41a1-b3db-0fb34b6d952c | example.com. | PRIMARY | 1674585045 | ACTIVE | NONE |
+--------------------------------------+---------------+---------+------------+--------+--------+
Deleting a zone
---------------
@ -249,3 +205,95 @@ Any records present in the zone are also deleted and will no longer resolve.
Zones that have shares cannot be deleted without removing the shares or
using the `delete-shares` modifier.
Associating a Zone with a Pool
------------------------------
When your administrator has configured designate to use multiple DNS server
pools, it might be necessary for you to indicate a specific pool attribute or
ID when you create a zone. Your administrator will provide you with the
necessary pool information to create a zone.
In this example, the pool attribute that indicates one of several service
tiers, must be specified when creating a zone:
.. code-block:: console
$ openstack zone create --email dnsmaster@example.com example.com. --attributes service_tier:silver
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | CREATE |
| attributes | service_tier:silver |
| | |
| created_at | 2023-04-04T18:30:45.000000 |
| description | None |
| email | dnsmaster@example.com |
| id | d106e7b0-9973-41a1-b3db-0fb34b6d952c |
| masters | |
| name | example.com. |
| pool_id | 10cec123-43f0-4b60-98a8-1204dd826c67 |
| project_id | 5160768b59524fd283a4fa82d7327644 |
| serial | 1674585045 |
| status | PENDING |
| transferred_at | None |
| ttl | 3600 |
| type | PRIMARY |
| updated_at | None |
| version | 1 |
+----------------+--------------------------------------+
.. note::
Remember that
[service:central]
scheduler_filters = attribute
configuration setting is required to associate a newly created zone with an existing pool.
In this example, a specific pool ID, ``7a2cde6b-d321-fa11-f99e-ccc378fe3dd1``,
must be specified when creating a zone:
.. code-block:: console
$ openstack zone create --email dnsmaster@example.com example.com. --attributes pool_id:7a2cde6b-d321-fa11-f99e-ccc378fe3dd1
+----------------+----------------------------------------------+
| Field | Value |
+----------------+----------------------------------------------+
| action | CREATE |
| attributes | pool_id:7a2cde6b-d321-fa11-f99e-ccc378fe3dd1 |
| | |
| created_at | 2023-04-04T18:39:12.000000 |
| description | None |
| email | dnsmaster@example.com |
| id | 54f2bcaa-65ef-8274-5fde-987234508afe |
| masters | |
| name | example.com. |
| pool_id | 7a2cde6b-d321-fa11-f99e-ccc378fe3dd1 |
| project_id | 5160768b59524fd283a4fa82d7327644 |
| serial | 2385822109 |
| status | PENDING |
| transferred_at | None |
| ttl | 3600 |
| type | PRIMARY |
| updated_at | None |
| version | 1 |
+----------------+----------------------------------------------+
.. note::
Remember that
[service:central]
scheduler_filters = pool_id_attribute
configuration setting is required to associate a newly created zone with an existing pool.
Verify that the zone has been created:
.. code-block:: console
$ openstack zone list
+--------------------------------------+---------------+---------+------------+--------+--------+
| id | name | type | serial | status | action |
+--------------------------------------+---------------+---------+------------+--------+--------+
| 54f2bcaa-65ef-8274-5fde-987234508afe | example.com. | PRIMARY | 2385822109 | ACTIVE | NONE |
+--------------------------------------+---------------+---------+------------+--------+--------+

4
releasenotes/notes/add-multiple-pools-docs-19071225709c5702.yaml Normal file
View File

@ -0,0 +1,4 @@
---
other:
- |
Add multiple pools guidance docs to Admin, User, and CLI docs.