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 which means that there are still new features and APIs planned that will be added in the future. Due to this breaking changes may still happen.
8
8
9
-
See the [design docs][design_docs] for planned work on upcoming milestones.
9
+
**Note:** The core APIs provided by the [controller-runtime][controller_runtime] will most likely stay unchanged however the expectation is that any breaking changes should be relatively minor and easier to handle than the changes from SDK `v0.0.7` to `v0.1.0`.
10
+
11
+
See the [proposal docs][proposals_docs] and issues for ongoing or planned work.
10
12
11
13
## Overview
12
14
13
15
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
16
15
17
[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
18
17
-
The Operator SDK is a framework designed to make writing operators easier by providing:
19
+
The Operator SDK is a framework that uses the [controller-runtime][controller_runtime] library to make writing operators easier by providing:
18
20
- High level APIs and abstractions to write the operational logic more intuitively
19
21
- Tools for scaffolding and code generation to bootstrap a new project fast
20
22
- Extensions to cover common operator use cases
21
23
22
24
## Workflow
23
25
24
-
The SDK provides the following workflow to develop a new operator:
26
+
The SDK provides workflows to develop operators in Go or Ansible.
27
+
28
+
The following workflow is for a new Go operator:
25
29
1. Create a new operator project using the SDK Command Line Interface(CLI)
26
30
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
31
+
3.Define Controllers to watch and reconcile resources
32
+
4.Write the reconciling logic for your Controller using the SDK and controller-runtime APIs
29
33
5. Use the SDK CLI to build and generate the operator deployment manifests
30
34
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-19Lines changed: 30 additions & 19 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
102
103
-
For this example replace the generated controller file`pkg/controller/memcached/memcached_controller.go` with the example [memcached_controller.go][memcached_controller] implementation.
103
+
This will scaffold a new Controller implementation under`pkg/controller/memcached/...`.
104
104
105
-
The example controller executes the following reconciliation logic for each `Memcached` CR:
105
+
For this example replace the generated Controller file `pkg/controller/memcached/memcached_controller.go` with the example [`memcached_controller.go`][memcached_controller] implementation.
106
+
107
+
The example Controller executes the following reconciliation logic for each `Memcached` CR:
106
108
- Create a memcached Deployment if it doesn't exist
107
109
- Ensure that the Deployment size is the same as specified by the `Memcached` CR spec
108
110
- Update the `Memcached` CR status with the names of the memcached pods
109
111
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.
112
+
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
113
112
114
### Resources watched by the Controller
113
115
114
-
Inspect the controller implementation at `pkg/controller/memcached/memcached_controller.go` to see how the controller watches resources.
116
+
Inspect the Controller implementation at `pkg/controller/memcached/memcached_controller.go` to see how the Controller watches resources.
115
117
116
118
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:
140
+
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
349
343
-
#### Register with the manager's scheme
350
+
#### Register with the Manager's scheme
351
+
344
352
Call the `AddToScheme()` function for your 3rd party resource and pass it the Manager's scheme via `mgr.GetScheme()`.
0 commit comments