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


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