summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFelipe Monteiro <felipe.monteiro@att.com>2017-10-05 21:52:52 +0100
committerFelipe Monteiro <felipe.monteiro@att.com>2017-10-06 15:07:07 -0400
commita821aeff005797b77992244d912fad7ab4ed19a7 (patch)
treef91b38353989666bb9499e7e8ddb9c794e323766
parent09b3e93f0e42fbe63e84c1145b6b097aa2f87df6 (diff)
Berth documentation via build_sphinx.
This PS adds tooling and automation to automatically generate Berth's documentation into feature-rich HTML pages that can be hosted. To run the documentation job, simply execute: tox -e docs Future docs should be written using the style described at http://www.sphinx-doc.org/en/stable/markup/code.html and located in berth/docs/source This PS also adds basic building blocks required by most any Python project: * test-requirements.txt * requirements.txt * setup.cfg * setup.py * added more filters to .gitignore Change-Id: I792b0244ce9909d70283730a29545304311c6dbc
-rw-r--r--.gitignore105
-rw-r--r--README.md93
-rw-r--r--README.rst105
-rw-r--r--docs/source/_static/.placeholder0
-rw-r--r--docs/source/conf.py155
-rw-r--r--docs/source/index.rst26
-rw-r--r--docs/source/readme.rst1
-rw-r--r--requirements.txt3
-rw-r--r--setup.cfg30
-rw-r--r--setup.py27
-rw-r--r--test-requirements.txt6
-rw-r--r--tox.ini19
12 files changed, 477 insertions, 93 deletions
diff --git a/.gitignore b/.gitignore
index a763170..b369923 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,107 @@
1# Misc
1helm.log 2helm.log
2berth-0.1.0.tgz 3berth-0.1.0.tgz
4
5# Byte-compiled / optimized / DLL files
6__pycache__/
7*.py[cod]
8*$py.class
9
10# C extensions
11*.so
12
13# Distribution / packaging
14.Python
15env/
16build/
17develop-eggs/
18dist/
19downloads/
20eggs/
21.eggs/
22lib/
23lib64/
24parts/
25sdist/
26var/
27wheels/
28*.egg-info/
29.installed.cfg
30*.egg
31
32# PyInstaller
33# Usually these files are written by a python script from a template
34# before PyInstaller builds the exe, so as to inject date/other infos into it.
35*.manifest
36*.spec
37
38# Installer logs
39pip-log.txt
40pip-delete-this-directory.txt
41
42# Unit test / coverage reports
43htmlcov/
44.tox/
45.coverage
46.coverage.*
47.cache
48nosetests.xml
49coverage.xml
50*.cover
51.hypothesis/
52.testrepository/*
53cover/*
54
55# Translations
56*.mo
57*.pot
58
59# Django stuff:
60*.log
61local_settings.py
62
63# Flask stuff:
64instance/
65.webassets-cache
66
67# Scrapy stuff:
68.scrapy
69
70# Sphinx documentation
71docs/_build/
72
73# PyBuilder
74target/
75
76# Jupyter Notebook
77.ipynb_checkpoints
78
79# pyenv
80.python-version
81
82# celery beat schedule file
83celerybeat-schedule
84
85# SageMath parsed files
86*.sage.py
87
88# dotenv
89.env
90
91# virtualenv
92.venv
93venv/
94ENV/
95
96# Spyder project settings
97.spyderproject
98.spyproject
99
100# Rope project settings
101.ropeproject
102
103# mkdocs documentation
104/site
105
106# mypy
107.mypy_cache/
diff --git a/README.md b/README.md
deleted file mode 100644
index 4a96a8c..0000000
--- a/README.md
+++ /dev/null
@@ -1,93 +0,0 @@
1Berth is a deliberately minimalist VM runner for Kubernetes.
2
3I'm not 100% sold on the name; before merging we could change it...
4
5## TL;DR Installation Guide
6
7```
8# Make sure you have Helm 2.5.x and Kubernetes 1.6.x
9#
10# edit values.yaml; set class_name and ssh key
11#
12helm package berth
13helm install --name=berth ./berth-0.1.0.tgz # ...
14kubectl get pods -o wide
15```
16
17You should be able to SSH to your VM at the Kubernetes IP for the
18container which you can retrieve with `kubectl get all -o wide`. VNC
19access is available on port 5900.
20
21```
22ssh -i ./you-ssh-private-key root@ip.of.vm.pod
23```
24<!-- https://mostsecure.pw/ -->
25
26### Example
27
28[Quick installation / sample](https://asciinema.org/a/4VazbwsokL3zpnGPf27eyFIfe)
29
30### Why this?
31
32The requirements are very narrow right now and the existing
33alternatives don't align well at present. This will likely change in
34time at which point we can realign the internal implementation.
35
36#### Minimalist requirements
37* Run VMs from inside of Kubernetes
38* Work with Calico
39* Have VM life-cycle match that of pods
40* Have VMs benefit from Kubernetes resiliency
41* Allow for persistent storage
42* Allow for state injection/access from a ConfigMaps
43
44## Requirements:
45* Helm 2.5.x
46* Kubernetes 1.6.x
47
48This does not need to be installed as part of the OpenStack chart
49collection.
50
51## How it works:
52
53At a high level, it works like this:
54* Create a SNAT/DNAT enabled linux bridge.
55* Assign the bridge a private IP address from a small /30 subnet
56 (controlled with `VM_IP` and `VM_GW`)
57* Plug the VM network interface into the bridge.
58* Run a dnsmasq process to allocate the VM the right name-servers, and
59 DNS search strings extracted from the parent container. Assign the
60 private IP address to the VM and have it use the bridges IP as its
61 default gateway.
62* Setup SNAT/DNAT on the parent container to do 1:1 mapping of all
63 ports, all protocols to the VM, except for TCP:5900 to allow for VNC
64 access (can be controlled with NO_VNC environment variable).
65* At this point, VM essentially assumes Pod Assigned IP.
66* Feed any meta-data or user-data down into the VM by leveraging these
67 ConfigMap mounts with the same name and turning them into an ISO
68 presented to the guest.
69
70The startvm entry-point supports several environment variables:
71
72* `IMG_SOURCE` which is an http or https URL that contains a qcow2
73 image. It can also be a full path to a local file baked into the
74 container image, e.g. "/image.qcow"
75* `IMG_TARGET` the name to save the image above as in the shared
76 volume.
77
78It also supports two files, which should be mounted as ConfigMaps if
79using Kubernetes at `/userdata` and `/metadata` as YAML files
80containing, obviously meta-data and user-data as YAML that will be fed
81to the VM as a config-drive iso.
82
83The "pet" version of the image, which is created using qemu-img -b to
84base it on the source, is stored in a separate volume dedicated to the
85VM itself, and named after the container hostname.
86
87There are a few other parameters you can control as an operator:
88
89* `VM_IP` is the IP address the VM should be allocated by DHCP. The
90 container will 1:1 NAT except for port 5900 for VNC access (defaults
91 to 192.168.254.2)
92* `VM_GW` is the gateway IP address the VM should use for its default
93 route (defaults to 192.168.254.1)
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..8734ba9
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,105 @@
1=====
2Berth
3=====
4
5Berth is a deliberately minimalist VM runner for Kubernetes.
6
7I'm not 100% sold on the name; before merging we could change it...
8
9TL;DR Installation Guide
10========================
11
12.. code-block:: bash
13
14 # Make sure you have Helm 2.5.x and Kubernetes 1.6.x
15 #
16 # edit values.yaml; set class_name and ssh key
17 #
18 helm package berth
19 helm install --name=berth ./berth-0.1.0.tgz # ...
20 kubectl get pods -o wide
21
22You should be able to SSH to your VM at the Kubernetes IP for the
23container which you can retrieve with `kubectl get all -o wide`. VNC
24access is available on port 5900.
25
26.. code-block:: bash
27
28 ssh -i ./you-ssh-private-key root@ip.of.vm.pod
29
30Example
31-------
32
33`Quick installation / sample <https://asciinema.org/a/4VazbwsokL3zpnGPf27eyFIfe>`_
34
35Why this?
36---------
37
38The requirements are very narrow right now and the existing
39alternatives don't align well at present. This will likely change in
40time at which point we can realign the internal implementation.
41
42Minimalist requirements
43-----------------------
44
45* Run VMs from inside of Kubernetes
46* Work with Calico
47* Have VM life-cycle match that of pods
48* Have VMs benefit from Kubernetes resiliency
49* Allow for persistent storage
50* Allow for state injection/access from a ConfigMaps
51
52Requirements
53============
54
55* Helm 2.5.x
56* Kubernetes 1.6.x
57
58This does not need to be installed as part of the OpenStack chart
59collection.
60
61How it works
62============
63
64At a high level, it works like this:
65
66 * Create a SNAT/DNAT enabled linux bridge.
67 * Assign the bridge a private IP address from a small /30 subnet
68 (controlled with `VM_IP` and `VM_GW`)
69 * Plug the VM network interface into the bridge.
70 * Run a dnsmasq process to allocate the VM the right name-servers, and
71 DNS search strings extracted from the parent container. Assign the
72 private IP address to the VM and have it use the bridges IP as its
73 default gateway.
74 * Setup SNAT/DNAT on the parent container to do 1:1 mapping of all
75 ports, all protocols to the VM, except for TCP:5900 to allow for VNC
76 access (can be controlled with NO_VNC environment variable).
77 * At this point, VM essentially assumes Pod Assigned IP.
78 * Feed any meta-data or user-data down into the VM by leveraging these
79 ConfigMap mounts with the same name and turning them into an ISO
80 presented to the guest.
81
82The startvm entry-point supports several environment variables:
83
84 * `IMG_SOURCE` which is an http or https URL that contains a qcow2
85 image. It can also be a full path to a local file baked into the
86 container image, e.g. "/image.qcow"
87 * `IMG_TARGET` the name to save the image above as in the shared
88 volume.
89
90It also supports two files, which should be mounted as ConfigMaps if
91using Kubernetes at `/userdata` and `/metadata` as YAML files
92containing, obviously meta-data and user-data as YAML that will be fed
93to the VM as a config-drive iso.
94
95The "pet" version of the image, which is created using qemu-img -b to
96base it on the source, is stored in a separate volume dedicated to the
97VM itself, and named after the container hostname.
98
99There are a few other parameters you can control as an operator:
100
101 * `VM_IP` is the IP address the VM should be allocated by DHCP. The
102 container will 1:1 NAT except for port 5900 for VNC access (defaults
103 to 192.168.254.2)
104 * `VM_GW` is the gateway IP address the VM should use for its default
105 route (defaults to 192.168.254.1)
diff --git a/docs/source/_static/.placeholder b/docs/source/_static/.placeholder
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/source/_static/.placeholder
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..4bd3229
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,155 @@
1# -*- coding: utf-8 -*-
2#
3# berth documentation build configuration file, created by
4# sphinx-quickstart on Sat Sep 16 03:40:50 2017.
5#
6# This file is execfile()d with the current directory set to its
7# containing dir.
8#
9# Note that not all possible configuration values are present in this
10# autogenerated file.
11#
12# All configuration values have a default; values that are commented out
13# serve to show the default.
14
15# If extensions (or modules to document with autodoc) are in another directory,
16# add these directories to sys.path here. If the directory is relative to the
17# documentation root, use os.path.abspath to make it absolute, like shown here.
18#
19# import os
20# import sys
21# sys.path.insert(0, os.path.abspath('.'))
22
23
24# -- General configuration ------------------------------------------------
25
26# If your documentation needs a minimal Sphinx version, state it here.
27#
28# needs_sphinx = '1.0'
29
30# Add any Sphinx extension module names here, as strings. They can be
31# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32# ones.
33extensions = ['sphinx.ext.autodoc']
34
35# Add any paths that contain templates here, relative to this directory.
36# templates_path = []
37
38# The suffix(es) of source filenames.
39# You can specify multiple suffix as a list of string:
40#
41# source_suffix = ['.rst', '.md']
42source_suffix = '.rst'
43
44# The master toctree document.
45master_doc = 'index'
46
47# General information about the project.
48project = u'Berth'
49copyright = u'2017, Berth Authors'
50author = u'Berth Authors'
51
52# The version info for the project you're documenting, acts as replacement for
53# |version| and |release|, also used in various other places throughout the
54# built documents.
55#
56# The short X.Y version.
57version = u'0.1.0'
58# The full version, including alpha/beta/rc tags.
59release = u'0.1.0'
60
61# The language for content autogenerated by Sphinx. Refer to documentation
62# for a list of supported languages.
63#
64# This is also used if you do content translation via gettext catalogs.
65# Usually you set "language" from the command line for these cases.
66language = None
67
68# List of patterns, relative to source directory, that match files and
69# directories to ignore when looking for source files.
70# This patterns also effect to html_static_path and html_extra_path
71exclude_patterns = []
72
73# The name of the Pygments (syntax highlighting) style to use.
74pygments_style = 'sphinx'
75
76# If true, `todo` and `todoList` produce output, else they produce nothing.
77todo_include_todos = False
78
79
80# -- Options for HTML output ----------------------------------------------
81
82# The theme to use for HTML and HTML Help pages. See the documentation for
83# a list of builtin themes.
84#
85import sphinx_rtd_theme
86html_theme = "sphinx_rtd_theme"
87html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
88
89# Theme options are theme-specific and customize the look and feel of a theme
90# further. For a list of options available for each theme, see the
91# documentation.
92#
93# html_theme_options = {}
94
95# Add any paths that contain custom static files (such as style sheets) here,
96# relative to this directory. They are copied after the builtin static files,
97# so a file named "default.css" will overwrite the builtin "default.css".
98html_static_path = ['_static']
99
100
101# -- Options for HTMLHelp output ------------------------------------------
102
103# Output file base name for HTML help builder.
104htmlhelp_basename = 'berthdoc'
105
106
107# -- Options for LaTeX output ---------------------------------------------
108
109latex_elements = {
110 # The paper size ('letterpaper' or 'a4paper').
111 #
112 # 'papersize': 'letterpaper',
113
114 # The font size ('10pt', '11pt' or '12pt').
115 #
116 # 'pointsize': '10pt',
117
118 # Additional stuff for the LaTeX preamble.
119 #
120 # 'preamble': '',
121
122 # Latex figure (float) alignment
123 #
124 # 'figure_align': 'htbp',
125}
126
127# Grouping the document tree into LaTeX files. List of tuples
128# (source start file, target name, title,
129# author, documentclass [howto, manual, or own class]).
130latex_documents = [
131 (master_doc, 'berth.tex', u'Berth Documentation',
132 u'Berth Authors', 'manual'),
133]
134
135
136# -- Options for manual page output ---------------------------------------
137
138# One entry per manual page. List of tuples
139# (source start file, name, description, authors, manual section).
140man_pages = [
141 (master_doc, 'Berth', u'Berth Documentation',
142 [author], 1)
143]
144
145
146# -- Options for Texinfo output -------------------------------------------
147
148# Grouping the document tree into Texinfo files. List of tuples
149# (source start file, target name, title, author,
150# dir menu entry, description, category)
151texinfo_documents = [
152 (master_doc, 'Berth', u'Berth Documentation',
153 author, 'Berth', 'A deliberately minimalist VM runner for Kubernetes.',
154 'Miscellaneous'),
155]
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..0ba30cc
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,26 @@
1..
2 Copyright 2017 AT&T Intellectual Property.
3 All Rights Reserved.
4
5 Licensed under the Apache License, Version 2.0 (the "License"); you may
6 not use this file except in compliance with the License. You may obtain
7 a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14 License for the specific language governing permissions and limitations
15 under the License.
16
17=================================
18Welcome to Berth's documentation!
19=================================
20
21Berth is a deliberately minimalist VM runner for Kubernetes.
22
23.. toctree::
24 :maxdepth: 2
25
26 readme
diff --git a/docs/source/readme.rst b/docs/source/readme.rst
new file mode 100644
index 0000000..38ba804
--- /dev/null
+++ b/docs/source/readme.rst
@@ -0,0 +1 @@
.. include:: ../../README.rst \ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..9dbc011
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,3 @@
1# The order of packages is significant, because pip processes them in the order
2# of appearance. Changing the order has an impact on the overall integration
3# process, which may cause wedges in the gate later.
diff --git a/setup.cfg b/setup.cfg
new file mode 100644
index 0000000..5a85dca
--- /dev/null
+++ b/setup.cfg
@@ -0,0 +1,30 @@
1[metadata]
2name = Berth
3summary = A deliberately minimalist VM runner for Kubernetes.
4description-file = README.rst
5
6author = Berth Authors
7home-page = http://berth.readthedocs.io/en/latest/
8classifier =
9 Intended Audience :: Information Technology
10 Intended Audience :: System Administrators
11 License :: OSI Approved :: Apache Software License
12 Operating System :: POSIX :: Linux
13 Programming Language :: Python
14 Programming Language :: Python :: 2
15 Programming Language :: Python :: 2.7
16 Programming Language :: Python :: 3
17 Programming Language :: Python :: 3.5
18
19[files]
20packages =
21 berth
22
23[build_sphinx]
24source-dir = docs/source
25build-dir = docs/build
26all_files = 1
27warning-is-error = 1
28
29[upload_sphinx]
30upload-dir = doc/build/html
diff --git a/setup.py b/setup.py
new file mode 100644
index 0000000..0b220f4
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,27 @@
1# Copyright 2017 AT&T Intellectual Property. All other rights reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15import setuptools
16
17# In python < 2.7.4, a lazy loading of package `pbr` will break
18# setuptools if some other modules registered functions in `atexit`.
19# solution from: http://bugs.python.org/issue15881#msg170215
20try:
21 import multiprocessing # noqa
22except ImportError:
23 pass
24
25setuptools.setup(
26 setup_requires=['pbr>=2.0.0'],
27 pbr=True)
diff --git a/test-requirements.txt b/test-requirements.txt
new file mode 100644
index 0000000..e200bfc
--- /dev/null
+++ b/test-requirements.txt
@@ -0,0 +1,6 @@
1# The order of packages is significant, because pip processes them in the order
2# of appearance. Changing the order has an impact on the overall integration
3# process, which may cause wedges in the gate later.
4
5sphinx>=1.6.2
6sphinx_rtd_theme==0.2.4
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 0000000..05526ac
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,19 @@
1[tox]
2envlist = py35
3
4[testenv]
5usedevelop = True
6whitelist_externals = rm
7setenv = VIRTUAL_ENV={envdir}
8 LANGUAGE=en_US
9 LC_ALL=en_US.utf-8
10deps = -r{toxinidir}/requirements.txt
11 -r{toxinidir}/test-requirements.txt
12commands =
13 find . -type f -name "*.pyc" -delete
14 rm -Rf .testrepository/times.dbm
15
16[testenv:docs]
17commands =
18 rm -rf doc/build
19 python setup.py build_sphinx {posargs}