From 620fc6ec97be21f5bbc0acbca82517ba49fbd245 Mon Sep 17 00:00:00 2001
From: Kiall Mac Innes <kiall@macinnes.ie>
Date: Thu, 14 Apr 2016 19:14:32 +0100
Subject: [PATCH] Add Agent DevStack Backend

* Add a new backend for DevStack allowing the Agent
  backend to be configured.
* Change the agent to choose a sane port by default, it's extremely
  unlikely anyone is exposing the agent on port 53 intentionally.
* The agent itself is not yet configured, this will come later as it
  involves refactoring most of the BIND non-agent backend into a lib.
* Fail when the user asks for the agent backend, without also enabling
  the agent service.

Change-Id: Iedde58f4f5a2ea89cb9da78aaec1853208af8fc9
---
 designate/agent/__init__.py                   |   4 +-
 designate/backend/agent.py                    |   2 +-
 devstack/designate_plugins/backend-agent      | 103 ++++++++++++++++++
 devstack/designate_plugins/backend-agent-fake |  55 ++++++++++
 devstack/plugin.sh                            |   8 +-
 devstack/settings                             |   3 +-
 doc/source/backends.rst                       |   4 +-
 doc/source/backends/agent.rst                 |  46 ++++++++
 .../backends/sample_yaml_snippets/agent.yaml  |  15 +++
 .../agent-port-number-c28462562a74cbf9.yaml   |   5 +
 10 files changed, 237 insertions(+), 8 deletions(-)
 create mode 100644 devstack/designate_plugins/backend-agent
 create mode 100644 devstack/designate_plugins/backend-agent-fake
 create mode 100644 doc/source/backends/agent.rst
 create mode 100644 doc/source/backends/sample_yaml_snippets/agent.yaml
 create mode 100644 releasenotes/notes/agent-port-number-c28462562a74cbf9.yaml

diff --git a/designate/agent/__init__.py b/designate/agent/__init__.py
index 91c7f5950..041fa196f 100644
--- a/designate/agent/__init__.py
+++ b/designate/agent/__init__.py
@@ -25,9 +25,9 @@ OPTS = [
     cfg.IntOpt('threads', default=1000,
                help='Number of agent greenthreads to spawn'),
     cfg.IPOpt('host', default='0.0.0.0',
-              help='The Agent Bind Host'),
+              help='The host for the Agent to bind to'),
     cfg.PortOpt('port', default=5358,
-                help='mDNS Port Number'),
+                help='The port for the Agent to bind to'),
     cfg.IntOpt('tcp-backlog', default=100,
                help='The Agent TCP Backlog'),
     cfg.FloatOpt('tcp-recv-timeout', default=0.5,
diff --git a/designate/backend/agent.py b/designate/backend/agent.py
index 75728e386..c9ed39cee 100644
--- a/designate/backend/agent.py
+++ b/designate/backend/agent.py
@@ -58,7 +58,7 @@ class AgentPoolBackend(base.Backend):
     def __init__(self, target):
         super(AgentPoolBackend, self).__init__(target)
         self.host = self.options.get('host', '127.0.0.1')
-        self.port = int(self.options.get('port', 53))
+        self.port = int(self.options.get('port', 5358))
         self.timeout = CONF['service:pool_manager'].poll_timeout
         self.retry_interval = CONF['service:pool_manager'].poll_retry_interval
         self.max_retries = CONF['service:pool_manager'].poll_max_retries
diff --git a/devstack/designate_plugins/backend-agent b/devstack/designate_plugins/backend-agent
new file mode 100644
index 000000000..e2579dc49
--- /dev/null
+++ b/devstack/designate_plugins/backend-agent
@@ -0,0 +1,103 @@
+# Configure the agent backend
+
+# Enable with:
+# DESIGNATE_BACKEND_DRIVER=agent
+# DESIGNATE_AGENT_BACKEND_DRIVER=<an agent backend>
+
+# Dependencies:
+# ``functions`` file
+# ``designate`` configuration
+
+# install_designate_backend - install any external requirements
+# configure_designate_backend - make configuration changes, including those to other services
+# init_designate_backend - initialize databases, etc.
+# start_designate_backend - start any external services
+# stop_designate_backend - stop any external services
+# cleanup_designate_backend - remove transient data and cache
+
+# Save trace setting
+DP_AGENT_XTRACE=$(set +o | grep xtrace)
+set +o xtrace
+
+# Get agent backend configuration
+# -------------------------------
+if [[ -r $DESIGNATE_PLUGINS/backend-agent-$DESIGNATE_AGENT_BACKEND_DRIVER ]]; then
+    # Load plugin
+    source $DESIGNATE_PLUGINS/backend-agent-$DESIGNATE_AGENT_BACKEND_DRIVER
+fi
+
+# Entry Points
+# ------------
+
+# install_designate_backend - install any external requirements
+function install_designate_backend {
+    # Install the Agent Backend
+    install_designate_agent_backend
+}
+
+# configure_designate_backend - make configuration changes, including those to other services
+function configure_designate_backend {
+    # Generate Designate pool.yaml file
+    sudo tee $DESIGNATE_CONF_DIR/pools.yaml > /dev/null <<EOF
+---
+- name: default
+  description: DevStack Agent Pool
+  attributes: {}
+
+  ns_records:
+    - hostname: $DESIGNATE_DEFAULT_NS_RECORD
+      priority: 1
+
+  nameservers:
+    - host: $DESIGNATE_SERVICE_HOST
+      port: $DESIGNATE_SERVICE_PORT_DNS
+
+  targets:
+    - type: agent
+      description: Agent Instance
+
+      masters:
+        - host: $DESIGNATE_SERVICE_HOST
+          port: $DESIGNATE_SERVICE_PORT_MDNS
+
+      options:
+        host: $DESIGNATE_SERVICE_HOST
+        port: $DESIGNATE_SERVICE_PORT_AGENT
+EOF
+
+    # Configure Agent Settings
+    iniset $DESIGNATE_CONF service:agent backend_driver $DESIGNATE_AGENT_BACKEND_DRIVER
+    iniset $DESIGNATE_CONF service:agent host $DESIGNATE_SERVICE_HOST
+    iniset $DESIGNATE_CONF service:agent port $DESIGNATE_SERVICE_PORT_AGENT
+    iniset $DESIGNATE_CONF service:agent masters "$DESIGNATE_SERVICE_HOST:$DESIGNATE_SERVICE_PORT_MDNS"
+
+    # Configure the Agent Backend
+    configure_designate_agent_backend
+}
+
+# init_designate_backend - initialize databases, etc.
+function init_designate_backend {
+    # Init the Agent Backend
+    init_designate_agent_backend
+}
+
+# start_designate_backend - start any external services
+function start_designate_backend {
+    # Start the Agent Backend
+    start_designate_agent_backend
+}
+
+# stop_designate_backend - stop any external services
+function stop_designate_backend {
+    # Stop the Agent Backend
+    stop_designate_agent_backend
+}
+
+# cleanup_designate_backend - remove transient data and cache
+function cleanup_designate_backend {
+    # Cleanup the Agent Backend
+    cleanup_designate_agent_backend
+}
+
+# Restore xtrace
+$DP_AGENT_XTRACE
diff --git a/devstack/designate_plugins/backend-agent-fake b/devstack/designate_plugins/backend-agent-fake
new file mode 100644
index 000000000..ca955ac96
--- /dev/null
+++ b/devstack/designate_plugins/backend-agent-fake
@@ -0,0 +1,55 @@
+# Configure the fake agent backend
+
+# Enable with:
+# DESIGNATE_BACKEND_DRIVER=agent
+# DESIGNATE_AGENT_BACKEND_DRIVER=fake
+
+# install_designate_agent_backend - install any external requirements
+# configure_designate_agent_backend - make configuration changes, including those to other services
+# init_designate_agent_backend - initialize databases, etc.
+# start_designate_agent_backend - start any external services
+# stop_designate_agent_backend - stop any external services
+# cleanup_designate_agent_backend - remove transient data and cache
+
+# Save trace setting
+DP_AGENT_FAKE_XTRACE=$(set +o | grep xtrace)
+set +o xtrace
+
+# Defaults
+# --------
+
+# Entry Points
+# ------------
+
+# install_designate_agent_backend - install any external requirements
+function install_designate_agent_backend {
+    :
+}
+
+# configure_designate_agent_backend - make configuration changes, including those to other services
+function configure_designate_agent_backend {
+    :
+}
+
+# init_designate_agent_backend - initialize databases, etc.
+function init_designate_agent_backend {
+    :
+}
+
+# start_designate_agent_backend - start any external services
+function start_designate_agent_backend {
+    :
+}
+
+# stop_designate_agent_backend - stop any external services
+function stop_designate_agent_backend {
+    :
+}
+
+# cleanup_designate_agent_backend - remove transient data and cache
+function cleanup_designate_agent_backend {
+    :
+}
+
+# Restore xtrace
+$DP_AGENT_FAKE_XTRACE
diff --git a/devstack/plugin.sh b/devstack/plugin.sh
index 41c458e9b..091ad6d2a 100755
--- a/devstack/plugin.sh
+++ b/devstack/plugin.sh
@@ -5,7 +5,7 @@ XTRACE=$(set +o | grep xtrace)
 set +o xtrace
 
 # Get backend configuration
-# ----------------------------
+# -------------------------
 if is_service_enabled designate && [[ -r $DESIGNATE_PLUGINS/backend-$DESIGNATE_BACKEND_DRIVER ]]; then
     # Load plugin
     source $DESIGNATE_PLUGINS/backend-$DESIGNATE_BACKEND_DRIVER
@@ -150,6 +150,7 @@ function configure_designatedashboard {
 function configure_designate_tempest() {
     if is_service_enabled tempest; then
         nameservers=$DESIGNATE_SERVICE_HOST:$DESIGNATE_SERVICE_PORT_DNS
+        # TODO(kiall): Remove hardcoded list of plugins
         case $DESIGNATE_BACKEND_DRIVER in
             bind9|powerdns)
                 nameservers="$DESIGNATE_SERVICE_HOST:$DESIGNATE_SERVICE_PORT_DNS"
@@ -306,6 +307,11 @@ function stop_designate {
 
 # This is the main for plugin.sh
 if is_service_enabled designate; then
+    # Sanify check for agent backend
+    # ------------------------------
+    if ! is_service_enabled designate-agent && [ "$DESIGNATE_BACKEND_DRIVER" == "agent" ]; then
+        die $LINENO "To use the agent backend, you must enable the designate-agent service"
+    fi
 
     if [[ "$1" == "stack" && "$2" == "install" ]]; then
         echo_summary "Installing Designate client"
diff --git a/devstack/settings b/devstack/settings
index 30d2d9a62..9788340db 100644
--- a/devstack/settings
+++ b/devstack/settings
@@ -1,5 +1,6 @@
 # Default options
 DESIGNATE_BACKEND_DRIVER=${DESIGNATE_BACKEND_DRIVER:=powerdns}
+DESIGNATE_AGENT_BACKEND_DRIVER=${DESIGNATE_AGENT_BACKEND_DRIVER:-"fake"}
 DESIGNATE_POOL_MANAGER_CACHE_DRIVER=${DESIGNATE_POOL_MANAGER_CACHE_DRIVER:-memcache}
 DESIGNATE_POOL_ID=${DESIGNATE_POOL_ID:-794ccc2c-d751-44fe-b57f-8894c9f5c842}
 DESIGNATE_DEFAULT_NS_RECORD=${DESIGNATE_DEFAULT_NS_RECORD:-ns1.devstack.org.}
@@ -21,6 +22,7 @@ DESIGNATE_SERVICE_PORT=${DESIGNATE_SERVICE_PORT:-9001}
 DESIGNATE_SERVICE_PORT_INT=${DESIGNATE_SERVICE_PORT_INT:-19001}
 DESIGNATE_SERVICE_PORT_DNS=${DESIGNATE_SERVICE_PORT_DNS:-53}
 DESIGNATE_SERVICE_PORT_MDNS=${DESIGNATE_SERVICE_PORT_MDNS:-5354}
+DESIGNATE_SERVICE_PORT_AGENT=${DESIGNATE_SERVICE_PORT_AGENT:-5358}
 
 # Default directories
 DESIGNATE_BIN_DIR=$(get_python_exec_prefix)
@@ -50,7 +52,6 @@ GITDIR["designate-tempest-plugin"]=$DEST/designate-tempest-plugin
 TEMPEST_SERVICES+=,designate
 
 # Turn on all Designate services by default
-
 enable_service designate
 enable_service designate-central
 enable_service designate-api
diff --git a/doc/source/backends.rst b/doc/source/backends.rst
index d7edde0d1..13c30b5fb 100644
--- a/doc/source/backends.rst
+++ b/doc/source/backends.rst
@@ -22,6 +22,4 @@ Contents:
    :maxdepth: 2
    :glob:
 
-   backends/bind9
-   backends/powerdns
-   backends/infoblox
+   backends/*
diff --git a/doc/source/backends/agent.rst b/doc/source/backends/agent.rst
new file mode 100644
index 000000000..6554e2416
--- /dev/null
+++ b/doc/source/backends/agent.rst
@@ -0,0 +1,46 @@
+..
+    Copyright 2016 Hewlett Packard Enterprise Development Company LP
+
+    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.
+
+Agent Backend
+=============
+
+This page documents using the Pool Manager Agent backend, and it's accompanying
+service, `designate-agent`. This backend uses an extension of the DNS protocol
+itself to send management requests to the remote agent processes, where the
+requests will be actioned.
+
+The traffic between `designate-pool-manager`, and `designate-agent` is both
+unauthenticated and unencrypted. Do not run this traffic over unsecured
+networks.
+
+Designate Configuration
+-----------------------
+
+For each designate-agent running, add a target to the pools.yaml configuration
+file, using the following template:
+
+   .. literalinclude:: sample_yaml_snippets/agent.yaml
+       :language: yaml
+
+Then update the designate pools database using the ``designate-manage pool``
+command - see :ref:`designate_manage_pool` for further details on the
+``designate-manage pool`` command:
+
+.. code-block:: console
+
+    $ designate-manage pool update
+
+.. TODO: Document how to configure the agent service itself, and the available
+   agent backends.
diff --git a/doc/source/backends/sample_yaml_snippets/agent.yaml b/doc/source/backends/sample_yaml_snippets/agent.yaml
new file mode 100644
index 000000000..35709824c
--- /dev/null
+++ b/doc/source/backends/sample_yaml_snippets/agent.yaml
@@ -0,0 +1,15 @@
+  targets:
+    - type: agent
+      description: Agent Server 1
+
+      # List out the designate-mdns servers from which Agent servers should
+      # request zone transfers (AXFRs) from.
+      masters:
+        - host: 192.0.2.1
+          port: 5354
+
+      # Agent Configuration options, this should be this targets
+      # designate-agent service's host and port.
+      options:
+        host: 192.0.2.2
+        port: 5358
diff --git a/releasenotes/notes/agent-port-number-c28462562a74cbf9.yaml b/releasenotes/notes/agent-port-number-c28462562a74cbf9.yaml
new file mode 100644
index 000000000..c2beb8f39
--- /dev/null
+++ b/releasenotes/notes/agent-port-number-c28462562a74cbf9.yaml
@@ -0,0 +1,5 @@
+---
+upgrade:
+  - The default port which 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.