From ba61dbeb64071a8d5e526ec2a3ffb9bc0ee14077 Mon Sep 17 00:00:00 2001 From: Petr Kovar Date: Fri, 10 Mar 2017 17:11:10 +0100 Subject: [PATCH] [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 | 8 +- install-guide/source/get_started.rst | 3 +- install-guide/source/install-rdo.rst | 211 ++++++++++++++++++++++++ install-guide/source/install-ubuntu.rst | 51 +++--- install-guide/source/install.rst | 3 +- install-guide/source/next-steps.rst | 6 +- install-guide/source/verify.rst | 2 + 7 files changed, 244 insertions(+), 40 deletions(-) create mode 100644 install-guide/source/install-rdo.rst diff --git a/install-guide/source/create-zone.rst b/install-guide/source/create-zone.rst index 01af1e48d..ea87ec27e 100644 --- a/install-guide/source/create-zone.rst +++ b/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 diff --git a/install-guide/source/get_started.rst b/install-guide/source/get_started.rst index ac7c0e247..ef2ea7a0d 100644 --- a/install-guide/source/get_started.rst +++ b/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 diff --git a/install-guide/source/install-rdo.rst b/install-guide/source/install-rdo.rst new file mode 100644 index 000000000..601acfa98 --- /dev/null +++ b/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 diff --git a/install-guide/source/install-ubuntu.rst b/install-guide/source/install-ubuntu.rst index 95cf6dfa9..0ab4e77e6 100644 --- a/install-guide/source/install-ubuntu.rst +++ b/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 - - .. code-block:: sql - - CREATE DATABASE `designate` - GRANT ALL PRIVILEGES ON designate.* TO 'designate'@'localhost' \ + # mysql -u root -p + mysql> CREATE DATABASE designate; + mysql> 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`` - user in the Identity service. + 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 + .. code-block:: ini - enabled = True - notify = True + enabled = 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 - you chose for the Designate database. + Replace ``DESIGNATE_DBPASS`` with the password you chose for the + ``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 - - # editor /etc/designate/pools.yaml - - .. code-block:: 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 - -#. Ensure the output file is correct (reference sample file for each value) -#. Run +#. Update the pools: .. 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 diff --git a/install-guide/source/install.rst b/install-guide/source/install.rst index 684ca6ed4..b480712e7 100644 --- a/install-guide/source/install.rst +++ b/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 diff --git a/install-guide/source/next-steps.rst b/install-guide/source/next-steps.rst index 5c398cf9b..56d56d821 100644 --- a/install-guide/source/next-steps.rst +++ b/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 -docs.openstack.org/install-guides/index.html . +To add additional services, see the `additional OpenStack install documentation +`_. To learn more about the designate service, read the `Designate developer documentation -`__. +`_. diff --git a/install-guide/source/verify.rst b/install-guide/source/verify.rst index 440e813d2..4be906091 100644 --- a/install-guide/source/verify.rst +++ b/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.