Browse Source

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
Bryan Strassner 9 months ago
parent
commit
1636f898eb
1 changed files with 244 additions and 0 deletions
  1. 244
    0
      specs/approved/k8s_update_node_labels_workflow.rst

+ 244
- 0
specs/approved/k8s_update_node_labels_workflow.rst View File

@@ -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
+=================================================
15
+Airship workflow to update Kubernetes node labels
16
+=================================================
17
+
18
+Proposal to enhance Airship to support updating `Kubernetes node labels`_ as a
19
+triggered workflow using Shipyard as an entrypoint, Deckhand as a document
20
+repository, Drydock as the decision maker about application of node labels, and
21
+Promenade as the interactive layer to Kubernetes_.
22
+
23
+Links
24
+=====
25
+
26
+None
27
+
28
+Problem description
29
+===================
30
+
31
+Over the lifecycle of a deployed site, there is a need to maintain the labels
32
+applied to Kubernetes nodes. Prior to this change the only Airship-supplied
33
+mechanism for this was during a node's deployment. Effectively, the way to
34
+change or remove labels from a deployed node is through a manual process.
35
+Airship aims to eliminate or minimize manual action on a deploy site.
36
+
37
+Without the ability to declaratively update the labels for a Kubernetes node,
38
+the engineers responsible for a site lose finer-grained ability to adjust where
39
+deployed software runs -- i.e. node affinity/anti-affinity. While the
40
+software's Helm or Armada chart could be adjusted and the site updated, the
41
+granularity of marking a single node with a label is still missed.
42
+
43
+Impacted components
44
+===================
45
+
46
+The 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
+
53
+Proposed 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
+
64
+Shipyard
65
+--------
66
+
67
+To achieve the goal of fine-grained declarative Kubernetes label management,
68
+a new Shipyard action will be introduced: ``update_labels``. The update_labels
69
+action 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
+
80
+The most recent committed configuration documents will be used to drive the
81
+labels 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
+
88
+A new workflow will be invoked for ``update_labels``, being passed the
89
+configuration documents revision and the target nodes as input, using existing
90
+parameter 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
+
101
+The workflow will perform a standard validation of the configuration documents
102
+by the involved components (Deckhand, Drydock, Promenade).
103
+
104
+Within the Shipyard codebase, a new Drydock operator will be defined to invoke
105
+and monitor the invocation of Drydock to trigger label updates. Using the
106
+task interface of Drydock, a node filter containing the target nodes will be
107
+used to limit the scope of the request to only those nodes, along with the
108
+design 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
+
136
+After invoking Drydock (see below), the workflow step will use the top level
137
+Drydock task result, and disposition the step as failure if any nodes are
138
+unsuccessful. This may result in a partial update. No rollbacks will be
139
+performed.
140
+
141
+
142
+Drydock
143
+-------
144
+
145
+Drydock's task API will provide a new action ``relabel_nodes``. This action will
146
+perform necessary analysis of the design to determine the full set of labels
147
+that should be applied to each node. Some labels are generated dynamically
148
+during node deployment; these will need to be generated and included in the
149
+set of node labels.
150
+
151
+Since multiple nodes can be targeted, and success or failure may occur on each,
152
+Drydock will track these as subtasks and roll up success/failure per node to
153
+the top level task.
154
+
155
+Promenade
156
+---------
157
+
158
+For each node, Drydock will invoke Promenade to apply the set of labels to the
159
+Kubernetes node, using a ``PUT`` against the (new) ``node-labels/{node_name}``
160
+endpoint. 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
+
169
+Promenade will perform a difference of the existing node labels against the
170
+requested 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
+
175
+API Clients and CLIs
176
+~~~~~~~~~~~~~~~~~~~~
177
+
178
+The Drydock, Promenade, and Shipyard API Clients and CLI components will need
179
+to be updated to match the new functionality defined above.
180
+
181
+Documentation impact
182
+--------------------
183
+
184
+Each of the identified components have associated API (and CLI) documentation
185
+that will be updated to match the new API endpoints and associated payload
186
+formats as noted above.
187
+
188
+Security impact
189
+---------------
190
+
191
+None - No new security impacts are introduced with this design. Existing
192
+mechanisms will be applied to the changes introduced.
193
+
194
+Performance impact
195
+------------------
196
+
197
+None - This workflow has no specific performance implications for the
198
+components involved.
199
+
200
+High 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
+
226
+Implementation
227
+==============
228
+
229
+There are no specific milestones identified for this blueprint.
230
+
231
+https://review.openstack.org/#/c/584925/ is work that has started for
232
+Promenade.
233
+
234
+Dependencies
235
+============
236
+
237
+None
238
+
239
+References
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

Loading…
Cancel
Save