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
The project is currently pre-alpha and it is expected that breaking changes to the API will be made in the upcoming releases.
7
+
The project is currently alpha. The core APIs provided by the controller-runtime will most likely be unchanged. New features and APIs may still be added in the future.
8
8
9
-
See the [design docs][design_docs] for planned work on upcoming milestones.
9
+
See the [proposal docs][proposals_docs] and issues for ongoing or planned work.
10
10
11
11
## Overview
12
12
13
13
This project is a component of the [Operator Framework][of-home], an open source toolkit to manage Kubernetes native applications, called Operators, in an effective, automated, and scalable way. Read more in the [introduction blog post][of-blog].
14
14
15
15
[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.
16
16
17
-
The Operator SDK is a framework designed to make writing operators easier by providing:
17
+
The Operator SDK is a framework that uses the [controller-runtime][controller_runtime] library to make writing operators easier by providing:
18
18
- High level APIs and abstractions to write the operational logic more intuitively
19
19
- Tools for scaffolding and code generation to bootstrap a new project fast
20
20
- Extensions to cover common operator use cases
21
21
22
22
## Workflow
23
23
24
-
The SDK provides the following workflow to develop a new operator:
24
+
The SDK provides the following workflow to develop a new operator in Go:
25
25
1. Create a new operator project using the SDK Command Line Interface(CLI)
26
26
2. Define new resource APIs by adding Custom Resource Definitions(CRD)
27
-
3.Specify resources to watch using the SDK API
28
-
4.Define the operator reconciling logic in a designated handler and use the SDK API to interact with resources
27
+
3.Define Controllers to watch and reconcile resources
28
+
4.Write the reconciling logic for your Controller using the SDK and controller-runtime APIs
29
29
5. Use the SDK CLI to build and generate the operator deployment manifests
30
30
31
-
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.
Copy file name to clipboardExpand all lines: doc/user-guide.md
+30-17Lines changed: 30 additions & 17 deletions
Original file line number
Diff line number
Diff line change
@@ -11,8 +11,8 @@ how to program an operator in Go.
11
11
-[git][git_tool]
12
12
-[go][go_tool] version v1.10+.
13
13
-[docker][docker_tool] version 17.03+.
14
-
-[kubectl][kubectl_tool] version v1.10.0+.
15
-
- Access to a kubernetes v.1.10.0+ cluster.
14
+
-[kubectl][kubectl_tool] version v1.11.0+.
15
+
- Access to a kubernetes v.1.11.0+ cluster.
16
16
17
17
**Note**: This guide uses [minikube][minikube_tool] version v0.25.0+ as the local kubernetes cluster and quay.io for the public registry.
18
18
@@ -48,11 +48,11 @@ $ cd memcached-operator
48
48
To learn about the project directory structure, see [project layout][layout_doc] doc.
49
49
50
50
### Manager
51
-
The main program for the operator is the Manager `cmd/manager/main.go`.
51
+
The main program for the operator `cmd/manager/main.go` initializes and runs the [Manager][manager_go_doc].
52
52
53
-
The manager will automatically register the scheme for all custom resources defined under `pkg/apis/...` and run all controllers under `pkg/controller/...`.
53
+
The Manager will automatically register the scheme for all custom resources defined under `pkg/apis/...` and run all controllers under `pkg/controller/...`.
54
54
55
-
The manager can restrict the namespace that all controllers will watch for resources:
55
+
The Manager can restrict the namespace that all controllers will watch for resources:
This will scaffold a new Controller implementation under `pkg/controller/memcached/...`
102
104
103
-
For this example replace the generated controller file `pkg/controller/memcached/memcached_controller.go` with the example [memcached_controller.go][memcached_controller] implementation.
105
+
This will scaffold a new Controller implementation under `pkg/controller/memcached/...`.
106
+
107
+
For this example replace the generated Controller file `pkg/controller/memcached/memcached_controller.go` with the example [memcached_controller.go][memcached_controller] implementation.
104
108
105
-
The example controller executes the following reconciliation logic for each `Memcached` CR:
109
+
The example Controller executes the following reconciliation logic for each `Memcached` CR:
106
110
- Create a memcached Deployment if it doesn't exist
107
111
- Ensure that the Deployment size is the same as specified by the `Memcached` CR spec
108
112
- Update the `Memcached` CR status with the names of the memcached pods
109
113
110
-
The next two subsections explain how the controller watches resources and how the reconcile loop is triggered. Skip to the [Build](#build-and-run-the-operator) section to see how to build and run the operator.
114
+
The next two subsections explain how the Controller watches resources and how the reconcile loop is triggered. Skip to the [Build](#build-and-run-the-operator) section to see how to build and run the operator.
111
115
112
116
### Resources watched by the Controller
113
117
114
-
Inspect the controller implementation at `pkg/controller/memcached/memcached_controller.go` to see how the controller watches resources.
118
+
Inspect the Controller implementation at `pkg/controller/memcached/memcached_controller.go` to see how the Controller watches resources.
115
119
116
120
The first watch is for the Memcached type as the primary resource. For each Add/Update/Delete event the reconcile loop will be sent a reconcile `Request` (a namespace/name key) for that Memcached object:
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:
142
+
Every Controller has a Reconciler object with a `Reconcile()` method that implements the reconcile loop. The reconcile loop is passed the [Request][request-go-doc] argument which is a Namespace/Name key used to lookup the primary resource object, Memcached, from the cache:
To add a 3rd party resource to an operator, you must add it to the Manager's scheme. By creating an `AddToScheme` method or reusing one you can easily add a resource to your scheme. An [example][deployments_register] shows that you define a function and then use the [runtime][runtime_package] package to create a `SchemeBuilder`.
342
351
343
-
#### Register with the manager's scheme
352
+
#### Register with the Manager's scheme
353
+
344
354
Call the `AddToScheme()` function for your 3rd party resource and pass it the Manager's scheme via `mgr.GetScheme()`.
0 commit comments