Extending Kubernetes: A Java Developer’s Guide to Custom Resource Definitions (CRDs)

Table of Contents

Article

Kubernetes is renowned for its built-in resources like Pods, Deployments, and Services. But what if your Java application needs to manage something more specific, like a "MySQLCluster," "KafkaTopic," or an "ApplicationConfiguration"? This is where Custom Resource Definitions (CRDs) come in, allowing you to extend the Kubernetes API itself.

For Java developers, CRDs represent a powerful paradigm shift, enabling you to build Kubernetes-native applications and leverage the platform's control loop for your own custom logic.

What is a Custom Resource Definition (CRD)?

In simple terms, a CRD is a schema that defines a new, custom resource type for your Kubernetes cluster. Once defined, you can create and manage instances of this resource using kubectl, just like any native resource.

Custom Resource Definition (CRD): The type or class. It's the blueprint that defines the spec and status fields for your resource (e.g., the CronTab type).
Custom Resource (CR): An instance of that type (e.g., a specific my-weekly-backup CronTab object).

The Java Angle: The Operator Pattern

Defining the CRD is only half the story. The real power for a Java developer comes from the Operator Pattern.

An Operator is a custom controller—a piece of software running in your cluster—that watches for events on your Custom Resources (e.g., CREATE, UPDATE, DELETE) and takes action to reconcile the actual state of the world with the desired state defined in the CR.

In essence: You write a Java application whose sole job is to manage your custom resources.

A Practical Example: The "Javapp" Resource

Let's imagine we want to define a simple CRD for a Java application that automatically manages a Deployment and a Service.

Step 1: Define the CRD (YAML)

This YAML defines the schema for our new Javapp resource. We apply this to the Kubernetes cluster to teach the API about our new type.

# javapp-crd.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: javapps.example.com
spec:
group: example.com
scope: Namespaced
names:
plural: javapps
singular: javapp
kind: Javapp
shortNames:
- japp # Just like 'po' for Pods!
versions:
- name: v1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
appName:
type: string
image:
type: string
replicas:
type: integer
servicePort:
type: integer
status:
type: object
properties:
url:
type: string
availableReplicas:
type: integer

After running kubectl apply -f javapp-crd.yaml, you can now create Javapp objects.

Step 2: Create a Custom Resource (YAML)

This is an instance of our Javapp type. It's the "desired state" for our application.

# my-springboot-app.yaml
apiVersion: example.com/v1
kind: Javapp
metadata:
name: my-springboot-app
spec:
appName: my-springboot-app
image: my-registry/springboot-app:1.0.0
replicas: 3
servicePort: 8080

We create it with kubectl apply -f my-springboot-app.yaml.

Step 3: Write the Java Controller (The Operator)

This is where the Java magic happens. We use a Kubernetes Java client library to watch for Javapp events.

Frameworks to Use:
The two most popular frameworks for building Java-based Operators are:

Fabric8 Kubernetes Client: A robust, general-purpose client.
java-operator-sdk (JOSDK): A higher-level framework specifically designed for building operators, handling much of the boilerplate.

Here's a simplified conceptual code snippet using a pseudo-framework:

@Component
public class JavappController {
@Override
public UpdateControl<Javapp> reconcile(Javapp javapp) {
String appName = javapp.getSpec().getAppName();
String image = javapp.getSpec().getImage();
int replicas = javapp.getSpec().getReplicas();
int port = javapp.getSpec().getServicePort();
// 1. Check if the Deployment already exists
Deployment existingDeployment = client.apps().deployments()
.inNamespace(javapp.getMetadata().getNamespace())
.withName(appName).get();
if (existingDeployment == null) {
// 2. If not, create it based on the Javapp's spec
Deployment deployment = createDeployment(appName, image, replicas);
client.apps().deployments().create(deployment);
}
// 3. Do the same for the Service
Service existingService = client.services()
.inNamespace(javapp.getMetadata().getNamespace())
.withName(appName).get();
if (existingService == null) {
Service service = createService(appName, port);
client.services().create(service);
}
// 4. Update the Javapp's status
String serviceUrl = appName + "." + namespace + ".svc.cluster.local:" + port;
javapp.getStatus().setUrl(serviceUrl);
// ... also set availableReplicas from the actual Deployment status
// 5. Tell the framework to update the status of the CR
return UpdateControl.updateStatus(javapp);
}
private Deployment createDeployment(String name, String image, int replicas) {
// ... use the Fabric8 builder DSL to create a Deployment YAML
return new DeploymentBuilder()
.withNewMetadata().withName(name).endMetadata()
.withNewSpec()
.withReplicas(replicas)
.withNewTemplate()
// ... specify Pod template, container, image, etc.
.endTemplate()
.endSpec()
.build();
}
// ... createService method similarly
}

Benefits for Java Developers

Domain-Driven Design (DDD): You can model your application domain directly within Kubernetes. A KafkaTopic CR is much more intuitive than a complex ConfigMap and StatefulSet combination.
Abstraction and Simplification: You can hide complex Kubernetes resource graphs behind a simple, application-specific CR.
Automation: Encapsulate operational knowledge ("if the replicas are increased, also update the thread pool") directly in your Java code.
Leverage Kubernetes Primitives: Your operator benefits from all of Kubernetes's features: events, monitoring, RBAC, and the robust etcd-backed state store.

Conclusion

Custom Resource Definitions, combined with the Operator Pattern, empower Java developers to build truly cloud-native applications that are deeply integrated with the Kubernetes control plane. Instead of writing scripts or complex CI/CD pipelines to manage infrastructure, you write a Java application—an Operator—that acts as an automated Site Reliability Engineer for your own domain-specific logic.

By embracing CRDs, you move from merely deploying on Kubernetes to actively extending and integrating with Kubernetes, unlocking a new level of automation and control for your Java systems.

Pyroscope Profiling in Java
Explains how to use Pyroscope for continuous profiling in Java applications, helping developers analyze CPU and memory usage patterns to improve performance and identify bottlenecks.
https://macronepal.com/blog/pyroscope-profiling-in-java/

OpenTelemetry Metrics in Java: Comprehensive Guide
Provides a complete guide to collecting and exporting metrics in Java using OpenTelemetry, including counters, histograms, gauges, and integration with monitoring tools. (MACRO NEPAL)
https://macronepal.com/blog/opentelemetry-metrics-in-java-comprehensive-guide/

OTLP Exporter in Java: Complete Guide for OpenTelemetry
Explains how to configure OTLP exporters in Java to send telemetry data such as traces, metrics, and logs to monitoring systems using HTTP or gRPC protocols. (MACRO NEPAL)
https://macronepal.com/blog/otlp-exporter-in-java-complete-guide-for-opentelemetry/

Thanos Integration in Java: Global View of Metrics
Explains how to integrate Thanos with Java monitoring systems to create a scalable global metrics view across multiple Prometheus instances.

https://macronepal.com/blog/thanos-integration-in-java-global-view-of-metrics

Time Series with InfluxDB in Java: Complete Guide (Version 2)
Explains how to manage time-series data using InfluxDB in Java applications, including storing, querying, and analyzing metrics data.

https://macronepal.com/blog/time-series-with-influxdb-in-java-complete-guide-2

Time Series with InfluxDB in Java: Complete Guide
Provides an overview of integrating InfluxDB with Java for time-series data handling, including monitoring applications and managing performance metrics.

https://macronepal.com/blog/time-series-with-influxdb-in-java-complete-guide

Implementing Prometheus Remote Write in Java (Version 2)
Explains how to configure Java applications to send metrics data to Prometheus-compatible systems using the remote write feature for scalable monitoring.

https://macronepal.com/blog/implementing-prometheus-remote-write-in-java-a-complete-guide-2

Implementing Prometheus Remote Write in Java: Complete Guide
Provides instructions for sending metrics from Java services to Prometheus servers, enabling centralized monitoring and real-time analytics.

https://macronepal.com/blog/implementing-prometheus-remote-write-in-java-a-complete-guide

Building a TileServer GL in Java: Vector and Raster Tile Server
Explains how to build a TileServer GL in Java for serving vector and raster map tiles, useful for geographic visualization and mapping applications.

https://macronepal.com/blog/building-a-tileserver-gl-in-java-vector-and-raster-tile-server

Indoor Mapping in Java
Explains how to create indoor mapping systems in Java, including navigation inside buildings, spatial data handling, and visualization techniques.