166 lines
6.0 KiB
ReStructuredText
166 lines
6.0 KiB
ReStructuredText
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.
|