operatorBox.observe.events

3 min read

operatorBox.observe.events declares Kubernetes Events that trigger reconciliation of the primary CR.

Declaration

spec:
  crds:
    app:
      operatorBox:
        observe:
          events:
            dbReady:
              reason: DatabaseReady
              type: Normal
              regarding:
                apiVersion: databases.example.com/v1
                kind: Database
                name: my-db

            dbFailed:
              reason: DatabaseFailed
              type: Warning
              regarding:
                apiVersion: databases.example.com/v1
                kind: Database
                name: my-db

events is a map. The map key is the Event declaration name and identifies the matching Event in the reconciliation context.

events[] fields

FieldTypeRequiredDescription
reasonstringnoMatch the Event’s reason field.
actionstringnoMatch the Event’s action field.
typestringnoMatch the Event’s type field.
reportingControllerstringnoMatch the Event’s reportingController field.
reportingInstancestringnoMatch the Event’s reportingInstance field.
namespacestringnoRestrict matching Events to this namespace.
on[]stringnoEvent lifecycle types: create, update, delete. Defaults to all three.
regardingManagedResourcenoMatch the object referenced by the Event’s regarding field.
relatedManagedResourcenoMatch the object referenced by the Event’s related field.
keyFromWatchKeyFromnoDefine how the primary CR key is resolved.

At least one matching or routing field must be declared. An empty Event entry is rejected.

Declaration name

Event declarations do not specify apiVersion or kind. The observed resource is always:

events.k8s.io/v1/Event

The map key is the declaration name:

events:
  dbReady:
    reason: DatabaseReady

  dbFailed:
    reason: DatabaseFailed

Declaration names must be camelCase. ork validate enforces this because the name is used by the resolver as the .events.<name> path.

The declaration name is independent of the Kubernetes Event’s metadata name.

Matching

Every non-empty field in an Event declaration is a matching constraint. Fields that are omitted are wildcards.

events:
  databaseWarning:
    reason: DatabaseDegraded
    type: Warning
    reportingController: database.example.com/operator

An Event must match all specified fields.

regarding and related match the corresponding objects referenced by the Event. They are matching constraints and do not change how the Event is represented.

ManagedResource

regarding and related use ManagedResource.

FieldTypeDescription
apiVersionstringAPI version of the referenced object.
kindstringKind of the referenced object.
namestringName of the referenced object.
namespacestringNamespace of the referenced object.

Unspecified fields are wildcards.

events:
  databaseEvents:
    regarding:
      kind: Database

on

on specifies which Event lifecycle types trigger the declaration.

Supported values:

  • create
  • update
  • delete

When omitted, all three are enabled:

on: [create, update, delete]

Example:

events:
  databaseReady:
    reason: DatabaseReady
    on: [create]

keyFrom

keyFrom defines the primary CR key associated with a matching Event.

events:
  databaseReady:
    reason: DatabaseReady
    keyFrom:
      label: app.kubernetes.io/cr-owner

Or:

events:
  databaseReady:
    reason: DatabaseReady
    keyFrom:
      name: my-operator
      namespace: default
FieldTypeDescription
labelstringLabel key whose value is the primary CR key.
namestringName of the primary CR to enqueue.
namespacestringNamespace of the primary CR. Only meaningful with name.

Validation

  • Exactly one of label or name must be set when keyFrom is present.
  • namespace cannot be combined with label.
  • namespace is only meaningful with name.

Multiple matching declarations

A Kubernetes Event can match multiple declarations.

events:
  allDatabaseEvents:
    regarding:
      kind: Database

  databaseWarnings:
    type: Warning
    regarding:
      kind: Database

Each declaration retains its own name.

Validation

ork validate enforces:

  • At least one matching or routing field is present.
  • on values are create, update, or delete.
  • keyFrom, when present, has exactly one of label or name.
  • keyFrom.namespace is rejected when label is used.
  • regarding and related use valid ManagedResource fields.
  • Event declaration names are camelCase.

Event observation always targets:

events.k8s.io/v1/Event