feat: add ActivityPolicy configurations for activity timelines

Add ActivityPolicy resources for DNSZone and DNSRecordSet that define
how API operations and controller events appear in activity timelines:

DNSZone policies:
- Audit rules for create/update/delete from API server audit logs
- Event rules for ZoneProgrammed and ZoneProgrammingFailed events
- Templates use domain-name and nameservers annotations for rich summaries

DNSRecordSet policies:
- Audit rules for create/update/delete from API server audit logs
- Event rules for RecordSetProgrammed and RecordSetProgrammingFailed events
- Separate templates for single vs multi-record sets
- Templates use record-type, record-names, domain-name annotations

Also updates event annotations to properly handle multi-record sets:
- Rename record-name to record-names (plural)
- Collect all unique owner names, not just the first

The policies leverage the structured annotations emitted by the DNS
controllers (dns.networking.miloapis.com/* prefix) to build
human-readable activity summaries without hardcoding display text
in the controller code.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: scotwells

config/activity/kustomization.yaml

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - policies

config/activity/policies/dnsrecordset-policy.yaml

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+
+# ActivityPolicy for DNSRecordSet resources.
+# Defines how DNSRecordSet API operations and controller events appear in activity timelines.
+#
+# Audit rules handle CRUD operations captured by the Kubernetes API server audit log.
+# Event rules handle async controller events for programming outcomes.
+apiVersion: activity.miloapis.com/v1alpha1
+kind: ActivityPolicy
+metadata:
+  name: dns.networking.miloapis.com-dnsrecordset
+spec:
+  resource:
+    apiGroup: dns.networking.miloapis.com
+    kind: DNSRecordSet
+
+  # Audit log rules for CRUD operations.
+  # These are automatically captured by the API server and don't require controller code.
+  auditRules:
+    - match: "audit.verb == 'create'"
+      summary: "{{ actor }} created {{ audit.responseObject.spec.recordType }} record {{ link(audit.objectRef.name, audit.responseObject) }} in zone {{ audit.responseObject.spec.dnsZoneRef.name }}"
+
+    - match: "audit.verb == 'delete'"
+      summary: "{{ actor }} deleted DNS record {{ audit.objectRef.name }}"
+
+    - match: "audit.verb in ['update', 'patch'] && !audit.objectRef.subresource"
+      summary: "{{ actor }} updated {{ audit.requestObject.spec.recordType }} record {{ link(audit.objectRef.name, audit.objectRef) }}"
+
+    # Status subresource updates are system-initiated and typically not shown to users,
+    # but can be enabled if needed for debugging.
+    # - match: "audit.verb in ['update', 'patch'] && audit.objectRef.subresource == 'status'"
+    #   summary: "System updated status of DNS record {{ link(audit.objectRef.name, audit.objectRef) }}"
+
+  # Event rules for controller-emitted Kubernetes events.
+  # These capture async outcomes that audit logs cannot represent.
+  #
+  # A DNSRecordSet can contain multiple records with potentially different names
+  # (e.g., "www" and "api" A records in one set). The annotations reflect this:
+  #   - record-count: total number of record entries
+  #   - record-names: comma-separated unique names (e.g., "www" or "www,api")
+  #   - ip-addresses: all IPs for A/AAAA types (may span multiple names)
+  eventRules:
+    # RecordSetProgrammed: DNS records successfully programmed to the DNS provider.
+    # Annotations available:
+    #   dns.networking.miloapis.com/event-type: dns.recordset.programmed
+    #   dns.networking.miloapis.com/domain-name: example.com
+    #   dns.networking.miloapis.com/record-type: A
+    #   dns.networking.miloapis.com/record-names: www (or "www,api" for multi-name)
+    #   dns.networking.miloapis.com/record-count: 2
+    #   dns.networking.miloapis.com/ip-addresses: 192.168.1.1,192.168.1.2  (A/AAAA only)
+    #   dns.networking.miloapis.com/zone-ref: my-zone
+    #   dns.networking.miloapis.com/resource-name: my-recordset
+    #   dns.networking.miloapis.com/resource-namespace: my-project
+
+    # Single A/AAAA record (most common case): show name and IPs
+    - match: "event.reason == 'RecordSetProgrammed' && event.annotations['dns.networking.miloapis.com/record-type'] in ['A', 'AAAA'] && event.annotations['dns.networking.miloapis.com/record-count'] == '1'"
+      summary: "{{ event.annotations['dns.networking.miloapis.com/record-type'] }} record {{ link(event.regarding.name, event.regarding) }} ({{ event.annotations['dns.networking.miloapis.com/record-names'] }}.{{ event.annotations['dns.networking.miloapis.com/domain-name'] }} -> {{ event.annotations['dns.networking.miloapis.com/ip-addresses'] }}) is now active"
+
+    # Multiple A/AAAA records: show count and names
+    - match: "event.reason == 'RecordSetProgrammed' && event.annotations['dns.networking.miloapis.com/record-type'] in ['A', 'AAAA'] && event.annotations['dns.networking.miloapis.com/record-count'] != '1'"
+      summary: "{{ event.annotations['dns.networking.miloapis.com/record-count'] }} {{ event.annotations['dns.networking.miloapis.com/record-type'] }} records {{ link(event.regarding.name, event.regarding) }} ({{ event.annotations['dns.networking.miloapis.com/record-names'] }}.{{ event.annotations['dns.networking.miloapis.com/domain-name'] }}) are now active"
+
+    # Single non-IP record: show name
+    - match: "event.reason == 'RecordSetProgrammed' && !(event.annotations['dns.networking.miloapis.com/record-type'] in ['A', 'AAAA']) && event.annotations['dns.networking.miloapis.com/record-count'] == '1'"
+      summary: "{{ event.annotations['dns.networking.miloapis.com/record-type'] }} record {{ link(event.regarding.name, event.regarding) }} ({{ event.annotations['dns.networking.miloapis.com/record-names'] }}.{{ event.annotations['dns.networking.miloapis.com/domain-name'] }}) is now active"
+
+    # Multiple non-IP records: show count and names
+    - match: "event.reason == 'RecordSetProgrammed' && !(event.annotations['dns.networking.miloapis.com/record-type'] in ['A', 'AAAA']) && event.annotations['dns.networking.miloapis.com/record-count'] != '1'"
+      summary: "{{ event.annotations['dns.networking.miloapis.com/record-count'] }} {{ event.annotations['dns.networking.miloapis.com/record-type'] }} records {{ link(event.regarding.name, event.regarding) }} ({{ event.annotations['dns.networking.miloapis.com/record-names'] }}.{{ event.annotations['dns.networking.miloapis.com/domain-name'] }}) are now active"
+
+    # RecordSetProgrammingFailed: DNS record programming failed after previous success.
+    # Annotations available:
+    #   dns.networking.miloapis.com/event-type: dns.recordset.programming_failed
+    #   dns.networking.miloapis.com/domain-name: example.com
+    #   dns.networking.miloapis.com/record-type: A
+    #   dns.networking.miloapis.com/record-names: www
+    #   dns.networking.miloapis.com/failure-reason: Provider API error
+    #   dns.networking.miloapis.com/zone-ref: my-zone
+    #   dns.networking.miloapis.com/resource-name: my-recordset
+    #   dns.networking.miloapis.com/resource-namespace: my-project
+    - match: "event.reason == 'RecordSetProgrammingFailed'"
+      summary: "{{ event.annotations['dns.networking.miloapis.com/record-type'] }} record {{ link(event.regarding.name, event.regarding) }} programming failed: {{ event.annotations['dns.networking.miloapis.com/failure-reason'] }}"

config/activity/policies/dnszone-policy.yaml

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+
+# ActivityPolicy for DNSZone resources.
+# Defines how DNSZone API operations and controller events appear in activity timelines.
+#
+# Audit rules handle CRUD operations captured by the Kubernetes API server audit log.
+# Event rules handle async controller events for programming outcomes.
+apiVersion: activity.miloapis.com/v1alpha1
+kind: ActivityPolicy
+metadata:
+  name: dns.networking.miloapis.com-dnszone
+spec:
+  resource:
+    apiGroup: dns.networking.miloapis.com
+    kind: DNSZone
+
+  # Audit log rules for CRUD operations.
+  # These are automatically captured by the API server and don't require controller code.
+  auditRules:
+    - match: "audit.verb == 'create'"
+      summary: "{{ actor }} created DNS zone {{ link(audit.objectRef.name, audit.responseObject) }} for domain {{ audit.responseObject.spec.domainName }}"
+
+    - match: "audit.verb == 'delete'"
+      summary: "{{ actor }} deleted DNS zone {{ audit.objectRef.name }}"
+
+    - match: "audit.verb in ['update', 'patch'] && !audit.objectRef.subresource"
+      summary: "{{ actor }} updated DNS zone {{ link(audit.objectRef.name, audit.objectRef) }}"
+
+    # Status subresource updates are system-initiated and typically not shown to users,
+    # but can be enabled if needed for debugging.
+    # - match: "audit.verb in ['update', 'patch'] && audit.objectRef.subresource == 'status'"
+    #   summary: "System updated status of DNS zone {{ link(audit.objectRef.name, audit.objectRef) }}"
+
+  # Event rules for controller-emitted Kubernetes events.
+  # These capture async outcomes that audit logs cannot represent.
+  eventRules:
+    # ZoneProgrammed: DNS zone successfully programmed to the DNS provider.
+    # Annotations available:
+    #   dns.networking.miloapis.com/event-type: dns.zone.programmed
+    #   dns.networking.miloapis.com/domain-name: example.com
+    #   dns.networking.miloapis.com/zone-class: production
+    #   dns.networking.miloapis.com/nameservers: ns1.example.com,ns2.example.com
+    #   dns.networking.miloapis.com/resource-name: my-zone
+    #   dns.networking.miloapis.com/resource-namespace: my-project
+    - match: "event.reason == 'ZoneProgrammed'"
+      summary: "DNS zone {{ link(event.regarding.name, event.regarding) }} for {{ event.annotations['dns.networking.miloapis.com/domain-name'] }} is now active with nameservers {{ event.annotations['dns.networking.miloapis.com/nameservers'] }}"
+
+    # ZoneProgrammingFailed: DNS zone programming failed after previous success.
+    # Annotations available:
+    #   dns.networking.miloapis.com/event-type: dns.zone.programming_failed
+    #   dns.networking.miloapis.com/domain-name: example.com
+    #   dns.networking.miloapis.com/failure-reason: Provider API error
+    #   dns.networking.miloapis.com/resource-name: my-zone
+    #   dns.networking.miloapis.com/resource-namespace: my-project
+    - match: "event.reason == 'ZoneProgrammingFailed'"
+      summary: "DNS zone {{ link(event.regarding.name, event.regarding) }} programming failed: {{ event.annotations['dns.networking.miloapis.com/failure-reason'] }}"

config/activity/policies/kustomization.yaml

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - dnszone-policy.yaml
+  - dnsrecordset-policy.yaml

internal/controller/events.go

@@ -32,7 +32,7 @@ const (
 	// DNSRecordSet-specific annotations.
 	AnnotationZoneRef     = "dns.networking.miloapis.com/zone-ref"
 	AnnotationRecordCount = "dns.networking.miloapis.com/record-count"
-	AnnotationRecordName  = "dns.networking.miloapis.com/record-name"
+	AnnotationRecordNames = "dns.networking.miloapis.com/record-names"
 	AnnotationIPAddresses = "dns.networking.miloapis.com/ip-addresses"
 
 	// Shared failure annotation.
@@ -169,8 +169,8 @@ func recordRecordSetActivityEventWithData(
 	}
 	if len(rs.Spec.Records) > 0 {
 		annotations[AnnotationRecordCount] = strconv.Itoa(len(rs.Spec.Records))
-		// Use the first record entry's name as the record name annotation.
-		annotations[AnnotationRecordName] = rs.Spec.Records[0].Name
+		// Collect unique record names preserving order of first occurrence.
+		annotations[AnnotationRecordNames] = strings.Join(uniqueRecordNames(rs), ",")
 	}
 	// Extract IP addresses for A/AAAA record types.
 	if ips := extractIPAddresses(rs); len(ips) > 0 {
@@ -182,6 +182,22 @@ func recordRecordSetActivityEventWithData(
 	recorder.AnnotatedEventf(rs, annotations, eventType, reason, messageFmt, args...)
 }
 
+// uniqueRecordNames returns a deduplicated list of record names from the
+// DNSRecordSet, preserving the order of first occurrence. This handles the
+// common case where multiple records share the same name (e.g., round-robin A
+// records) as well as the less common case of different names in one set.
+func uniqueRecordNames(rs *dnsv1alpha1.DNSRecordSet) []string {
+	seen := make(map[string]struct{})
+	var names []string
+	for _, r := range rs.Spec.Records {
+		if _, ok := seen[r.Name]; !ok {
+			seen[r.Name] = struct{}{}
+			names = append(names, r.Name)
+		}
+	}
+	return names
+}
+
 // extractIPAddresses collects IP address content values from A and AAAA record
 // entries in the given DNSRecordSet. Returns nil for all other record types.
 func extractIPAddresses(rs *dnsv1alpha1.DNSRecordSet) []string {

internal/controller/events_test.go

@@ -689,8 +689,8 @@ func TestRecordRecordSetActivityEventWithData_ResourceIdentityAnnotations(t *tes
 	if got := ann[AnnotationRecordCount]; got != "2" {
 		t.Errorf("%s = %q, want %q", AnnotationRecordCount, got, "2")
 	}
-	if got := ann[AnnotationRecordName]; got != "www" {
-		t.Errorf("%s = %q, want %q", AnnotationRecordName, got, "www")
+	if got := ann[AnnotationRecordNames]; got != "www,api" {
+		t.Errorf("%s = %q, want %q", AnnotationRecordNames, got, "www,api")
 	}
 }