368 lines
7.7 KiB
ReStructuredText
368 lines
7.7 KiB
ReStructuredText
..
|
||
Copyright 2013 Rackspace Hosting
|
||
|
||
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.
|
||
|
||
*********************************
|
||
Development Environment on Ubuntu
|
||
*********************************
|
||
|
||
Designate is comprised of four main components :ref:`designate-api`, :ref:`designate-central`,
|
||
designate-mdns, and designate-pool-manager, supported by a few
|
||
standard open source components. For more information see :ref:`architecture`.
|
||
|
||
There are many different options for customizing Designate, and two of these options
|
||
have a major impact on the installation process:
|
||
|
||
* The storage backend used (SQLite or MySQL)
|
||
* The DNS backend used (PowerDNS or BIND9)
|
||
|
||
This guide will walk you through setting up a typical development environment for Designate,
|
||
using BIND9 as the DNS backend and MySQL as the storage backend. For a more complete discussion on
|
||
installation & configuration options, please see :ref:`architecture`.
|
||
|
||
For this guide you will need access to an Ubuntu Server (16.04).
|
||
|
||
.. _Development Environment:
|
||
|
||
Development Environment
|
||
+++++++++++++++++++++++
|
||
|
||
Installing Designate
|
||
====================
|
||
|
||
.. index::
|
||
double: install; designate
|
||
|
||
1. Install system package dependencies (Ubuntu)
|
||
|
||
::
|
||
|
||
$ sudo apt update
|
||
$ sudo apt install -y python-pip python-virtualenv libssl-dev libffi-dev git
|
||
$ sudo apt build-dep -y python-lxml
|
||
|
||
2. Clone the Designate repo
|
||
|
||
::
|
||
|
||
$ mkdir openstack
|
||
$ cd openstack
|
||
$ git clone https://git.openstack.org/openstack/designate.git
|
||
$ cd designate
|
||
|
||
|
||
3. Setup a virtualenv
|
||
|
||
.. note::
|
||
This step is necessary to allow the installation of an up-to-date
|
||
pip, independent of the version packaged for Ubuntu. it is
|
||
also useful in isolating the remainder of Designate's dependencies
|
||
from the rest of the system.
|
||
|
||
::
|
||
|
||
$ virtualenv .venv
|
||
$ . .venv/bin/activate
|
||
|
||
4. Install an up-to-date pip
|
||
|
||
::
|
||
|
||
$ pip install -U pip
|
||
|
||
|
||
5. Install Designate and its dependencies
|
||
|
||
::
|
||
|
||
$ pip install -e .
|
||
|
||
|
||
6. Change directories to the etc/designate folder.
|
||
|
||
.. note::
|
||
Everything from here on out should take place in or below your designate/etc folder
|
||
|
||
::
|
||
|
||
$ cd etc/designate
|
||
|
||
|
||
7. Create Designate's config files by copying the sample config files
|
||
|
||
::
|
||
|
||
$ cp -a rootwrap.conf.sample rootwrap.conf
|
||
|
||
|
||
8. Make the directory for Designate’s state files
|
||
|
||
::
|
||
|
||
$ mkdir -p ../../state
|
||
|
||
|
||
Configuring Designate
|
||
======================
|
||
|
||
.. index::
|
||
double: configure; designate
|
||
|
||
Create the designate.conf file
|
||
|
||
::
|
||
|
||
$ editor designate.conf
|
||
|
||
|
||
Copy or mirror the configuration from this sample file here:
|
||
|
||
.. literalinclude:: ../examples/basic-config-sample.conf
|
||
:language: ini
|
||
|
||
|
||
Installing RabbitMQ
|
||
===================
|
||
|
||
Install the RabbitMQ package
|
||
|
||
::
|
||
|
||
$ sudo apt install -y rabbitmq-server
|
||
|
||
Create a user:
|
||
|
||
::
|
||
|
||
$ sudo rabbitmqctl add_user designate designate
|
||
|
||
Give the user access to the / vhost:
|
||
|
||
::
|
||
|
||
$ sudo rabbitmqctl set_permissions -p "/" designate ".*" ".*" ".*"
|
||
|
||
|
||
Installing MySQL
|
||
================
|
||
|
||
.. index::
|
||
double: install; mysql
|
||
|
||
Install the MySQL server package
|
||
|
||
::
|
||
|
||
$ sudo apt install -y mysql-server
|
||
|
||
|
||
If you do not have MySQL previously installed, you will be prompted to change the root password.
|
||
By default, the MySQL root password for Designate is "password". You can:
|
||
|
||
* Change the root password to "password"
|
||
* If you want your own password, edit the designate.conf file and change any instance of
|
||
"mysql+pymysql://root:password@127.0.0.1/designate?charset=utf8" to "mysql+pymysql://root:YOUR_PASSWORD@127.0.0.1/designate?charset=utf8"
|
||
|
||
You can change your MySQL password anytime with the following command::
|
||
|
||
$ mysqladmin -u root -p password NEW_PASSWORD
|
||
Enter password <enter your old password>
|
||
|
||
Create the Designate tables
|
||
|
||
::
|
||
|
||
$ mysql -u root -p
|
||
Enter password: <enter your password here>
|
||
|
||
mysql> CREATE DATABASE `designate` CHARACTER SET utf8 COLLATE utf8_general_ci;
|
||
mysql> exit;
|
||
|
||
|
||
Install additional packages
|
||
|
||
::
|
||
|
||
$ sudo apt install -y libmysqlclient-dev
|
||
$ pip install pymysql
|
||
|
||
|
||
Installing BIND9
|
||
================
|
||
|
||
.. index::
|
||
double: install; bind9
|
||
|
||
Install the DNS server, BIND9
|
||
|
||
::
|
||
|
||
$ sudo apt install -y bind9
|
||
|
||
Update the BIND9 Configuration
|
||
|
||
::
|
||
|
||
$ sudo editor /etc/bind/named.conf.options
|
||
|
||
Change the corresponding lines in the config file:
|
||
|
||
::
|
||
|
||
options {
|
||
directory "/var/cache/bind";
|
||
dnssec-validation auto;
|
||
auth-nxdomain no; # conform to RFC1035
|
||
listen-on-v6 { any; };
|
||
allow-new-zones yes;
|
||
request-ixfr no;
|
||
recursion no;
|
||
};
|
||
|
||
Disable AppArmor for BIND9
|
||
|
||
::
|
||
|
||
$ sudo touch /etc/apparmor.d/disable/usr.sbin.named
|
||
$ sudo systemctl reload apparmor
|
||
|
||
Restart BIND9:
|
||
|
||
::
|
||
|
||
$ sudo systemctl restart bind9
|
||
|
||
Create and Import pools.yaml File
|
||
=================================
|
||
|
||
.. index::
|
||
double: install; pools
|
||
|
||
Create the pools.yaml file
|
||
|
||
::
|
||
|
||
$ editor pools.yaml
|
||
|
||
Copy or mirror the configuration from this sample file here:
|
||
|
||
.. literalinclude:: ../examples/basic-pools-sample.yaml
|
||
:language: yaml
|
||
|
||
Initialize the Database
|
||
=======================
|
||
|
||
.. index::
|
||
double: install; database
|
||
|
||
Sync the Designate database.
|
||
|
||
::
|
||
|
||
$ designate-manage database sync
|
||
|
||
Start the Central Service
|
||
=========================
|
||
|
||
.. index::
|
||
double: install; central
|
||
|
||
|
||
Start the central service.
|
||
|
||
::
|
||
|
||
$ designate-central
|
||
|
||
|
||
You'll now be seeing the log from the central service.
|
||
|
||
|
||
Initialize Pools Information
|
||
============================
|
||
|
||
Import the pools.yaml file into Designate. It is important that
|
||
``designate-central`` is started before invoking this command
|
||
|
||
::
|
||
|
||
$ designate-manage pool update --file pools.yaml
|
||
|
||
|
||
Start the other Services
|
||
========================
|
||
|
||
.. index::
|
||
double: install; services
|
||
|
||
Open up some new ssh windows and log in to your server (or open some new screen/tmux sessions).
|
||
|
||
::
|
||
|
||
$ cd openstack/designate
|
||
$ source .venv/bin/activate
|
||
|
||
Start the other services
|
||
|
||
::
|
||
|
||
$ designate-api
|
||
$ designate-mdns
|
||
$ designate-worker
|
||
$ designate-producer
|
||
|
||
You’ll now be seeing the logs from the other services.
|
||
|
||
Exercising the API
|
||
==================
|
||
|
||
.. note:: If you have a firewall enabled, make sure to open port 53, as well as Designate's default port (9001).
|
||
|
||
Using a web browser, curl statement, or a REST client, calls can be made to the
|
||
Designate API. You can find the various API calls on the api-ref_ document.
|
||
|
||
For example:
|
||
|
||
::
|
||
|
||
$ curl 127.0.0.1:9001/v2/zones -H 'Content-Type: application/json' --data '
|
||
{
|
||
"name": "example.com.",
|
||
"email": "example@example.com"
|
||
}'
|
||
|
||
{"status": "PENDING",.....
|
||
$ curl 127.0.0.1:9001/v2/zones
|
||
{"zones": [{"status": "ACTIVE",.....
|
||
|
||
The ``ACTIVE`` status shows that the zone propagated. So you should be able to perform a DNS query and
|
||
see it:
|
||
|
||
::
|
||
|
||
$ dig @127.0.0.1 example.com SOA +short
|
||
ns1-1.example.org. example.example.com. 1487884120 3531 600 86400 3600
|
||
|
||
You can find the IP Address of your server by running
|
||
|
||
::
|
||
|
||
ip addr show eth0 | grep "inet\b" | awk '{print $2}' | cut -d/ -f1
|
||
|
||
If you have Keystone set up, you can use it by configuring the ``[keystone_authtoken]`` section and changing
|
||
the ``auth_strategy = keystone`` in the ``service:api`` section. This will make it easier to use clients
|
||
like the ``openstack`` CLI that expect Keystone.
|
||
|
||
.. _api-ref: https://developer.openstack.org/api-ref/dns/
|