airship/specs
Code Issues Proposed changes

Initial commit of specs repo

Browse Source 
The airship-specs repo is for specifications that impact the components
that are part of the airship project group.

Includes the update_labels_workflow spec.

Change-Id: Ic72f970f211de95ee0c08616a3a43869270b6061
This commit is contained in:
Bryan Strassner 2018-07-17 11:02:12 -05:00
parent ca404ab799
commit 65d949e7db
7 changed files with 506 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.gitignore vendored Normal file
View File

@ -0,0 +1,6 @@
# Sphinx artifacts
/doc/build/
/doc/*/_static/
/AUTHORS
/ChangeLog

20
Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = airship-specs
SOURCEDIR = doc/source
BUILDDIR = doc/build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

155
doc/source/conf.py Normal file
View File

@ -0,0 +1,155 @@
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# 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('.'))
# -- Project information -----------------------------------------------------
project = 'airship-specs'
copyright = '2018, Airship Authors'
author = 'Airship Authors'
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = '0.1.0'
# -- 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 = [
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# 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'
# 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 pattern also affects html_static_path and html_extra_path .
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# 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']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'airship-specsdoc'
# -- 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, 'airship-specs.tex', 'airship-specs Documentation',
'Airship 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, 'airship-specs', 'airship-specs 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, 'airship-specs', 'airship-specs Documentation',
author, 'airship-specs', 'One line description of project.',
'Miscellaneous'),
]

13
doc/source/index.rst Normal file
View File

@ -0,0 +1,13 @@
.. airship-specs documentation master file, created by
sphinx-quickstart on Tue Jul 10 09:26:57 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to airship-specs's documentation!
=========================================
.. toctree::
:maxdepth: 1
:glob:
specs/*

1
doc/source/specs Symbolic link
View File

@ -0,0 +1 @@
../../specs

96
specs/template.rst Normal file
View File

@ -0,0 +1,96 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
.. note::
Blueprints are written using ReSTructured text.
=====================================
Template: The title of your blueprint
=====================================
Introduction paragraph -- What is this blueprint about?
Links
=====
Include pertinent links to where the work is being tracked (e.g. Storyboard),
as well as any other foundational information that may lend clarity to this
blueprint
Problem description
===================
A detailed description of the problem being addressed or solved by this
blueprint
Impacted components
===================
List the Airship components that are impacted by this blueprint
Proposed change
===============
Provide a detailed description of the change being proposed. Include how the
problem will be addressed or solved.
If this is an incremental part of a larger solution or effort, provide the
specific scope of this blueprint, and how it fits into the overarching
solution.
Details of changes to specific Airship components should be specified in this
section, as well as interaction between those components.
Special attention should be given to interfaces between components. New
interfaces shuld attempt to follow established patterns within Airship, or
should be evaluated for suitability as new precedent.
If this blueprint changes testing needs or approaches, that information
should be disclosed here, and should be regarded as part of the deliverable
related to this design.
If this blueprint introduces new functionality that requires new kinds of
documentation, or a change to the documentation processes, that information
should be included in this section.
Security impact
---------------
Details of any security-related concerns that this proposed change introduces
or addresses.
Performance impact
------------------
Analysis of performance changes that are introduced or addressed with this
proposed design.
Alternatives
------------
If other approaches were considered, include a summary of those here, and a
short discussion of why the proposed approach is preferred.
Implementation
==============
If known, include any information detailing assigned individuals, proposed
milestones, intermediate deliverable products, and work items.
If there are Assignee(s) or Work Items, use a sub-heading for that
information.
Dependencies
============
If there are any dependencies on other work, blueprints, or other things that
impact the ability to deliver this solution, include that information here.
References
==========
Any external references (other than the direct links above)

215
specs/update_labels_workflow.rst Normal file
View File

@ -0,0 +1,215 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
============================================
Airship workflow to update Kubernetes labels
============================================
Proposal to enhance Airship to support updating Kubernetes labels as a
triggered workflow using Shipyard as an entrypoint, Deckhand as a document
repository, Drydock as the decision maker about application of labels, and
Promenade as the interactive layer to Kubernetes.
Links
=====
None
Problem description
===================
Over the lifecycle of a deployed site, there is a need to maintain the labels
applied to Kubernetes nodes. Prior to this change the only Airship-supplied
mechanism for this was during a node's deployment. Effectively, the way to
change or remove labels from a deployed node is manual process. Airship aims
to eliminate or minimize manual action on a site.
Without the ability to declaratively update the labels for a Kubernetes node,
the engineers responsible for a site lose finer-grained ability to adjust where
deployed software runs -- i.e. node affinity/anti-affinity. While the
software's Helm or Armada chart could be adjusted and the site updated, the
granularity of marking a single node with a label is still missed.
Impacted components
===================
The following Airship components would be impacted by this solution:
#. Drydock - endpoint(s) to evaluate and trigger adding or removing labels on
a node
#. Promenade - endpoint(s) to add/remove labels on a node.
#. Shipyard - new workflow: update_labels
Proposed change
===============
.. note::
External to Airship, the process requires updating the site definition
documents to properly reflect the desired labels for a node. The workflow
proposed below does not allow for addition or elimination of node labels
without going through an update the site definition documents.
To achieve the goal of fine-grained declarative Kubernetes label management,
a new Shipyard action will be introduced: ``update_labels``. The update_labels
action will accept a list of targeted nodes as an action parameter. E.g.::
POST /v1.0/actions
{
"name" : "action name",
"parameters" : {
"target_nodes": [ "node1", "node2"]
}
}
The most recent committed configuration documents will be used to drive the
labels that result on the target nodes.
- If there is no committed version of the configuration documents, the action
will be rejected.
- If there are no revisions of the configuration documents marked as
participating in a site action, the action will be rejected.
A new workflow will be invoked for ``update_labels``, being passed the
configuration documents revision and the target nodes as input, using existing
parameter mechanisms.
The workflow will perform a standard validation of the configuration documents
by the involved components (Deckhand, Drydock, Promenade).
Within the Shipyard codebase, a new Drydock operator will be defined to invoke
and monitor the invocation of Drydock to trigger label updates. Using the
task interface of Drydock, a node filter containing the target nodes will be
used to limit the scope of the request to only those nodes, along with the
design reference. E.g.::
POST /v1.0/tasks
{
"action": "update_labels",
"design_ref": "<deckhand_uri>",
"node_filter": {
"filter_set_type": "union",
"filter_set": [
{
"filter_type": "union",
"node_names": ["node1", "node2"],
"node_tags": [],
"node_labels": {},
"rack_names": [],
"rack_labels": {},
}
]
}
}
.. note::
Since a node filter is part of this interface, it would technically allow for
other ways to assign labels across nodes. However at this time, Shipyard will
only leverage the node_names field.
Drydock's task API will provide a new action ``relabel_node``. This action will
perform necessary analysis of the design to determine the full set of labels
that should be applied to each node. Some labels are generated dynamically
during node deployment; these will need to be generated and included in the
set of labels.
For each node, Drydock will invoke Promenade to apply the set of labels to the
Kubernetes node, using a ``PUT`` against the (new) ``node-labels/{node_name}``
endpoint. The payload of this request is a list of labels for that node. E.g.::
PUT /v1.0/node-labels/node1
{"labels": [
{"label-a":"true"},
{"label-n":"some-value"}
]}
.. todo::
Does Promenade need the design ref to be able to find things to act upon?
Promenade will perform a difference of the existing node labels against the
requested node labels. Promenade will then in order:
#) apply new labels and change existing labels with new values
#) remove labels that are not in the request body
Since multiple nodes can be targeted, and success or failure may occur on each,
Drydock will track these as subtasks and roll up success/failure per node to
the top level task.
The workflow step will use the top level Drydock task result, and disposition
the step as failure if any nodes are unsuccessful. This may result in a partial
update. No rollbacks will be performed.
.. note::
At the time of writing this blueprint, there are no other actions exposed by
Shipyard that are focused on a set of target nodes instead of the whole site.
This introduces a new category of ``targeted`` actions, as opposed to the
existing ``site`` actions. Targeted actions should not set the site action
labels (e.g. successful-site-action) on Deckhand revisions as part of the
workflow.
The Drydock, Promenade, and Shipyard API Clients and CLI components will need
to be updated to match the new functionality defined above.
Security impact
---------------
None - No new security impacts are introduced with this design. Existing
mechanisms will be applied to the changes introduced.
Performance impact
------------------
None - This workflow has no specific performance implications for the
components involved.
High level process
------------------
::
Shipyard Workflow Drydock Promenade
+---------------+ +-------------+
| Submit Action +------> | |
| update_labels | | |
| | |Drydock Task:| +------------------+
+---------------+ | relabel_node+-----> |Evaluate baremetal|
| | |definition; |
|Monitor Task +-----> |generate k8s node |
| | Poll |labels |
| | <-----+ |
| | |Promenade: | +-------------------+
| | | PUT node-labels +-------> |Diff existing node |
| | | (list of labels)| Wait | labels. |
| | | | <-------+ Add new labels |
| | +------------------+ | Remove orphaned |
| | | labels |
| | | |
| | +-------------------+
|End workflow |
| |
+-------------+
Implementation
==============
None - there are no specific milestones identified for this blueprint
Dependencies
============
None
References
==========
None