README.rst

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