Difficulty: beginner
Estimated Time: 30 minutes

Why an Operator?

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

What is the Operator SDK?

The Operator SDK is a framework that uses the 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.

How do I use it?

The following is the workflow for a new Go-based Operator with the Operator SDK:

  1. Create a new Operator project using the SDK CLI.
  2. Create a new Custom Resource Definition API Type using the SDK CLI.
  3. Add your Custom Resource Definition (CRD) to your live Kubernetes cluster.
  4. Define your Custom Resource Spec and Status.
  5. Create a new Controller for your Custom Resource Definition API.
  6. Write the reconciling logic for your Controller.
  7. Run the Operator locally to test your code against your live Kubernetes cluster.
  8. Add your Custom Resource (CR) to your live Kubernetes cluster and watch your Operator in action!
  9. After you are satisifed with your work, use the SDK CLI to build and generate the Operator Deployment manifests.
  10. Optionally add additional APIs and Controllers using the SDK CLI.

PodSet Operator

In this tutorial, we will create an Operator called a PodSet. A PodSet is a simple Controller/Operator that manages pods.

A user provides a number of pods specified in spec.replicas. The PodSet also conveniently outputs the name of all Pods currently controlled by the PodSet in the status.PodNames field.

Let's begin!

Thank you for taking a closer look at the Go Operator. For more Information, check out the links below:

Git Hub

YouTube

Samples

Chat

Operator SDK with Go

Step 1 of 7

Creating a New Project

Let's begin by creating a new project called myproject:

oc new-project myproject


Let's now create a new directory in our $GOPATH/src/ directory:

mkdir -p $GOPATH/src/github.com/redhat/


Navigate to the directory:

cd $GOPATH/src/github.com/redhat/


Create a new Go-based Operator SDK project for the PodSet:

operator-sdk new podset-operator --type=go --skip-git-init


Navigate to the project root:

cd podset-operator


Operator scope

A namespace-scoped operator (the default) watches and manages resources in a single namespace, whereas a cluster-scoped operator watches and manages resources cluster-wide. Namespace-scoped operators are preferred because of their flexibility. They enable decoupled upgrades, namespace isolation for failures and monitoring, and differing API definitions. However, there are use cases where a cluster-scoped operator may make sense. For example, the cert-manager operator is often deployed with cluster-scoped permissions and watches so that it can manage issuing certificates for an entire cluster.

If you'd like to create your memcached-operator project to be cluster-scoped use the following operator-sdk new command instead:

# operator-sdk new podset-operator --cluster-scoped

Project Scaffolding Layout

The operator-sdk CLI generates a number of packages for each project. The following table describes a basic rundown of each generated file/directory.

File/Folders Purpose
cmd Contains manager/main.go which is the main program of the operator. This instantiates a new manager which registers all custom resource definitions under pkg/apis/... and starts all controllers under pkg/controllers/... .
pkg/apis Contains the directory tree that defines the APIs of the Custom Resource Definitions(CRD). Users are expected to edit the pkg/apis/<group>/<version>/<kind>_types.go files to define the API for each resource type and import these packages in their controllers to watch for these resource types.
pkg/controller This pkg contains the controller implementations. Users are expected to edit the pkg/controller/<kind>/<kind>_controller.go to define the controller's reconcile logic for handling a resource type of the specified kind.
build Contains the Dockerfile and build scripts used to build the operator.
deploy Contains various YAML manifests for registering CRDs, setting up RBAC, and deploying the operator as a Deployment.
Gopkg.toml Gopkg.lock The Go Dep manifests that describe the external dependencies of this operator.
vendor The golang vendor folder that contains the local copies of the external dependencies that satisfy the imports of this project. Go Dep manages the vendor directly.