summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBryan Strassner <bryan.strassner@gmail.com>2018-07-17 14:08:06 -0500
committerBryan Strassner <bryan.strassner@gmail.com>2018-07-27 14:42:10 -0500
commit1636f898eb70c4257942cb8d3b0b4f54b589dca1 (patch)
tree6eb09c0d67fea409215d3ba99a5029d26e039a5b
parent6104cac943bff489702f5e05b44914cc4141d503 (diff)
Add update_labels spec
The update_labels spec outlines the workflow and associated changes by which kubernetes node labels can be updated using Airship. Change-Id: Idac6237aeba92d7a852031863c360a82b0fff9a5
Notes
Notes (review): Code-Review+2: Scott Hussey <sthussey@att.com> Code-Review+2: Mark Burnett <mark.m.burnett@gmail.com> Code-Review+2: Felipe Monteiro <felipe.monteiro@att.com> Code-Review+1: Pallav Gupta <pallavgupta84@gmail.com> Workflow+1: Bryan Strassner <bryan.strassner@gmail.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Mon, 30 Jul 2018 19:33:44 +0000 Reviewed-on: https://review.openstack.org/583343 Project: openstack/airship-specs Branch: refs/heads/master
-rw-r--r--specs/approved/k8s_update_node_labels_workflow.rst244
1 files changed, 244 insertions, 0 deletions
diff --git a/specs/approved/k8s_update_node_labels_workflow.rst b/specs/approved/k8s_update_node_labels_workflow.rst
new file mode 100644
index 0000000..b46b96d
--- /dev/null
+++ b/specs/approved/k8s_update_node_labels_workflow.rst
@@ -0,0 +1,244 @@
1..
2 This work is licensed under a Creative Commons Attribution 3.0 Unported
3 License.
4
5 http://creativecommons.org/licenses/by/3.0/legalcode
6
7.. index::
8 single: Kubernetes node labels
9 single: workflow
10 single: Promenade
11 single: Shipyard
12 single: Drydock
13
14=================================================
15Airship workflow to update Kubernetes node labels
16=================================================
17
18Proposal to enhance Airship to support updating `Kubernetes node labels`_ as a
19triggered workflow using Shipyard as an entrypoint, Deckhand as a document
20repository, Drydock as the decision maker about application of node labels, and
21Promenade as the interactive layer to Kubernetes_.
22
23Links
24=====
25
26None
27
28Problem description
29===================
30
31Over the lifecycle of a deployed site, there is a need to maintain the labels
32applied to Kubernetes nodes. Prior to this change the only Airship-supplied
33mechanism for this was during a node's deployment. Effectively, the way to
34change or remove labels from a deployed node is through a manual process.
35Airship aims to eliminate or minimize manual action on a deploy site.
36
37Without the ability to declaratively update the labels for a Kubernetes node,
38the engineers responsible for a site lose finer-grained ability to adjust where
39deployed software runs -- i.e. node affinity/anti-affinity. While the
40software's Helm or Armada chart could be adjusted and the site updated, the
41granularity of marking a single node with a label is still missed.
42
43Impacted components
44===================
45
46The following Airship components would be impacted by this solution:
47
48#. Drydock - endpoint(s) to evaluate and trigger adding or removing labels on
49 a node
50#. Promenade - endpoint(s) to add/remove labels on a node.
51#. Shipyard - new workflow: update_labels
52
53Proposed change
54===============
55
56.. note::
57
58 External to Airship, the process requires updating the site definition
59 documents describing `Baremetal Nodes`_ to properly reflect the desired
60 labels for a node. The workflow proposed below does not allow for addition
61 or elimination of node labels without going through an update of the site
62 definition documents.
63
64Shipyard
65--------
66
67To achieve the goal of fine-grained declarative Kubernetes label management,
68a new Shipyard action will be introduced: ``update_labels``. The update_labels
69action will accept a list of targeted nodes as an action parameter. E.g.::
70
71 POST /v1.0/actions
72
73 {
74 "name" : "action name",
75 "parameters" : {
76 "target_nodes": [ "node1", "node2"]
77 }
78 }
79
80The most recent committed configuration documents will be used to drive the
81labels that result on the target nodes.
82
83- If there is no committed version of the configuration documents, the action
84 will be rejected.
85- If there are no revisions of the configuration documents marked as
86 participating in a site action, the action will be rejected.
87
88A new workflow will be invoked for ``update_labels``, being passed the
89configuration documents revision and the target nodes as input, using existing
90parameter mechanisms.
91
92.. note::
93
94 At the time of writing this blueprint, there are no other actions exposed by
95 Shipyard that are focused on a set of target nodes instead of the whole site.
96 This introduces a new category of ``targeted`` actions, as opposed to the
97 existing ``site`` actions. Targeted actions should not set the site action
98 labels (e.g. successful-site-action) on Deckhand revisions as part of the
99 workflow.
100
101The workflow will perform a standard validation of the configuration documents
102by the involved components (Deckhand, Drydock, Promenade).
103
104Within the Shipyard codebase, a new Drydock operator will be defined to invoke
105and monitor the invocation of Drydock to trigger label updates. Using the
106task interface of Drydock, a node filter containing the target nodes will be
107used to limit the scope of the request to only those nodes, along with the
108design reference. E.g.::
109
110 POST /v1.0/tasks
111
112 {
113 "action": "relabel_nodes",
114 "design_ref": "<deckhand_uri>",
115 "node_filter": {
116 "filter_set_type": "union",
117 "filter_set": [
118 {
119 "filter_type": "union",
120 "node_names": ["node1", "node2"],
121 "node_tags": [],
122 "node_labels": {},
123 "rack_names": [],
124 "rack_labels": {},
125 }
126 ]
127 }
128 }
129
130.. note::
131
132 Since a node filter is part of this interface, it would technically allow for
133 other ways to assign labels across nodes. However at this time, Shipyard will
134 only leverage the node_names field.
135
136After invoking Drydock (see below), the workflow step will use the top level
137Drydock task result, and disposition the step as failure if any nodes are
138unsuccessful. This may result in a partial update. No rollbacks will be
139performed.
140
141
142Drydock
143-------
144
145Drydock's task API will provide a new action ``relabel_nodes``. This action will
146perform necessary analysis of the design to determine the full set of labels
147that should be applied to each node. Some labels are generated dynamically
148during node deployment; these will need to be generated and included in the
149set of node labels.
150
151Since multiple nodes can be targeted, and success or failure may occur on each,
152Drydock will track these as subtasks and roll up success/failure per node to
153the top level task.
154
155Promenade
156---------
157
158For each node, Drydock will invoke Promenade to apply the set of labels to the
159Kubernetes node, using a ``PUT`` against the (new) ``node-labels/{node_name}``
160endpoint. The payload of this request is a list of labels for that node. E.g.::
161
162 PUT /v1.0/node-labels/node1
163
164 {
165 "label-a":"true",
166 "label-n":"some-value"
167 }
168
169Promenade will perform a difference of the existing node labels against the
170requested node labels. Promenade will then in order:
171
172#) apply new labels and change existing labels with new values
173#) remove labels that are not in the request body
174
175API Clients and CLIs
176~~~~~~~~~~~~~~~~~~~~
177
178The Drydock, Promenade, and Shipyard API Clients and CLI components will need
179to be updated to match the new functionality defined above.
180
181Documentation impact
182--------------------
183
184Each of the identified components have associated API (and CLI) documentation
185that will be updated to match the new API endpoints and associated payload
186formats as noted above.
187
188Security impact
189---------------
190
191None - No new security impacts are introduced with this design. Existing
192mechanisms will be applied to the changes introduced.
193
194Performance impact
195------------------
196
197None - This workflow has no specific performance implications for the
198components involved.
199
200High level process
201------------------
202::
203
204 Shipyard Workflow Drydock Promenade
205 +---------------+ +-------------+
206 | Submit Action +------> | |
207 | update_labels | | |
208 | | |Drydock Task:| +------------------+
209 +---------------+ | relabel_node+-----> |Evaluate baremetal|
210 | | |definition; |
211 |Monitor Task +-----> |generate k8s node |
212 | | Poll |labels |
213 | | <-----+ |
214 | | |Promenade: | +-------------------+
215 | | | PUT node-labels +-------> |Diff existing node |
216 | | | (list of labels)| Wait | labels. |
217 | | | | <-------+ Add new labels |
218 | | +------------------+ | Remove orphaned |
219 | | | labels |
220 | | | |
221 | | +-------------------+
222 |End workflow |
223 | |
224 +-------------+
225
226Implementation
227==============
228
229There are no specific milestones identified for this blueprint.
230
231https://review.openstack.org/#/c/584925/ is work that has started for
232Promenade.
233
234Dependencies
235============
236
237None
238
239References
240==========
241
242.. _Kubernetes: https://kubernetes.io/
243.. _Kubernetes node labels: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
244.. _Baremetal Nodes: https://airshipit.readthedocs.io/projects/drydock/en/latest/topology.html#host-profiles-and-baremetal-nodes