Promenade Configuration
=======================

Promenade is configured using a set Kubernetes-like YAML documents.  Many of
these documents can be automatically derived from a few core configuration
documents or generated automatically (e.g. certificates).  All of these
documents can be specified in detail allowing for fine-grained control over
cluster deployment.

Generally, these documents have the following form:

.. code-block:: yaml

    ---
    apiVersion: promenade/v1
    kind: Kind
    metadata:
    compliant: metadata
    spec:
    detailed: data

``apiVersion`` identifies the document as Promenade configuration.  Currently
only ``promenade/v1`` is supported.

``kind`` describe the detailed type of document.  Valid kinds are:

- ``Certificate`` - An x509 certificate.
- ``CertificateAuthority`` - An x509 certificate authority certificate.
- ``CertificateAuthorityKey`` - The private key for a certificate authority.
- ``CertificateKey`` - The private key for a certificate.
- ``Cluster`` - Cluster configuration containing node host names, IPs & roles.
- ``Etcd`` - Specific configuration for an etcd cluster.
- ``Masters`` - Host names and IPs of master nodes.
- ``Network`` - Configuration details for Kubernetes networking components.
- ``Node`` - Specific configuration for a single host.
- ``PrivateKey`` - A private key, e.g. the ``controller-manager``'s token signing key.
- ``PublicKey`` - A public key, e.g. the key for verifying service account tokens.
- ``Versions`` - Specifies versions of packages and images to be deployed.

``metadata`` are used to select specific documents of a given ``kind``.  For
example, the various services must each select their specific ``Certificate``s.
``metadata`` are also used by Drydock to select the configuration files that are
needed for a particular node.

``spec`` contains specific data for each kind of configuration document.

Additionally, documents for [Armada](https://github.com/att-comdev/armada) are
allowed and will be applied after CNI and DNS are deployed.

Generating Configuration from Minimal Input
-------------------------------------------

To construct a complete set of cluster configuration, the minimal input are
``Cluster``, ``Network`` and ``Versions`` documents.  To see complete examples of
these, please see the [example](example/vagrant-input-config.yaml).

The ``Cluster`` configuration must contain an entry for each host for which
configuration should be generated.  Each host must contain an ``ip``, and
optionally ``roles`` and ``additional_labels``.  Valid ``roles`` are currently
``genesis`` and ``master``.  ``additional_labels`` are Kubernetes labels which will
be added to the node.

Here's an example ``Cluster`` document:

.. code-block:: yaml

    apiVersion: promenade/v1
    kind: Cluster
    metadata:
      name: example
      target: none
    spec:
      nodes:
        n0:
          ip: 192.168.77.10
          roles:
            - master
            - genesis
          additional_labels:
            - beta.kubernetes.io/arch=amd64

The ``Network`` document must contain:

- ````cluster_domain```` - The domain for the cluster, e.g. ``cluster.local``.
- ````cluster_dns```` - The IP of the cluster DNS,e .g. ``10.96.0.10``.
- ``kube_service_ip`` - The IP of the ``kubernetes`` service, e.g. ``10.96.0.1``.
- ``pod_ip_cidr`` - The CIDR from which pod IPs will be assigned, e.g. ``10.97.0.0/16``.
- ``service_ip_cidr`` - The CIDR from which service IPs will be assigned, e.g. ``10.96.0.0/16``.
- ``etcd_service_ip`` - The IP address of the ``etcd`` service, e.g. ``10.96.232.136``.
- ``dns_servers`` - A list of upstream DNS server IPs.

Optionally, proxy settings can be specified here as well.  These should all
generally be set together: ``http_proxy``, ``https_proxy``, ``no_proxy``.  ``no_proxy``
must include all master IP addresses, and the ``kubernetes`` service name.

Here's an example ``Network`` document:

.. code-block:: yaml

    apiVersion: promenade/v1
    kind: Network
    metadata:
      cluster: example
      name: example
      target: all
    spec:
      cluster_domain: cluster.local
      cluster_dns: 10.96.0.10
      kube_service_ip: 10.96.0.1
      pod_ip_cidr: 10.97.0.0/16
      service_ip_cidr: 10.96.0.0/16
      etcd_service_ip: 10.96.232.136
      dns_servers:
        - 8.8.8.8
        - 8.8.4.4
      http_proxy: http://proxy.example.com:8080
      https_proxy: http://proxy.example.com:8080
      no_proxy: 192.168.77.10,192.168.77.11,192.168.77.12,127.0.0.1,kubernetes,kubernetes.default.svc.cluster.local

The ``Versions`` document must define the Promenade image to be used and the
Docker package version.  Currently, only the versions specified for these two
items are respected.

Here's an example ``Versions`` document:

.. code-block:: yaml

    apiVersion: promenade/v1
    kind: Versions
    metadata:
      cluster: example
      name: example
      target: all
    spec:
      images:
        promenade: quay.io/attcomdev/promenade:latest
      packages:
        docker: docker.io=1.12.6-0ubuntu1~16.04.1

Given these documents (see the [example](example/vagrant-input-config.yaml)),
Promenade can derive the remaining configuration and generate certificates and
keys using the following command:

.. code-block:: bash

    mkdir -p configs
    docker run --rm -t \
        -v $(pwd):/target \
        quay.io/attcomdev/promenade:latest \
        promenade -v generate \
          -c /target/example/vagrant-input-config.yaml \
          -o /target/configs

This will generate the following files in the ``configs`` directory:

- ``up.sh`` - A script which will bring up a node to create or join a cluster.
- ``admin-bundle.yaml`` - A collection of generated certificates, private keys
  and core configuration.
- ``complete-bundle.yaml`` - A set of generated documents suitable for upload
  into Drydock for future delivery to nodes to be provisioned to join the
  cluster.

Additionally, a YAML file for each host described in the ``Cluster`` document
will be placed here.  These files each contain every document needed for that
particular node to create or join the cluster.