Building Production-Grade
Kubernetes Operators
with Java

The Problem

What are Kubernetes Operators?

Declarative — the user requests what, the operator figures out how

Operator vs. Controller

Every Operator is a Controller, but not every Controller is an Operator.

Fabric8 Client powers both — JOSDK adds the operator boilerplate: reconciliation loop, retries, event handling, dependent resources.

Real-World Example

apiVersion: example.io/v1
kind: MicroService
metadata:
  name: petclinic
spec:
  image: spring-petclinic:3.5.6
  replicas: 2
  database: { databaseName: petclinicdb }
  exposed: true

The Java Stack

Fabric8 Kubernetes Client

The industry-standard Java client for Kubernetes & OpenShift

Fabric8 in Action

Fluent DSL for CRUD, watching, and custom resources

// List pods by label
client.pods().inNamespace("production")
    .withLabel("app", "petclinic").list();

// Create a resource
client.resource(deployment).create();

// Watch for real-time events
client.pods().watch(new Watcher<Pod>() {
    public void eventReceived(Action action, Pod pod) {
        log.info("{}: {}", action, pod.getMetadata().getName());
    }
});

// Type-safe Custom Resources
client.resources(MicroService.class)
    .inNamespace("production").withName("petclinic").get();

From Client to Framework

Fabric8 is the client. Building a production operator needs more:

→ Java Operator SDK (JOSDK)

JOSDK — Key Concepts

CNCF Project 929 stars Quarkus + Spring Boot

Custom Resource Definition

Define your CRD as a Java class — Fabric8 K8s Client CRD Generator generates the YAML schema automatically

@Group("example.io") @Version("v1") @ShortNames("ms")
public class MicroService extends
    CustomResource<MicroServiceSpec, MicroServiceStatus>
    implements Namespaced { }

public class MicroServiceSpec {
    private String image;
    private int replicas;
    private DatabaseSpec database;
    private boolean exposed;
    private String hostname;
}

Custom Resource — What Users Write

apiVersion: example.io/v1
kind: MicroService
metadata:
  name: petclinic
spec:
  image: spring-petclinic:3.5.6
  replicas: 2
  exposed: true

spec:
  image: spring-petclinic:4.0.3
  replicas: 2
  database: { databaseName: petclinicdb }
  autoscaling:
    minReplicas: 2
    maxReplicas: 8
  exposed: true
  hostname: petclinic.example.com

One simple resource — the operator creates Deployments, Services, ConfigMaps, database, HPA, Ingress automatically.

Full Custom Resource — Production Example

Operator-managed database, autoscaling, ingress — all from one CR

apiVersion: example.io/v1
kind: MicroService
metadata:
  name: petclinic-prod
  namespace: production
spec:
  image: quay.io/ash-thakur/spring-petclinic:4.0.3-arm64
  replicas: 2
  containerPort: 8080
  database:                              # Operator provisions PostgreSQL
    databaseName: petclinicdb
    username: petclinic
    storageSize: 5Gi
  autoscaling: { minReplicas: 2, maxReplicas: 8, targetCPUUtilizationPercentage: 20 }
  exposed: true
  hostname: petclinic.apps.mycluster.example.com

Auto-generates DB credentials Secret, StatefulSet, headless Service — no manual kubectl create secret.

Implementing the Reconciler

@Workflow declares the dependency graph — reconcile() just reads status

@Workflow(dependents = {
    @Dependent(type = ConfigMapDependentResource.class),
    @Dependent(type = DeploymentDependentResource.class,
               dependsOn = "ConfigMap"),
    @Dependent(type = ServiceDependentResource.class,
               dependsOn = "Deployment"),
    @Dependent(type = IngressDependentResource.class,
               reconcilePrecondition = ExposedCondition.class)
})
@ControllerConfiguration
public class MicroServiceReconciler
    implements Reconciler<MicroService> {

    public UpdateControl<MicroService> reconcile(
            MicroService ms, Context<MicroService> ctx) {
        int ready = ctx.getSecondaryResource(Deployment.class)
            .map(d -> d.getStatus().getReadyReplicas())
            .orElse(0);
        return UpdateControl.patchStatus(
            buildStatusPatch(ms, ready));
    }
}

Dependent Resources

Define desired state — the framework diffs against reality and reconciles

public class DeploymentDependentResource
    extends CRUDKubernetesDependentResource
             <Deployment, MicroService> {

    protected Deployment desired(MicroService ms,
                        Context<MicroService> ctx) {
        return new DeploymentBuilder()
            .withNewMetadata()
                .withName(ms.getMetadata().getName())
                .withNamespace(ms.getMetadata().getNamespace())
            .endMetadata()
            .withNewSpec()
                .withReplicas(ms.getSpec().getReplicas())
                .withNewSelector()
                  .withMatchLabels(Map.of("app",
                    ms.getMetadata().getName()))
                .endSelector()
                // ... template, container, probes ...
            .endSpec().build();
    }
}

Patterns and Best Practices

Error Handling

Write errors to status subresource — cleanup uses owner references for automatic GC

@Override
public ErrorStatusUpdateControl<MicroService> updateErrorStatus(
        MicroService ms, Context<MicroService> ctx, Exception e) {
    log.error("Error reconciling {}/{}: {}",
        ms.getMetadata().getNamespace(),
        ms.getMetadata().getName(), e.getMessage());
    MicroService patch = buildStatusPatch(ms, Phase.ERROR, 0);
    patch.getStatus()
         .setMessage("Reconciliation error: " + e.getMessage());
    return ErrorStatusUpdateControl.patchStatus(patch);
}

@Override
public DeleteControl cleanup(MicroService ms,
                              Context<MicroService> ctx) {
    // Owner references handle garbage collection automatically
    return DeleteControl.defaultDelete();
}

Who’s Using It in Production?