Introduction to Kubernetes Operators and Building a Simple Nginx Operator

k8s Operator Introduction

Kubernetes Operators are custom controllers that extend the Kubernetes API to manage complex applications by encapsulating domain‑specific knowledge, enabling automated lifecycle tasks such as deployment, scaling, upgrades, backups, and recovery. Common examples include etcd‑operator and prometheus‑operator.

How an Operator Works

An Operator uses Custom Resources (CR) and Custom Resource Definitions (CRD) to represent application state. When deployed, it watches the API server for events on its CR type and reconciles the actual cluster state to match the desired state defined in the CR.

Tools for Building Operators

The Operator SDK (by CoreOS) is a popular tool for quickly scaffolding operators. Alternatives include KUDO, Kubebuilder, and Metacontroller.

Creating a Simple Nginx Operator

Development environment :

docker 20.10.5
operator-sdk 1.9.0
golang 1.16.3
kubernetes 1.19
macOS 11.4

1. Initialize the project

mkdir -p $HOME/nginx-operator && cd $HOME/nginx-operator
operator-sdk init --domain example.com --repo github.com/example/nginx-operator

2. Create a CRD

operator-sdk create api --group proxy --version v1alpha1 --kind Nginx --resource --controller

This generates api/v1alpha1/nginx_types.go and controllers/nginx_controller.go , which you will edit to define the spec and controller logic.

3. Define the Nginx spec and status

// NginxSpec defines the desired state of Nginx
type NginxSpec struct {
    Count int32 `json:"count"`
}

// NginxStatus defines the observed state of Nginx
type NginxStatus struct {
    // Nodes are the names of the nginx pods
    Nodes []string `json:"nodes"`
}

Run make generate after each change, then make manifests to produce the CRD YAML file.

4. Implement controller logic

In controllers/nginx_controller.go , set up the manager to watch Nginx resources and owned Deployments:

func (r *NginxReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&proxyv1alpha1.Nginx{}).
        Owns(&appsv1.Deployment{}).
        Complete(r)
}

The Reconcile method will contain the logic to ensure the actual pods match the desired Count .

5. Deploy the Operator

Update the Makefile image variable, then build and push the image:

-IMG ?= controller:latest
+IMG ?= $(IMAGE_TAG_BASE):$(VERSION)

make docker-build
make deploy

Verify the deployment:

$ kubectl get deployment -n nginx-operator-system
NAME                                READY   UP-TO-DATE   AVAILABLE   AGE
nginx-operator-controller-manager   1/1     1            1           5m14s

Create an Nginx CR:

apiVersion: proxy.example.com/v1alpha1
kind: Nginx
metadata:
  name: nginx-sample
spec:
  count: 3

$ kubectl apply -f config/samples/proxy_v1alpha1_nginx.yaml

Check the pods and CR status:

$ kubectl get pods
NAME                            READY   STATUS    RESTARTS   AGE
nginx-sample-66b6c48dd5-bcqc8   1/1     Running   0          15m
nginx-sample-66b6c48dd5-thnx6   1/1     Running   0          15m
nginx-sample-66b6c48dd5-xrd9l   1/1     Running   0          15m

$ kubectl get nginx/nginx-sample -o yaml
apiVersion: proxy.example.com/v1alpha1
kind: Nginx
metadata:
  name: nginx-sample
  namespace: default
spec:
  count: 3
status:
  nodes:
  - nginx-sample-66b6c48dd5-bcqc8
  - nginx-sample-66b6c48dd5-thnx6
  - nginx-sample-66b6c48dd5-xrd9l

To clean up, delete the CR and undeploy the operator:

$ kubectl delete -f config/samples/proxy_v1alpha1_nginx.yaml
make undeploy