[install-guide] Add install-rdo

* Make instructions more consistent with other project install guides.
* rndc-confgen seems to require -r /dev/urandom for RDO.
* Language, markup, and reference fixes.

Change-Id: I71ccec32c3b918f44f71dd7149045cd934e6d0d9

install-guide/source/create-zone.rst

@@ -12,7 +12,7 @@ In environments that include the DNS service, you can create a DNS Zone.
 
       $ . demo-openrc
 
-#. Create a Zone called ``example.com.``:
+#. Create a DNS Zone called ``example.com.``:
 
    .. code-block:: console
 
@@ -39,7 +39,7 @@ In environments that include the DNS service, you can create a DNS Zone.
       | version        | 1                                    |
       +----------------+--------------------------------------+
 
-#. After a short time, verify successful creation of the zone
+#. After a short time, verify successful creation of the DNS Zone:
 
    .. code-block:: console
 
@@ -50,7 +50,7 @@ In environments that include the DNS service, you can create a DNS Zone.
       | 14093115-0f0f-497a-ac69-42235e46c26f | example.com. | PRIMARY | 1468421656 | ACTIVE | NONE   |
       +--------------------------------------+--------------+---------+------------+--------+--------+
 
-#. We can now create RecordSets in this zone
+#. You can now create RecordSets in this DNS Zone:
 
    .. code-block:: console
 
@@ -74,7 +74,7 @@ In environments that include the DNS service, you can create a DNS Zone.
       | zone_name   | example.com.                         |
       +-------------+--------------------------------------+
 
-#. Delete the zone.
+#. Delete the DNS Zone:
 
    .. code-block:: console
 

install-guide/source/get_started.rst

@@ -37,7 +37,8 @@ The DNS service consists of the following components:
   Some DNS Servers requrire commands be run locally, and to do this we use
   this component.
 
-  .. note:: The majority of Designate installs will not need this component.
+  .. note:: The majority of the DNS service installs will not need this
+     component.
 
 ``Customer Facing DNS Servers``
   Serves DNS requests to end users. They are orchestreated by the

install-guide/source/install-rdo.rst

@@ -0,0 +1,211 @@
+.. _install-rdo:
+
+Install and configure for Red Hat Enterprise Linux and CentOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes how to install and configure the DNS
+service for Red Hat Enterprise Linux 7 and CentOS 7.
+
+.. include:: common_prerequisites.rst
+
+Install and configure components
+--------------------------------
+
+.. note::
+
+   Default configuration files vary by distribution. You might need
+   to add these sections and options rather than modifying existing
+   sections and options. Also, an ellipsis (``...``) in the configuration
+   snippets indicates potential default configuration options that you
+   should retain.
+
+#. Install the packages:
+
+   .. code-block:: console
+
+      # yum install openstack-designate\*
+
+#. Create a ``designate`` database that is accessible by the ``designate``
+   user. Replace ``DESIGNATE_DBPASS`` with a suitable password:
+
+   .. code-block:: console
+
+      # mysql -u root -p
+      MariaDB [(none)]> CREATE DATABASE designate;
+      MariaDB [(none)]> GRANT ALL PRIVILEGES ON designate.* TO 'designate'@'localhost' \
+      IDENTIFIED BY 'DESIGNATE_DBPASS';
+
+#. Install the BIND packages:
+
+   .. code-block:: console
+
+      # yum install bind
+
+#. Add the following options in the ``/etc/named.conf`` file:
+
+   .. code-block:: none
+
+      options {
+          ...
+          allow-new-zones yes;
+          request-ixfr no;
+          recursion no;
+      };
+
+#. Create an RNDC Key:
+
+   .. code-block:: console
+
+      # rndc-confgen -a -k designate -c /etc/designate/rndc.key -r /dev/urandom
+
+#. Add the key to ``/etc/named.conf``:
+
+   .. code-block:: none
+
+      ...
+      # This should be the contents of ``/etc/designate/rndc.key``
+      key "designate" {
+        algorithm hmac-md5;
+        secret "OAkHNQy0m6UPcv55fiVAPw==";
+      };
+      # End of content from ``/etc/designate/rndc.key``
+
+      controls {
+        inet 127.0.0.1 port 953
+          allow { 127.0.0.1; } keys { "designate"; };
+      };
+
+
+#. Start the DNS service and configure it to start when the system boots:
+
+   .. code-block:: console
+
+      # systemctl enable named
+
+      # systemctl start named
+
+#. Edit the ``/etc/designate/designate.conf`` file and
+   complete the following actions:
+
+   * In the ``[service:api]`` section, configure ``auth_strategy``:
+
+     .. code-block:: ini
+
+        [service:api]
+        api_host = 0.0.0.0
+        api_port = 9001
+        auth_strategy = keystone
+        enable_api_v1 = True
+        enabled_extensions_v1 = quotas, reports
+        enable_api_v2 = True
+
+   * In the ``[keystone_authtoken]`` section, configure the following options:
+
+     .. code-block:: ini
+
+        [keystone_authtoken]
+        auth_host = controller
+        auth_port = 35357
+        auth_protocol = http
+        admin_tenant_name = service
+        admin_user = designate
+        admin_password = DESIGNATE_PASS
+
+     Replace ``DESIGNATE_PASS`` with the password you chose for the
+     ``designate`` user in the Identity service.
+
+   * In the ``[service:worker]`` section, enable the worker model:
+
+     .. code-block:: ini
+
+        enabled = True
+        notify = True
+
+   * In the ``[storage:sqlalchemy]`` section, configure database access:
+
+     .. code-block:: ini
+
+        [storage:sqlalchemy]
+        connection = mysql+pymysql://designate:DESIGNATE_DBPASS@controller/designate
+
+     Replace ``DESIGNATE_DBPASS`` with the password you chose for the
+     ``designate`` database.
+
+   * Populate the designate database
+
+     .. code-block:: console
+
+        # su -s /bin/sh -c "designate-manage database sync" designate
+
+#. Start the designate central and API services and configure them to start when
+   the system boots:
+
+   .. code-block:: console
+
+      # systemctl enable designate-central designate-api
+
+      # systemctl start designate-central designate-api
+
+#. Create a pools.yaml file in ``/etc/designate/pools.yaml`` with the following
+   contents:
+
+   .. code-block:: yaml
+
+      - name: default
+        # The name is immutable. There will be no option to change the name after
+        # creation and the only way will to change it will be to delete it
+        # (and all zones associated with it) and recreate it.
+        description: Default Pool
+
+        attributes: {}
+
+        # List out the NS records for zones hosted within this pool
+        # This should be a record that is created outside of designate, that
+        # points to the public IP of the controller node.
+        ns_records:
+          - hostname: ns1-1.example.org.
+            priority: 1
+
+        # List out the nameservers for this pool. These are the actual BIND servers.
+        # We use these to verify changes have propagated to all nameservers.
+        nameservers:
+          - host: 127.0.0.1
+            port: 53
+
+        # List out the targets for this pool. For BIND there will be one
+        # entry for each BIND server, as we have to run rndc command on each server
+        targets:
+          - type: bind
+            description: BIND9 Server 1
+
+            # List out the designate-mdns servers from which BIND servers should
+            # request zone transfers (AXFRs) from.
+            # This should be the IP of the controller node.
+            # If you have multiple controllers you can add multiple masters
+            # by running designate-mdns on them, and adding them here.
+            masters:
+              - host: 127.0.0.1
+                port: 5354
+
+            # BIND Configuration options
+            options:
+              host: 127.0.0.1
+              port: 53
+              rndc_host: 127.0.0.1
+              rndc_port: 953
+              rndc_key_file: /etc/designate/rndc.key
+
+#. Update the pools:
+
+   .. code-block:: console
+
+        # su -s /bin/sh -c "designate-manage pool update" designate
+
+#. Start the designate and mDNS services and configure them to start when the
+   system boots:
+
+   .. code-block:: console
+
+      # systemctl enable designate-worker designate-producer designate-mdns
+
+      # systemctl start designate-worker designate-producer designate-mdns

install-guide/source/install-ubuntu.rst

@@ -25,19 +25,16 @@ Install and configure components
 
       # apt-get install designate
 
-#. Create the databases:
+#. Create a ``designate`` database that is accessible by the ``designate``
+   user. Replace ``DESIGNATE_DBPASS`` with a suitable password:
 
    .. code-block:: console
 
-      # mysql
+      # mysql -u root -p
-
+      mysql> CREATE DATABASE designate;
-   .. code-block:: sql
+      mysql> GRANT ALL PRIVILEGES ON designate.* TO 'designate'@'localhost' \
-
-      CREATE DATABASE `designate`
-      GRANT ALL PRIVILEGES ON designate.* TO 'designate'@'localhost' \
       IDENTIFIED BY 'DESIGNATE_DBPASS';
 
-
 #. Install the BIND9 packages:
 
    .. code-block:: console
@@ -61,7 +58,7 @@ Install and configure components
 
       # rndc-confgen -a -k designate -c /etc/designate/rndc.key
 
-#. Add the key to ``/etc/bind/named.conf``
+#. Add the key to ``/etc/bind/named.conf``:
 
    .. code-block:: none
 
@@ -78,7 +75,6 @@ Install and configure components
           allow { 127.0.0.1; } keys { "designate"; };
       };
 
-
 #. Restart the DNS service:
 
    .. code-block:: console
@@ -112,15 +108,15 @@ Install and configure components
         admin_user = designate
         admin_password = DESIGNATE_PASS
 
-     Replace DESIGNATE_PASS with the password you chose for the ``designate``
+     Replace ``DESIGNATE_PASS`` with the password you chose for the
-     user in the Identity service.
+     ``designate`` user in the Identity service.
 
    * In the ``[service:worker]`` section, enable the worker model:
 
-    .. code-block:: ini
+     .. code-block:: ini
 
-       enabled = True
+        enabled = True
-       notify = True
+        notify = True
 
    * In the ``[storage:sqlalchemy]`` section, configure database access:
 
@@ -129,8 +125,8 @@ Install and configure components
         [storage:sqlalchemy]
         connection = mysql+pymysql://designate:DESIGNATE_DBPASS@controller/designate
 
-     ``DESIGNATE_DBPASS`` is automatically set to the password
+     Replace ``DESIGNATE_DBPASS`` with the password you chose for the
-     you chose for the Designate database.
+     ``designate`` database.
 
    * Populate the designate database
 
@@ -138,21 +134,17 @@ Install and configure components
 
         # su -s /bin/sh -c "designate-manage database sync" designate
 
-
+#. Restart the designate central and API services:
-#. Restart the Designate central and API services:
 
    .. code-block:: console
 
       # service designate-central restart
       # service designate-api restart
 
-#. Create a pools.yaml file in ``/etc/designate/pools.yaml``
+#. Create a pools.yaml file in ``/etc/designate/pools.yaml`` with the following
+   contents:
 
-    .. code-block:: console
+   .. code-block:: yaml
-
-      # editor /etc/designate/pools.yaml
-
-    .. code-block:: yaml
 
       - name: default
         # The name is immutable. There will be no option to change the name after
@@ -198,14 +190,11 @@ Install and configure components
               rndc_port: 953
               rndc_key_file: /etc/designate/rndc.key
 
-
+#. Update the pools:
-#. Ensure the output file is correct (reference sample file for each value)
-#. Run
 
    .. code-block:: console
 
-        sudo su -s /bin/sh -c "designate-manage pool update" designate
+        # su -s /bin/sh -c "designate-manage pool update" designate
-
 
 #. Install Designate Worker, producer and mini-dns
 
@@ -215,7 +204,7 @@ Install and configure components
       # apt install designate-producer
       # apt install designate-mdns
 
-#. Restart Designate services and mDNS services:
+#. Restart the designate and mDNS services:
 
    .. code-block:: console
 

install-guide/source/install.rst

@@ -8,11 +8,12 @@ DNS service, code-named designate, on the controller node.
 
 This section assumes that you already have a working OpenStack
 environment with at least the following components installed:
-.. (add the appropriate services here and further notes)
+Identity service, Image service, Compute service, and Networking service.
 
 Note that installation and configuration vary by distribution.
 
 .. toctree::
    :maxdepth: 2
 
+   install-rdo.rst
    install-ubuntu.rst

install-guide/source/next-steps.rst

@@ -5,8 +5,8 @@ Next steps
 
 Your OpenStack environment now includes the designate service.
 
-To add additional services, see
+To add additional services, see the `additional OpenStack install documentation
-docs.openstack.org/install-guides/index.html .
+<http://docs.openstack.org/#install-guides>`_.
 
 To learn more about the designate service, read the `Designate developer documentation
-<http://docs.openstack.org/developer/designate/index.html>`__.
+<http://docs.openstack.org/developer/designate/index.html>`_.

install-guide/source/verify.rst

@@ -36,3 +36,5 @@ Verify operation of the DNS service.
       This output should indicate at least one of each of the ``central``,
       ``api``, ``zone_manager``, ``mdns`` and ``pool_manager`` components
       on the controller node.
+
+      This output may differ slightly depending on the distribution.