Welcome!

Operator SDK with Go

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 is for a new Go-based Operator with the Operator SDK:

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.

Adding a New Custom API

Add a new Custom Resource Definition(CRD) API called PodSet, with APIVersion app.example.com/v1alpha1 and Kind PodSet:

Running the Operator Locally (Inside the Cluster)

Now we can test our logic by running our Operator outside the cluster via our kubeconfig credentials. Once running, the command will block the current session. You can continue interacting with the OpenShift cluster by opening a new terminal window.

Help

Katacoda offerings an Interactive Learning Environment for Developers. This course uses a command line and a pre-configured sandboxed environment for you to use. Below are useful commands when working with the environment.

cd <directory>

Change directory

ls

List directory

echo 'contents' > <file>

Write contents to a file

cat <file>

Output contents of file

Vim

In the case of certain exercises you will be required to edit files or text. The best approach is with Vim. Vim has two different modes, one for entering commands (Command Mode) and the other for entering text (Insert Mode). You need to switch between these two modes based on what you want to do. The basic commands are: