Skip to content

Commit d1582c8

Browse files
hasbro17hasbro17
authored
Merge pull request #145 from hasbro17/haseeb/add-user-guide-example
user-guide: Add memcached-operator walkthrough
2 parents a7429f5 + 28eb1a2 commit d1582c8

File tree

2 files changed

+176
-14
lines changed

2 files changed

+176
-14
lines changed

‎doc/milestone/user_guide.md‎

Lines changed: 175 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,199 @@
1-
# Getting Started
1+
# User Guide
2+
3+
This guide walks through an example of building a simple memcached-operator using tools and libraries provided by the Operator SDK.
24

35
## Prerequisites
46

57
- [dep][dep_tool] version v0.4.1+.
68
- [go][go_tool] version v1.10+.
79
- [docker][docker_tool] version 17.03+.
8-
- Access to a public registry such as quay.io.
910
- [kubectl][kubectl_tool] version v1.9.0+.
1011
- Access to a kubernetes v.1.9.0+ cluster.
1112

1213
**Note**: This guide uses [minikube][minikube_tool] version v0.25.0+ as the local kubernetes cluster and quay.io for the public registry.
1314

14-
## Installing Operator SDK CLI
15+
## Install the Operator SDK CLI
1516

16-
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.
17+
The Operator SDK has a CLI tool that helps the developer to create, build, and deploy a new operator project.
1718

1819
Checkout the desired release tag and install the SDK CLI tool:
1920
```
20-
git checkout tags/v0.0.2
21-
go install github.com/coreos/operator-sdk/commands/operator-sdk
21+
$ git checkout tags/v0.0.2
22+
$ go install github.com/coreos/operator-sdk/commands/operator-sdk
23+
```
24+
25+
This installs the CLI binary `operator-sdk` at `$GOPATH/bin`.
26+
27+
## Create a new project
28+
29+
Use the CLI to create a new memcached-operator project:
30+
31+
```
32+
$ cd $GOPATH/src/github.com/example-inc/
33+
$ operator-sdk new memcached-operator --api-version=cache.example.com/v1alpha1 --kind=Memcached
34+
$ cd memcached-operator
35+
```
36+
37+
This creates the memcached-operator project specifically for watching the Memcached resource with APIVersion `cache.example.com/v1apha1` and Kind `Memcached`.
38+
39+
To learn more about the project directory structure, see [project layout][layout_doc] doc.
40+
41+
## Customize the operator logic
42+
43+
For this example the memcached-operator will execute the following reconciliation logic for each `Memcached` CR:
44+
- Create a memcached Deployment if it doesn't exist
45+
- Ensure that the Deployment size is the same as specified by the `Memcached` CR spec
46+
- Update the `Memcached` CR status with the names of the memcached pods
47+
48+
### Watch the Memcached CR
49+
50+
By default, the memcached-operator watches `Memcached` resource events as shown in `cmd/memcached-operator/main.go`.
51+
52+
```Go
53+
func main() {
54+
sdk.Watch("cache.example.com/v1alpha1", "Memcached", "default")
55+
sdk.Handle(stub.NewHandler())
56+
sdk.Run(context.TODO())
57+
}
58+
```
59+
60+
### Define the Memcached spec and status
61+
62+
Modify the spec and status of the `Memcached` CR at `pkg/apis/cache/v1alpha1/types.go`:
63+
64+
```Go
65+
type MemcachedSpec struct {
66+
// Size is the size of the memcached deployment
67+
Size int32 `json:"size"`
68+
}
69+
type MemcachedStatus struct {
70+
// Nodes are the names of the memcached pods
71+
Nodes []string `json:"nodes"`
72+
}
73+
```
74+
Update the generated code for the CR:
75+
76+
```
77+
$ operator-sdk generate k8s
78+
```
79+
80+
### Define the Handler
81+
82+
The reconciliation loop for an event is defined in the `Handle()` function at `pkg/stub/handler.go`.
83+
84+
Replace the default handler with the reference [memcached handler][memcached_handler] implementation.
85+
86+
> Note: The provided handler implementation is only meant to demonstrate the use of the SDK APIs and is not representative of the best practices of a reconciliation loop.
87+
88+
### Build and run the operator
89+
90+
Build the memcached-operator image and push it to a registry:
91+
```
92+
$ operator-sdk build quay.io/example/memcached-operator:v0.0.1
93+
$ docker push quay.io/example/memcached-operator:v0.0.1
2294
```
2395

24-
This will install the CLI binary `operator-sdk` at `$GOPATH/bin`.
96+
Kubernetes deployment manifests are generated in `deploy/operator.yaml`. The deployment image is set to the container image specified above.
2597

26-
## Creating a new project
98+
Deploy the memcached-operator:
2799

28-
TODO
100+
```
101+
kubectl create -f deploy/rbac.yaml
102+
kubectl create -f deploy/operator.yaml
103+
```
104+
105+
Verify that the memcached-operator is up and running:
106+
107+
```
108+
$ kubectl get deployment
109+
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
110+
memcached-operator 1 1 1 1 1m
111+
```
112+
113+
### Create a Memcached CR
114+
115+
Run the following command to create a `Memcached` custom resource:
116+
117+
```sh
118+
$ cat <<EOF | kubectl apply -f -
119+
apiVersion: "cache.example.com/v1alpha1"
120+
kind: "Memcached"
121+
metadata:
122+
name: "example-memcached"
123+
spec:
124+
size: 3
125+
EOF
126+
```
127+
128+
Ensure that the memcached-operator creates the deployment for the CR:
129+
130+
```
131+
$ kubectl get deployment
132+
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
133+
memcached-operator 1 1 1 1 2m
134+
example-memcached 3 3 3 3 1m
135+
```
136+
137+
Check the pods and CR status to confirm the status is updated with the memcached pod names:
138+
139+
```
140+
$ kubectl get pods
141+
NAME READY STATUS RESTARTS AGE
142+
example-memcached-6fd7c98d8-7dqdr 1/1 Running 0 1m
143+
example-memcached-6fd7c98d8-g5k7v 1/1 Running 0 1m
144+
example-memcached-6fd7c98d8-m7vn7 1/1 Running 0 1m
145+
memcached-operator-7cc7cfdf86-vvjqk 1/1 Running 0 2m
146+
```
147+
148+
```
149+
$ kubectl get memcached/example-memcached -o yaml
150+
apiVersion: cache.example.com/v1alpha1
151+
kind: Memcached
152+
metadata:
153+
clusterName: ""
154+
creationTimestamp: 2018-03-31T22:51:08Z
155+
generation: 0
156+
name: example-memcached
157+
namespace: default
158+
resourceVersion: "245453"
159+
selfLink: /apis/cache.example.com/v1alpha1/namespaces/default/memcacheds/example-memcached
160+
uid: 0026cc97-3536-11e8-bd83-0800274106a1
161+
spec:
162+
size: 3
163+
status:
164+
nodes:
165+
- example-memcached-6fd7c98d8-7dqdr
166+
- example-memcached-6fd7c98d8-g5k7v
167+
- example-memcached-6fd7c98d8-m7vn7
168+
```
169+
170+
### Update the size
171+
172+
Change the `spec.size` field in the memcached CR from 3 to 4:
173+
```
174+
$ kubectl get memcached/example-memcached -o yaml | sed 's|size: 3|size: 4|g' | kubectl apply -f -
175+
```
176+
177+
Confirm that the operator changes the deployment size:
178+
```
179+
$ kubectl get deployment
180+
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
181+
example-memcached 4 4 4 4 5m
182+
```
183+
184+
### Cleanup
185+
186+
Clean up the resources:
187+
188+
```
189+
kubectl delete memcached example-memcached
190+
kubectl delete -f deploy/operator.yaml
191+
```
29192

30-
[scaffold_doc]:./doc/project_layout.md
31-
[mc_protocol]:https://github.com/memcached/memcached/blob/master/doc/protocol.txt
193+
[memcached_handler]: example/memcached-operator/handler.go
194+
[layout_doc]:./doc/project_layout.md
32195
[dep_tool]:https://golang.github.io/dep/docs/installation.html
33196
[go_tool]:https://golang.org/dl/
34197
[docker_tool]:https://docs.docker.com/install/
35198
[kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/
36-
[minikube_tool]:https://github.com/kubernetes/minikube#installation
37-
[operator_link]:https://coreos.com/operators/
38-
[design_docs]:./doc/design
199+
[minikube_tool]:https://github.com/kubernetes/minikube#installation

‎example/memcached-operator/handler.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
// TODO

0 commit comments

Comments
 (0)