:gitroot: https://github.com/openshift

== DNS Service for OpenStack with Heat

NOTE: This repository contains deprecated scripts and ansible playbooks. Refer to the official documentation https://access.redhat.com/documentation/en-us/reference_architectures/2018/html-single/deploying_and_managing_openshift_3.9_on_red_hat_openstack_platform_10/[Deploying and Managing OpenShift 3.9 on Red Hat OpenStack Platform 10]

This repository defines a simple distributed DNS service within an
OpenStack Heat stack.  The goal is to de-mystify DNS services and
deployments for low level delegated sub-domains.  It is NOT to provide
enterprise scale and quality DNS services.

The service consists of BIND in a master/slave configuration set up
with dynamic updates defined in RFC 2136.

== Requirements

* Ansible
* python-openstackclient
* bind-utils

== Deployment Procedure

The stack is deployed using an Ansible playbook. Internally, Heat
creates the VMs, networks, etc. and Ansible then installs and
configures the packages.

=== Get the GIT repository

.Clone the Heat and Ansible repositories

[subs=attributes]
----
git clone {gitroot}/openshift-ansible-contrib.git
cd openshift-ansible-contrib/reference-architecture/osp-dns
----

=== Input Values

=== Ansible Input File

To deploy the DNS service, you need to provide some values first.
Create a `vars.yaml` file. This file will be passed to Ansible
later on.

See `vars.sample.yaml` for an example configuration.


==== Required Values

DOMAIN_NAME::
  The DNS zone to be served +
  Type: string +
  Example: `ocp3.example.com`

DNS_FORWARDERS::
  The upstream DNS servers. Any domain outside of the `domain_name`
  above will be forwarded to one of these servers. +
  Type: list +
  Example: `[8.8.8.8, 8.8.4.4]`

  If you're not sure what to put here, the values from your own
  `/etc/resolv.conf` might be a good start:

  ----
  $ grep '^\s*nameserver.*$' /etc/resolv.conf | awk '{print $2}'
  ----

UPDATE_KEY::
  A symmetric key value for dynamic DNS updates +
  Type: string +
  This is a BASE64 encoded MD5 hash, randomly generated by
  `ddns-confgen(8)` (bundled with `bind-utils`) or `rndc-confgen(8)`
  (bundled with `bind`).

  To generate the key, you can do this:

  ----
  $ ddns-confgen -r /dev/urandom | grep secret
  ----

  The key should look something like this:

  ----
  VXQsVJgDtEj1CFPjnt/OK3ilgJyAzT6OeY9CDoqa0/Q=
  ----

  NOTE: anyone with this key will be able to update the entries in your
  DNS server. Treat it as secret.

EXTERNAL_NETWORK::
  The name of an existing Neutron network in the OSP environment which
  allows inbound and outbound traffic. +
  Type: string +
  Example: `ext-net`

IMAGE::
  The name of a Glance image that will be used to for the DNS virtual
  machines. +
  Type: string +
  Example: `centos7`

SSH_USER::

  The username you can SSH as into the deployed VMs. This depends on
  the `image` you're using. For RHEL, it's `cloud-user`, for CentOS
  it's `centos`, for Fedora it's `fedora`. +
  Type: string +
  Example: `centos`

SSH_KEY_NAME::
  The name of an existing Nova keypair +
  Type: string +
  Example: `ocp_key`

==== Optional Values

STACK_NAME::
  The name of the Heat stack +
  Type: string +
  Default: `dns-service`

SLAVE_COUNT::
  The number of the BIND slave servers +
  Type: number +
  Default: `3`

SLAVE_SERVER_GROUP_POLICIES::

  List of OpenStack Nova policies applied on the slave servers. The
  default value places every VM in a different Nova Compute node. For
  small/all-in-one environments, you can change this to `affinity` +
  Type: array +
  Default: `['anti-affinity']`

FLAVOR::

  The OpenStack Nova flavor the VMs will use +
  Type: string +
  Default: `m1.small`

CONTACT::

  The email address that will serve in the DNS' contact for the given
  zone/domain. +
  Type: string +
  Default: `admin@ocp3.example.com`


==== Optional Values for Red Hat Enterprise Linux Images

The following values are all optional and only useful if your guest
images use Red Hat Enterprise Linux. They are used to register your
VMs with RHN.

RHN_USERNAME::
  Type: string +
  Default: `None`

RHN_PASSWORD::
  Type: string +
  Default: `None`

RHN_POOL::
  Type: string +
  Default: `None`

SAT6_HOSTNAME::
  Type: string +
  Default: `None`

SAT6_ORGANIZATION::
  Type: string +
  Default: `None`

SAT6_ACTIVATION_KEY::
  Type: string +
  Default: `None`


== Deploying the DNS service

The deployment uses the `vars.yaml` configuration file created in the
previous section.

The authentication variables for talking to the OpenStack services
(e.g. `OS_USERNAME` and `OS_AUTH_URL`) must be loaded (so running
`openstack stack list` succeeds).

Ansible must also be aware of the private SSH key for connecting to
the deployed VMs. The key should either be in a default location such
as `~/.ssh/id_rsa`, passed to the Ansible invocation via
`--private-key=path/to/key` or added to the SSH agent vith `ssh-add
path/to/key`.

NOTE: If you plan to delete and re-create the VMs multiple times (e.g.
  for testing or development) you may want to `export
  ANSIBLE_HOST_KEY_CHECKING=False` or prune your `~/.ssh/known_hosts`
  regularly. Otherwise SSH will fail if two VMs from different runs
  happen to receive the same IP address.

----
$ ansible-playbook deploy-dns.yaml -e @vars.yaml
----

The playbook takes three distinct actions:

1. Create a heat stack with network connectivity and instances created
and named to specification
1. Query the instances for hostname and IP address and create an inventory for Ansible
1. Install the packages and configure the DNS service
