Kubebuilder Custom Operators Guide

apiVersion: database.example.com/v1
kind: PostgresCluster
metadata:
  name: orders-db
spec:
  version: "16"
  replicas: 3
  storage: 100Gi
  backup:
    schedule: "0 2 * * *"
    retention: 7d

# Install Kubebuilder
curl -L -o kubebuilder https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)
chmod +x kubebuilder && mv kubebuilder /usr/local/bin/

# Initialize project
mkdir my-operator && cd my-operator
kubebuilder init --domain example.com --repo github.com/myorg/my-operator

# Create an API (CRD + Controller)
kubebuilder create api --group webapp --version v1 --kind Application

// api/v1/application_types.go
type ApplicationSpec struct {
    // Image is the container image to deploy
    Image string `json:"image"`
    
    // Replicas is the desired number of pods
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=100
    Replicas int32 `json:"replicas"`
    
    // Port is the container port
    Port int32 `json:"port"`
}

type ApplicationStatus struct {
    // ReadyReplicas is the number of ready pods
    ReadyReplicas int32 `json:"readyReplicas"`
    
    // Conditions represent the latest observations
    Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Replicas",type=integer,JSONPath=`.spec.replicas`
// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`
type Application struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec              ApplicationSpec   `json:"spec,omitempty"`
    Status            ApplicationStatus `json:"status,omitempty"`
}

// internal/controller/application_controller.go
func (r *ApplicationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    log := log.FromContext(ctx)
    
    // Fetch the Application resource
    var app webappv1.Application
    if err := r.Get(ctx, req.NamespacedName, &app); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }
    
    // Create or update the Deployment
    deploy := &appsv1.Deployment{
        ObjectMeta: metav1.ObjectMeta{
            Name:      app.Name,
            Namespace: app.Namespace,
        },
    }
    
    _, err := ctrl.CreateOrUpdate(ctx, r.Client, deploy, func() error {
        deploy.Spec.Replicas = &app.Spec.Replicas
        deploy.Spec.Template.Spec.Containers = []corev1.Container{
            {
                Name:  "app",
                Image: app.Spec.Image,
                Ports: []corev1.ContainerPort{
                    {ContainerPort: app.Spec.Port},
                },
            },
        }
        return ctrl.SetControllerReference(&app, deploy, r.Scheme)
    })
    if err != nil {
        return ctrl.Result{}, err
    }
    
    // Update status
    app.Status.ReadyReplicas = deploy.Status.ReadyReplicas
    if err := r.Status().Update(ctx, &app); err != nil {
        return ctrl.Result{}, err
    }
    
    return ctrl.Result{}, nil
}

# Generate CRD manifests
make manifests

# Install CRDs in cluster
make install

# Build and push the operator image
make docker-build docker-push IMG=ghcr.io/myorg/my-operator:v0.1.0

# Deploy the operator
make deploy IMG=ghcr.io/myorg/my-operator:v0.1.0

apiVersion: webapp.example.com/v1
kind: Application
metadata:
  name: order-api
spec:
  image: ghcr.io/myorg/order-api:v2.1.0
  replicas: 3
  port: 8080

kubectl apply -f application.yaml
kubectl get applications
# NAME        REPLICAS   READY
# order-api   3          3