You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/book/src/developer/architecture/controllers/control-plane.md
-255Lines changed: 0 additions & 255 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,261 +13,6 @@ A reference implementation is managed within the core Cluster API project as the
13
13
Kubeadm control plane controller (`KubeadmControlPlane`). In this document,
14
14
we refer to an example `ImplementationControlPlane` where not otherwise specified.
15
15
16
-
## Contracts
17
-
18
-
### Control Plane Provider
19
-
20
-
The general expectation of a control plane controller is to instantiate a
21
-
Kubernetes control plane consisting of the following services:
22
-
23
-
#### Required Control Plane Services
24
-
25
-
* etcd
26
-
* Kubernetes API Server
27
-
* Kubernetes Controller Manager
28
-
* Kubernetes Scheduler
29
-
30
-
#### Optional Control Plane Services
31
-
32
-
* Cloud controller manager
33
-
* Cluster DNS (e.g. CoreDNS)
34
-
* Service proxy (e.g. kube-proxy)
35
-
36
-
#### Prohibited Services
37
-
38
-
* CNI - should be left to user to apply once control plane is instantiated.
39
-
40
-
### Relationship to other Cluster API types
41
-
42
-
The Cluster controller will set an OwnerReference on the Control Plane. The Control Plane controller should normally take no action during reconciliation until it sees the ownerReference.
43
-
44
-
A Control Plane controller implementation must either supply a controlPlaneEndpoint (via its own `spec.controlPlaneEndpoint` field),
45
-
or rely on `spec.controlPlaneEndpoint` in its parent [Cluster](./cluster.md) object.
46
-
47
-
If an endpoint is not provided, the implementer should exit reconciliation until it sees `cluster.spec.controlPlaneEndpoint` populated.
48
-
49
-
A Control Plane controller can optionally provide a `controlPlaneEndpoint`
50
-
51
-
The Cluster controller bubbles up `status.ready` into `status.controlPlaneReady` and `status.initialized` into a `controlPlaneInitialized` condition from the Control Plane CR.
52
-
53
-
### CRD contracts
54
-
55
-
The CRD name must have the format produced by `sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)`.
56
-
The same applies for the name of the corresponding ControlPlane template CRD.
57
-
58
-
#### Required `spec` fields for implementations using replicas
59
-
60
-
*`replicas` - is an integer representing the number of desired
61
-
replicas. In the KubeadmControlPlane, this represents the desired
62
-
number of control plane machines.
63
-
64
-
*`scale` subresource with the following signature:
65
-
66
-
```yaml
67
-
scale:
68
-
labelSelectorPath: .status.selector
69
-
specReplicasPath: .spec.replicas
70
-
statusReplicasPath: .status.replicas
71
-
status: {}
72
-
```
73
-
74
-
More information about the [scale subresource can be found in the Kubernetes
75
-
documentation][scale].
76
-
77
-
#### Required `spec` fields for implementations using version
78
-
79
-
* `version` - is a string representing the Kubernetes version to be used
80
-
by the control plane machines. The value must be a valid semantic version;
81
-
also if the value provided by the user does not start with the v prefix, it
82
-
must be added.
83
-
84
-
#### Required `spec` fields for implementations using Machines
85
-
86
-
* `machineTemplate` - is a struct containing details of the control plane
87
-
machine template.
88
-
89
-
* `machineTemplate.metadata` - is a struct containing info about metadata for control plane
90
-
machines.
91
-
92
-
* `machineTemplate.metadata.labels` - is a map of string keys and values that can be used
93
-
to organize and categorize control plane machines.
94
-
95
-
* `machineTemplate.metadata.annotations` - is a map of string keys and values containing
96
-
arbitrary metadata to be applied to control plane machines.
97
-
98
-
* `machineTemplate.infrastructureRef` - is a corev1.ObjectReference to a custom resource
99
-
offered by an infrastructure provider. The namespace in the ObjectReference must
100
-
be in the same namespace of the control plane object.
101
-
102
-
* `machineTemplate.nodeDrainTimeout` - is a *metav1.Duration defining the total amount of time
103
-
that the controller will spend on draining a control plane node.
104
-
The default value is 0, meaning that the node can be drained without any time limitations.
105
-
106
-
* `machineTemplate.nodeVolumeDetachTimeout` - is a *metav1.Duration defining how long the controller
107
-
will spend on waiting for all volumes to be detached.
108
-
The default value is 0, meaning that the volume can be detached without any time limitations.
109
-
110
-
* `machineTemplate.nodeDeletionTimeout` - is a *metav1.Duration defining how long the controller
111
-
will attempt to delete the Node that is hosted by a Machine after the Machine is marked for
112
-
deletion. A duration of 0 will retry deletion indefinitely. It defaults to 10 seconds on the
113
-
Machine.
114
-
115
-
#### Optional `spec` fields for implementations providing endpoints
116
-
117
-
The `ImplementationControlPlane` object may provide a `spec.controlPlaneEndpoint` field to inform the Cluster
118
-
controller where the endpoint is located.
119
-
120
-
Implementers might opt to choose the `APIEndpoint` struct exposed by Cluster API types, or the following:
121
-
122
-
<table>
123
-
<tr>
124
-
<th> Field </th>
125
-
<th> Type </th>
126
-
<th> Description </th>
127
-
</tr>
128
-
<tr>
129
-
<td><code>host</code></td>
130
-
<td>String</td>
131
-
<td>
132
-
The hostname on which the API server is serving.
133
-
</td>
134
-
</tr>
135
-
<tr>
136
-
<td><code>port</code></td>
137
-
<td>Integer</td>
138
-
<td>
139
-
The port on which the API server is serving.
140
-
</td>
141
-
</tr>
142
-
</table>
143
-
144
-
#### Required `status` fields
145
-
146
-
The `ImplementationControlPlane` object **must** have a `status` object.
147
-
148
-
The `status` object **must** have the following fields defined:
149
-
150
-
<table>
151
-
<tr>
152
-
<th> Field </th>
153
-
<th> Type </th>
154
-
<th> Description </th>
155
-
<th> Implementation in Kubeadm Control Plane Controller </th>
156
-
</tr>
157
-
<tr>
158
-
<td><code>initialized</code></td>
159
-
<td>Boolean</td>
160
-
<td>
161
-
a boolean field that is true when the target cluster has
162
-
completed initialization such that at least once, the
163
-
target's control plane has been contactable.
164
-
</td>
165
-
<td>
166
-
Transitions to initialized when the controller detects that kubeadm has uploaded
167
-
a kubeadm-config configmap, which occurs at the end of kubeadm provisioning.
168
-
</td>
169
-
</tr>
170
-
<tr>
171
-
<td><code>ready</code></td>
172
-
<td>Boolean</td>
173
-
<td>
174
-
Ready denotes that the target API Server is ready to receive requests.
175
-
</td>
176
-
<td></td>
177
-
</tr>
178
-
</table>
179
-
180
-
#### Required `status` fields for implementations using replicas
181
-
182
-
Where the `ImplementationControlPlane` has a concept of replicas, e.g. most
183
-
high availability control planes, then the `status` object **must** have the
184
-
following fields defined:
185
-
186
-
<table>
187
-
<tr>
188
-
<th> Field </th>
189
-
<th> Type </th>
190
-
<th> Description </th>
191
-
<th> Implementation in Kubeadm Control Plane Controller </th>
192
-
</tr>
193
-
<tr>
194
-
<td><code>readyReplicas</code></td>
195
-
<td>Integer</td>
196
-
<td>Total number of fully running and ready control plane instances.</td>
197
-
<td>Is equal to the number of fully running and ready control plane machines</td>
198
-
</tr>
199
-
<tr>
200
-
<td><code>replicas</code></td>
201
-
<td>Integer</td>
202
-
<td>Total number of non-terminated control plane instances,
203
-
i.e. the state machine for this instance
204
-
of the control plane is able to transition to ready.</td>
205
-
<td>Is equal to the number of non-terminated control plane machines</td>
206
-
</tr>
207
-
<tr>
208
-
<td><code>selector</code></td>
209
-
<td>String</td>
210
-
<td>`selector` is the label selector in string format to avoid
211
-
introspection by clients, and is used to provide the CRD-based integration
212
-
for the scale subresource and additional integrations for things like
213
-
kubectl describe. The string will be in the same format as the query-param
214
-
syntax. More info about label selectors: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
215
-
</td>
216
-
<td></td>
217
-
</tr>
218
-
<tr>
219
-
<td><code>unavailableReplicas</code></td>
220
-
<td>Integer</td>
221
-
<td>
222
-
Total number of unavailable control plane instances targeted by this control plane, equal
223
-
to the desired number of control plane instances - ready instances.
224
-
</td>
225
-
<td>
226
-
Total number of unavailable machines targeted by this control
227
-
plane. This is the total number of machines that are still required
228
-
for the deployment to have 100% available capacity. They may either
229
-
be machines that are running but not yet ready or machines that still
230
-
have not been created.
231
-
</td>
232
-
</tr>
233
-
<tr>
234
-
<td>
235
-
<code>updatedReplicas</code>
236
-
</td>
237
-
<td>integer</td>
238
-
<td>
239
-
Total number of non-terminated machines targeted by this
240
-
control plane that have the desired template spec.
241
-
</td>
242
-
<td>
243
-
Total number of non-terminated machines targeted by this
244
-
control plane that have the desired template spec.
245
-
</td>
246
-
</tr>
247
-
</table>
248
-
249
-
#### Required `status` fields for implementations using version
250
-
251
-
* `version` - is a string representing the minimum Kubernetes version for the
252
-
control plane machines in the cluster.
253
-
NOTE: The minimum Kubernetes version, and more specifically the API server
254
-
version, will be used to determine when a control plane is fully upgraded
255
-
(`spec.version == status.version`) and for enforcing [Kubernetes version
256
-
skew policies](https://kubernetes.io/releases/version-skew-policy/) in managed topologies.
257
-
258
-
#### Optional `status` fields
259
-
260
-
The `status` object **may** define several fields:
261
-
262
-
* `failureReason` - is a string that explains why an error has occurred, if possible.
263
-
* `failureMessage` - is a string that holds the message contained by the error.
264
-
* `externalManagedControlPlane` - is a bool that should be set to true if the Node objects do not
265
-
exist in the cluster. For example, managed control plane providers for AKS, EKS, GKE, etc, should
266
-
set this to `true`. Leaving the field undefined is equivalent to setting the value to `false`.
267
-
268
-
Note: once any of `failureReason` or `failureMessage` surface on the cluster who is referencing the control plane object,
269
-
they cannot be restored anymore (it is considered a terminal error; the only way to recover is to delete and recreate the cluster).
0 commit comments