Skip to content
This repository was archived by the owner on Sep 21, 2020. It is now read-only.

Commit 7c18265

Browse files
jmrodrijmrodri
authored
Merge pull request #46 from camilamacedo86/ISSUE_32
Improve getting started information in order to avoid issues as 32
2 parents 2be3e81 + e66037d commit 7c18265

File tree

1 file changed

+115
-20
lines changed

1 file changed

+115
-20
lines changed

‎README.md

Lines changed: 115 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,36 @@
11
# Getting Started
22

3+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
4+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
<!-- **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* -->
6+
7+
- [Overview](#overview)
8+
- [Build an operator using the Operator SDK](#build-an-operator-using-the-operator-sdk)
9+
- [Create a new project](#create-a-new-project)
10+
- [Manager](#manager)
11+
- [Add a new Custom Resource Definition](#add-a-new-custom-resource-definition)
12+
- [Define the Memcached spec and status](#define-the-memcached-spec-and-status)
13+
- [Add a new Controller](#add-a-new-controller)
14+
- [Resources watched by the Controller](#resources-watched-by-the-controller)
15+
- [Reconcile loop](#reconcile-loop)
16+
- [Build and run the operator](#build-and-run-the-operator)
17+
- [1. Run as a Deployment inside the cluster](#1-run-as-a-deployment-inside-the-cluster)
18+
- [2. Run locally outside the cluster](#2-run-locally-outside-the-cluster)
19+
- [Create a Memcached CR](#create-a-memcached-cr)
20+
- [Update the size](#update-the-size)
21+
- [Cleanup](#cleanup)
22+
- [Reference implementation](#reference-implementation)
23+
- [Manage the operator using the Operator Lifecycle Manager](#manage-the-operator-using-the-operator-lifecycle-manager)
24+
- [Generate an operator manifest](#generate-an-operator-manifest)
25+
- [Deploy the Operator](#deploy-the-operator)
26+
- [Create an application instance](#create-an-application-instance)
27+
- [Update an application](#update-an-application)
28+
- [Conclusion](#conclusion)
29+
30+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
31+
32+
## Overview
33+
334
The [Operator Framework][org_operator_framework] ([intro blog post][site_blog_post]) is an open source toolkit to manage Kubernetes native applications, called operators, in an effective, automated, and scalable way. Operators take advantage of Kubernetes's extensibility to deliver the automation advantages of cloud services like provisioning, scaling, and backup/restore while being able to run anywhere that Kubernetes can run.
435

536
This guide shows how to build a simple [memcached][site_memcached] operator and how to manage its lifecycle from install to update to a new version. For that, we will use two center pieces of the framework:
@@ -17,28 +48,22 @@ This section walks through an example of building a simple memcached operator us
1748

1849
### Create a new project
1950

20-
Use the CLI to create a new `memcached-operator` project:
51+
1. Use the CLI to create a new `memcached-operator` project:
2152

2253

2354
```sh
2455
$ mkdir -p $GOPATH/src/github.com/example-inc/
2556
$ cd $GOPATH/src/github.com/example-inc/
2657
$ export GO111MODULE=on
2758
$ operator-sdk new memcached-operator
28-
Create cmd/manager/main.go
29-
...
30-
Run dep ensure ...
31-
...
32-
Run dep ensure done
33-
Run git init ...
34-
...
35-
Run git init done
3659
$ cd memcached-operator
3760
```
3861

3962
This creates the `memcached-operator` project.
4063

41-
Learn more about the project directory structure from the SDK [project layout][layout_doc] documentation.
64+
2. Install dependencies by running `go mod tidy`
65+
66+
**NOTE:** Learn more about the project directory structure from the SDK [project layout][layout_doc] documentation.
4267

4368
### Manager
4469

@@ -89,6 +114,14 @@ After modifying the `*_types.go` file always run the following command to update
89114
$ operator-sdk generate k8s
90115
```
91116

117+
Also run the following command in order to automatically generate the OpenAPI validations.
118+
119+
```sh
120+
$ operator-sdk generate openapi
121+
```
122+
123+
You can see the changes applied in `deploy/crds/cache_v1alpha1_memcached_crd.yaml`
124+
92125
## Add a new Controller
93126

94127
Add a new [Controller][controller_go_doc] to the project that will watch and reconcile the `Memcached` resource:
@@ -163,16 +196,31 @@ Once this is done, there are two ways to run the operator:
163196

164197
### 1. Run as a Deployment inside the cluster
165198

166-
Build the memcached-operator image and push it to a registry:
199+
Build the memcached-operator image and push it to your registry. The following example uses https://quay.io as the registry.
167200

168201
```sh
169-
$ operator-sdk build quay.io/example/memcached-operator:v0.0.1
170-
$ sed -i 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml
202+
$ operator-sdk build quay.io/<user>/memcached-operator:v0.0.1
203+
$ sed -i 's|REPLACE_IMAGE|quay.io/<user>/memcached-operator:v0.0.1|g' deploy/operator.yaml
171204
# On OSX use:
172-
$ sed -i "" 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml
173-
$ docker push quay.io/example/memcached-operator:v0.0.1
205+
$ sed -i "" 's|REPLACE_IMAGE|quay.io/<user>/memcached-operator:v0.0.1|g' deploy/operator.yaml
206+
$ docker push quay.io/<user>/memcached-operator:v0.0.1
207+
```
208+
209+
The above command will replace the string `REPLACE_IMAGE` with the `<image>:<tag>` built above. Afterwards, verify that your `operator.yaml` file was updated successfully.
210+
211+
```yaml
212+
serviceAccountName: memcached-operator
213+
containers:
214+
- name: memcached-operator
215+
# Replace this with the built image name
216+
image: quay.io/<user>/memcached-operator:v0.0.1
217+
command:
218+
- memcached-operator
219+
imagePullPolicy: Always
174220
```
175221
222+
**IMPORTANT:** Ensure that your cluster is able to pull the image pushed to your registry.
223+
176224
The Deployment manifest is generated at `deploy/operator.yaml`. Be sure to update the deployment image as shown above since the default is just a placeholder.
177225

178226
Setup RBAC and deploy the memcached-operator:
@@ -184,14 +232,64 @@ $ kubectl create -f deploy/role_binding.yaml
184232
$ kubectl create -f deploy/operator.yaml
185233
```
186234

187-
Verify that the memcached-operator is up and running:
235+
**NOTE:** To apply the RBAC you need to be logged in `system:admin`. (E.g. By using for OCP: `oc login -u system:admin.`)
236+
237+
Verify that the `memcached-operator` Deployment is up and running:
188238

189239
```sh
190240
$ kubectl get deployment
191241
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
192242
memcached-operator 1 1 1 1 1m
193243
```
194244

245+
Verify that the `memcached-operator` pod is up and running:
246+
247+
```sh
248+
$ kubectl get pod
249+
NAME READY STATUS RESTARTS AGE
250+
memcached-operator-7d76948766-nrcp7 1/1 Running 0 44s
251+
```
252+
253+
**IMPORTANT:** Ensure that you built and pushed the image, and updated the `operator.yaml` file.
254+
255+
Verify that the operator is running successfully by checking its logs.
256+
257+
```sh
258+
$ kubectl logs memcached-operator-7d76948766-nrcp7
259+
{"level":"info","ts":1567613603.7161574,"logger":"cmd","msg":"Go Version: go1.12.7"}
260+
{"level":"info","ts":1567613603.7163043,"logger":"cmd","msg":"Go OS/Arch: linux/amd64"}
261+
{"level":"info","ts":1567613603.7163143,"logger":"cmd","msg":"Version of operator-sdk: v0.10.0+git"}
262+
{"level":"info","ts":1567613603.7166178,"logger":"leader","msg":"Trying to become the leader."}
263+
{"level":"info","ts":1567613603.8369129,"logger":"leader","msg":"No pre-existing lock was found."}
264+
{"level":"info","ts":1567613603.8667152,"logger":"leader","msg":"Became the leader."}
265+
{"level":"info","ts":1567613603.9393756,"logger":"cmd","msg":"Registering Components."}
266+
{"level":"info","ts":1567613603.9396026,"logger":"kubebuilder.controller","msg":"Starting EventSource","controller":"memcached-controller","source":"kind source: /, Kind="}
267+
{"level":"info","ts":1567613603.9398162,"logger":"kubebuilder.controller","msg":"Starting EventSource","controller":"memcached-controller","source":"kind source: /, Kind="}
268+
{"level":"info","ts":1567613604.0514739,"logger":"metrics","msg":"Metrics Service object created","Service.Name":"memcached-operator-metrics","Service.Namespace":"myproject"}
269+
{"level":"info","ts":1567613604.0976534,"logger":"cmd","msg":"Could not create ServiceMonitor object","error":"no ServiceMonitor registered with the API"}
270+
{"level":"info","ts":1567613604.0986068,"logger":"cmd","msg":"Install prometheus-operator in your cluster to create ServiceMonitor objects","error":"no ServiceMonitor registered with the API"}
271+
{"level":"info","ts":1567613604.0988326,"logger":"cmd","msg":"Starting the Cmd."}
272+
{"level":"info","ts":1567613604.2993534,"logger":"kubebuilder.controller","msg":"Starting Controller","controller":"memcached-controller"}
273+
{"level":"info","ts":1567613604.3995395,"logger":"kubebuilder.controller","msg":"Starting workers","controller":"memcached-controller","worker count":1}
274+
```
275+
276+
The following error will occur if your cluster was unable to pull the image:
277+
278+
```sh
279+
$ kubectl get pod
280+
NAME READY STATUS RESTARTS AGE
281+
memcached-operator-6b5dc697fb-t62cv 0/1 ImagePullBackOff 0 2m
282+
```
283+
284+
Following the logs in the error scenario described above.
285+
286+
```sh
287+
$ kubectl logs memcached-operator-6b5dc697fb-t62cv
288+
Error from server (BadRequest): container "memcached-operator" in pod "memcached-operator-6b5dc697fb-t62cv" is waiting to start: image can't be pulled
289+
```
290+
291+
**NOTE:** Just for tests purposes make the image public and setting up the cluster to allow use insecure registry. ( E.g `--insecure-registry 172.30.0.0/16` )
292+
195293
### 2. Run locally outside the cluster
196294

197295
This method is preferred during development cycle to deploy and test faster.
@@ -231,7 +329,7 @@ spec:
231329
$ kubectl apply -f deploy/crds/cache_v1alpha1_memcached_cr.yaml
232330
```
233331

234-
Ensure that the memcached-operator creates the deployment for the CR:
332+
Ensure that the `memcached-operator` creates the deployment for the CR:
235333

236334
```sh
237335
$ kubectl get deployment
@@ -320,8 +418,6 @@ The previous section has covered manually running an operator. In the next secti
320418

321419
OLM helps you to install, update, and generally manage the lifecycle of all of the operators (and their associated services) on a Kubernetes cluster. It runs as an Kubernetes extension and lets you use `kubectl` for all the lifecycle management functions without any additional tools.
322420

323-
324-
325421
### Generate an operator manifest
326422

327423
The first step to leveraging OLM is to create a [Cluster Service Version][csv_design_doc] (CSV) manifest. An operator manifest describes how to display, create and manage the application, in this case memcached, as a whole. It is required for OLM to function.
@@ -332,7 +428,6 @@ $ operator-sdk olm-catalog gen-csv --csv-version 0.0.1
332428
```
333429
For more details see the SDK's [CSV generation doc][csv_generation_doc].
334430

335-
336431
For the purpose of this guide, we will continue with this [predefined manifest][manifest_v1] file for the next steps. If you’d like, you can alter the image field within this manifest to reflect the image you built in previous steps, but it is unnecessary.
337432

338433
### Deploy the Operator

0 commit comments

Comments
 (0)