🚀 WebApp Operator

WebApp Operator is a simple Kubernetes operator built with Go and Kubebuilder. It introduces a custom resource named WebApp that lets a user declare an application image, replica count, and port, while the operator automatically creates and manages the corresponding Kubernetes Deployment and Service.

Instead of manually creating multiple Kubernetes resources, the user only defines a single WebApp object. The operator watches that object, creates the required resources, keeps them in sync, updates status, and cleans everything up when the WebApp is deleted.

---

✨ What This Project Does

A user creates a custom resource like this:

apiVersion: apps.example.com/v1alpha1
kind: WebApp
metadata:
  name: my-nginx-app
spec:
  image: nginx:latest
  replicas: 3
  port: 80
status:
  phase: Running
  readyReplicas: 3

The operator will:

• 👀 Watch the WebApp resource
• 📦 Create a Deployment with the requested image and replicas
• 🌐 Create a Service exposing the requested port
• 🔄 Reconcile changes continuously
• 📊 Update status.phase and status.readyReplicas
• 🧹 Clean up owned resources when the WebApp is deleted

If the user changes:

replicas: 3

to:

replicas: 5

the operator automatically updates the Deployment so the application scales to 5 pods.

---

🧠 Why This Project Matters

This project demonstrates the Kubernetes Operator pattern, where a custom resource and a controller work together to automate application lifecycle management. Kubernetes operators commonly use CRDs plus reconciliation loops to turn high-level user intent into actual cluster state.

This operator has the following:

• one custom resource
• one controller
• one managed Deployment
• one managed Service
• status updates
• cleanup behavior through owner references and reconciliation

---

🧰 Tech Stack

• Go
• Kubernetes
• Kubebuilder
• controller-runtime
• CRDs
• Deployments
• Services
• Docker
• Kustomize
• Makefile

---

🏗️ High-Level Flow

flowchart LR
  User["User applies WebApp YAML"] --> API["Kubernetes API Server"]
  API --> Operator["WebApp Operator"]
  Operator --> Deployment["Deployment"]
  Operator --> Service["Service"]
  Operator --> Status["WebApp Status"]

Loading

Flow summary

1. User applies a WebApp custom resource.
2. Kubernetes stores it through the CRD.
3. The operator watches the new object.
4. The operator creates or updates the matching Deployment.
5. The operator creates or updates the matching Service.
6. The operator updates status.phase and status.readyReplicas.

---

📁 Project Structure

.
├── api/                     API definitions for the WebApp CRD
├── cmd/                     Operator entrypoint
├── config/                  CRD, RBAC, manager, and sample manifests
├── internal/controller/     Reconciliation logic
├── hack/                    Boilerplate headers
├── bin/                     Generated binaries/tools
├── Dockerfile               Container image build
├── Makefile                 Common development commands
├── PROJECT                  Kubebuilder project metadata
├── go.mod                   Go module definition
└── README.md                Project documentation

---

🧩 Custom Resource

The custom resource is WebApp.

Spec fields

These fields are declared by the user:

• image: container image to run
• replicas: number of pod replicas
• port: container port to expose

Status fields

These fields are written by the operator:

• phase: high-level state such as Pending, Running, or Degraded
• readyReplicas: number of ready pods
• conditions: standard Kubernetes conditions array

---

📄 Example WebApp

apiVersion: apps.example.com/v1alpha1
kind: WebApp
metadata:
  name: my-nginx-app
spec:
  image: nginx:latest
  replicas: 3
  port: 80

Apply it with:

kubectl apply -f config/samples/apps_v1alpha1_webapp.yaml

---

⚙️ What The Operator Creates

For each WebApp, the operator creates:

• a Deployment
• a Service

For example, for:

metadata:
  name: my-nginx-app

the operator may create:

• Deployment/my-nginx-app
• Service/my-nginx-app

These resources are continuously reconciled. If someone changes them manually, the operator will move them back toward the desired state defined in the WebApp resource.

---

🔁 Reconciliation Logic

The controller follows the standard reconciliation model used by Kubernetes operators [web:208][web:207]:

1. Fetch the WebApp resource
2. Check whether the target Deployment exists
3. Create or update the Deployment
4. Check whether the target Service exists
5. Create or update the Service
6. Read current pod readiness
7. Update WebApp.status
8. Requeue on future changes automatically through watches

This design keeps the system idempotent: running reconciliation multiple times should still lead to the same desired state.

---

🧹 Cleanup Behavior

The operator should set owner references from the Deployment and Service back to the WebApp. That way, when the WebApp is deleted, Kubernetes garbage collection can clean up the owned resources automatically, which is a common controller pattern.

---

🛠️ Setup Prerequisites

Install these tools first:

brew install go kubectl kustomize kind

Install Kubebuilder if needed:

brew install kubebuilder

Optional but useful:

go install sigs.k8s.io/controller-tools/cmd/controller-gen@latest

Check your cluster access:

kubectl cluster-info
kubectl get nodes

---

🧪 Local Development Setup

1. Clone the project

git clone https://github.com/<your-username>/webapp-operator.git
cd webapp-operator

2. Download dependencies

go mod tidy
go mod download

3. Create a local Kubernetes cluster

kind create cluster --name webapp-operator

Verify access:

kubectl cluster-info
kubectl get nodes

---

🧱 Generate Code And Manifests

Generate deepcopy code and CRD-related artifacts:

make generate
make manifests

These commands use controller-gen, which is the standard way Kubebuilder projects generate API and manifest artifacts [web:179][web:168].

---

✅ Run Local Checks

Format and validate the code:

make fmt
make vet

Run tests:

make test

---

▶️ Run The Operator Locally

Install the CRD into the current cluster:

make install

Run the controller locally against your current kubeconfig:

make run

This starts the operator process on your machine, but it will manage resources inside the Kubernetes cluster pointed to by your kubeconfig.

---

🚢 Deploy The Operator Into Kubernetes

Build the operator image:

make docker-build IMG=webapp-operator:latest

Load the image into kind:

kind load docker-image webapp-operator:latest --name webapp-operator

Deploy the operator:

make deploy IMG=webapp-operator:latest

Check the operator pod:

kubectl get pods -n webapp-operator-system

---

📦 Apply A Sample WebApp

Create the sample resource:

kubectl apply -f config/samples/apps_v1alpha1_webapp.yaml

Check the custom resource:

kubectl get webapps
kubectl get webapp my-nginx-app -o yaml

Check the resources created by the operator:

kubectl get deploy
kubectl get svc
kubectl get pods

Describe the custom resource:

kubectl describe webapp my-nginx-app

---

🔄 Update The App

Edit the resource:

kubectl edit webapp my-nginx-app

Change:

replicas: 3

to:

replicas: 5

Then verify scaling:

kubectl get deploy
kubectl get pods
kubectl get webapp my-nginx-app -o yaml

The operator should reconcile the change and update the deployment replica count automatically.

---

🧼 Delete The App

Delete the custom resource:

kubectl delete webapp my-nginx-app

Then verify cleanup:

kubectl get webapps
kubectl get deploy
kubectl get svc

If owner references are configured correctly, the related Deployment and Service should also be removed.

---

📋 Common Commands

Create cluster

kind create cluster --name webapp-operator

Delete cluster

kind delete cluster --name webapp-operator

Generate code

make generate

Generate manifests

make manifests

Format code

make fmt

Vet code

make vet

Run tests

make test

Install CRD

make install

Run locally

make run

Deploy operator

make deploy IMG=webapp-operator:latest

Undeploy operator

make undeploy

---

🔍 Useful Debug Commands

Check operator logs:

kubectl logs -n webapp-operator-system deploy/webapp-operator-controller-manager

Check CRD:

kubectl get crd
kubectl get crd webapps.apps.example.com

Check all related resources:

kubectl get webapps,deploy,svc,pods

Inspect a resource:

kubectl get webapp my-nginx-app -o yaml
kubectl get deploy my-nginx-app -o yaml
kubectl get svc my-nginx-app -o yaml

---

🌱 Future Improvements

• Add finalizers for explicit cleanup control
• Add validation for image and port fields
• Add support for environment variables and resource requests
• Add Ingress generation
• Add status conditions for rollout progress
• Add unit and e2e tests
• Add Helm packaging for operator installation
• Add Prometheus metrics for reconciliation behavior

---

📚 Key Learning Outcomes

This project is useful for understanding:

• Kubernetes CRDs
• Kubernetes operators
• reconciliation loops
• controller-runtime
• status subresources
• Deployments and Services
• owner references
• declarative infrastructure patterns

---

🙌 Summary

A realistic Kubernetes operator project. It shows how to extend the Kubernetes API with a custom resource and automate application lifecycle management through a controller, which is the core idea behind the operator pattern.