Package v1alpha1 contains API Schema definitions for the activity v1alpha1 API group
Activity is a human-readable summary of something that happened in your cluster. Think of it as the "what changed and who did it" record that powers activity feeds, audit trails, and change history views.
Activities are created automatically from audit logs and Kubernetes events based on your ActivityPolicy rules. They're read-only - you query them, not create them.
There are three ways to get activity data, depending on what you need:
| What you need | API to use | Notes |
|---|---|---|
| Live feed | GET /activities?watch=true | Streams new activities as they happen. List only returns the last hour. |
| Search history | POST /activityqueries | Query any time range with filters, search, and pagination. |
| Filter options | POST /activityfacetqueries | Get values for dropdowns (e.g., "which actors have activities?"). |
Watch for new activities:
kubectl get activities --watch
List recent human-initiated changes:
kubectl get activities --field-selector spec.changeSource=human
For historical queries or advanced filtering, use ActivityQuery instead.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec ActivitySpec |
ActivityActor identifies who performed an action.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type string |
Type indicates the actor category. Values: "user", "serviceaccount", "controller" |
||
name string |
Name is the display name for the actor. For users, this is typically the email address. For service accounts, this is the full name (e.g., "system:serviceaccount:default:my-sa"). For controllers, this is the controller name. |
||
uid string |
UID is the unique identifier for the actor. Stable across username changes. |
||
email string |
Email is the actor's email address. Only populated for user actors when available. |
ActivityChange represents a field-level change in an update/patch operation.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
field string |
Field is the path to the changed field (e.g., "spec.virtualhost.fqdn"). | ||
old string |
Old is the previous value. May be empty for new fields. | ||
new string |
New is the new value. May be empty for deleted fields. |
ActivityFacetQuerySpec defines what you want facet data for.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
timeRange FacetTimeRange |
TimeRange sets how far back to look. Defaults to the last 7 days if not set. Use relative times like "now-7d" or absolute timestamps. |
||
filter string |
Filter lets you narrow down which activities to include before computing facets. Uses CEL (Common Expression Language) syntax. This is useful when you want facet values for a specific subset - for example, "show me actors, but only for human-initiated changes." Fields you can filter on: spec.changeSource - "human" or "system" spec.actor.name - who did it (e.g., "alice@example.com") spec.actor.type - user, serviceaccount, or controller spec.resource.kind - what type of resource (Deployment, Pod, etc.) spec.resource.namespace - which namespace spec.resource.name - resource name spec.resource.apiGroup - API group (empty string for core resources) Example filters: "spec.changeSource == 'human'" - Only human actions "spec.resource.kind == 'Deployment'" - Only Deployment changes "!spec.actor.name.startsWith('system:')" - Exclude system accounts |
||
facets FacetSpec array |
Facets specifies which fields to get distinct values for. Each facet returns the top N values with counts. |
ActivityFacetQueryStatus contains the facet results.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
facets FacetResult array |
Facets contains the results for each requested facet. |
ActivityLink represents a clickable reference in an activity summary.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
marker string |
Marker is the text substring in the summary that should be linked. The portal scans the summary for this marker and makes it clickable. Example: "HTTP proxy api-gateway" |
||
resource ActivityResource |
Resource identifies what the marker links to. |
ActivityOrigin identifies the source record for an activity.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type string |
Type indicates the source type. Values: "audit" (from audit logs), "event" (from Kubernetes events) |
||
id string |
ID is the correlation ID to the source record. For audit: the auditID from the audit log entry. For event: the metadata.uid of the Kubernetes Event. |
ActivityPolicy defines translation rules for a specific resource type. Service providers create one ActivityPolicy per resource kind to customize activity descriptions without modifying the Activity Processor.
Example:
apiVersion: activity.miloapis.com/v1alpha1
kind: ActivityPolicy
metadata:
name: networking-httpproxy
spec:
resource:
apiGroup: networking.datumapis.com
kind: HTTPProxy
auditRules:
- match: "verb == 'create'"
summary: "{{ actor }} created {{ link(kind + ' ' + objectRef.name, responseObject) }}"
eventRules:
- match: "event.reason == 'Programmed'"
summary: "{{ link(kind + ' ' + event.regarding.name, event.regarding) }} is now programmed"
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec ActivityPolicySpec |
|||
status ActivityPolicyStatus |
ActivityPolicyResource identifies the target Kubernetes resource for a policy.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiGroup string |
APIGroup is the API group of the target resource (e.g., "networking.datumapis.com"). Use an empty string for core API group resources. |
||
kind string |
Kind is the kind of the target resource (e.g., "HTTPProxy", "Network"). |
ActivityPolicyRule defines a single translation rule that matches input events and generates human-readable activity summaries.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is a unique identifier for this rule within the policy. Used for strategic merge patching and error reporting. |
||
description string |
Description is an optional human-readable description of what this rule does. | ||
match string |
Match is a CEL expression that determines if this rule applies to the input. For audit rules, use top-level variables (e.g., "verb == 'create'", "objectRef.namespace == 'default'"). For event rules, use the event variable (e.g., "event.reason == 'Programmed'").Examples: "verb == 'create'" "verb in ['update', 'patch']" "event.reason.startsWith('Failed')" "true" (fallback rule that always matches) |
||
summary string |
Summary is a CEL template for generating the activity summary. Use {{ }} delimiters to embed CEL expressions within strings. Available variables: - For audit rules: verb, objectRef, user, responseStatus, responseObject, actor, actorRef, kind - For event rules: event, actor Available functions: - link(displayText, resourceRef): Creates a clickable reference Examples: "{{ actor }} created {{ link(kind + ' ' + objectRef.name, responseObject) }}" "{{ link(kind + ' ' + event.regarding.name, event.regarding) }} is now programmed" |
ActivityPolicySpec defines the translation rules for a resource type.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
resource ActivityPolicyResource |
Resource identifies the Kubernetes resource this policy applies to. One ActivityPolicy should exist per resource kind. |
||
auditRules ActivityPolicyRule array |
AuditRules define how to translate audit log entries into activity summaries. Rules are evaluated in order; the first matching rule wins. Available variables: verb, objectRef, user, responseStatus, responseObject, actor, actorRef, kind Convenience variables available: actor |
||
eventRules ActivityPolicyRule array |
EventRules define how to translate Kubernetes events into activity summaries. Rules are evaluated in order; the first matching rule wins. The event variable contains the full Kubernetes Event structure.Convenience variables available: actor |
ActivityPolicyStatus represents the current state of an ActivityPolicy.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array |
Conditions represent the current state of the policy. The "Ready" condition indicates whether all rules compile successfully. |
||
observedGeneration integer |
ObservedGeneration is the generation last processed by the controller. |
ActivityQuerySpec defines the search parameters for activities.
Required: startTime and endTime define your search window. Optional: filter (CEL expression), namespace, changeSource, search, limit, continue.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
startTime string |
StartTime is the beginning of your search window (inclusive). Format Options: - Relative: "now-7d", "now-2h", "now-30m" (units: s, m, h, d, w) - Absolute: "2024-01-01T00:00:00Z" (RFC3339 with timezone) |
||
endTime string |
EndTime is the end of your search window (exclusive). Uses the same formats as StartTime. Commonly "now" for current moment. Must be greater than StartTime. |
||
namespace string |
Namespace filters activities to a specific namespace. Leave empty for cluster-wide results. |
||
changeSource string |
ChangeSource filters by who initiated the change. Values: - "human": User actions via kubectl, API, or UI - "system": Controller reconciliation, operator actions Leave empty for both. |
||
search string |
Search performs full-text search on activity summaries. Example: "created deployment" matches activities with those words in the summary. |
||
filter string |
Filter narrows results using CEL (Common Expression Language). Available Fields: spec.changeSource - "human" or "system" spec.actor.name - who performed the action spec.actor.type - "user", "serviceaccount", "controller" spec.actor.uid - actor's unique identifier spec.resource.apiGroup - resource API group (empty for core) spec.resource.kind - resource kind (Deployment, Pod, etc.) spec.resource.name - resource name spec.resource.namespace - resource namespace spec.resource.uid - resource UID spec.summary - activity summary text spec.origin.type - "audit" or "event" metadata.namespace - activity namespace Operators: ==, !=, &&, ||, !, in String Functions: startsWith(), endsWith(), contains() Examples: "spec.changeSource == 'human'" "spec.resource.kind == 'Deployment'" "spec.actor.name.contains('admin')" "spec.resource.kind in ['Deployment', 'StatefulSet']" |
||
resourceKind string |
ResourceKind filters by the kind of resource affected. Examples: "Deployment", "Pod", "ConfigMap", "HTTPProxy" |
||
resourceUID string |
ResourceUID filters activities for a specific resource by UID. Use this to get the full history of changes to a single resource. |
||
apiGroup string |
APIGroup filters by the API group of affected resources. Examples: "apps", "projectcontour.io", "" (empty for core API) |
||
actorName string |
ActorName filters by who performed the action. Examples: "alice@example.com", "system:serviceaccount:default:my-sa" |
||
limit integer |
Limit sets the maximum number of results per page. Default: 100, Maximum: 1000. |
||
continue string |
Continue is the pagination cursor for fetching additional pages. Leave empty for the first page. Copy status.continue here to get the next page. Keep all other parameters identical across paginated requests. |
ActivityQueryStatus contains the query results and pagination state.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
results Activity array |
Results contains matching activities, sorted newest-first. | ||
continue string |
Continue is the pagination cursor. Non-empty means more results are available. |
||
effectiveStartTime string |
EffectiveStartTime is the actual start time used (RFC3339 format). Shows the resolved timestamp when relative times are used. |
||
effectiveEndTime string |
EffectiveEndTime is the actual end time used (RFC3339 format). Shows the resolved timestamp when relative times are used. |
ActivityResource identifies the Kubernetes resource affected by an activity.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiGroup string |
APIGroup is the API group of the resource. Empty string for core API group. |
||
apiVersion string |
APIVersion is the API version of the resource. | ||
kind string |
Kind is the kind of the resource. | ||
name string |
Name is the name of the resource. | ||
namespace string |
Namespace is the namespace of the resource. Empty for cluster-scoped resources. |
||
uid string |
UID is the unique identifier of the resource. |
ActivitySpec contains the translated activity details.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
summary string |
Summary is the human-readable description of what happened. Generated from ActivityPolicy templates. Example: "alice created HTTP proxy api-gateway" |
||
changeSource string |
ChangeSource indicates who initiated the change. Used to filter human actions from system reconciliation noise. Values: - "human": User action via kubectl, API, or UI - "system": Controller reconciliation, operator actions, scheduled jobs |
||
actor ActivityActor |
Actor identifies who performed the action. | ||
resource ActivityResource |
Resource identifies the Kubernetes resource that was affected. | ||
links ActivityLink array |
Links contains clickable references found in the summary. The portal uses these to make resource names in the summary clickable. |
||
tenant ActivityTenant |
Tenant identifies the scope for multi-tenant isolation. | ||
changes ActivityChange array |
Changes contains field-level changes for update/patch operations. Shows old and new values for modified fields. NOTE: This field may be empty in the initial implementation. Populating old values requires resource history lookups. |
||
origin ActivityOrigin |
Origin identifies the source record for correlation. |
ActivityTenant identifies the scope for multi-tenant isolation.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type string |
Type is the scope level. Values: "global", "organization", "project", "user" |
||
name string |
Name is the tenant identifier within the scope type. |
AuditLogFacetsQuerySpec defines which facets to retrieve from audit logs.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
timeRange FacetTimeRange |
TimeRange limits the time window for facet aggregation. If not specified, defaults to the last 7 days. |
||
filter string |
Filter narrows the audit logs before computing facets using CEL. This allows you to get facet values for a subset of audit logs. Available Fields: verb - API action: get, list, create, update, patch, delete, watch user.username - who made the request (user or service account) user.uid - unique user identifier 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.apiGroup - API group of the resource objectRef.name - specific resource name Operators: ==, !=, <, >, <=, >=, &&, ||, !, in String Functions: startsWith(), endsWith(), contains() Examples: "verb in ['create', 'update', 'delete']" - Facets for write operations only "!(verb in ['get', 'list', 'watch'])" - Exclude read-only operations "!user.username.startsWith('system:')" - Exclude system users "objectRef.namespace == 'production'" - Facets for production namespace |
||
facets FacetSpec array |
Facets specifies which fields to get distinct values for. Each facet returns the top N values with counts. Supported fields: - verb: API action (get, list, create, update, patch, delete, watch) - user.username: Actor display names - user.uid: Unique user identifiers - responseStatus.code: HTTP response codes - objectRef.namespace: Namespaces - objectRef.resource: Resource types - objectRef.apiGroup: API groups |
AuditLogFacetsQueryStatus contains the facet results.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
facets FacetResult array |
Facets contains the results for each requested facet. |
AuditLogQuerySpec defines the search parameters.
Required: startTime and endTime define your search window. Optional: filter (narrow results), limit (page size, default 100), continue (pagination).
Performance: Smaller time ranges and specific filters perform better. The maximum time window is typically 30 days. If your range is too large, you'll get an error with guidance on splitting your query into smaller chunks.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
startTime string |
StartTime is the beginning of your search window (inclusive). Format Options: - Relative: "now-30d", "now-2h", "now-30m" (units: s, m, h, d, w) Use for dashboards and recurring queries - they adjust automatically. - Absolute: "2024-01-01T00:00:00Z" (RFC3339 with timezone) Use for historical analysis of specific time periods. Examples: "now-30d" → 30 days ago "2024-06-15T14:30:00-05:00" → specific time with timezone offset |
||
endTime string |
EndTime is the end of your search window (exclusive). Uses the same formats as StartTime. Commonly "now" for current moment. Must be greater than StartTime. Examples: "now" → current time "2024-01-02T00:00:00Z" → specific end point |
||
filter string |
Filter narrows results using CEL (Common Expression Language). Leave empty to get all events. Available Fields: verb - API action: get, list, create, update, patch, delete, watch auditID - unique event identifier requestReceivedTimestamp - when the API server received the request (RFC3339 timestamp) user.username - who made the request (user or service account) user.uid - unique user identifier (stable across username changes) 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 Operators: ==, !=, <, >, <=, >=, &&, ||, !, in String Functions: startsWith(), endsWith(), contains() Common Patterns: "verb == 'delete'" - All deletions "objectRef.namespace == 'production'" - Activity in production namespace "verb in ['create', 'update', 'delete', 'patch']" - All write operations "!(verb in ['get', 'list', 'watch'])" - Exclude read-only operations "responseStatus.code >= 400" - Failed requests "user.username.startsWith('system:serviceaccount:')" - Service account activity "!user.username.startsWith('system:')" - Exclude system users "user.uid == '550e8400-e29b-41d4-a716-446655440000'" - Specific user by UID "objectRef.resource == 'secrets'" - Secret access "verb == 'delete' && objectRef.namespace == 'production'" - Production deletions Note: Use single quotes for strings. Field names are case-sensitive. CEL reference: https://cel.dev |
||
limit integer |
Limit sets the maximum number of results per page. Default: 100, Maximum: 1000. Use smaller values (10-50) for exploration, larger (500-1000) for data collection. Use continue to fetch additional pages. |
||
continue string |
Continue is the pagination cursor for fetching additional pages. Leave empty for the first page. If status.continue is non-empty after a query, copy that value here in a new query with identical parameters to get the next page. Repeat until status.continue is empty. Important: Keep all other parameters (startTime, endTime, filter, limit) identical across paginated requests. The cursor is opaque - copy it exactly without modification. |
AuditLogQueryStatus contains the query results and pagination state.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
results Event array |
Results contains matching audit events, sorted newest-first. Each event follows the Kubernetes audit.Event format with fields like: verb, user.username, objectRef.{namespace,resource,name}, requestReceivedTimestamp, stageTimestamp, responseStatus.code, requestObject, responseObject Empty results? Try broadening your filter or time range. Full documentation: https://kubernetes.io/docs/reference/config-api/apiserver-audit.v1/ |
||
continue string |
Continue is the pagination cursor. Non-empty means more results are available - copy this to spec.continue for the next page. Empty means you have all results. |
||
effectiveStartTime string |
EffectiveStartTime is the actual start time used for this query (RFC3339 format). When you use relative times like "now-7d", this shows the exact timestamp that was calculated. Useful for understanding exactly what time range was queried, especially for auditing, debugging, or recreating queries with absolute timestamps. Example: If you query with startTime="now-7d" at 2025-12-17T12:00:00Z, this will be "2025-12-10T12:00:00Z". |
||
effectiveEndTime string |
EffectiveEndTime is the actual end time used for this query (RFC3339 format). When you use relative times like "now", this shows the exact timestamp that was calculated. Useful for understanding exactly what time range was queried. Example: If you query with endTime="now" at 2025-12-17T12:00:00Z, this will be "2025-12-17T12:00:00Z". |
AutoFetchSpec configures automatic sample data retrieval.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
limit integer |
Limit is the maximum number of sample inputs to fetch (default: 10, max: 50). The API fetches up to this many audit logs and/or events. |
10 | Maximum: 50 Minimum: 1 |
timeRange string |
TimeRange specifies how far back to look for samples (default: "24h"). Supports relative format: "1h", "24h", "7d", "30d" |
24h | |
sources string |
Sources specifies which data sources to query: "audit", "events", or "both" (default: "both"). - "audit": Only fetch audit logs (only tests auditRules) - "events": Only fetch Kubernetes events (only tests eventRules) - "both": Fetch both types (tests all rules) |
both | Enum: [audit events both] |
EventFacetQuerySpec defines which facets to retrieve from Kubernetes Events.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
timeRange FacetTimeRange |
TimeRange limits the time window for facet aggregation. If not specified, defaults to the last 7 days. |
||
facets FacetSpec array |
Facets specifies which fields to get distinct values for. Each facet returns the top N values with counts. Supported fields: - regarding.kind: Resource kinds (Pod, Deployment, etc.) - regarding.namespace: Namespaces of regarding objects - reason: Event reasons (Scheduled, Pulled, Created, etc.) - type: Event types (Normal, Warning) - source.component: Source components (kubelet, scheduler, etc.) - namespace: Event namespace |
EventFacetQueryStatus contains the facet results.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
facets FacetResult array |
Facets contains the results for each requested facet. |
EventQuery searches Kubernetes Events stored in ClickHouse.
Unlike the native Events list (limited to 24 hours), EventQuery supports up to 60 days of history. Results are returned in the Status field, ordered newest-first.
Quick Start:
apiVersion: activity.miloapis.com/v1alpha1
kind: EventQuery
metadata:
name: recent-pod-failures
spec:
startTime: "now-7d" # last 7 days
endTime: "now"
namespace: "production" # optional: limit to namespace
fieldSelector: "type=Warning" # optional: standard K8s field selector
limit: 100
Time Formats:
- Relative: "now-30d" (great for dashboards and recurring queries)
- Absolute: "2024-01-01T00:00:00Z" (great for historical analysis)
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec EventQuerySpec |
|||
status EventQueryStatus |
EventQuerySpec defines the search parameters.
Required: startTime and endTime define your search window (max 60 days). Optional: namespace (limit to namespace), fieldSelector (standard K8s syntax), limit (page size, default 100), continue (pagination).
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
startTime string |
StartTime is the beginning of your search window (inclusive). Format Options: - Relative: "now-30d", "now-2h", "now-30m" (units: s, m, h, d, w) Use for dashboards and recurring queries - they adjust automatically. - Absolute: "2024-01-01T00:00:00Z" (RFC3339 with timezone) Use for historical analysis of specific time periods. Maximum lookback is 60 days from now. Examples: "now-7d" → 7 days ago "2024-06-15T14:30:00-05:00" → specific time with timezone offset |
||
endTime string |
EndTime is the end of your search window (exclusive). Uses the same formats as StartTime. Commonly "now" for the current moment. Must be greater than StartTime. Examples: "now" → current time "2024-01-02T00:00:00Z" → specific end point |
||
namespace string |
Namespace limits results to events from a specific namespace. Leave empty to query events across all namespaces. |
||
fieldSelector string |
FieldSelector filters events using standard Kubernetes field selector syntax. Supported Fields: metadata.name - event name metadata.namespace - event namespace metadata.uid - event UID regarding.apiVersion - regarding resource API version regarding.kind - regarding resource kind (e.g., Pod, Deployment) regarding.namespace - regarding resource namespace regarding.name - regarding resource name regarding.uid - regarding resource UID regarding.fieldPath - regarding resource field path reason - event reason (e.g., FailedMount, Pulled) type - event type (Normal or Warning) source.component - reporting component source.host - reporting host reportingComponent - reporting component (alias for source.component) reportingInstance - reporting instance (alias for source.host) Operators: = (or ==), != Multiple conditions: comma-separated (all must match) Common Patterns: "type=Warning" - Warning events only "regarding.kind=Pod" - Events for pods "reason=FailedMount" - Mount failure events "regarding.name=my-pod,type=Warning" - Warnings for a specific pod |
||
limit integer |
Limit sets the maximum number of results per page. Default: 100, Maximum: 1000. Use smaller values (10-50) for exploration, larger (500-1000) for data collection. Use continue to fetch additional pages. |
||
continue string |
Continue is the pagination cursor for fetching additional pages. Leave empty for the first page. If status.continue is non-empty after a query, copy that value here in a new query with identical parameters to get the next page. Repeat until status.continue is empty. Important: Keep all other parameters (startTime, endTime, namespace, fieldSelector, limit) identical across paginated requests. The cursor is opaque - copy it exactly without modification. |
EventQueryStatus contains the query results and pagination state.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
results EventRecord array |
Results contains matching Kubernetes Events, sorted newest-first. Each event follows the eventsv1.Event format with fields like: regarding.{kind,name,namespace}, reason, note, type, eventTime, series.count, reportingController Empty results? Try broadening your field selector or time range. |
||
continue string |
Continue is the pagination cursor. Non-empty means more results are available - copy this to spec.continue for the next page. Empty means you have all results. |
||
effectiveStartTime string |
EffectiveStartTime is the actual start time used for this query (RFC3339 format). When you use relative times like "now-7d", this shows the exact timestamp that was calculated. Useful for understanding exactly what time range was queried, especially for auditing, debugging, or recreating queries with absolute timestamps. Example: If you query with startTime="now-7d" at 2025-12-17T12:00:00Z, this will be "2025-12-10T12:00:00Z". |
||
effectiveEndTime string |
EffectiveEndTime is the actual end time used for this query (RFC3339 format). When you use relative times like "now", this shows the exact timestamp that was calculated. Useful for understanding exactly what time range was queried. Example: If you query with endTime="now" at 2025-12-17T12:00:00Z, this will be "2025-12-17T12:00:00Z". |
EventRecord represents a Kubernetes Event returned in EventQuery results. This is a wrapper type registered under activity.miloapis.com/v1alpha1 that embeds the events.k8s.io/v1 Event to avoid OpenAPI GVK conflicts while preserving full event data.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
event Event |
Event contains the full Kubernetes Event data in events.k8s.io/v1 format. This includes fields like eventTime, regarding, note, type, reason, reportingController, reportingInstance, series, and action. |
FacetResult contains the distinct values for a single facet.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
field string |
Field is the field path that was queried. | ||
values FacetValue array |
Values contains the distinct values and their counts. |
FacetSpec defines a single facet to retrieve.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
field string |
Field is the activity field path to get distinct values for. Supported fields: - spec.actor.name: Actor display names - spec.actor.type: Actor types (user, serviceaccount, controller) - spec.resource.apiGroup: API groups - spec.resource.kind: Resource kinds - spec.resource.namespace: Namespaces - spec.changeSource: Change sources (human, system) |
||
limit integer |
Limit is the maximum number of distinct values to return. Default: 20, Maximum: 100. |
FacetTimeRange specifies the time window for facet queries.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
start string |
Start is the beginning of the time window (inclusive). Supports RFC3339 timestamps and relative times (e.g., "now-7d"). |
||
end string |
End is the end of the time window (exclusive). Supports RFC3339 timestamps and relative times. Defaults to "now". |
FacetValue represents a single distinct value with its occurrence count.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
value string |
Value is the distinct field value. | ||
count integer |
Count is the number of activities with this value. |
PolicyPreviewInput contains the sample input for policy testing.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type string |
Type indicates whether this is an audit log or event input. Values: "audit", "event" |
||
audit Event |
Audit contains a sample audit log entry. Required when Type is "audit". |
||
event RawExtension |
Event contains a sample Kubernetes event. Required when Type is "event". Uses RawExtension to allow flexible event structure. |
PolicyPreviewInputResult contains the result for a single input.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
inputIndex integer |
InputIndex is the index of this input in spec.inputs (0-based). | ||
matched boolean |
Matched indicates whether any rule matched this input. | ||
matchedRuleIndex integer |
MatchedRuleIndex is the index of the rule that matched (0-based). -1 if no rule matched. |
||
matchedRuleType string |
MatchedRuleType indicates whether the matched rule was an audit or event rule. Empty if no rule matched. |
||
matchedRuleName string |
MatchedRuleName is the name of the rule that matched this input. This is the value from the rule's Name field in the policy spec. Empty if no rule matched. |
||
error string |
Error contains any error message if evaluating this input failed. This could be a CEL compilation error or evaluation error. |
PolicyPreviewSpec defines the policy and inputs to test.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
policy ActivityPolicySpec |
Policy is the ActivityPolicy spec to test. You can use the full spec from an existing policy or create a new one. |
||
inputs PolicyPreviewInput array |
Inputs contains sample audit logs and/or events to test against the policy. Each input is evaluated independently and produces an Activity if a rule matches. You can mix audit logs and events in the same request. Optional when AutoFetch is specified. |
||
autoFetch AutoFetchSpec |
AutoFetch automatically retrieves sample inputs based on the policy resource type. When specified, the API queries recent audit logs and/or events matching the policy. Mutually exclusive with manual inputs - only one should be provided. |
||
kindLabel string |
KindLabel overrides the display label for the resource kind. | ||
kindLabelPlural string |
KindLabelPlural overrides the plural display label. |
PolicyPreviewStatus contains the preview results.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
activities Activity array |
Activities contains the rendered Activity objects for inputs that matched a rule. The order corresponds to the order of matched inputs (not necessarily the input order). Inputs that don't match any rule are not included here. |
||
results PolicyPreviewInputResult array |
Results contains detailed results for each input, in the same order as spec.inputs. Use this to see which inputs matched and any errors that occurred. |
||
fetchedInputs PolicyPreviewInput array |
FetchedInputs contains the auto-fetched sample inputs (only present when autoFetch was used). This allows clients to see what data was tested. |
||
error string |
Error contains a general error message if the preview failed entirely. Individual input errors are reported in results[].error. |
ReindexConfig contains processing configuration options.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
batchSize integer |
BatchSize is the number of events to process per batch. Larger batches are faster but use more memory. Default: 1000 |
1000 | Maximum: 10000 Minimum: 100 |
rateLimit integer |
RateLimit is the maximum events per second to process. Prevents overwhelming ClickHouse. Default: 100 |
100 | Maximum: 1000 Minimum: 10 |
dryRun boolean |
DryRun previews changes without writing activities. Useful for estimating impact before execution. Default: false |
ReindexJob triggers re-processing of historical audit logs and events through current ActivityPolicy rules. Use this to fix policy bugs retroactively, add coverage for new policies, or refine activity summaries after policy improvements.
ReindexJob is a one-shot resource: once completed or failed, it cannot be re-run. Create a new ReindexJob for subsequent re-indexing operations.
KUBERNETES EVENT LIMITATION:
When a Kubernetes Event is updated (e.g., count incremented from 1 to 5), it retains the same UID. Re-indexing will produce ONE activity per Event UID, reflecting the Event's final state. Historical activity occurrences from earlier Event states are lost.
Example: Event "pod-oom" fires 5 times (count=5) → Re-indexing produces 1 activity (not 5)
Mitigation: Scope re-indexing to audit logs only via spec.policySelector to preserve activities from earlier Event occurrences.
Example:
kubectl apply -f - <<EOF
apiVersion: activity.miloapis.com/v1alpha1
kind: ReindexJob
metadata:
name: fix-policy-bug-2026-02-27
spec:
timeRange:
startTime: "now-7d" # last 7 days (or use absolute: "2026-02-25T00:00:00Z")
endTime: "now" # defaults to "now" if omitted
policySelector:
names: ["httpproxy-policy"]
EOF
kubectl get reindexjobs -w # Watch progress
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec ReindexJobSpec |
|||
status ReindexJobStatus |
Underlying type: string
ReindexJobPhase represents the lifecycle phase of a ReindexJob.
Appears in:
| Field | Description |
|---|---|
Pending |
|
Running |
|
Succeeded |
|
Failed |
ReindexJobSpec defines the parameters for a re-indexing operation.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
timeRange ReindexTimeRange |
TimeRange specifies the time window of events to re-index. Events outside this range are not processed. |
||
policySelector ReindexPolicySelector |
PolicySelector optionally limits re-indexing to specific policies. If omitted, all active ActivityPolicies are evaluated. |
||
config ReindexConfig |
Config contains processing configuration options. | ||
ttlSecondsAfterFinished integer |
TTLSecondsAfterFinished limits the lifetime of a ReindexJob after it finishes execution (either Succeeded or Failed). If set, the controller will delete the ReindexJob resource after it has been in a terminal state for this many seconds. This field is optional. If unset, completed jobs are retained indefinitely. Example: Setting to 3600 (1 hour) allows users to inspect job results for an hour after completion, after which the job is automatically cleaned up. |
Minimum: 0 |
ReindexJobStatus represents the current state of a ReindexJob.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
phase ReindexJobPhase |
Phase is the current lifecycle phase. Values: Pending, Running, Succeeded, Failed |
||
message string |
Message is a human-readable description of the current state. | ||
progress ReindexProgress |
Progress contains detailed progress information. | ||
startedAt Time |
StartedAt is when processing began. | ||
completedAt Time |
CompletedAt is when processing finished (success or failure). | ||
conditions Condition array |
Conditions represent the latest observations of the job's state. |
ReindexPolicySelector specifies which policies to include in re-indexing.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
names string array |
Names is a list of ActivityPolicy names to include. Mutually exclusive with MatchLabels. |
||
matchLabels object (keys:string, values:string) |
MatchLabels selects policies by label. Mutually exclusive with Names. |
ReindexProgress contains detailed progress metrics.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
totalEvents integer |
TotalEvents is the estimated total events to process. | ||
processedEvents integer |
ProcessedEvents is the number of events processed so far. | ||
activitiesGenerated integer |
ActivitiesGenerated is the number of activities created. | ||
errors integer |
Errors is the count of non-fatal errors encountered. | ||
currentBatch integer |
CurrentBatch is the batch number currently being processed. | ||
totalBatches integer |
TotalBatches is the estimated total number of batches. |
ReindexTimeRange specifies the time window for re-indexing.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
startTime string |
StartTime is the beginning of the time range (inclusive). Must be within the ClickHouse retention window (60 days). Format Options: - Relative: "now-30d", "now-2h", "now-30m" (units: s, m, h, d, w) Use for recent time windows - they adjust automatically at job start. - Absolute: "2026-02-01T00:00:00Z" (RFC3339 with timezone) Use for specific historical time periods. Examples: "now-7d" → 7 days before job starts "2026-02-25T00:00:00Z" → specific time with UTC "2026-02-25T00:00:00-08:00" → specific time with timezone offset Note: Relative times are resolved when the job STARTS processing, not when the resource is created. This ensures consistent time ranges even if the job is queued. |
||
endTime string |
EndTime is the end of the time range (exclusive). Defaults to "now" (job start time) if omitted. Uses the same formats as StartTime. Must be greater than StartTime. Examples: "now" → current time when job starts "2026-03-01T00:00:00Z" → specific end point "now-1h" → 1 hour before job starts |