feat(events): publish k8s events

Signed-off-by: ivan katliarchuk <[email protected]>

Author: ivankatliarchuk

controller/controller.go

@@ -246,7 +246,6 @@ func (c *Controller) RunOnce(ctx context.Context) error {
 		if err != nil {
 			registryErrorsTotal.Counter.Inc()
 			deprecatedRegistryErrors.Counter.Inc()
-			emitChangeEvent(c.EventController, *plan.Changes, events.RecordError)
 			return err
 		} else {
 			emitChangeEvent(c.EventController, *plan.Changes, events.RecordReady)

controller/controller_test.go

@@ -28,6 +28,7 @@ import (
 	"sigs.k8s.io/external-dns/endpoint"
 	"sigs.k8s.io/external-dns/internal/testutils"
 	"sigs.k8s.io/external-dns/pkg/apis/externaldns"
+	"sigs.k8s.io/external-dns/pkg/events/fake"
 	"sigs.k8s.io/external-dns/plan"
 	"sigs.k8s.io/external-dns/provider"
 	"sigs.k8s.io/external-dns/registry"
@@ -216,6 +217,8 @@ func TestRunOnce(t *testing.T) {
 	cfg := getTestConfig()
 	provider := getTestProvider()
 
+	emitter := fake.NewFakeEventEmitter()
+
 	r, err := registry.NewNoopRegistry(provider)
 	require.NoError(t, err)
 
@@ -225,6 +228,7 @@ func TestRunOnce(t *testing.T) {
 		Registry:           r,
 		Policy:             &plan.SyncPolicy{},
 		ManagedRecordTypes: cfg.ManagedDNSRecordTypes,
+		EventController:    emitter,
 	}
 
 	assert.NoError(t, ctrl.RunOnce(context.Background()))
@@ -235,6 +239,8 @@ func TestRunOnce(t *testing.T) {
 
 	testutils.TestHelperVerifyMetricsGaugeVectorWithLabels(t, 1, verifiedRecords.Gauge, map[string]string{"record_type": "a"})
 	testutils.TestHelperVerifyMetricsGaugeVectorWithLabels(t, 1, verifiedRecords.Gauge, map[string]string{"record_type": "aaaa"})
+
+	emitter.AssertNumberOfCalls(t, "Add", 6)
 }
 
 // TestRun tests that Run correctly starts and stops

controller/events.go

@@ -32,6 +32,6 @@ func emitChangeEvent(e events.EventEmitter, ch plan.Changes, reason events.Reaso
 		e.Add(events.NewEvent(change.RefObject(), change.Describe(), events.ActionUpdate, reason))
 	}
 	for _, change := range ch.Delete {
-		e.Add(events.NewEvent(change.RefObject(), change.Describe(), events.ActionDelete, reason))
+		e.Add(events.NewEvent(change.RefObject(), change.Describe(), events.ActionDelete, events.RecordDeleted))
 	}
 }

controller/events_test.go

@@ -19,43 +19,88 @@ package controller
 import (
 	"testing"
 
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
+	"sigs.k8s.io/external-dns/endpoint"
 	"sigs.k8s.io/external-dns/pkg/events"
+	"sigs.k8s.io/external-dns/pkg/events/fake"
 	"sigs.k8s.io/external-dns/plan"
 )
 
-type mockEventEmitter struct {
-	events []events.Event
-}
+func TestEmit_RecordReady(t *testing.T) {
+	refObj := &events.ObjectReference{}
+
+	tests := []struct {
+		name    string
+		changes plan.Changes
+		asserts func(em *fake.EventEmitter, ch plan.Changes)
+	}{
+		{
+			name: "create, update and delete endpoints",
+			changes: plan.Changes{
+				Create: []*endpoint.Endpoint{
+					endpoint.NewEndpoint("one.example.com", endpoint.RecordTypeA, "10.10.10.0").WithRefObject(refObj),
+					endpoint.NewEndpoint("two.example.com", endpoint.RecordTypeA, "10.10.10.1").WithRefObject(refObj),
+				},
+				UpdateNew: []*endpoint.Endpoint{
+					endpoint.NewEndpoint("three.example.com", endpoint.RecordTypeA, "10.10.10.2").WithRefObject(refObj),
+					endpoint.NewEndpoint("four.example.com", endpoint.RecordTypeA, "10.10.10.3").WithRefObject(refObj),
+				},
+				Delete: []*endpoint.Endpoint{
+					endpoint.NewEndpoint("five.example.com", endpoint.RecordTypeA, "192.10.10.0").WithRefObject(refObj),
+				},
+			},
+			asserts: func(em *fake.EventEmitter, ch plan.Changes) {
+				for _, ep := range ch.Create {
+					em.AssertCalled(t, "Add", events.NewEvent(ep.RefObject(), ep.Describe(), events.ActionCreate, events.RecordReady))
+				}
+				for _, ep := range ch.Delete {
+					em.AssertCalled(t, "Add", events.NewEvent(ep.RefObject(), ep.Describe(), events.ActionDelete, events.RecordDeleted))
+				}
+				em.AssertNotCalled(t, "Add", mock.MatchedBy(func(e events.Event) bool {
+					return e.EventType() == events.EventTypeWarning
+				}))
+				em.AssertNumberOfCalls(t, "Add", 5)
+			},
+		},
+		{
+			name: "delete endpoints",
+			changes: plan.Changes{
+				Create:    []*endpoint.Endpoint{},
+				UpdateNew: []*endpoint.Endpoint{},
+				Delete: []*endpoint.Endpoint{
+					endpoint.NewEndpoint("five.example.com", endpoint.RecordTypeA, "192.10.10.0").WithRefObject(refObj),
+				},
+			},
+			asserts: func(em *fake.EventEmitter, ch plan.Changes) {
+				for _, ep := range ch.Delete {
+					em.AssertCalled(t, "Add", events.NewEvent(ep.RefObject(), ep.Describe(), events.ActionDelete, events.RecordDeleted))
+				}
+				em.AssertCalled(t, "Add", mock.MatchedBy(func(e events.Event) bool {
+					return e.EventType() == events.EventTypeNormal &&
+						e.Action() == events.ActionDelete &&
+						e.Reason() == events.RecordDeleted
+				}))
 
-func (m *mockEventEmitter) Add(events ...events.Event) {
-	for _, event := range events {
-		m.events = append(m.events, event)
+				em.AssertNumberOfCalls(t, "Add", 1)
+			},
+		},
 	}
 
-}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			emitter := fake.NewFakeEventEmitter()
 
-func TestEmit(t *testing.T) {
-	// emitter := &mockEventEmitter{}
-	// obj := &struct{}{} // dummy object
-
-	// change := plan.Change{
-	// 	Ref: obj,
-	// }
-	// changes := plan.Changes{
-	// 	Create:    []plan.Change{change},
-	// 	UpdateNew: []plan.Change{change},
-	// 	Delete:    []plan.Change{change},
-	// }
-	//
-	// emitChangeEvent(emitter, changes, events.Reason("TestReason"))
-	//
-	// require.Len(t, emitter.events, 3)
-	// require.Equal(t, events.ActionCreate, emitter.events[0].Action)
-	// require.Equal(t, events.ActionUpdate, emitter.events[1].Action)
-	// require.Equal(t, events.ActionDelete, emitter.events[2].Action)
+			emitChangeEvent(emitter, tt.changes, events.RecordReady)
+
+			tt.asserts(emitter, tt.changes)
+			mock.AssertExpectationsForObjects(t, emitter)
+		})
+	}
 }
 
 func TestEmit_NilEmitter(t *testing.T) {
-	emitChangeEvent(nil, plan.Changes{}, events.Reason("TestReason"))
-	// Should not panic or do anything
+	assert.NotPanics(t, func() {
+		emitChangeEvent(nil, plan.Changes{}, events.RecordError)
+	})
 }

controller/execute.go

@@ -122,8 +122,7 @@ func Execute() {
 	}
 
 	eventsController, err := events.NewEventController(events.NewConfig(
-		events.WithKubeConfig(cfg.KubeConfig),
-		events.WithAPIServerURL(cfg.APIServerURL),
+		events.WithKubeConfig(cfg.KubeConfig, cfg.APIServerURL, cfg.RequestTimeout),
 		events.WithEmitEvents(cfg.EmitEvents),
 		events.WithDryRun(cfg.DryRun),
 	))

controller/execute_test.go

@@ -484,7 +484,7 @@ func (m *MockProvider) Records(ctx context.Context) ([]*endpoint.Endpoint, error
 	return nil, nil
 }
 
-func (p *MockProvider) ApplyChanges(ctx context.Context, changes *plan.Changes) error {
+func (m *MockProvider) ApplyChanges(ctx context.Context, changes *plan.Changes) error {
 	return nil
 }
 

docs/advanced/events.md

@@ -0,0 +1,90 @@
+# Kubernetes Events in External-DNS
+
+External-DNS manages DNS records dynamically based on Kubernetes resources like Services and Ingresses. Emitting Kubernetes Events provides a lightweight, observable way for users and systems to understand what External-DNS is doing, especially in production environments where DNS correctness is essential.
+
+> Note; events is currently alpha feature. Functionality is limited and subject to change
+
+## ✨ Why Events Matter
+
+Kubernetes Events enable External-DNS to provide real-time feedback to users and controllers, complementing logs with a simpler way to track DNS changes. This enhances debugging, monitoring, and automation around DNS operations.
+
+### Use Cases of Emitting Events
+
+| Use Case                                          | Description                                                                                                  |
+|---------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| **DNS Record Visibility**                         | Events show what DNS records were created, updated, or deleted (e.g., `Created A record "api.example.com"`). |
+| **Developer Feedback**                            | Users deploying Ingresses or Services can see if External-DNS processed their resource.                      |
+| **Surface Errors, Debugging and Troubleshooting** | Easily identify resource misannotations, sync failures, or IAM permission issues.                            |
+| **Error Reporting**                               | Emit warning events when record sync fails due to provider issues, duplicate records, or misconfigurations.  |
+| **Integration with Alerting/Automation/Auditing** | This enables automated remediation or notifications when DNS sync fails or changes unexpectedly.             |
+| **Observability**                                 | Trace why a DNS record wasn’t created.                                                                       |
+| **Alerting/automation**                           | Trigger actions based on failed events.                                                                      |
+| **Operator and Developer feedback**               | It removes the black-box feeling of "I deployed an Ingress, but why doesn’t the DNS work?"                   |
+
+## Consuming Events
+
+You can observe External-DNS events using:
+
+```sh
+kubectl describe service <name>
+kubectl get events --field-selector involvedObject.kind=Service
+kubectl get events --field-selector type=Normal|Warning
+kubectl get events --field-selector reason=RecordReady|RecordDeleted|RecordError
+kubectl get events --field-selector action=Created|Updated|Deleted|FailedSync
+kubectl get events --field-selector reportingComponent=external-dns
+```
+
+Or integrate with tools like:
+
+- Prometheus (via event exporters)
+- Loki/Fluentd for log/event aggregation
+- Argo CD / Flux for GitOps monitoring
+
+### Practices for Understanding Events
+
+- **Action field**: Events include a short label describing the `Action`, such as `Created`, `Updated`, `Deleted`, or `FailedSync`
+- **Reason field**: Events include a short label `Reason` is why the action was taken, such as `RecordReady`, `RecordDeleted`, or `RecordError`.
+- **Type field**:
+  - `Normal` means the operation succeeded (e.g., a DNS record was created).
+  - `Warning`  indicates a problem (e.g., DNS sync failed due to configuration or provider issues).
+- **Linked** resource: Events are attached to the relevant Kubernetes resource (like an `Ingress` or `Service`), so you can view them with tools like `kubectl describe`.
+- **Event noise**: If you see repeated identical events, it may indicate a misconfiguration or an issue worth investigating.
+
+### Caveats
+
+- Events are ephemeral (default retention is ~1 hour).
+- They are best-effort and not guaranteed to be delivered or stored long-term.
+- Not a substitute for logging or metrics, but complementary.
+
+## Supported Sources
+
+Events are emitted for all sources that External-DNS supports. The following table lists the sources and whether they currently emit events.
+If a source does not emit events, it may in the future.
+
+| Source                 | Supported |
+|:-----------------------|:---------:|
+| `ambassador-host`      |           |
+| `cloudfoundry`         |           |
+| `connector`            |           |
+| `contour-httpproxy`    |           |
+| `crd`                  |           |
+| `empty`                |           |
+| `f5-transportserver`   |           |
+| `f5-virtualserver`     |           |
+| `fake`                 |     ✅     |
+| `gateway-grpcroute`    |           |
+| `gateway-httproute`    |           |
+| `gateway-tcproute`     |           |
+| `gateway-tlsroute`     |           |
+| `gateway-udproute`     |           |
+| `gloo-proxy`           |           |
+| `ingress`              |           |
+| `istio-gateway`        |           |
+| `istio-virtualservice` |           |
+| `kong-tcpingress`      |           |
+| `node`                 |           |
+| `openshift-route`      |           |
+| `pod`                  |           |
+| `service`              |           |
+| `skipper-routegroup`   |           |
+| `traefik-proxy`        |           |

docs/flags.md

@@ -52,6 +52,7 @@
 | `--target-net-filter=TARGET-NET-FILTER` | Limit possible targets by a net filter; specify multiple times for multiple possible nets (optional) |
 | `--[no-]traefik-enable-legacy` | Enable legacy listeners on Resources under the traefik.containo.us API Group |
 | `--[no-]traefik-disable-new` | Disable listeners on Resources under the traefik.io API Group |
+| `--events-emit=EVENTS-EMIT` | Events that should be emitted. (optional, default: none, expected: RecordReady, RecordDeleted, RecordError) |
 | `--provider=provider` | The DNS provider where the DNS records will be created (required, options: akamai, alibabacloud, aws, aws-sd, azure, azure-dns, azure-private-dns, civo, cloudflare, coredns, digitalocean, dnsimple, exoscale, gandi, godaddy, google, inmemory, linode, ns1, oci, ovh, pdns, pihole, plural, rfc2136, scaleway, skydns, transip, webhook) |
 | `--provider-cache-time=0s` | The time to cache the DNS provider record list requests. |
 | `--domain-filter=` | Limit possible target zones by a domain suffix; specify multiple times for multiple domains (optional) |

endpoint/endpoint_test.go

@@ -22,6 +22,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"sigs.k8s.io/external-dns/pkg/events"
 )
 
 func TestNewEndpoint(t *testing.T) {
@@ -968,3 +969,16 @@ func TestEndpoint_UniqueOrderedTargets(t *testing.T) {
 		})
 	}
 }
+
+func TestEndpoint_WithRefObject(t *testing.T) {
+	ep := &Endpoint{}
+	ref := &events.ObjectReference{
+		Kind:      "Service",
+		Namespace: "default",
+		Name:      "my-service",
+	}
+	result := ep.WithRefObject(ref)
+
+	assert.Equal(t, ref, ep.RefObject(), "refObject should be set")
+	assert.Equal(t, ep, result, "should return the same Endpoint pointer")
+}

pkg/apis/externaldns/types.go

@@ -160,10 +160,9 @@ type Config struct {
 	ExoscaleAPISecret                             string `secure:"yes"`
 	ExoscaleAPIEnvironment                        string
 	ExoscaleAPIZone                               string
-	ServiceTypeFilter                             []string
 	CRDSourceAPIVersion                           string
 	CRDSourceKind                                 string
-	EmitEvents                                    []string
+	ServiceTypeFilter                             []string
 	CFAPIEndpoint                                 string
 	CFUsername                                    string
 	CFPassword                                    string
@@ -213,6 +212,7 @@ type Config struct {
 	TraefikDisableNew                             bool
 	NAT64Networks                                 []string
 	ExcludeUnschedulable                          bool
+	EmitEvents                                    []string
 	ForceDefaultTargets                           bool
 }
 
@@ -490,7 +490,7 @@ func App(cfg *Config) *kingpin.Application {
 	app.Flag("traefik-enable-legacy", "Enable legacy listeners on Resources under the traefik.containo.us API Group").Default(strconv.FormatBool(defaultConfig.TraefikEnableLegacy)).BoolVar(&cfg.TraefikEnableLegacy)
 	app.Flag("traefik-disable-new", "Disable listeners on Resources under the traefik.io API Group").Default(strconv.FormatBool(defaultConfig.TraefikDisableNew)).BoolVar(&cfg.TraefikDisableNew)
 
-	app.Flag("events-emit", "Events that should be emitted. (optional, default: none, expected: RecordReady, RecordError)").Default(defaultConfig.EmitEvents...).StringsVar(&cfg.EmitEvents)
+	app.Flag("events-emit", "Events that should be emitted. (optional, default: none, expected: RecordReady, RecordDeleted, RecordError)").Default(defaultConfig.EmitEvents...).StringsVar(&cfg.EmitEvents)
 
 	// Flags related to providers
 	providers := []string{"akamai", "alibabacloud", "aws", "aws-sd", "azure", "azure-dns", "azure-private-dns", "civo", "cloudflare", "coredns", "digitalocean", "dnsimple", "exoscale", "gandi", "godaddy", "google", "inmemory", "linode", "ns1", "oci", "ovh", "pdns", "pihole", "plural", "rfc2136", "scaleway", "skydns", "transip", "webhook"}