feat(events): raise k8s events with fake provider

[ivankatliarchuk]

What does it do ?

Note: safe to merge as it does not break any current functionality, and only supported with fake source

• Publish k8s events. Scoped to fake source, to keep change size relatively small.
  • fake events do not have any object reference
• currently only supported successful events, as to support failed cases need more effort
• emit only specific events, similar to --service-type-filter logic
• events emit relevant docs

I'm slicing this feature into multiple PRs, as there is a lot to add + tests are usually 3x lines vs actual logic + docs + smoke testing is simpler when delivered in chunks

High Level Diagram

sequenceDiagram
  participant Source
  participant ReferenceObject
  participant Endpoint
  participant Plan
  participant Event
  participant Provider
  participant EventEmitter


  loop Process each Endpoint
    Source->>Endpoint: Add Endpoint with Reference
  end

  Endpoint-->>ReferenceObject: Contains
  Plan-->>Endpoint: Contains multiple

  loop Apply Changes
    Plan->>Provider: Apply Endpoint Changes
    Provider-->>Endpoint: Label with Skip/Success/Failed
    Provider-->>Plan: Return Result
  end


  loop Process each Event
    Provider->>Plan: Label with Skip/Success/Failed
    Plan-->>Event: Construct Event
    Event-->>ReferenceObject: Contains
    Event->>EventEmitter: Emit
  end

Loading

Follow-up:

• Provider a reliable way to label each endpoint with Success, Skip, Failed so that we could emit correct event per endpiont. This may take time.
• improved unit-test coverage
• metrics
• helm changes
• support CRD DNSEndpoint as source
• support all other sources
• externalise method func (ec *Controller) run(ctx context.Context) with metrics instrumentation
• instrument kubeclient with metrics centrally

Motivation

Fixes #646
Relates #5243. The change will enable us to raise events for CRD changes

More

• Yes, this PR title follows Conventional Commits
• Yes, I added unit tests
• Yes, I updated end user documentation accordingly
• Smoke tests results
• Update what does it do with references if any

Example Fake event initiated for core-dns pod.

At the moment plan is not aware where or not changes applied or skipped, or failed for certain Endpoints. This will be added in follow-up PR

example, skipped endpoint creation due to domain is not supported

Example Event in Json format

{
            "action": "Created",
            "apiVersion": "v1",
            "eventTime": "2025-07-20T15:29:02.768054Z",
            "firstTimestamp": null,
            "involvedObject": {
                "apiVersion": "v1",
                "kind": "Pod",
                "name": "coredns-668d6bf9bc-2d2ds",
                "namespace": "kube-system",
                "uid": "558f5d67-f678-4581-b0bd-0f8c031aec75"
            },
            "kind": "Event",
            "lastTimestamp": null,
            "message": "record:buzd.example.com, owner:fake, type:A, targets:192.0.2.190",
            "metadata": {
                "creationTimestamp": "2025-07-20T15:29:01Z",
                "name": "coredns-668d6bf9bc-2d2ds.1853ff42e5f27ef0",
                "namespace": "kube-system",
                "resourceVersion": "3792",
                "uid": "3e9fe0e3-b5b1-4381-8dca-24fc00a06357"
            },
            "reason": "RecordReady",
            "related": {
                "apiVersion": "v1",
                "kind": "Pod",
                "name": "coredns-668d6bf9bc-2d2ds",
                "namespace": "kube-system",
                "uid": "558f5d67-f678-4581-b0bd-0f8c031aec75"
            },
            "reportingComponent": "external-dns-Ivans-MacBook-Pro.local",
            "reportingInstance": "external-dns",
            "source": {},
            "type": "Normal"
        },

[ivankatliarchuk]

Heh silly things missed ;-)

[mloiseleur]

/lgtm

[ivankatliarchuk]

rebase and resolved merge conflicts

[mloiseleur]

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: mloiseleur

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [mloiseleur]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[vflaux]

This PR cause a panic at:

external-dns/pkg/events/controller.go

Lines 136 to 137 in 81290c0

	func (ec *Controller) Add(events ...Event) {
	if ec.queue.Len() >= ec.maxQueuedEvents {

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x1f3cb3d]

goroutine 1 [running]:
sigs.k8s.io/external-dns/pkg/events.(*Controller).Add(0x0, {0xc0008756b0, 0x1, 0x1})
	/external-dns/pkg/events/controller.go:137 +0x3d
sigs.k8s.io/external-dns/controller.emitChangeEvent({0x79f0500, 0x0}, {{0xc0005b4438, 0x1, 0x1}, {0xa7370e0, 0x0, 0x0}, {0xa7370e0, 0x0, ...}, ...}, ...)
	/external-dns/controller/events.go:32 +0x207
sigs.k8s.io/external-dns/controller.(*Controller).RunOnce(0xc0006fd110, {0x7a3fe78, 0xc00094a990})
	/external-dns/controller/controller.go:250 +0xdc5
sigs.k8s.io/external-dns/controller.(*Controller).Run(0xc0006fd110, {0x7a3feb0, 0xc000357630})
	/external-dns/controller/controller.go:347 +0x113
sigs.k8s.io/external-dns/controller.Execute()
	/external-dns/controller/execute.go:144 +0xe7a
main.main()
	/external-dns/main.go:26 +0xf

ec is actually nil.
There is a check for nil here:

external-dns/controller/events.go

Lines 27 to 30 in 81290c0

	func emitChangeEvent(e events.EventEmitter, ch plan.Changes, reason events.Reason) {
	if e == nil {
	return
	}

But we receive a typed pointer to nil, not nil directly.

This value come from here:

external-dns/controller/execute.go

Lines 362 to 385 in 81290c0

	eventsCfg := events.NewConfig(
	events.WithKubeConfig(cfg.KubeConfig, cfg.APIServerURL, cfg.RequestTimeout),
	events.WithEmitEvents(cfg.EmitEvents),
	events.WithDryRun(cfg.DryRun))
	var eventsCtrl *events.Controller
	if eventsCfg.IsEnabled() {
	eventsCtrl, err = events.NewEventController(eventsCfg)
	if err != nil {
	log.Fatal(err)
	}
	eventsCtrl.Run(ctx)
	}
	return &Controller{
	Source: src,
	Registry: reg,
	Policy: policy,
	Interval: cfg.Interval,
	DomainFilter: filter,
	ManagedRecordTypes: cfg.ManagedDNSRecordTypes,
	ExcludeRecordTypes: cfg.ExcludeDNSRecordTypes,
	MinEventSyncInterval: cfg.MinEventSyncInterval,
	EventController: eventsCtrl,
	}, nil

Passing an nil *events.Controller to an interface field is not the same as passing nil to this field. Which is quite confusing.

This is shown in debugger:

• Passing a nil *events.Controller:
• Not assigning any value: