README.rst - salt-formulas/designate - Gitiles


 =================
 Designate formula
 =================

 Designate provides DNSaaS services for OpenStack.

 Sample pillars
 ==============

 For Designate with BIND9 local backend:

 .. code:: yaml

     designate:
       server:
         enabled: true
         region: RegionOne
         domain_id: 5186883b-91fb-4891-bd49-e6769234a8fc
         version: ocata
         backend:
           bind9:
             rndc_key: 4pc+X4PDqb2q+5o72dISm72LM1Ds9X2EYZjqg+nmsS7FhdTwzFFY8l/iEDmHxnyjkA33EQC8H+z0fLLBunoitw==
             rndc_algorithm: hmac-sha512
         api:
           base_uri: 'http://127.0.0.1:9001'
           quotas_verify_project_id: False
         admin_api:
           enabled: true
           enabled_extensions_admin: quotas
         bind:
           api:
             address: 127.0.0.1
         database:
           engine: mysql
           host: 127.0.0.1
           port: 3306
           name:
             main_database: designate
             pool_manager: designate_pool_manager
           user: designate
           password: passw0rd
         identity:
           engine: keystone
           host: 127.0.0.1
           port: 35357
           tenant: service
           user: designate
           password: passw0rd
         mdns:
           address: 0.0.0.0
           port: 5354
         message_queue:
           engine: rabbitmq
           members:
           - host: 127.0.0.1
           user: openstack
           password: password
           virtual_host: '/openstack'
         pools:
           default:
             description: 'default pool'
             attributes:
               service_tier: GOLD
             ns_records:
               - hostname: 'ns1.example.org.'
                 priority: 10
             nameservers:
               - host: 127.0.0.1
                 port: 53
             targets:
               default_target:
                 type: bind9
                 description: 'default target'
                 masters:
                   - host: 127.0.0.1
                     port: 5354
                 options:
                   host: 127.0.0.1
                   port: 53
                   rndc_host: 127.0.0.1
                   rndc_port: 953
                   rndc_key_file: /etc/designate/rndc.key
         quota:
           zones: 40
       worker:
         enabled: true
 .. note::
    *domain_id* parameter is UUID of DNS zone managed by designate-sink service. This zone will
    be populated by A records for fixed and floating ip addresses of spawned VMs. After designate
    is deployed and zone is created, this parameter should be updated accordingly to UUID of
    newly created zone. Then designate state should be reapplied.

 .. note::
    *server:api:base_uri* allows to set URL which is returned in designate-api responses, it is
    useful in cases when, designate-api is deployed under proxy server. If not overriden in reclass,
    it defaults to http://*server:bind:api:address*:9001/.

 .. note::
    *server:mdns:address* and *server:mdns:port* options allow to change MDNS listening address and
    port. Changes to server:pools:*:targets will be also required if the MDNS's address and port are
    being used there.

 .. note::
    *worker:enabled* sets worker role and installs designate-worker and designate-producer packages
    which services will push changes to backend DNS servers.
    *pool_manager:enabled* should be a default role for older releases of OpenStack, older than
    Newton in which designate-worker and designate-producer were represented.
    In releases starting from Newton, only Designate pool manager service still allows live syncs
    with Power DNS server for now.

 .. note::
    *server:quota:zones* allows to set default value for zones quota for all projects and users.
    In case with Designate tempest plugin (0.2.0) zones quota should be increased to 40, so all
    tests can pass.

 .. note::
    *server:api:quotas_verify_project_id* allows to enable project id verification when setting quotas
    for project, when Designate will ask Keystone if the project id is valid

 Pools pillar for BIND9 master and multiple slaves setup:

 .. code:: yaml

     pools:
       default:
         description: 'default pool'
         attributes:
           service_tier: GOLD
         ns_records:
           - hostname: 'ns1.example.org.'
             priority: 10
         nameservers:
           - host: 192.168.0.1
             port: 53
           - host: 192.168.0.2
             port: 53
           - host: 192.168.0.3
             port: 53
         targets:
           default_target:
             type: bind9
             description: 'default target'
             masters:
               - host: 192.168.0.4
                 port: 5354
             options:
               host: 192.168.0.4
               port: 53
               rndc_host: 192.168.0.4
               rndc_port: 953
               rndc_key_file: /etc/designate/rndc.key

 Enhanced logging with logging.conf
 ----------------------------------

 By default logging.conf is disabled.

 That is possible to enable per-binary logging.conf with new variables:
   * openstack_log_appender - set it to true to enable log_config_append for all OpenStack services;
   * openstack_fluentd_handler_enabled - set to true to enable FluentHandler for all Openstack services.

 Only WatchedFileHandler and FluentHandler are available.

 Also it is possible to configure this with pillar:

 .. code-block:: yaml

   designate:
     server:
       logging:
         log_appender: true
         log_handlers:
           watchedfile:
             enabled: true
           fluentd:
             enabled: true

 Usage
 =====

 Create server

 .. code:: bash

     designate server-create --name ns.example.com.

 Create domain

 .. code:: bash

     designate domain-create --name example.com. --email mail@example.com

 Create record

 .. code:: bash

     designate record-create example.com. --name test.example.com. --type A --data 10.2.14.15

 Test it

 .. code:: bash

     dig @127.0.0.1 test.example.com.

 Enable x509 and ssl communication between Designate and Galera cluster.
 ---------------------
 By default communication between Designate and Galera is unsecure.

 designate:
   server:
     database:
       x509:
         enabled: True

 You able to set custom certificates in pillar:

 designate:
   server:
     database:
       x509:
         cacert: (certificate content)
         cert: (certificate content)
         key: (certificate content)

 You can read more about it here:
     https://docs.openstack.org/security-guide/databases/database-access-control.html

 Enable x509 and ssl communication between Designate and Rabbitmq.
 ---------------------
 By default communication between Designate and Rabbitmq is unsecure.

 .. code-block:: yaml

 designate:
   server:
     message_queue:
       x509:
         enabled: True

 You able to set custom certificates in pillar:

 .. code-block:: yaml

 designate:
   server:
     message_queue:
       x509:
         cacert: (certificate content)
         cert: (certificate content)
         key: (certificate content)

 You can read more about it here:
     https://docs.openstack.org/security-guide/messaging/security.html

 Using designate client to create zones and install client packages
 -------------------------------------------------------------------

 designate:
   client:
     enabled: true
     resources:
       v2:
         enabled: true
         cloud_name: admin_identity
         zones:
           test_zone:
             name: test.zone.
             email: admin@test.zone

 Upgrades
 ========

 Each openstack formula provide set of phases (logical bloks) that will help to
 build flexible upgrade orchestration logic for particular components. The list
 of phases might and theirs descriptions are listed in table below:

 +-------------------------------+------------------------------------------------------+
 | State                         | Description                                          |
 +===============================+======================================================+
 | <app>.upgrade.service_running | Ensure that all services for particular application  |
 |                               | are enabled for autostart and running                |
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.service_stopped | Ensure that all services for particular application  |
 |                               | disabled for autostart and dead                      |
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.pkgs_latest     | Ensure that packages used by particular application  |
 |                               | are installed to latest available version.           |
 |                               | This will not upgrade data plane packages like qemu  |
 |                               | and openvswitch as usually minimal required version  |
 |                               | in openstack services is really old. The data plane  |
 |                               | packages should be upgraded separately by `apt-get   |
 |                               | upgrade` or `apt-get dist-upgrade`                   |
 |                               | Applying this state will not autostart service.      |
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.render_config   | Ensure configuration is rendered actual version.     +
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.pre             | We assume this state is applied on all nodes in the  |
 |                               | cloud before running upgrade.                        |
 |                               | Only non destructive actions will be applied during  |
 |                               | this phase. Perform service built in service check   |
 |                               | like (keystone-manage doctor and nova-status upgrade)|
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.upgrade.pre     | Mostly applicable for data plane nodes. During this  |
 |                               | phase resources will be gracefully removed from      |
 |                               | current node if it is allowed. Services for upgraded |
 |                               | application will be set to admin disabled state to   |
 |                               | make sure node will not participate in resources     |
 |                               | scheduling. For example on gtw nodes this will set   |
 |                               | all agents to admin disable state and will move all  |
 |                               | routers to other agents.                             |
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.upgrade         | This state will basically upgrade application on     |
 |                               | particular target. Stop services, render             |
 |                               | configuration, install new packages, run offline     |
 |                               | dbsync (for ctl), start services. Data plane should  |
 |                               | not be affected, only OpenStack python services.     |
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.upgrade.post    | Add services back to scheduling.                     |
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.post            | This phase should be launched only when upgrade of   |
 |                               | the cloud is completed. Cleanup temporary files,     |
 |                               | perform other post upgrade tasks.                    |
 +-------------------------------+------------------------------------------------------+
 | <app>.upgrade.verify          | Here we will do basic health checks (API CRUD        |
 |                               | operations, verify do not have dead network          |
 |                               | agents/compute services)                             |
 +-------------------------------+------------------------------------------------------+


 Upgrade pillar example:

 .. code-block:: yaml

 designate:
   upgrade:
     enabled: true
     old_release: pike
     new_release: queens
     verify:
       zone:
         enabled: true
         name: upgradetest.com.

 .. note::
    During upgrade zone creation testing is disabled by default,
    because conditions for zone successfull creation, are very specific to each environment.
    When enabling zone testing, allowed tlds in Designate should be considered.
    More details about TLDS - https://docs.openstack.org/designate/pike/admin/tlds.html

 Documentation and Bugs
 ======================

 To learn how to install and update salt-formulas, consult the documentation
 available online at:

     http://salt-formulas.readthedocs.io/

 In the unfortunate event that bugs are discovered, they should be reported to
 the appropriate issue tracker. Use Github issue tracker for specific salt
 formula:

     https://github.com/salt-formulas/salt-formula-letsencrypt/issues

 For feature requests, bug reports or blueprints affecting entire ecosystem,
 use Launchpad salt-formulas project:

     https://launchpad.net/salt-formulas

 You can also join salt-formulas-users team and subscribe to mailing list:

     https://launchpad.net/~salt-formulas-users

 Developers wishing to work on the salt-formulas projects should always base
 their work on master branch and submit pull request against specific formula.

     https://github.com/salt-formulas/salt-formula-letsencrypt

 Any questions or feedback is always welcome so feel free to join our IRC
 channel:

     #salt-formulas @ irc.freenode.net

	=================
	Designate formula
	=================

	Designate provides DNSaaS services for OpenStack.

	Sample pillars
	==============

	For Designate with BIND9 local backend:

	.. code:: yaml

	designate:
	server:
	enabled: true
	region: RegionOne
	domain_id: 5186883b-91fb-4891-bd49-e6769234a8fc
	version: ocata
	backend:
	bind9:
	rndc_key: 4pc+X4PDqb2q+5o72dISm72LM1Ds9X2EYZjqg+nmsS7FhdTwzFFY8l/iEDmHxnyjkA33EQC8H+z0fLLBunoitw==
	rndc_algorithm: hmac-sha512
	api:
	base_uri: 'http://127.0.0.1:9001'
	quotas_verify_project_id: False
	admin_api:
	enabled: true
	enabled_extensions_admin: quotas
	bind:
	api:
	address: 127.0.0.1
	database:
	engine: mysql
	host: 127.0.0.1
	port: 3306
	name:
	main_database: designate
	pool_manager: designate_pool_manager
	user: designate
	password: passw0rd
	identity:
	engine: keystone
	host: 127.0.0.1
	port: 35357
	tenant: service
	user: designate
	password: passw0rd
	mdns:
	address: 0.0.0.0
	port: 5354
	message_queue:
	engine: rabbitmq
	members:
	- host: 127.0.0.1
	user: openstack
	password: password
	virtual_host: '/openstack'
	pools:
	default:
	description: 'default pool'
	attributes:
	service_tier: GOLD
	ns_records:
	- hostname: 'ns1.example.org.'
	priority: 10
	nameservers:
	- host: 127.0.0.1
	port: 53
	targets:
	default_target:
	type: bind9
	description: 'default target'
	masters:
	- host: 127.0.0.1
	port: 5354
	options:
	host: 127.0.0.1
	port: 53
	rndc_host: 127.0.0.1
	rndc_port: 953
	rndc_key_file: /etc/designate/rndc.key
	quota:
	zones: 40
	worker:
	enabled: true
	.. note::
	domain_id parameter is UUID of DNS zone managed by designate-sink service. This zone will
	be populated by A records for fixed and floating ip addresses of spawned VMs. After designate
	is deployed and zone is created, this parameter should be updated accordingly to UUID of
	newly created zone. Then designate state should be reapplied.

	.. note::
	server:api:base_uri allows to set URL which is returned in designate-api responses, it is
	useful in cases when, designate-api is deployed under proxy server. If not overriden in reclass,
	it defaults to http://server:bind:api:address:9001/.

	.. note::
	server:mdns:address and server:mdns:port options allow to change MDNS listening address and
	port. Changes to server:pools:*:targets will be also required if the MDNS's address and port are
	being used there.

	.. note::
	worker:enabled sets worker role and installs designate-worker and designate-producer packages
	which services will push changes to backend DNS servers.
	pool_manager:enabled should be a default role for older releases of OpenStack, older than
	Newton in which designate-worker and designate-producer were represented.
	In releases starting from Newton, only Designate pool manager service still allows live syncs
	with Power DNS server for now.

	.. note::
	server:quota:zones allows to set default value for zones quota for all projects and users.
	In case with Designate tempest plugin (0.2.0) zones quota should be increased to 40, so all
	tests can pass.

	.. note::
	server:api:quotas_verify_project_id allows to enable project id verification when setting quotas
	for project, when Designate will ask Keystone if the project id is valid

	Pools pillar for BIND9 master and multiple slaves setup:

	.. code:: yaml

	pools:
	default:
	description: 'default pool'
	attributes:
	service_tier: GOLD
	ns_records:
	- hostname: 'ns1.example.org.'
	priority: 10
	nameservers:
	- host: 192.168.0.1
	port: 53
	- host: 192.168.0.2
	port: 53
	- host: 192.168.0.3
	port: 53
	targets:
	default_target:
	type: bind9
	description: 'default target'
	masters:
	- host: 192.168.0.4
	port: 5354
	options:
	host: 192.168.0.4
	port: 53
	rndc_host: 192.168.0.4
	rndc_port: 953
	rndc_key_file: /etc/designate/rndc.key

	Enhanced logging with logging.conf
	----------------------------------

	By default logging.conf is disabled.

	That is possible to enable per-binary logging.conf with new variables:
	* openstack_log_appender - set it to true to enable log_config_append for all OpenStack services;
	* openstack_fluentd_handler_enabled - set to true to enable FluentHandler for all Openstack services.

	Only WatchedFileHandler and FluentHandler are available.

	Also it is possible to configure this with pillar:

	.. code-block:: yaml

	designate:
	server:
	logging:
	log_appender: true
	log_handlers:
	watchedfile:
	enabled: true
	fluentd:
	enabled: true

	Usage
	=====

	Create server

	.. code:: bash

	designate server-create --name ns.example.com.

	Create domain

	.. code:: bash

	designate domain-create --name example.com. --email mail@example.com

	Create record

	.. code:: bash

	designate record-create example.com. --name test.example.com. --type A --data 10.2.14.15

	Test it

	.. code:: bash

	dig @127.0.0.1 test.example.com.

	Enable x509 and ssl communication between Designate and Galera cluster.
	---------------------
	By default communication between Designate and Galera is unsecure.

	designate:
	server:
	database:
	x509:
	enabled: True

	You able to set custom certificates in pillar:

	designate:
	server:
	database:
	x509:
	cacert: (certificate content)
	cert: (certificate content)
	key: (certificate content)

	You can read more about it here:
	https://docs.openstack.org/security-guide/databases/database-access-control.html

	Enable x509 and ssl communication between Designate and Rabbitmq.
	---------------------
	By default communication between Designate and Rabbitmq is unsecure.

	.. code-block:: yaml

	designate:
	server:
	message_queue:
	x509:
	enabled: True

	You able to set custom certificates in pillar:

	.. code-block:: yaml

	designate:
	server:
	message_queue:
	x509:
	cacert: (certificate content)
	cert: (certificate content)
	key: (certificate content)

	You can read more about it here:
	https://docs.openstack.org/security-guide/messaging/security.html

	Using designate client to create zones and install client packages
	-------------------------------------------------------------------

	designate:
	client:
	enabled: true
	resources:
	v2:
	enabled: true
	cloud_name: admin_identity
	zones:
	test_zone:
	name: test.zone.
	email: admin@test.zone

	Upgrades
	========

	Each openstack formula provide set of phases (logical bloks) that will help to
	build flexible upgrade orchestration logic for particular components. The list
	of phases might and theirs descriptions are listed in table below:

	+-------------------------------+------------------------------------------------------+
	\| State \| Description \|
	+===============================+======================================================+
	\| <app>.upgrade.service_running \| Ensure that all services for particular application \|
	\| \| are enabled for autostart and running \|
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.service_stopped \| Ensure that all services for particular application \|
	\| \| disabled for autostart and dead \|
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.pkgs_latest \| Ensure that packages used by particular application \|
	\| \| are installed to latest available version. \|
	\| \| This will not upgrade data plane packages like qemu \|
	\| \| and openvswitch as usually minimal required version \|
	\| \| in openstack services is really old. The data plane \|
	\| \| packages should be upgraded separately by `apt-get \|
	\| \| upgrade` or `apt-get dist-upgrade` \|
	\| \| Applying this state will not autostart service. \|
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.render_config \| Ensure configuration is rendered actual version. +
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.pre \| We assume this state is applied on all nodes in the \|
	\| \| cloud before running upgrade. \|
	\| \| Only non destructive actions will be applied during \|
	\| \| this phase. Perform service built in service check \|
	\| \| like (keystone-manage doctor and nova-status upgrade)\|
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.upgrade.pre \| Mostly applicable for data plane nodes. During this \|
	\| \| phase resources will be gracefully removed from \|
	\| \| current node if it is allowed. Services for upgraded \|
	\| \| application will be set to admin disabled state to \|
	\| \| make sure node will not participate in resources \|
	\| \| scheduling. For example on gtw nodes this will set \|
	\| \| all agents to admin disable state and will move all \|
	\| \| routers to other agents. \|
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.upgrade \| This state will basically upgrade application on \|
	\| \| particular target. Stop services, render \|
	\| \| configuration, install new packages, run offline \|
	\| \| dbsync (for ctl), start services. Data plane should \|
	\| \| not be affected, only OpenStack python services. \|
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.upgrade.post \| Add services back to scheduling. \|
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.post \| This phase should be launched only when upgrade of \|
	\| \| the cloud is completed. Cleanup temporary files, \|
	\| \| perform other post upgrade tasks. \|
	+-------------------------------+------------------------------------------------------+
	\| <app>.upgrade.verify \| Here we will do basic health checks (API CRUD \|
	\| \| operations, verify do not have dead network \|
	\| \| agents/compute services) \|
	+-------------------------------+------------------------------------------------------+


	Upgrade pillar example:

	.. code-block:: yaml

	designate:
	upgrade:
	enabled: true
	old_release: pike
	new_release: queens
	verify:
	zone:
	enabled: true
	name: upgradetest.com.

	.. note::
	During upgrade zone creation testing is disabled by default,
	because conditions for zone successfull creation, are very specific to each environment.
	When enabling zone testing, allowed tlds in Designate should be considered.
	More details about TLDS - https://docs.openstack.org/designate/pike/admin/tlds.html

	Documentation and Bugs
	======================

	To learn how to install and update salt-formulas, consult the documentation
	available online at:

	http://salt-formulas.readthedocs.io/

	In the unfortunate event that bugs are discovered, they should be reported to
	the appropriate issue tracker. Use Github issue tracker for specific salt
	formula:

	https://github.com/salt-formulas/salt-formula-letsencrypt/issues

	For feature requests, bug reports or blueprints affecting entire ecosystem,
	use Launchpad salt-formulas project:

	https://launchpad.net/salt-formulas

	You can also join salt-formulas-users team and subscribe to mailing list:

	https://launchpad.net/~salt-formulas-users

	Developers wishing to work on the salt-formulas projects should always base
	their work on master branch and submit pull request against specific formula.

	https://github.com/salt-formulas/salt-formula-letsencrypt

	Any questions or feedback is always welcome so feel free to join our IRC
	channel:

	#salt-formulas @ irc.freenode.net