feat: Add Event Recorder

docs/content/en/docs/documentation/operations/configuration.md

@@ -294,6 +294,26 @@ All operator-level keys are prefixed with `josdk.`.
 |---|---|---|
 | `josdk.dependent-resources.ssa-based-create-update-match` | `Boolean` | Use SSA-based matching for dependent resource create/update |
 
+#### Events
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.events.cluster-scoped-namespace` | `String` | Namespace to record events about cluster scoped resources in (defaults to `default`) |
+
+Recording events requires the operator's service account to be allowed `get`, `create` and `patch` on
+`events` in the core (`""`) API group. All three are used: an event that does not exist yet is
+created, and an event that does is a repeat of one already recorded, which is patched to count the
+new occurrence instead of being recorded a second time. The
+[generic Helm chart](helm-chart.md) grants all three. If you write your own RBAC and a permission is
+missing, recording fails silently as far as reconciliation is concerned: the failure is swallowed so
+that it cannot break a reconciliation, and only shows up as a warning in the operator log.
+
+Note that events live in a namespace of their own choosing, which is the namespace of the object
+they are about, and for cluster scoped objects the namespace configured above. A namespaced `Role`
+therefore has to grant the permission in every namespace events are recorded in — including
+`default`, or whatever `josdk.events.cluster-scoped-namespace` is set to, if the operator reconciles
+cluster scoped resources. A `ClusterRole` covers all of them at once.
+
 #### Leader Election
 
 Leader election is activated when at least one `josdk.leader-election.*` key is present.

docs/content/en/docs/documentation/operations/helm-chart.md

@@ -49,6 +49,12 @@ secondaryResources:
 Primary resources get read/watch/patch permissions and status sub-resource access.
 Secondary resources get full CRUD permissions. Default verbs can be overridden per resource entry.
 
+The ClusterRole always grants `get`, `create` and `patch` on `events` in the core API group, so
+recording events works without any extra configuration. All three are needed: an event is looked up
+by name before it is created, so that recording the same event again resolves to the event already
+recorded, and that event is then patched to count the new occurrence rather than recorded again. See
+[Events](configuration.md#events) for what this means if you write your own RBAC.
+
 ### Operator Environment
 
 The chart injects `OPERATOR_NAMESPACE` automatically. You can optionally set `WATCH_NAMESPACE` to

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

@@ -71,11 +71,15 @@ rules:
   {{- end }}
 {{- end }}
 # Event permissions - for recording events
+# All three verbs are used: an event is looked up by name ("get") so that a repeat of it resolves to
+# the event already recorded, which is then "patch"ed to count the new occurrence instead of being
+# "create"d a second time. Without them recording fails, visible only as a warning in the log.
 - apiGroups:
   - ""
   resources:
   - events
   verbs:
+  - get
   - create
   - patch
 {{- /* Leader election - Lease permissions */}}

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

@@ -44,6 +44,7 @@ tests:
             resources:
               - events
             verbs:
+              - get
               - create
               - patch
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/RegisteredController.java

@@ -18,11 +18,25 @@
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.javaoperatorsdk.operator.api.config.ControllerConfiguration;
 import io.javaoperatorsdk.operator.api.config.NamespaceChangeable;
+import io.javaoperatorsdk.operator.api.event.EventRecorder;
 import io.javaoperatorsdk.operator.health.ControllerHealthInfo;
 
 public interface RegisteredController<P extends HasMetadata> extends NamespaceChangeable {
 
   ControllerConfiguration<P> getConfiguration();
 
   ControllerHealthInfo getControllerHealthInfo();
+
+  /**
+   * Returns the {@link EventRecorder} of this controller, to record Kubernetes events outside of a
+   * reconciliation, for example from a status listener or a background task. Within a
+   * reconciliation, use {@link io.javaoperatorsdk.operator.api.reconciler.Context#eventRecorder()}
+   * instead.
+   *
+   * @return the event recorder associated with this controller
+   */
+  default EventRecorder eventRecorder() {
+    throw new UnsupportedOperationException(
+        "This implementation of RegisteredController does not provide an EventRecorder");
+  }
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java

@@ -34,6 +34,7 @@
 import io.fabric8.kubernetes.client.KubernetesClient;
 import io.fabric8.kubernetes.client.KubernetesClientBuilder;
 import io.fabric8.kubernetes.client.utils.KubernetesSerialization;
+import io.javaoperatorsdk.operator.api.event.DefaultEventRecorder;
 import io.javaoperatorsdk.operator.api.monitoring.Metrics;
 import io.javaoperatorsdk.operator.api.reconciler.Context;
 import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
@@ -274,6 +275,23 @@ default Optional<LeaderElectionConfiguration> getLeaderElectionConfiguration() {
     return Optional.empty();
   }
 
+  /**
+   * The namespace in which Kubernetes events about cluster scoped resources are created, since such
+   * events still have to live in some namespace.
+   *
+   * <p>Defaults to the {@code default} namespace, following the Kubernetes convention, which is
+   * also what the Go client does, so that events recorded by an operator end up alongside the ones
+   * recorded by the built-in controllers. Operators whose RBAC does not allow creating events in
+   * the {@code default} namespace should override this, typically with the namespace the operator
+   * itself runs in. Note that recording an event is best effort, so a missing permission results in
+   * the event being dropped with a warning in the log rather than in an error.
+   *
+   * @return the namespace to record events about cluster scoped resources in
+   */
+  default String clusterScopedEventNamespace() {
+    return DefaultEventRecorder.CLUSTER_SCOPED_EVENT_NAMESPACE;
+  }
+
   /**
    * if true, operator stops if there are some issues with informers {@link
    * io.javaoperatorsdk.operator.processing.event.source.informer.InformerEventSource} or {@link

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationServiceOverrider.java

@@ -45,6 +45,7 @@ public class ConfigurationServiceOverrider {
   private ExecutorService executorService;
   private ExecutorService workflowExecutorService;
   private LeaderElectionConfiguration leaderElectionConfiguration;
+  private String clusterScopedEventNamespace;
   private InformerStoppedHandler informerStoppedHandler;
   private Boolean stopOnInformerErrorDuringStartup;
   private Duration cacheSyncTimeout;
@@ -131,6 +132,19 @@ public ConfigurationServiceOverrider withLeaderElectionConfiguration(
     return this;
   }
 
+  /**
+   * Sets the namespace in which Kubernetes events about cluster scoped resources are recorded. Use
+   * this when the operator is not allowed to create events in the {@code default} namespace,
+   * passing for example the namespace the operator itself runs in.
+   *
+   * @param namespace the namespace to record events about cluster scoped resources in
+   * @return this {@link ConfigurationServiceOverrider} for chained customization
+   */
+  public ConfigurationServiceOverrider withClusterScopedEventNamespace(String namespace) {
+    this.clusterScopedEventNamespace = namespace;
+    return this;
+  }
+
   public ConfigurationServiceOverrider withInformerStoppedHandler(InformerStoppedHandler handler) {
     this.informerStoppedHandler = handler;
     return this;
@@ -258,6 +272,13 @@ public Optional<LeaderElectionConfiguration> getLeaderElectionConfiguration() {
             : original.getLeaderElectionConfiguration();
       }
 
+      @Override
+      public String clusterScopedEventNamespace() {
+        return clusterScopedEventNamespace != null
+            ? clusterScopedEventNamespace
+            : original.clusterScopedEventNamespace();
+      }
+
       @Override
       public Optional<InformerStoppedHandler> getInformerStoppedHandler() {
         return informerStoppedHandler != null