Add 'Getting Started' Doc
Add a 'Getting Started' page to the Documentation under doc/source/gettingstarted.rst. Added a sample configuration file that's referenced in the file under doc/examples. Bug: 1201490 Change-Id: I3d307568230f61d105908540ae809d583b347e56
This commit is contained in:
TimSimmons
parent
7030199923
commit
5f2b5fe266
156
doc/examples/basic-config-sample.conf
Normal file
156
doc/examples/basic-config-sample.conf
Normal file
@ -0,0 +1,156 @@
|
||||
[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 = /root/designate
|
||||
|
||||
# Log directory #Make sure and create this directory, or set it to some other directory that exists
|
||||
logdir = /var/log/designate
|
||||
|
||||
# Driver used for issuing notifications
|
||||
notification_driver = designate.openstack.common.notifier.rabbit_notifier
|
||||
|
||||
# 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 comand directly
|
||||
root_helper = sudo
|
||||
|
||||
# There has to be a better way to set these defaults
|
||||
allowed_rpc_exception_modules = designate.exceptions, designate.openstack.common.exception
|
||||
default_log_levels = amqplib=WARN, sqlalchemy=WARN, boto=WARN, suds=INFO, keystone=INFO, eventlet.wsgi.server=WARN, stevedore=WARN, keystoneclient.middleware.auth_token=INFO
|
||||
|
||||
########################
|
||||
## Service Configuration
|
||||
########################
|
||||
#-----------------------
|
||||
# Central Service
|
||||
#-----------------------
|
||||
[service:central]
|
||||
# Driver used for backend communication (e.g. fake, rpc, bind9, powerdns)
|
||||
backend_driver = powerdns
|
||||
|
||||
# List of blacklist domain name regexes
|
||||
#domain_name_blacklist = \.arpa\.$, \.novalocal\.$, \.localhost\.$, \.localdomain\.$, \.local\.$
|
||||
|
||||
# Accepted TLD list - http://data.iana.org/TLD/tlds-alpha-by-domain.txt
|
||||
accepted_tld_list = COM, NET
|
||||
|
||||
# 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 the bind the API server to
|
||||
api_port = 9001
|
||||
|
||||
# Authentication strategy to use - can be either "noauth" or "keystone"
|
||||
auth_strategy = noauth
|
||||
|
||||
# Enabled API Version 1 extensions
|
||||
enabled_extensions_v1 = diagnostics, sync, import, export, reports
|
||||
|
||||
#-----------------------
|
||||
# Agent Service
|
||||
#-----------------------
|
||||
[service:agent]
|
||||
# Driver used for backend communication (e.g. bind9, powerdns)
|
||||
#backend_driver = bind9
|
||||
|
||||
#-----------------------
|
||||
# Sink Service
|
||||
#-----------------------
|
||||
[service:sink]
|
||||
# List of notification handlers to enable, configuration of these needs to
|
||||
# correspond to a [handler:my_driver] section below or else in the config
|
||||
#enabled_notification_handlers = nova_fixed
|
||||
|
||||
########################
|
||||
## Storage Configuration
|
||||
########################
|
||||
#-----------------------
|
||||
# SQLAlchemy Storage
|
||||
#-----------------------
|
||||
[storage:sqlalchemy]
|
||||
# Database connection string - to configure options for a given implementation
|
||||
# like sqlalchemy or other see below
|
||||
database_connection = sqlite:///$state_path/designate.sqlite
|
||||
connection_debug = 100
|
||||
connection_trace = True
|
||||
sqlite_synchronous = True
|
||||
idle_timeout = 3600
|
||||
max_retries = 10
|
||||
retry_interval = 10
|
||||
|
||||
########################
|
||||
## Handler Configuration
|
||||
########################
|
||||
#-----------------------
|
||||
# Nova Fixed Handler
|
||||
#-----------------------
|
||||
[handler:nova_fixed]
|
||||
#domain_id = <random uuid>
|
||||
#notification_topics = monitor
|
||||
#control_exchange = 'nova'
|
||||
#format = '%(octet0)s-%(octet1)s-%(octet2)s-%(octet3)s.%(domain)s'
|
||||
|
||||
#------------------------
|
||||
# Quantum Floating Handler
|
||||
#------------------------
|
||||
[handler:quantum_floating]
|
||||
#domain_id = <random uuid>
|
||||
#notification_topics = monitor
|
||||
#control_exchange = 'quantum'
|
||||
#format = '%(octet0)s-%(octet1)s-%(octet2)s-%(octet3)s.%(domain)s'
|
||||
|
||||
|
||||
########################
|
||||
## Backend Configuration
|
||||
########################
|
||||
#-----------------------
|
||||
# Bind9 Backend
|
||||
#-----------------------
|
||||
[backend:bind9]
|
||||
#rndc_host = 127.0.0.1
|
||||
#rndc_port = 953
|
||||
#rndc_config_file = /etc/rndc.conf
|
||||
#rndc_key_file = /etc/rndc.key
|
||||
|
||||
#-----------------------
|
||||
# Bind9+MySQL Backend
|
||||
#-----------------------
|
||||
[backend:mysqlbind9]
|
||||
#database_connection = mysql://user:password@host/schema
|
||||
#rndc_host = 127.0.0.1
|
||||
#rndc_port = 953
|
||||
#rndc_config_file = /etc/rndc.conf
|
||||
#rndc_key_file = /etc/rndc.key
|
||||
#write_database = True
|
||||
#dns_server_type = master
|
||||
|
||||
#-----------------------
|
||||
# PowerDNS Backend
|
||||
#-----------------------
|
||||
[backend:powerdns]
|
||||
#database_connection = mysql://root:password@localhost/pdns
|
||||
database_connection = sqlite:///$state_path/pdns.sqlite
|
||||
connection_debug = 100
|
||||
connection_trace = True
|
||||
sqlite_synchronous = True
|
||||
idle_timeout = 3600
|
||||
max_retries = 10
|
||||
retry_interval = 10
|
||||
196
doc/source/gettingstarted.rst
Normal file
196
doc/source/gettingstarted.rst
Normal file
@ -0,0 +1,196 @@
|
||||
..
|
||||
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/
|
||||
|
||||
@ -12,6 +12,7 @@ Contents:
|
||||
:maxdepth: 2
|
||||
|
||||
architecture
|
||||
gettingstarted
|
||||
install
|
||||
configuration
|
||||
rest
|
||||
|
||||
Loading…
Reference in New Issue
Block a user