wip

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>

Author: csviri

docs/content/en/docs/documentation/operations/health-probes.md

@@ -0,0 +1,104 @@
+---
+title: Health Probes
+weight: 75
+---
+
+Operators running in Kubernetes should expose health probe endpoints so that the kubelet can detect startup
+failures and runtime degradation. JOSDK provides the building blocks through its
+[`RuntimeInfo`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/RuntimeInfo.java)
+API.
+
+## RuntimeInfo
+
+`RuntimeInfo` is available via `operator.getRuntimeInfo()` and exposes:
+
+| Method | Purpose |
+|---|---|
+| `isStarted()` | `true` once the operator and all its controllers have fully started |
+| `allEventSourcesAreHealthy()` | `true` when every registered event source (informers, polling sources, etc.) reports a healthy status |
+| `unhealthyEventSources()` | returns a map of controller name → unhealthy event sources, useful for diagnostics |
+
+These map naturally to Kubernetes probes:
+
+- **Startup probe** → `isStarted()` — fails until all informers have synced and the operator is ready to
+  reconcile.
+- **Readiness probe** → `allEventSourcesAreHealthy()` — fails if an informer loses its watch connection
+  or any event source reports an unhealthy status.
+
+## Setting Up Probe Endpoints
+
+The example below uses [Jetty](https://eclipse.dev/jetty/) to expose health probe endpoints. Any HTTP
+server library works — the key is calling the `RuntimeInfo` methods to determine the response code.
+
+```java
+import org.eclipse.jetty.server.Server;
+import org.eclipse.jetty.server.handler.ContextHandler;
+import org.eclipse.jetty.server.handler.ContextHandlerCollection;
+
+Operator operator = new Operator();
+operator.register(new MyReconciler());
+operator.start();
+
+var startup = new ContextHandler(new StartupHandler(operator), "/startup");
+var readiness = new ContextHandler(new ReadinessHandler(operator), "/ready");
+Server server = new Server(8080);
+server.setHandler(new ContextHandlerCollection(startup, readiness));
+server.start();
+```
+
+Where `StartupHandler` and `ReadinessHandler` extend `org.eclipse.jetty.server.Handler.Abstract` and
+check `operator.getRuntimeInfo().isStarted()` and
+`operator.getRuntimeInfo().allEventSourcesAreHealthy()` respectively.
+
+See the
+[`operations` sample operator](https://github.com/java-operator-sdk/java-operator-sdk/tree/main/sample-operators/operations)
+for a complete working example.
+
+## Kubernetes Deployment Configuration
+
+Once your operator exposes probe endpoints, configure them in your Deployment manifest:
+
+```yaml
+containers:
+- name: operator
+  ports:
+  - name: probes
+    containerPort: 8080
+  startupProbe:
+    httpGet:
+      path: /startup
+      port: probes
+    initialDelaySeconds: 1
+    periodSeconds: 3
+    failureThreshold: 20
+  readinessProbe:
+    httpGet:
+      path: /ready
+      port: probes
+    initialDelaySeconds: 5
+    periodSeconds: 5
+    failureThreshold: 3
+```
+
+The startup probe gives the operator time to start (up to ~60 s with the settings above). Once the startup
+probe succeeds, the readiness probe takes over and will mark the pod as not-ready if any event source
+becomes unhealthy.
+
+## Helm Chart Support
+
+The [generic Helm chart](/docs/documentation/operations/helm-chart) supports health probes out of the box.
+Enable them in your `values.yaml`:
+
+```yaml
+probes:
+  port: 8080
+  startup:
+    enabled: true
+    path: /startup
+  readiness:
+    enabled: true
+    path: /ready
+```
+
+All probe timing parameters (`initialDelaySeconds`, `periodSeconds`, `failureThreshold`) have sensible
+defaults and can be overridden.

helm/generic-helm-chart/templates/deployment.yaml

@@ -54,6 +54,30 @@ spec:
           {{- toYaml .Values.securityContext | nindent 12 }}
         image: "{{ required "A valid .Values.image.repository is required" .Values.image.repository }}:{{ include "generic-operator.imageTag" . }}"
         imagePullPolicy: {{ .Values.image.pullPolicy }}
+        {{- if or .Values.probes.startup.enabled .Values.probes.readiness.enabled }}
+        ports:
+        - name: probes
+          containerPort: {{ .Values.probes.port }}
+          protocol: TCP
+        {{- end }}
+        {{- if .Values.probes.startup.enabled }}
+        startupProbe:
+          httpGet:
+            path: {{ .Values.probes.startup.path }}
+            port: probes
+          initialDelaySeconds: {{ .Values.probes.startup.initialDelaySeconds }}
+          periodSeconds: {{ .Values.probes.startup.periodSeconds }}
+          failureThreshold: {{ .Values.probes.startup.failureThreshold }}
+        {{- end }}
+        {{- if .Values.probes.readiness.enabled }}
+        readinessProbe:
+          httpGet:
+            path: {{ .Values.probes.readiness.path }}
+            port: probes
+          initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds }}
+          periodSeconds: {{ .Values.probes.readiness.periodSeconds }}
+          failureThreshold: {{ .Values.probes.readiness.failureThreshold }}
+        {{- end }}
         env:
         - name: OPERATOR_NAMESPACE
           valueFrom:

helm/generic-helm-chart/tests/deployment_test.yaml

@@ -288,3 +288,57 @@ tests:
       - equal:
           path: spec.template.spec.serviceAccountName
           value: my-operator
+
+  - it: should not include probes by default
+    asserts:
+      - isNull:
+          path: spec.template.spec.containers[0].startupProbe
+      - isNull:
+          path: spec.template.spec.containers[0].readinessProbe
+
+  - it: should add startup probe when enabled
+    documentSelector:
+      path: kind
+      value: Deployment
+    set:
+      probes.startup.enabled: true
+    asserts:
+      - equal:
+          path: spec.template.spec.containers[0].startupProbe.httpGet.path
+          value: /startup
+      - equal:
+          path: spec.template.spec.containers[0].startupProbe.httpGet.port
+          value: probes
+      - contains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: probes
+            containerPort: 8080
+            protocol: TCP
+
+  - it: should add readiness probe when enabled
+    documentSelector:
+      path: kind
+      value: Deployment
+    set:
+      probes.readiness.enabled: true
+    asserts:
+      - equal:
+          path: spec.template.spec.containers[0].readinessProbe.httpGet.path
+          value: /ready
+      - equal:
+          path: spec.template.spec.containers[0].readinessProbe.httpGet.port
+          value: probes
+
+  - it: should add both probes when both enabled
+    documentSelector:
+      path: kind
+      value: Deployment
+    set:
+      probes.startup.enabled: true
+      probes.readiness.enabled: true
+    asserts:
+      - isNotNull:
+          path: spec.template.spec.containers[0].startupProbe
+      - isNotNull:
+          path: spec.template.spec.containers[0].readinessProbe

helm/generic-helm-chart/values.yaml

@@ -128,3 +128,19 @@ extraVolumeMounts: []
 # RBAC configuration
 rbac:
   create: true
+
+# Health probes configuration
+probes:
+  port: 8080
+  startup:
+    enabled: false
+    path: /startup
+    initialDelaySeconds: 1
+    periodSeconds: 3
+    failureThreshold: 20
+  readiness:
+    enabled: false
+    path: /ready
+    initialDelaySeconds: 5
+    periodSeconds: 5
+    failureThreshold: 3

sample-operators/operations/pom.xml

@@ -82,6 +82,11 @@
       <artifactId>awaitility</artifactId>
       <scope>compile</scope>
     </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-server</artifactId>
+      <version>12.1.0</version>
+    </dependency>
     <dependency>
       <groupId>io.javaoperatorsdk</groupId>
       <artifactId>operator-framework-junit</artifactId>

sample-operators/operations/src/main/java/io/javaoperatorsdk/operator/sample/metrics/MetricsHandlingSampleOperator.java

@@ -23,6 +23,9 @@
 import java.util.HashMap;
 import java.util.Map;
 
+import org.eclipse.jetty.server.Server;
+import org.eclipse.jetty.server.handler.ContextHandler;
+import org.eclipse.jetty.server.handler.ContextHandlerCollection;
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
@@ -59,7 +62,7 @@ public class MetricsHandlingSampleOperator {
    * Based on env variables a different flavor of Reconciler is used, showcasing how the same logic
    * can be implemented using the low level and higher level APIs.
    */
-  public static void main(String[] args) {
+  public static void main(String[] args) throws Exception {
     log.info("Metrics Handling Sample Operator starting!");
 
     var configProviders = new ArrayList<ConfigProvider>();
@@ -77,6 +80,13 @@ public static void main(String[] args) {
         new MetricsHandlingReconciler2(),
         configLoader.applyControllerConfigs(MetricsHandlingReconciler2.NAME));
     operator.start();
+
+    var startup = new ContextHandler(new StartupHandler(operator), "/startup");
+    var readiness = new ContextHandler(new ReadinessHandler(operator), "/ready");
+    Server server = new Server(8080);
+    server.setHandler(new ContextHandlerCollection(startup, readiness));
+    server.start();
+    log.info("Health probe server started on port 8080");
   }
 
   public static @NonNull Metrics initOTLPMetrics(boolean localRun) {

sample-operators/operations/src/main/java/io/javaoperatorsdk/operator/sample/metrics/ReadinessHandler.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.sample.metrics;
+
+import org.eclipse.jetty.server.Handler;
+import org.eclipse.jetty.server.Request;
+import org.eclipse.jetty.server.Response;
+import org.eclipse.jetty.util.Callback;
+
+import io.javaoperatorsdk.operator.Operator;
+
+import static io.javaoperatorsdk.operator.sample.metrics.StartupHandler.sendMessage;
+
+public class ReadinessHandler extends Handler.Abstract {
+
+  private final Operator operator;
+
+  public ReadinessHandler(Operator operator) {
+    this.operator = operator;
+  }
+
+  @Override
+  public boolean handle(Request request, Response response, Callback callback) {
+    if (operator.getRuntimeInfo().allEventSourcesAreHealthy()) {
+      sendMessage(response, 200, "ready", callback);
+    } else {
+      sendMessage(response, 400, "not ready: an event source is not healthy", callback);
+    }
+    return true;
+  }
+}

sample-operators/operations/src/main/java/io/javaoperatorsdk/operator/sample/metrics/StartupHandler.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.sample.metrics;
+
+import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
+
+import org.eclipse.jetty.server.Handler;
+import org.eclipse.jetty.server.Request;
+import org.eclipse.jetty.server.Response;
+import org.eclipse.jetty.util.Callback;
+
+import io.javaoperatorsdk.operator.Operator;
+
+public class StartupHandler extends Handler.Abstract {
+
+  private final Operator operator;
+
+  public StartupHandler(Operator operator) {
+    this.operator = operator;
+  }
+
+  @Override
+  public boolean handle(Request request, Response response, Callback callback) {
+    if (operator.getRuntimeInfo().isStarted()) {
+      sendMessage(response, 200, "started", callback);
+    } else {
+      sendMessage(response, 400, "not started yet", callback);
+    }
+    return true;
+  }
+
+  static void sendMessage(Response response, int code, String message, Callback callback) {
+    response.setStatus(code);
+    response.getHeaders().put("Content-Type", "text/plain; charset=utf-8");
+    response.write(true, ByteBuffer.wrap(message.getBytes(StandardCharsets.UTF_8)), callback);
+  }
+}

sample-operators/operations/src/test/resources/helm-values.yaml

@@ -33,3 +33,9 @@ primaryResources:
     - metricshandlingcustomresource1s
     - metricshandlingcustomresource2s
 
+probes:
+  startup:
+    enabled: true
+  readiness:
+    enabled: true
+