Designate is comprised of four main components Designate API, Designate Central, designate-mdns, 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:
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.
For this guide you will need access to an Ubuntu Server (16.04).
$ sudo apt update
$ sudo apt install -y python-pip python-virtualenv libssl-dev libffi-dev git
$ sudo apt build-dep -y python-lxml
$ mkdir openstack
$ cd openstack
$ git clone https://git.openstack.org/openstack/designate.git
$ cd designate
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
$ pip install -U pip
$ pip install -e .
Note
Everything from here on out should take place in or below your designate/etc folder
$ cd etc/designate
$ cp -a rootwrap.conf.sample rootwrap.conf
$ mkdir -p ../../state
Create the designate.conf file
$ editor designate.conf
Copy or mirror the configuration from this sample file here:
[DEFAULT]
########################
## General Configuration
########################
# Show debugging output in logs (sets DEBUG log level output)
debug = True
# Top-level directory for maintaining designate's state.
state_path = $pybasedir/state
# 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
#-----------------------
# Worker Service
#-----------------------
[service:worker]
# Whether to send events to worker instead of Pool Manager
enabled = True
#workers = None
#threads = 1000
#threshold_percentage = 100
#poll_timeout = 30
#poll_retry_interval = 15
#poll_max_retries = 10
#poll_delay = 5
notify = True
#-----------------------
# Producer Service
#-----------------------
[service:producer]
#workers = None
#threads = 1000
#enabled_tasks = None
#export_synchronous = True
#------------------------
# Deleted domains purging
#------------------------
[producer_task:domain_purge]
#interval = 3600 # 1h
#batch_size = 100
#time_threshold = 604800 # 7 days
#------------------------
# Delayed zones NOTIFY
#------------------------
[producer_task:delayed_notify]
#interval = 5
#------------------------
# Worker Periodic Recovery
#------------------------
[producer_task:worker_periodic_recovery]
#interval = 120
########################
## 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
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 ".*" ".*" ".*"
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:
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
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 the pools.yaml file
$ editor pools.yaml
Copy or mirror the configuration from this sample file here:
- 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 BIND9 Pool
attributes: {}
# List out the NS records for zones hosted within this pool
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, most often, there will be one
# entry for each BIND server.
targets:
- type: bind9
description: BIND9 Server 1
# List out the designate-mdns servers from which BIND servers should
# request zone transfers (AXFRs) from.
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/bind/rndc.key
# Optional list of additional IP/Port's for which designate-mdns will send
# DNS NOTIFY packets to
# also_notifies:
# - host: 192.0.2.4
# port: 53
Start the central service.
$ designate-central
You’ll now be seeing the log from the central service.
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
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.
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.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.