Promenade documentation via build_sphinx.
This PS adds tooling and automation to automatically generate Promenade's documentation into feature-rich HTML pages that can be hosted. To run the documentation job, simply execute: tox -e docs Change-Id: I5a925c82544c14c34c1796da5804cf12b45ae575
This commit is contained in:
parent
4712f60eb4
commit
b3de5e990a
|
@ -12,3 +12,9 @@ __pycache__
|
||||||
/join_image_cache/
|
/join_image_cache/
|
||||||
/promenade.egg-info
|
/promenade.egg-info
|
||||||
/tmp
|
/tmp
|
||||||
|
.tox/
|
||||||
|
ChangeLog
|
||||||
|
|
||||||
|
# Sphinx documentation
|
||||||
|
docs/build/
|
||||||
|
docs/*/_static/
|
||||||
|
|
|
@ -1,163 +0,0 @@
|
||||||
# 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:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```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.
|
|
|
@ -1,81 +0,0 @@
|
||||||
# Getting Started
|
|
||||||
|
|
||||||
## Development
|
|
||||||
|
|
||||||
### Deployment using Vagrant
|
|
||||||
|
|
||||||
Deployment using Vagrant uses KVM instead of Virtualbox due to better
|
|
||||||
performance of disk and networking, which both have significant impact on the
|
|
||||||
stability of the etcd clusters.
|
|
||||||
|
|
||||||
Make sure you have [Vagrant](https://vagrantup.com) installed, then
|
|
||||||
run `./tools/full-vagrant-setup.sh`, which will do the following:
|
|
||||||
|
|
||||||
* Install Vagrant libvirt plugin and its dependencies
|
|
||||||
* Install NFS dependencies for Vagrant volume sharing
|
|
||||||
* Install [packer](https://packer.io) and build a KVM image for Ubuntu 16.04
|
|
||||||
|
|
||||||
Generate the per-host configuration, certificates and keys to be used:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir 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
|
|
||||||
```
|
|
||||||
|
|
||||||
Start the VMs:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
vagrant up
|
|
||||||
```
|
|
||||||
|
|
||||||
Start the genesis node:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
vagrant ssh n0 -c 'sudo bash /vagrant/configs/up.sh /vagrant/configs/n0.yaml'
|
|
||||||
```
|
|
||||||
|
|
||||||
Join the master nodes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
vagrant ssh n1 -c 'sudo bash /vagrant/configs/up.sh /vagrant/configs/n1.yaml'
|
|
||||||
vagrant ssh n2 -c 'sudo bash /vagrant/configs/up.sh /vagrant/configs/n2.yaml'
|
|
||||||
```
|
|
||||||
|
|
||||||
Join the worker node:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
vagrant ssh n3 -c 'sudo bash /vagrant/configs/up.sh /vagrant/configs/n3.yaml'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Building the image
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker build -t promenade:local .
|
|
||||||
```
|
|
||||||
|
|
||||||
For development, you may wish to save it and have the `up.sh` script load it:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker save -o promenade.tar promenade:local
|
|
||||||
```
|
|
||||||
|
|
||||||
Then on a node:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
PROMENADE_LOAD_IMAGE=/vagrant/promenade.tar bash /vagrant/up.sh /vagrant/path/to/node-config.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
These commands are combined in a convenience script at `tools/dev-build.sh`.
|
|
||||||
|
|
||||||
To build the image from behind a proxy, you can:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export http_proxy=...
|
|
||||||
export no_proxy=...
|
|
||||||
docker build --build-arg http_proxy=$http_proxy --build-arg https_proxy=$http_proxy --build-arg no_proxy=$no_proxy -t promenade:local .
|
|
||||||
```
|
|
||||||
|
|
||||||
## Using Promenade Behind a Proxy
|
|
||||||
|
|
||||||
To use Promenade from behind a proxy, use the proxy settings described in the
|
|
||||||
[configuration docs](configuration.md).
|
|
|
@ -0,0 +1,160 @@
|
||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
#
|
||||||
|
# promenade documentation build configuration file, created by
|
||||||
|
# sphinx-quickstart on Sat Sep 16 03:40:50 2017.
|
||||||
|
#
|
||||||
|
# This file is execfile()d with the current directory set to its
|
||||||
|
# containing dir.
|
||||||
|
#
|
||||||
|
# Note that not all possible configuration values are present in this
|
||||||
|
# autogenerated file.
|
||||||
|
#
|
||||||
|
# All configuration values have a default; values that are commented out
|
||||||
|
# serve to show the default.
|
||||||
|
|
||||||
|
# If extensions (or modules to document with autodoc) are in another directory,
|
||||||
|
# add these directories to sys.path here. If the directory is relative to the
|
||||||
|
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||||
|
#
|
||||||
|
# import os
|
||||||
|
# import sys
|
||||||
|
# sys.path.insert(0, os.path.abspath('.'))
|
||||||
|
|
||||||
|
|
||||||
|
# -- General configuration ------------------------------------------------
|
||||||
|
|
||||||
|
# If your documentation needs a minimal Sphinx version, state it here.
|
||||||
|
#
|
||||||
|
# needs_sphinx = '1.0'
|
||||||
|
|
||||||
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
|
# ones.
|
||||||
|
extensions = [
|
||||||
|
'sphinx.ext.autodoc',
|
||||||
|
'sphinx.ext.todo',
|
||||||
|
'sphinx.ext.viewcode'
|
||||||
|
]
|
||||||
|
|
||||||
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
|
# templates_path = []
|
||||||
|
|
||||||
|
# The suffix(es) of source filenames.
|
||||||
|
# You can specify multiple suffix as a list of string:
|
||||||
|
#
|
||||||
|
# source_suffix = ['.rst', '.md']
|
||||||
|
source_suffix = '.rst'
|
||||||
|
|
||||||
|
# The master toctree document.
|
||||||
|
master_doc = 'index'
|
||||||
|
|
||||||
|
# General information about the project.
|
||||||
|
project = u'Promenade'
|
||||||
|
copyright = u'2017, Promenade Authors'
|
||||||
|
author = u'Promenade Authors'
|
||||||
|
|
||||||
|
# The version info for the project you're documenting, acts as replacement for
|
||||||
|
# |version| and |release|, also used in various other places throughout the
|
||||||
|
# built documents.
|
||||||
|
#
|
||||||
|
# The short X.Y version.
|
||||||
|
version = u'0.1.0'
|
||||||
|
# The full version, including alpha/beta/rc tags.
|
||||||
|
release = u'0.1.0'
|
||||||
|
|
||||||
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
|
# for a list of supported languages.
|
||||||
|
#
|
||||||
|
# This is also used if you do content translation via gettext catalogs.
|
||||||
|
# Usually you set "language" from the command line for these cases.
|
||||||
|
language = None
|
||||||
|
|
||||||
|
# List of patterns, relative to source directory, that match files and
|
||||||
|
# directories to ignore when looking for source files.
|
||||||
|
# This patterns also effect to html_static_path and html_extra_path
|
||||||
|
exclude_patterns = []
|
||||||
|
|
||||||
|
# The name of the Pygments (syntax highlighting) style to use.
|
||||||
|
pygments_style = 'sphinx'
|
||||||
|
|
||||||
|
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||||
|
todo_include_todos = False
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for HTML output ----------------------------------------------
|
||||||
|
|
||||||
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
|
# a list of builtin themes.
|
||||||
|
#
|
||||||
|
import sphinx_rtd_theme
|
||||||
|
html_theme = "sphinx_rtd_theme"
|
||||||
|
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||||
|
|
||||||
|
# Theme options are theme-specific and customize the look and feel of a theme
|
||||||
|
# further. For a list of options available for each theme, see the
|
||||||
|
# documentation.
|
||||||
|
#
|
||||||
|
# html_theme_options = {}
|
||||||
|
|
||||||
|
# Add any paths that contain custom static files (such as style sheets) here,
|
||||||
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
|
html_static_path = ['_static']
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for HTMLHelp output ------------------------------------------
|
||||||
|
|
||||||
|
# Output file base name for HTML help builder.
|
||||||
|
htmlhelp_basename = 'promenadedoc'
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for LaTeX output ---------------------------------------------
|
||||||
|
|
||||||
|
latex_elements = {
|
||||||
|
# The paper size ('letterpaper' or 'a4paper').
|
||||||
|
#
|
||||||
|
# 'papersize': 'letterpaper',
|
||||||
|
|
||||||
|
# The font size ('10pt', '11pt' or '12pt').
|
||||||
|
#
|
||||||
|
# 'pointsize': '10pt',
|
||||||
|
|
||||||
|
# Additional stuff for the LaTeX preamble.
|
||||||
|
#
|
||||||
|
# 'preamble': '',
|
||||||
|
|
||||||
|
# Latex figure (float) alignment
|
||||||
|
#
|
||||||
|
# 'figure_align': 'htbp',
|
||||||
|
}
|
||||||
|
|
||||||
|
# Grouping the document tree into LaTeX files. List of tuples
|
||||||
|
# (source start file, target name, title,
|
||||||
|
# author, documentclass [howto, manual, or own class]).
|
||||||
|
latex_documents = [
|
||||||
|
(master_doc, 'promenade.tex', u'Promenade Documentation',
|
||||||
|
u'Promenade Authors', 'manual'),
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for manual page output ---------------------------------------
|
||||||
|
|
||||||
|
# One entry per manual page. List of tuples
|
||||||
|
# (source start file, name, description, authors, manual section).
|
||||||
|
man_pages = [
|
||||||
|
(master_doc, 'Promenade', u'Promenade Documentation',
|
||||||
|
[author], 1)
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for Texinfo output -------------------------------------------
|
||||||
|
|
||||||
|
# Grouping the document tree into Texinfo files. List of tuples
|
||||||
|
# (source start file, target name, title, author,
|
||||||
|
# dir menu entry, description, category)
|
||||||
|
texinfo_documents = [
|
||||||
|
(master_doc, 'Promenade', u'Promenade Documentation',
|
||||||
|
author, 'Promenade',
|
||||||
|
'Tool for bootstrapping a resilient Kubernetes cluster and managing its life-cycle.',
|
||||||
|
'Miscellaneous'),
|
||||||
|
]
|
|
@ -0,0 +1,165 @@
|
||||||
|
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.
|
|
@ -0,0 +1,91 @@
|
||||||
|
Getting Started
|
||||||
|
===============
|
||||||
|
|
||||||
|
Development
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Deployment using Vagrant
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Deployment using Vagrant uses KVM instead of Virtualbox due to better
|
||||||
|
performance of disk and networking, which both have significant impact on the
|
||||||
|
stability of the etcd clusters.
|
||||||
|
|
||||||
|
Make sure you have [Vagrant](https://vagrantup.com) installed, then
|
||||||
|
run `./tools/full-vagrant-setup.sh`, which will do the following:
|
||||||
|
|
||||||
|
* Install Vagrant libvirt plugin and its dependencies
|
||||||
|
* Install NFS dependencies for Vagrant volume sharing
|
||||||
|
* Install [packer](https://packer.io) and build a KVM image for Ubuntu 16.04
|
||||||
|
|
||||||
|
Generate the per-host configuration, certificates and keys to be used:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
mkdir 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
|
||||||
|
|
||||||
|
|
||||||
|
Start the VMs:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
vagrant up
|
||||||
|
|
||||||
|
Start the genesis node:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
vagrant ssh n0 -c 'sudo bash /vagrant/configs/up.sh /vagrant/configs/n0.yaml'
|
||||||
|
|
||||||
|
Join the master nodes:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
vagrant ssh n1 -c 'sudo bash /vagrant/configs/up.sh /vagrant/configs/n1.yaml'
|
||||||
|
vagrant ssh n2 -c 'sudo bash /vagrant/configs/up.sh /vagrant/configs/n2.yaml'
|
||||||
|
|
||||||
|
Join the worker node:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
vagrant ssh n3 -c 'sudo bash /vagrant/configs/up.sh /vagrant/configs/n3.yaml'
|
||||||
|
|
||||||
|
Building the image
|
||||||
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
docker build -t promenade:local .
|
||||||
|
|
||||||
|
|
||||||
|
For development, you may wish to save it and have the `up.sh` script load it:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
docker save -o promenade.tar promenade:local
|
||||||
|
|
||||||
|
|
||||||
|
Then on a node:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
PROMENADE_LOAD_IMAGE=/vagrant/promenade.tar bash /vagrant/up.sh /vagrant/path/to/node-config.yaml
|
||||||
|
|
||||||
|
|
||||||
|
These commands are combined in a convenience script at `tools/dev-build.sh`.
|
||||||
|
|
||||||
|
To build the image from behind a proxy, you can:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
export http_proxy=...
|
||||||
|
export no_proxy=...
|
||||||
|
docker build --build-arg http_proxy=$http_proxy --build-arg https_proxy=$http_proxy --build-arg no_proxy=$no_proxy -t promenade:local .
|
||||||
|
|
||||||
|
|
||||||
|
Using Promenade Behind a Proxy
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
To use Promenade from behind a proxy, use the proxy settings described in the
|
||||||
|
[configuration docs](configuration.md).
|
|
@ -0,0 +1,34 @@
|
||||||
|
..
|
||||||
|
Copyright 2017 AT&T Intellectual Property.
|
||||||
|
All Rights Reserved.
|
||||||
|
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||||
|
not use this file except in compliance with the License. You may obtain
|
||||||
|
a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||||
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||||
|
License for the specific language governing permissions and limitations
|
||||||
|
under the License.
|
||||||
|
|
||||||
|
=====================================
|
||||||
|
Welcome to Promenade's documentation!
|
||||||
|
=====================================
|
||||||
|
|
||||||
|
Promenade is a tool for bootstrapping a resilient Kubernetes cluster and
|
||||||
|
managing its life-cycle.
|
||||||
|
|
||||||
|
User's Guide
|
||||||
|
============
|
||||||
|
|
||||||
|
Promenade Configuration Guide
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
getting-started
|
||||||
|
configuration
|
|
@ -27,3 +27,12 @@ package-data =
|
||||||
[entry_points]
|
[entry_points]
|
||||||
console_scripts =
|
console_scripts =
|
||||||
promenade = promenade.cli:promenade
|
promenade = promenade.cli:promenade
|
||||||
|
|
||||||
|
[build_sphinx]
|
||||||
|
source-dir = docs/source
|
||||||
|
build-dir = docs/build
|
||||||
|
all_files = 1
|
||||||
|
warning-is-error = 1
|
||||||
|
|
||||||
|
[upload_sphinx]
|
||||||
|
upload-dir = docs/build/html
|
||||||
|
|
|
@ -0,0 +1,3 @@
|
||||||
|
# Documentation
|
||||||
|
sphinx>=1.6.2
|
||||||
|
sphinx_rtd_theme==0.2.4
|
|
@ -0,0 +1,17 @@
|
||||||
|
[tox]
|
||||||
|
envlist = py35
|
||||||
|
|
||||||
|
[testenv]
|
||||||
|
deps = -r{toxinidir}/requirements.txt
|
||||||
|
-r{toxinidir}/test-requirements.txt
|
||||||
|
setenv=
|
||||||
|
PYTHONWARNING=all
|
||||||
|
commands=
|
||||||
|
pytest \
|
||||||
|
{posargs}
|
||||||
|
|
||||||
|
[testenv:docs]
|
||||||
|
whitelist_externals=rm
|
||||||
|
commands =
|
||||||
|
rm -rf docs/build
|
||||||
|
python setup.py build_sphinx {posargs}
|
Loading…
Reference in New Issue