Initial commit of specs repo
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
parent
ca404ab799
commit
b1024c5366
|
|
@ -0,0 +1,6 @@
|
|||
# Sphinx artifacts
|
||||
/doc/build/
|
||||
/doc/*/_static/
|
||||
/AUTHORS
|
||||
/ChangeLog
|
||||
|
||||
|
|
@ -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)
|
||||
|
|
@ -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'),
|
||||
]
|
||||
|
|
@ -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/*
|
||||
|
|
@ -0,0 +1 @@
|
|||
../../specs
|
||||
|
|
@ -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)
|
||||
|
|
@ -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 node labels
|
||||
=================================================
|
||||
|
||||
Proposal to enhance Airship to support updating Kubernetes node labels as a
|
||||
triggered workflow using Shipyard as an entrypoint, Deckhand as a document
|
||||
repository, Drydock as the decision maker about application of node 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 node 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
|
||||
Loading…
Reference in New Issue