feat: add aggregated API server implementation

[scotwells]

Summary

This PR implements a Kubernetes aggregated API server for querying audit logs from ClickHouse. Includes API types, REST storage implementation with cursor-based pagination, CEL expression filtering, and OpenTelemetry instrumentation for metrics and tracing.

Refer to the API documentation for more details on how to interact with the API. Refer to the apiserver architecture documentation for more information on implementation of the apiserver.

Important

This PR is showing a very large diff because of the auto-generated openapi specification (~19k lines).

Details

The AuditLogQuery type can be created to query the system for audit logs. This type is ephemeral meaning the type is not actually created in the system, the audit log results are added to the status of the resource and returned to the client.

Here's an example showing how to use relative timestamps to query audit logs over the last 7 days for objects in the production or staging namespace.

apiVersion: activity.miloapis.com/v1alpha1
kind: AuditLogQuery
metadata:
  name: production-staging-events
spec:
  # Query the last 7 days
  startTime: "now-7d"
  endTime: "now"
  # Query events from multiple namespaces
  filter: "objectRef.namespace in ['production', 'staging']"
  limit: 10

The status of the AuditLogQuery will contain the results of the query, pagination information, and the effective start / end times used in the request.

apiVersion: activity.miloapis.com/v1alpha1
kind: AuditLogQuery
metadata:
  name: last-7-days
spec:
  # Query the last 7 days
  startTime: "now-7d"
  endTime: "now"
  # Query events from multiple namespaces
  filter: "objectRef.namespace in ['production', 'staging']"
  limit: 10
status:
  continue: eyJ0IjoiMjAyNS0xMi0xN1QxODozOToyOC43OTMyMTdaIiwiYSI6ImVhNDQ3NzAxLTE1ZTAtNDVkZC1hNDg3LTYxODY4ZTgzNWFlYiIsImgiOiJ4Y0dFYlZpMGpINk1QdTlpYTh1cTd3PT0iLCJpIjoiMjAyNS0xMi0xN1QxODozOTozMy4wNjQ1MzI4MDRaIn0=
  effectiveEndTime: "2025-12-17T18:39:32Z"
  effectiveStartTime: "2025-12-10T18:39:32Z"
  results:
  - annotations:
      authorization.k8s.io/decision: allow
      authorization.k8s.io/reason: 'RBAC: allowed by ClusterRoleBinding "kubeadm:cluster-admins"
        of ClusterRole "cluster-admin" to Group "kubeadm:cluster-admins"'
    apiVersion: audit.k8s.io/v1
    auditID: 983cf1c7-fc4c-40e1-8aaf-fa3a781ad04f
    kind: Event
    level: RequestResponse
  ...

Pagination is done by using the cursor from the previous request in the spec.continue field of the request. Cursor tokens are only valid with the same page size, filter, time range and will expire after 1 hour.

apiVersion: activity.miloapis.com/v1alpha1
kind: AuditLogQuery
metadata:
  name: production-staging-events
spec:
  # Fields from the previous page request
  ...
  continue: eyJ0IjoiMjAyNS0xMi0xN1QxODozOToyOC43OTM...

CEL expressions provide a powerful and type-safe querying language can be used to filter the audit logs returned in the results. Users can input their CEL expression into spec.filter with the following fields available to them:

Available Fields:

• verb - API action: get, list, create, update, patch, delete, watch
• auditID - unique event identifier
• stage - request phase: RequestReceived, ResponseStarted, ResponseComplete, Panic
• stageTimestamp - when this stage occurred (RFC3339 timestamp)
• user.username - who made the request (user or service account)
• responseStatus.code - HTTP response code (200, 201, 404, 500, etc.)
• objectRef.namespace - target resource namespace
• objectRef.resource - resource type (pods, deployments, secrets, configmaps, etc.)
• objectRef.name - specific resource name

Up Next

• Deployment configurations for the apiserver
• Vector / NATS pipeline configuration w/ e2e testing environment
• Automated end-to-end testing with CI pipeline
• CLI package for interacting with the new activity audit log querying API w/ kubectl plugin
• Operational dashboards & performance testing

---

Relates to datum-cloud/enhancements#536

[ecv]

Well damn.