Skip to content

doc: clean up README and user-guide #661

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 29, 2018
Merged

doc: clean up README and user-guide #661

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
036411b
doc: clean up README and user-guide
hasbro17 Oct 26, 2018
69d4a11
doc: clarify alpha, fix typos
hasbro17 Oct 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 20 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,42 +2,44 @@

[![Build Status](https://travis-ci.org/operator-framework/operator-sdk.svg?branch=master)](https://travis-ci.org/operator-framework/operator-sdk)

### Project Status: pre-alpha
### Project Status: alpha

The project is currently pre-alpha and it is expected that breaking changes to the API will be made in the upcoming releases.
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.

See the [design docs][design_docs] for planned work on upcoming milestones.
**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`.

See the [proposal docs][proposals_docs] and issues for ongoing or planned work.

## Overview

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].

[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.

The Operator SDK is a framework designed to make writing operators easier by providing:
The Operator SDK is a framework that uses the [controller-runtime][controller_runtime] library to make writing operators easier by providing:
- High level APIs and abstractions to write the operational logic more intuitively
- Tools for scaffolding and code generation to bootstrap a new project fast
- Extensions to cover common operator use cases

## Workflow

The SDK provides the following workflow to develop a new operator:
The SDK provides workflows to develop operators in Go or Ansible.

The following workflow is for a new Go operator:
1. Create a new operator project using the SDK Command Line Interface(CLI)
2. Define new resource APIs by adding Custom Resource Definitions(CRD)
3. Specify resources to watch using the SDK API
4. Define the operator reconciling logic in a designated handler and use the SDK API to interact with resources
3. Define Controllers to watch and reconcile resources
4. Write the reconciling logic for your Controller using the SDK and controller-runtime APIs
5. Use the SDK CLI to build and generate the operator deployment manifests

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.

## Prerequisites

- [dep][dep_tool] version v0.5.0+.
- [git][git_tool]
- [go][go_tool] version v1.10+.
- [docker][docker_tool] version 17.03+.
- [kubectl][kubectl_tool] version v1.10.0+.
- Access to a kubernetes v.1.10.0+ cluster.
- [kubectl][kubectl_tool] version v1.11.0+.
- Access to a kubernetes v.1.11.0+ cluster.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How come it doesn't work on v.1.10.0 clusters anymore?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should work on v1.10, but we don't test v1.10 anymore, only v1.11 (technically openshift v3.11)


## Quick Start

Expand Down Expand Up @@ -104,9 +106,11 @@ $ kubectl delete -f deploy/service_account.yaml
$ kubectl delete -f deploy/crds/app_v1alpha1_appservice_crd.yaml
```

## User Guide
## User Guides

To learn more about the writing an operator in Go, see the [user guide][guide].

To learn more about the operator-sdk, see the [user guide][guide].
The SDK also supports developing an operator using Ansible. See the [Ansible operator user guide][ansible_user_guide].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a note about this in the Workflow section as well. Perhaps @shawn-hurley or another Ansible-focused team member could write a workflow in this or a separate PR.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we will add a follow up PR just to keep it easy


## Samples

Expand All @@ -125,7 +129,7 @@ See [reporting bugs][bug_guide] for details about reporting any issues.
Operator SDK is under Apache 2.0 license. See the [LICENSE][license_file] file for details.

[operator_link]: https://coreos.com/operators/
[design_docs]: ./doc/design
[proposals_docs]: ./doc/proposals
[guide]: ./doc/user-guide.md
[samples]: https://github.com/operator-framework/operator-sdk-samples
[of-home]: https://github.com/operator-framework
Expand All @@ -138,3 +142,5 @@ Operator SDK is under Apache 2.0 license. See the [LICENSE][license_file] file f
[go_tool]:https://golang.org/dl/
[docker_tool]:https://docs.docker.com/install/
[kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/
[controller_runtime]: https://github.com/kubernetes-sigs/controller-runtime
[ansible_user_guide]:./ansible/user-guide.md
49 changes: 30 additions & 19 deletions doc/user-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ how to program an operator in Go.
- [git][git_tool]
- [go][go_tool] version v1.10+.
- [docker][docker_tool] version 17.03+.
- [kubectl][kubectl_tool] version v1.10.0+.
- Access to a kubernetes v.1.10.0+ cluster.
- [kubectl][kubectl_tool] version v1.11.0+.
- Access to a kubernetes v.1.11.0+ cluster.

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

Expand Down Expand Up @@ -48,11 +48,11 @@ $ cd memcached-operator
To learn about the project directory structure, see [project layout][layout_doc] doc.

### Manager
The main program for the operator is the Manager `cmd/manager/main.go`.
The main program for the operator `cmd/manager/main.go` initializes and runs the [Manager][manager_go_doc].

The manager will automatically register the scheme for all custom resources defined under `pkg/apis/...` and run all controllers under `pkg/controller/...`.
The Manager will automatically register the scheme for all custom resources defined under `pkg/apis/...` and run all controllers under `pkg/controller/...`.

The manager can restrict the namespace that all controllers will watch for resources:
The Manager can restrict the namespace that all controllers will watch for resources:
```Go
mgr, err := manager.New(cfg, manager.Options{Namespace: namespace})
```
Expand All @@ -61,18 +61,18 @@ By default this will be the namespace that the operator is running in. To watch
mgr, err := manager.New(cfg, manager.Options{Namespace: ""})
```

**// TODO:** Doc on manager options(Sync period, leader election, registering 3rd party types)

## Add a new Custom Resource Definition

Add a new Custom Resource Defintion(CRD) API called Memcached, with APIVersion `cache.example.com/v1apha1` and Kind `Memcached`.
Add a new Custom Resource Definition(CRD) API called Memcached, with APIVersion `cache.example.com/v1apha1` and Kind `Memcached`.

```sh
$ operator-sdk add api --api-version=cache.example.com/v1alpha1 --kind=Memcached
```

This will scaffold the Memcached resource API under `pkg/apis/cache/v1alpha1/...`.

### Define the spec and status

Modify the spec and status of the `Memcached` Custom Resource(CR) at `pkg/apis/cache/v1alpha1/memcached_types.go`:

```Go
Expand All @@ -94,24 +94,26 @@ $ operator-sdk generate k8s

## Add a new Controller

Add a new Controller to the project that will watch and reconcile the Memcached resource:
```
Add a new [Controller][controller-go-doc] to the project that will watch and reconcile the Memcached resource:

```sh
$ operator-sdk add controller --api-version=cache.example.com/v1alpha1 --kind=Memcached
```
This will scaffold a new Controller implementation under `pkg/controller/memcached/...`

For this example replace the generated controller file `pkg/controller/memcached/memcached_controller.go` with the example [memcached_controller.go][memcached_controller] implementation.
This will scaffold a new Controller implementation under `pkg/controller/memcached/...`.

The example controller executes the following reconciliation logic for each `Memcached` CR:
For this example replace the generated Controller file `pkg/controller/memcached/memcached_controller.go` with the example [`memcached_controller.go`][memcached_controller] implementation.

The example Controller executes the following reconciliation logic for each `Memcached` CR:
- Create a memcached Deployment if it doesn't exist
- Ensure that the Deployment size is the same as specified by the `Memcached` CR spec
- Update the `Memcached` CR status with the names of the memcached pods

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.
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.

### Resources watched by the Controller

Inspect the controller implementation at `pkg/controller/memcached/memcached_controller.go` to see how the controller watches resources.
Inspect the Controller implementation at `pkg/controller/memcached/memcached_controller.go` to see how the Controller watches resources.

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:

Expand All @@ -135,7 +137,7 @@ err := c.Watch(&source.Kind{Type: &appsv1.Deployment{}}, &handler.EnqueueRequest

### Reconcile loop

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:
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:

```Go
func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Result, error) {
Expand All @@ -146,7 +148,8 @@ func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Res
}
```

Based on the return value of `Reconcile()` the reconcile `Request` may be requeued and the loop may be triggered again:
Based on the return values, [`Result`][result_go_doc] and error, the `Request` may be requeued and the reconcile loop may be triggered again:

```Go
// Reconcile successful - don't requeue
return reconcile.Result{}, nil
Expand All @@ -164,6 +167,8 @@ import "time"
return reconcile.Result{RequeueAfter: time.Second*5}, nil
```

**Note:** Returning `Result` with `RequeueAfter` set is how you can periodically reconcile a CR.

For a guide on Reconcilers, Clients, and interacting with resource Events, see the [Client API doc][doc_client_api].

## Build and run the operator
Expand Down Expand Up @@ -325,7 +330,9 @@ $ kubectl delete -f deploy/service_account.yaml
```

## Advanced Topics

### Adding 3rd Party Resources To Your Operator

By default the operator's Manager will register all custom resource types defined in your project under `pkg/apis` with its scheme.
```Go
import (
Expand All @@ -340,7 +347,8 @@ if err := apis.AddToScheme(mgr.GetScheme()); err != nil {

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`.

#### Register with the manager's scheme
#### Register with the Manager's scheme

Call the `AddToScheme()` function for your 3rd party resource and pass it the Manager's scheme via `mgr.GetScheme()`.

Example:
Expand Down Expand Up @@ -372,4 +380,7 @@ func main() {
[deployments_register]: https://github.com/kubernetes/api/blob/master/apps/v1/register.go#L41
[doc_client_api]:./user/client.md
[runtime_package]: https://godoc.org/k8s.io/apimachinery/pkg/runtime
[osdk_add_to_scheme]: https://github.com/operator-framework/operator-sdk/blob/4179b6ac459b2b0cb04ab3a1b438c280bd28d1a5/pkg/util/k8sutil/k8sutil.go#L67
[manager_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Manager
[controller-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg#hdr-Controller
[request-go-doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Request
[result_go_doc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result