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
= Building a Go-based Operator using the Operator SDK
7
7
8
-
The Operator SDK makes it easier to build Kubernetes native applications, a
9
-
process that can require deep, application-specific operational knowledge. The
10
-
SDK not only lowers that barrier, but it also helps reduce the amount of
11
-
boilerplate code needed for many common management capabilities, such as
12
-
metering or monitoring.
8
+
The Operator SDK makes it easier to build Kubernetes native applications, a process that can require deep, application-specific operational knowledge. The SDK not only lowers that barrier, but it also helps reduce the amount of boilerplate code needed for many common management capabilities, such as metering or monitoring.
13
9
14
-
This procedure walks through an example of building a simple Memcached Operator
15
-
using tools and libraries provided by the SDK.
10
+
This procedure walks through an example of building a simple Memcached Operator using tools and libraries provided by the SDK.
16
11
17
12
.Prerequisites
18
13
@@ -48,10 +43,9 @@ $ operator-sdk new memcached-operator
48
43
$ cd memcached-operator
49
44
----
50
45
51
-
. *Add a new Custom Resource Definition (CRD).*
46
+
. *Add a new custom resource definition (CRD).*
52
47
53
-
.. Use the CLI to add a new CRD API called `Memcached`, with `APIVersion` set to
54
-
`cache.example.com/v1apha1` and `Kind` set to `Memcached`:
48
+
.. Use the CLI to add a new CRD API called `Memcached`, with `APIVersion` set to `cache.example.com/v1apha1` and `Kind` set to `Memcached`:
55
49
+
56
50
[source,terminal]
57
51
----
@@ -62,8 +56,7 @@ $ operator-sdk add api \
62
56
+
63
57
This scaffolds the Memcached resource API under `pkg/apis/cache/v1alpha1/`.
64
58
65
-
.. Modify the spec and status of the `Memcached` Custom Resource (CR) at the
.. Modify the spec and status of the `Memcached` custom resource (CR) at the `pkg/apis/cache/v1alpha1/memcached_types.go` file:
67
60
+
68
61
[source,go]
69
62
----
@@ -77,8 +70,7 @@ type MemcachedStatus struct {
77
70
}
78
71
----
79
72
80
-
.. After modifying the `*_types.go` file, always run the following command to
81
-
update the generated code for that resource type:
73
+
.. After modifying the `*_types.go` file, always run the following command to update the generated code for that resource type:
82
74
+
83
75
[source,terminal]
84
76
----
@@ -87,39 +79,21 @@ $ operator-sdk generate k8s
87
79
88
80
. *Optional: Add custom validation to your CRD.*
89
81
+
90
-
OpenAPI v3.0 schemas are added to CRD manifests in the `spec.validation` block when
91
-
the manifests are generated. This validation block allows Kubernetes to validate
92
-
the properties in a Memcached CR when it is created or updated.
82
+
OpenAPI v3.0 schemas are added to CRD manifests in the `spec.validation` block when the manifests are generated. This validation block allows Kubernetes to validate the properties in a Memcached CR when it is created or updated.
93
83
+
94
-
Additionally, a `pkg/apis/<group>/<version>/zz_generated.openapi.go` file is
95
-
generated. This file contains the Go representation of this validation block if
96
-
the `+k8s:openapi-gen=true annotation` is present above the `Kind` type
97
-
declaration, which is present by default. This auto-generated code is your Go
98
-
`Kind` type's OpenAPI model, from which you can create a full OpenAPI
99
-
Specification and generate a client.
84
+
Additionally, a `pkg/apis/<group>/<version>/zz_generated.openapi.go` file is generated. This file contains the Go representation of this validation block if the `+k8s:openapi-gen=true annotation` is present above the `Kind` type declaration, which is present by default. This auto-generated code is the OpenAPI model of your Go `Kind` type, from which you can create a full OpenAPI Specification and generate a client.
100
85
+
101
-
As an Operator author, you can use Kubebuilder markers (annotations) to
102
-
configure custom validations for your API. These markers must always have a
103
-
`+kubebuilder:validation` prefix. For example, adding an enum-type specification
104
-
can be done by adding the following marker:
86
+
As an Operator author, you can use Kubebuilder markers (annotations) to configure custom validations for your API. These markers must always have a `+kubebuilder:validation` prefix. For example, adding an enum-type specification can be done by adding the following marker:
105
87
+
106
88
[source,go]
107
89
----
108
90
// +kubebuilder:validation:Enum=Lion;Wolf;Dragon
109
91
type Alias string
110
92
----
111
93
+
112
-
Usage of markers in API code is discussed in the Kubebuilder
Usage of markers in API code is discussed in the Kubebuilder link:https://book.kubebuilder.io/reference/generating-crd.html[Generating CRDs] and link:https://book.kubebuilder.io/reference/markers.html[Markers for Config/Code Generation] documentation. A full list of OpenAPIv3 validation markers is also available in the Kubebuilder link:https://book.kubebuilder.io/reference/markers/crd-validation.html[CRD Validation] documentation.
119
95
+
120
-
If you add any custom validations, run the following command to update the
If you add any custom validations, run the following command to update the OpenAPI validation section in the `deploy/crds/cache.example.com_memcacheds_crd.yaml` file for the CRD:
123
97
+
124
98
[source,terminal]
125
99
----
@@ -140,10 +114,9 @@ spec:
140
114
type: integer
141
115
----
142
116
143
-
. *Add a new Controller.*
117
+
. *Add a new controller.*
144
118
145
-
.. Add a new Controller to the project to watch and reconcile the Memcached
146
-
resource:
119
+
.. Add a new controller to the project to watch and reconcile the `Memcached` resource:
.. For this example, replace the generated controller file `pkg/controller/memcached/memcached_controller.go` with the link:https://github.com/operator-framework/operator-sdk/blob/master/example/memcached-operator/memcached_controller.go.tmpl[example implementation].
161
131
+
162
-
The example controller executes the following reconciliation logic for each
163
-
`Memcached` CR:
132
+
The example controller executes the following reconciliation logic for each `Memcached` resource:
164
133
+
165
134
--
166
-
* Create a Memcached Deployment if it does not exist.
135
+
* Create a Memcached deployment if it does not exist.
167
136
* Ensure that the Deployment size is the same as specified by the `Memcached` CR spec.
168
-
* Update the `Memcached` CR status with the names of the Memcached pods.
137
+
* Update the `Memcached` resource status with the names of the Memcached pods.
169
138
--
170
139
+
171
-
The next two sub-steps inspect how the Controller watches resources and how the
172
-
reconcile loop is triggered. You can skip these steps
173
-
to go directly to building and running the Operator.
140
+
The next two sub-steps inspect how the controller watches resources and how the reconcile loop is triggered. You can skip these steps to go directly to building and running the Operator.
174
141
175
-
.. Inspect the Controller implementation at the
176
-
`pkg/controller/memcached/memcached_controller.go` file to see how the
177
-
Controller watches resources.
142
+
.. Inspect the controller implementation at the `pkg/controller/memcached/memcached_controller.go` file to see how the controller watches resources.
178
143
+
179
-
The first watch is for the Memcached type as the primary resource. For each Add,
180
-
Update, or Delete event, the reconcile loop is sent a reconcile `Request` (a
181
-
`<namespace>:<name>` key) for that Memcached object:
144
+
The first watch is for the `Memcached` type as the primary resource. For each add, update, or delete event, the reconcile loop is sent a reconcile `Request` (a `<namespace>:<name>` key) for that `Memcached` object:
The next watch is for Deployments, but the event handler maps each event to a
190
-
reconcile `Request` for the owner of the Deployment. In this case, this is the
191
-
Memcached object for which the Deployment was created. This allows the
192
-
controller to watch Deployments as a secondary resource:
152
+
The next watch is for `Deployment` objects, but the event handler maps each event to a reconcile `Request` for the owner of the deployment. In this case, this is the `Memcached` object for which the deployment was created. This allows the controller to watch deployments as a secondary resource:
.. Every Controller has a Reconciler object with a `Reconcile()` method that
203
-
implements the reconcile loop. The reconcile loop is passed the `Request`
204
-
argument which is a `<namespace>:<name>` key used to lookup the primary resource
205
-
object, Memcached, from the cache:
162
+
.. Every controller has a `Reconciler` object with a `Reconcile()` method that implements the reconcile loop. The reconcile loop is passed the `Request` argument which is a `<namespace>:<name>` key used to lookup the primary resource object, `Memcached`, from the cache:
.... The Deployment manifest is generated at `deploy/operator.yaml`. Update the
261
-
Deployment image as follows since the default is just a placeholder:
215
+
.... The deployment manifest is generated at `deploy/operator.yaml`. Update the deployment image as follows since the default is just a placeholder:
262
216
+
263
217
[source,terminal]
264
218
----
265
219
$ sed -i 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml
266
220
----
267
221
268
-
.... Ensure you have an account on link:https://quay.io[Quay.io] for the next step,
269
-
or substitute your preferred container registry. On the registry,
270
-
link:https://quay.io/new/[create a new public image] repository named
271
-
`memcached-operator`.
222
+
.... Ensure you have an account on link:https://quay.io[Quay.io] for the next step, or substitute your preferred container registry. On the registry, link:https://quay.io/new/[create a new public image] repository named `memcached-operator`.
272
223
273
224
.... Push the image to the registry:
274
225
+
@@ -277,7 +228,7 @@ link:https://quay.io/new/[create a new public image] repository named
* For more information about OpenAPI v3.0 validation schemas in CRDs, refer to the link:https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#specifying-a-structural-schema[Kubernetes documentation].
= Creating cluster roles for Custom Resource Definitions
6
+
= Creating cluster roles for custom resource definitions
7
7
8
-
Cluster administrators can grant permissions to existing cluster-scoped Custom
9
-
Resource Definitions (CRDs). If you use the `admin`, `edit`, and `view` default
10
-
cluster roles, take advantage of cluster role aggregation for their rules.
8
+
Cluster administrators can grant permissions to existing cluster-scoped custom resource definitions (CRDs). If you use the `admin`, `edit`, and `view` default cluster roles, you can take advantage of cluster role aggregation for their rules.
11
9
12
10
[IMPORTANT]
13
11
====
14
-
You must explicitly assign permissions to each of these roles. The roles with
15
-
more permissions do not inherit rules from roles with fewer permissions. If you
16
-
assign a rule to a role, you must also assign that verb to roles that have more
17
-
permissions. For example, if you grant the `get crontabs` permission to the view
18
-
role, you must also grant it to the `edit` and `admin` roles. The `admin` or
19
-
`edit` role is usually assigned to the user that created a project through the
20
-
project template.
12
+
You must explicitly assign permissions to each of these roles. The roles with more permissions do not inherit rules from roles with fewer permissions. If you assign a rule to a role, you must also assign that verb to roles that have more permissions. For example, if you grant the `get crontabs` permission to the view role, you must also grant it to the `edit` and `admin` roles. The `admin` or `edit` role is usually assigned to the user that created a project through the project template.
21
13
====
22
14
23
15
.Prerequisites
@@ -31,10 +23,7 @@ endif::[]
31
23
32
24
.Procedure
33
25
34
-
. Create a cluster role definition file for the CRD. The cluster role definition
35
-
is a YAML file that contains the rules that apply to each cluster role. The
36
-
{product-title} controller adds the rules that you specify to the default
37
-
cluster roles.
26
+
. Create a cluster role definition file for the CRD. The cluster role definition is a YAML file that contains the rules that apply to each cluster role. A {product-title} controller adds the rules that you specify to the default cluster roles.
38
27
+
39
28
.Example YAML file for a cluster role definition
40
29
[source,yaml]
@@ -70,9 +59,7 @@ rules:
70
59
<4> Specify this label to grant permissions to the edit default role.
71
60
<5> Specify the group name of the CRD.
72
61
<6> Specify the plural name of the CRD that these rules apply to.
73
-
<7> Specify the verbs that represent the permissions that are granted to the role.
74
-
For example, apply read and write permissions to the `admin` and `edit` roles
75
-
and only read permission to the `view` role.
62
+
<7> Specify the verbs that represent the permissions that are granted to the role. For example, apply read and write permissions to the `admin` and `edit` roles and only read permission to the `view` role.
76
63
<8> Specify this label to grant permissions to the `view` default role.
77
64
<9> Specify this label to grant permissions to the `cluster-reader` default role.
0 commit comments