designate/doc/source/gettingstarted.rst

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

.. _gettingstarted:

========================
Getting Started
========================

Designate provides DNS As A Service (DNSaaS) for OpenStack:

- REST API for domain/record management
- Multi-tenant
- Integrated with Keystone for authentication
- Framework in place to integrate with Nova and Quantum notifications (for auto-generated records)

- Support for PowerDNS and Bind9 out of the box

Designate is comprised of three components. For more info see :doc:`architecture`.

This guide will show how to install a simple development environment for Designate, with a PowerDNS backend.
You will be able to see Designate in action, although not to its full potential.

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

Development Environment
+++++++++++++++++++++++

Installing Designate
====================

.. index::
   double: install; designate

1. Install system package dependencies (Ubuntu)

::

   $ apt-get install python-pip python-virtualenv
   $ apt-get install rabbitmq-server
   $ apt-get build-dep python-lxml

2. Clone the Designate repo off of Stackforge

::

   $ git clone https://github.com/stackforge/designate.git
   $ cd designate


3. Setup virtualenv

.. note::
   This is to not interfere with system packages etc.

::

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

4. Install Designate and its dependencies

::

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


.. note::
   Everything from here on out should take place in or below your designate/etc folder

5. Copy sample config files to edit

::

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

6. Install the DNS server, PowerDNS

::

      $ DEBIAN_FRONTEND=noninteractive apt-get install pdns-server pdns-backend-sqlite3
      #Update path to SQLite database to /root/designate/powerdns.sqlite or wherever your top level designate directory resides
      $ editor /etc/powerdns/pdns.d/pdns.local.gsqlite3
      #Change the corresponding line in the config file to mirror:
      gsqlite3-database=/root/designate/powerdns.sqlite
      #Restart PowerDNS:
      $ service pdns restart


7. If you intend to run Designate as a non-root user, then sudo permissions need to be granted

::

   $ echo "designate ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/90-designate
   $ sudo chmod 0440 /etc/sudoers.d/90-designate


Configure Designate
===================

.. index::
   double: configure; designate
::

  $ editor designate.conf

Copy or mirror the configuration from this sample file here:

.. literalinclude:: ../examples/basic-config-sample.conf

Initialize & Start the Central Service
======================================

.. index::
   double: install; central

::

   #Initialize and sync the Designate database:
   $ designate-manage database-init
   $ designate-manage database-sync
   #Initialize and sync the PowerDNS database:
   $ designate-manage powerdns database-init
   $ designate-manage powerdns database-sync
   #Start the central service:
   $ designate-central

.. note::
   If you get an error of the form: ERROR [designate.openstack.common.rpc.common] AMQP server on localhost:5672 is unreachable: Socket closed

   Run the following command:

::

   $ rabbitmqctl change_password guest guest
   #Then try starting the service again
   $ designate-central

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

Initialize & Start the API Service
==================================

.. index::
   double: install; api

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

::

   $ cd root/designate
   #Make sure your virtualenv is sourced
   $ . .venv/bin/activate
   $ cd etc/designate
   #Start the API Service
   $ designate-api
   #You may have to run root/designate/bin/designate-api

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

Exercising the API
==================
Using a web browser, curl statement, or a Rest client calls can be made to the Designate API using the following format where “command” is any of the commands listed in the Designate Documentation_.

.. _Documentation: http://designate.readthedocs.org/en/latest/rest.html

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

You can find the IP Address of your server by running

::

   wget http://ipecho.net/plain -O - -q ; echo

If you’d like to see an instance in action, go here:
http://166.78.183.212:9001/

A couple of notes on the API:

- Before Domains are created, you must create a server.
- On GET requests for domains, servers, records, etc be sure not to append a ‘/’ to the end of the request. For example …:9001/v1/servers/