diff --git a/doc/source/index.rst b/doc/source/index.rst index 3445cb33e..7ecb1ee40 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -39,7 +39,6 @@ User Guide .. toctree:: :maxdepth: 1 - :glob: howtos/manage-ptr-records howtos/secondary-zones @@ -50,7 +49,6 @@ Administration Guide .. toctree:: :maxdepth: 1 - :glob: pools pool-scheduler @@ -71,6 +69,8 @@ Upgrades upgrade/kilo upgrade/mitaka + upgrade/newton + upgrade/ocata Other Modules ============= diff --git a/doc/source/upgrade/mitaka.rst b/doc/source/upgrade/mitaka.rst index f80cc2d3d..c239e3f7b 100644 --- a/doc/source/upgrade/mitaka.rst +++ b/doc/source/upgrade/mitaka.rst @@ -17,8 +17,6 @@ Upgrading to Mitaka from Liberty ******************************** -.. note:: This is a WIP - it will be updated as more items are added to Mitaka - Pools Configuration =================== diff --git a/doc/source/upgrade/newton.rst b/doc/source/upgrade/newton.rst new file mode 100644 index 000000000..6394a5300 --- /dev/null +++ b/doc/source/upgrade/newton.rst @@ -0,0 +1,111 @@ +.. + Copyright 2017 Rackspace, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=============================== +Upgrading to Newton from Mitaka +=============================== + +The Newton release of Designate adds two new services ``designate-producer``, +``designate-worker``. These replace ``designate-zone-manager`` and +``designate-pool-manager``, respectively. In a future cycle, the old services +will be removed, and the new ones will be enabled by default. In Newton, +you must enable the new services yourself. Designate will work with both +configurations, as there is no breaking change from Mitaka. + +Breaking Changes +---------------- + +The default port the ``designate-agent`` service listens on has changed from 53 to 5358. +This matches the port we have always used in the sample configuration, and the port used +in the agent backend class. + +Upgrading Code and Enabling Services +------------------------------------ + +To enable the new services with minimal impact, the following process can +be followed. This assumes you have all Mitaka Designate services running. + +1. Deploy the Newton code. +2. Add the ``[service:worker]`` and ``[service:producer]`` sections to your + configuration file. Ensure ``enabled`` and ``notify`` in the worker section + are ``True``. + + .. code-block:: ini + + [service:worker] + enabled = True + #workers = None + #threads = 1000 + #threshold_percentage = 100 + #poll_timeout = 30 + #poll_retry_interval = 15 + #poll_max_retries = 10 + #poll_delay = 5 + notify = True + + [service:producer] + #workers = None + #threads = 1000 + # Can be any/all of: periodic_exists, delayed_notify, worker_periodic_recovery + # None => All tasks enabled + #enabled_tasks = None + + [producer_task:domain_purge] + #interval = 3600 # 1h + #batch_size = 100 + #time_threshold = 604800 # 7 days + + [producer_task:delayed_notify] + #interval = 5 + + [producer_task:worker_periodic_recovery] + #interval = 120 + +3. Stop the ``designate-pool-manager`` and ``designate-zone-manager`` processes. +4. Restart the ``designate-api``, ``designate-central`` and ``designate-mdns`` services. +5. Start the ``designate-producer`` and ``designate-worker`` services. + + +New Features +------------ + +- ``designate-mdns``, ``designate-agent`` and ``designate-api`` can now bind to + multiple host:port pairs via the new "listen" configuration arguments for + each service. +- New pool scheduler "attribute" filter for scheduling zones across pools. + This can be enabled in the ``[service:central]`` section of the config by adding + ``attribute`` to the list of values in the ``filters`` option. +- An experimental agent backend to support TinyDNS, the DNS resolver from the + djbdns tools. +- An experimental agent backend to support Knot DNS 2 +- A new recordset api ``/v2/recordsets`` is exposed, docs can be found + `here `_. +- Designate services now report running status. The information is exposed via + `api `_. +- The quotas API from the admin API has been ported to /v2 with some changes + and is now `stable `_. + +Deprecation Notices +------------------- + +- ``designate-api``'s api_host and api_port configuration options have been + deprecated, please use the new combined "listen" argument in place of these. +- ``designate-mdns``'s host and port configuration options have been deprecated, + please use the new combined "listen" argument in place of these. +- ``designate-agents``'s host and port configuration options have been + deprecated, please use the new combined "listen" argument in place of these. +- ``designate-zone-manager`` and ``designate-pool-manager`` are now deprecated + and will be removed in a future release. + diff --git a/doc/source/upgrade/ocata.rst b/doc/source/upgrade/ocata.rst new file mode 100644 index 000000000..a03522c41 --- /dev/null +++ b/doc/source/upgrade/ocata.rst @@ -0,0 +1,44 @@ +.. + Copyright 2017 Rackspace, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============================== +Upgrading to Ocata from Newton +============================== + +Upgrading Code and Enabling Services +------------------------------------ + +1. Deploy Ocata code or packages. +2. Restart all services. See the Newton upgrade guide for enabling + ``designate-producer`` and ``designate-worker``. + +New Features +------------ + +- The notifications Designate emits via MQ are now pluggable, drivers are + defined by python entrypoints and the new ``notification_plugin`` option + in the ``DEFAULT`` config section enables selection. By default, the + notifications have not changed. There is an ``audit`` plugin that can + be used, if desired. + +- Scheduling zones across pools. See these + `docs `_ + for more details. + +Deprecation Notices +------------------- + +- ``designate-zone-manager`` and ``designate-pool-manager`` remain deprecated + and will be removed in a future release.