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
See the [design docs][design_docs] for planned work on upcoming milestones.
10
8
11
9
## Overview
12
10
13
-
[Operators][operator_link] make it easy to manage complex stateful applications on top of Kubernetes. However writing an operator today can be a significant effort that involves challenges like using low level APIs, writing boilerplate, and a lack of modularity which leads to duplication.
11
+
[Operators][operator_link] make it easy to manage complex stateful applications on top of Kubernetes. However writing an operator today can be difficult because of challenges such as using low level APIs, writing boilerplate, and a lack of modularity which leads to duplication.
14
12
15
13
The Operator SDK is a framework designed to make writing operators easier by providing:
16
14
- High level APIs and abstractions to write the operational logic more intuitively
@@ -26,307 +24,50 @@ The SDK provides the following workflow to develop a new operator:
26
24
4. Define the operator reconciling logic in a designated handler and use the SDK API to interact with resources
27
25
5. Use the SDK CLI to build and generate the operator deployment manifests
28
26
29
-
At a high level the architecture of an operator using the SDK looks as shown below. The operator processes events for watched resources in a user defined handler and takes actions to reconcile the state of the application.
27
+
At a high level an operator using the SDK processes events for watched resources in a user defined handler and takes actions to reconcile the state of the application.
This guide is designed for beginners who want to start an operator project from scratch.
38
-
39
-
## Guide prerequisites
40
-
41
-
Before creating any project, this guide has the following prerequisites:
42
-
43
-
-[dep][dep_tool] version v0.4.1+.
44
-
-[go][go_tool] version v1.10+.
45
-
-[docker][docker_tool] version 17.03+.
46
-
This guide uses image repository `quay.io/example/memcached-operator` as an example.
47
-
-[kubectl][kubectl_tool] version v1.9.0+.
48
-
- (optional) [minikube][minikube_tool] version v0.25.0+.
49
-
This guide uses minikube as a quickstart Kubernetes playground. Run the command:
50
-
```
51
-
minikube start
52
-
```
53
-
This will start minikube in the background and set up kubectl configuration accordingly.
54
-
55
-
## Installing Operator SDK CLI
56
-
57
-
The Operator SDK comes with a CLI tool that manages the development lifecycle. It helps create the project scaffolding, preprocess custom resource API to generate Kubernetes related code, and generate deployment scripts.
58
-
59
-
Checkout the desired release tag and install the SDK CLI tool:
60
-
```
61
-
git checkout tags/v0.0.1
62
-
go install github.com/coreos/operator-sdk/commands/operator-sdk
63
-
```
64
-
65
-
This will install the CLI binary `operator-sdk` at `$GOPATH/bin`.
66
-
67
-
## Creating a new project
68
-
69
-
Navigate to `$GOPATH/src/github.com/example-inc/`.
70
-
71
-
Use the `new` command to create a new operator project:
72
-
73
-
```
74
-
operator-sdk new memcached-operator --api-version=cache.example.com/v1alpha1 --kind=Memcached
75
-
```
76
-
77
-
This creates the project directory `memcached-operator` and generates the API pkg tree for a custom resource with APIVersion `cache.example.com/v1apha1` and Kind `Memcached`.
78
-
79
-
Navigate to the project folder:
80
-
81
-
```
82
-
cd memcached-operator
83
-
```
84
-
85
-
More details about the project directory structure can be found in the [project layout][scaffold_doc] doc.
86
-
87
-
## Up and running
88
-
89
-
At this point we are ready to build and run a functional operator.
90
-
91
-
The default operator behaviour defined in the entry point `cmd/memcached-operator/main.go` is to watch for Deployments in the default namespace and print out their names.
92
-
93
-
> Note: This example watches Deployments for the APIVersion `apps/v1` which is only present in k8s versions 1.9+. So for k8s versions < 1.9 change the APIVersion to something that is supported e.g `apps/v1beta1`.
94
-
95
-
To see it, first build the memcached-operator container and then push it to a public registry:
$ go install github.com/coreos/operator-sdk/commands/operator-sdk
100
36
```
101
37
102
-
Kubernetes deployment manifests are generated in `deploy/operator.yaml`. The deployment image is set to the container image specified above.
103
-
104
-
Deploy the memcached-operator:
105
-
106
-
```
107
-
kubectl create -f deploy/rbac.yaml
108
-
kubectl create -f deploy/operator.yaml
109
-
```
38
+
Create and deploy an app-operator using the SDK CLI:
110
39
111
-
Verify that the memcached-operator is up and running:
40
+
```sh
41
+
# Create an app-operator project that defines the App CR.
42
+
$ cd$GOPATH/src/github.com/example-inc/
43
+
$ operator-sdk new app-operator --api-version=app.example.com/v1alpha1 --kind=App
44
+
$ cd app-operator
112
45
113
-
```
114
-
$ kubectl get deploy
115
-
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
116
-
memcached-operator 1 1 1 1 1m
117
-
```
46
+
# Build and push the app-operator image to a public registry such as quay.io
47
+
$ operator-sdk build quay.io/example/app-operator
48
+
$ docker push quay.io/example/app-operator
118
49
119
-
Check the memcached-operator pod’s log:
50
+
# Deploy the app-operator
51
+
$ kubectl create -f deploy/rbac.yaml
52
+
$ kubectl create -f deploy/operator.yaml
120
53
121
-
```
122
-
$ kubectl get pod | grep memcached-operator | cut -d' ' -f1 | xargs kubectl logs
123
-
Received Deployment: memcached-operator
124
-
```
54
+
# By default, creating a custom resource (App) triggers the app-operator to deploy a busybox pod
55
+
$ kubectl create -f deploy/cr.yaml
125
56
126
-
Clean up resources:
57
+
# Verify that the busybox pod is created
58
+
$ kubectl get pod -l app=busy-box
59
+
NAME READY STATUS RESTARTS AGE
60
+
busy-box 1/1 Running 0 50s
127
61
62
+
# Cleanup
63
+
$ kubectl delete -f deploy/cr.yaml
64
+
$ kubectl delete -f deploy/operator.yaml
65
+
$ kubectl delete -f deploy/rbac.yaml
128
66
```
129
-
kubectl delete -f deploy/operator.yaml
130
-
```
131
-
132
-
This is a basic test that verifies everything works correctly. Next we are going to write the business logic and do something more interesting.
133
-
134
-
135
-
## Customizing operator logic
136
-
137
-
An operator is used to extend the kube-API and codify application domain knowledge. Operator SDK is designed to provide non-Kubernetes developers an easy way to write the business logic.
138
67
139
-
In the following steps we are adding a custom resource `Memcached`, and customizing the operator logic that creating a new Memcached CR will create a Memcached Deployment and (optional) Service.
68
+
To learn more about the operator-sdk, see the [user guide][guide].
140
69
141
-
In `pkg/apis/cache/v1alpha1/types.go`, add to `MemcachedSpec` a new field `WithService`:
142
-
143
-
```Go
144
-
typeMemcachedSpecstruct {
145
-
WithServicebool`json:"withService"`
146
-
}
147
-
```
148
-
149
-
Re-render the generated code for custom resource:
150
-
151
-
```
152
-
operator-sdk generate k8s
153
-
```
154
-
155
-
In `cmd/memcached-operator/main.go`, modify `sdk.Watch` to watch on `Memcached` custom resource:
0 commit comments