Development Environment on Ubuntu

Designate is comprised of four main components Designate API, Designate Central, Designate MiniDNS, and Designate Pool Manager, supported by a few standard open source components. For more information see 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 Architecture and Production Architecture.

For this guide you will need access to an Ubuntu Server (14.04).

Development Environment

Installing Designate

1. Install system package dependencies (Ubuntu)

$ apt-get update
$ apt-get install python-pip python-virtualenv git
$ apt-get build-dep python-lxml

2. Clone the Designate repo from GitHub

$ mkdir openstack
$ cd openstack
$ git clone https://git.openstack.org/openstack/designate.git
$ cd designate

3. Setup a virtualenv

Note

This is an optional step, but will allow Designate’s dependencies to be installed in a contained environment that can be easily deleted if you choose to start over or uninstall Designate.

$ virtualenv --no-site-packages .venv
$ . .venv/bin/activate

4. Install Designate and its dependencies

Note

If you run into the error: Installed distribution pbr 1.1.1 conflicts with requirement pbr>=0.6,!=0.7,<1.0, try doing pip install pbr==0.11.0

$ pip install -r requirements.txt -r test-requirements.txt
$ python setup.py develop

5. 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

6. Create Designate’s config files by copying the sample config files

$ ls *.sample | while read f; do cp $f $(echo $f | sed "s/.sample$//g"); done

7. Make the directory for Designate’s log files

$ mkdir -p ../../log

8. Make the directory for Designate’s state files

$ mkdir -p ../../state

Configuring Designate

Open the designate.conf file for editing

$ editor designate.conf

Copy or mirror the configuration from this sample file here:

[DEFAULT]
########################
## General Configuration
########################
# Show more verbose log output (sets INFO log level output)
verbose = True

# Show debugging output in logs (sets DEBUG log level output)
debug = True

# Top-level directory for maintaining designate's state.
state_path = $pybasedir/state

# Log directory
logdir = $pybasedir/log

# Driver used for issuing notifications
notification_driver = messaging

# Use "sudo designate-rootwrap /etc/designate/rootwrap.conf" to use the real
# root filter facility.
# Change to "sudo" to skip the filtering and just run the command directly
# root_helper = sudo

# Supported record types
#supported_record_type = A, AAAA, CNAME, MX, SRV, TXT, SPF, NS, PTR, SSHFP, SOA

# RabbitMQ Config
rabbit_userid = designate
rabbit_password = designate
#rabbit_virtual_host = /
#rabbit_use_ssl = False
#rabbit_hosts = 127.0.0.1:5672

########################
## Service Configuration
########################
#-----------------------
# Central Service
#-----------------------
[service:central]
# Maximum domain name length
#max_domain_name_len = 255

# Maximum record name length
#max_record_name_len = 255

#-----------------------
# API Service
#-----------------------
[service:api]
# Address to bind the API server
api_host = 0.0.0.0

# Port to bind the API server
api_port = 9001

# Authentication strategy to use - can be either "noauth" or "keystone"
auth_strategy = noauth

# Enable API Version 1
enable_api_v1 = True

# Enabled API Version 1 extensions
enabled_extensions_v1 = diagnostics, quotas, reports, sync, touch

# Enable API Version 2
enable_api_v2 = True

# Enabled API Version 2 extensions
enabled_extensions_v2 = quotas, reports

#-----------------------
# mDNS Service
#-----------------------
[service:mdns]
#workers = None
#host = 0.0.0.0
#port = 5354
#tcp_backlog = 100

#-----------------------
# Pool Manager Service
#-----------------------
[service:pool_manager]
pool_id = 794ccc2c-d751-44fe-b57f-8894c9f5c842
#workers = None
#threshold_percentage = 100
#poll_timeout = 30
#poll_retry_interval = 2
#poll_max_retries = 3
#poll_delay = 1
#periodic_recovery_interval = 120
#periodic_sync_interval = 300
#periodic_sync_seconds = None
#cache_driver = sqlalchemy

#####################
## Pool Configuration
#####################
[pool:794ccc2c-d751-44fe-b57f-8894c9f5c842]
nameservers = f02a0c72-c701-4ec2-85d7-197b30992ce8
targets = f02a0c72-c701-4ec2-85d7-197b30992ce9

[pool_nameserver:f02a0c72-c701-4ec2-85d7-197b30992ce8]
host = 127.0.0.1
port = 53

[pool_target:f02a0c72-c701-4ec2-85d7-197b30992ce9]
masters = 127.0.0.1:5354
type = bind9
options = port: 53, host: 127.0.0.1

###################################
## Pool Manager Cache Configuration
###################################
#-----------------------
# SQLAlchemy Pool Manager Cache
#-----------------------
[pool_manager_cache:sqlalchemy]
connection = mysql+pymysql://root:password@127.0.0.1/designate_pool_manager?charset=utf8
#connection_debug = 100
#connection_trace = False
#sqlite_synchronous = True
#idle_timeout = 3600
#max_retries = 10
#retry_interval = 10

########################
## Storage Configuration
########################
#-----------------------
# SQLAlchemy Storage
#-----------------------
[storage:sqlalchemy]
# Database connection string - to configure options for a given implementation
# like sqlalchemy or other see below
connection = mysql+pymysql://root:password@127.0.0.1/designate?charset=utf8
#connection_debug = 100
#connection_trace = True
#sqlite_synchronous = True
#idle_timeout = 3600
#max_retries = 10
#retry_interval = 10

Installing RabbitMQ

Note

Do the following commands as “root” or via sudo <command>

Install the RabbitMQ package

$ apt-get install rabbitmq-server

Create a user:

$ rabbitmqctl add_user designate designate

Give the user access to the / vhost:

$ sudo rabbitmqctl set_permissions -p "/" designate ".*" ".*" ".*"

Installing MySQL

Install the MySQL server package

$ apt-get install mysql-server-5.5

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> CREATE DATABASE `designate_pool_manager` CHARACTER SET utf8 COLLATE utf8_general_ci;
mysql> exit;

Install additional packages

$ apt-get install libmysqlclient-dev
$ pip install pymysql

Installing BIND9

Install the DNS server, BIND9

$ apt-get install bind9

# Update the BIND9 Configuration
$ 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
$ touch /etc/apparmor.d/disable/usr.sbin.named
$ service apparmor reload

# Restart BIND9:
$ service bind9 restart

Initialize & Start the Central Service

Sync the Designate database.

$ designate-manage database sync

Start the central service.

$ designate-central

You’ll now be seeing the log from the central service.

Initialize & Start the API Service

Open up a new ssh window and log in to your server (or however you’re communicating with your server).

$ cd openstack/designate

# Make sure your virtualenv is sourced
$ source .venv/bin/activate

# Start the API Service
$ designate-api

You’ll now be seeing the log from the API service.

Initialize & Start the Pool Manager Service

Open up a new ssh window and log in to your server (or however you’re communicating with your server).

# Sync the Pool Manager's cache:
$ designate-manage pool-manager-cache sync

# Start the pool manager service:
$ designate-pool-manager

You’ll now be seeing the log from the Pool Manager service.

Initialize & Start the MiniDNS Service

Open up a new ssh window and log in to your server (or however you’re communicating with your server).

# Start the minidns service:
$ designate-mdns

You’ll now be seeing the log from the MiniDNS service.

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 using the following format where “api_version” is either v1 or v2 and “command” is any of the commands listed under the corresponding version at REST API Documentation

http://IP.Address:9001/api_version/command

You can find the IP Address of your server by running

curl -s checkip.dyndns.org | sed -e 's/.*Current IP Address: //' -e 's/<.*$//'

A couple of notes on the API:

• Before Domains are created, you must create a server (/v1/servers).