Workload Events

Workload events record what happened when a workload interacted with the SPIFFE Workload API. They capture whether the caller was attested, which selectors the attestor plugins produced, and which SVIDs, if any, were delivered.

This is distinct from the two other records Connect keeps about workloads. Audit logs record actions taken against the Connect API, such as a user creating an attestation policy. If a complete record of control plane actions is what you need, that is the page to read. The Connect workload API tracks an inventory of current and previous workloads. Workload events describe interactions that occurred between workloads and the SPIFFE Workload API.

Events are emitted by Cofide SPIRE agents and published to Connect over SPIFFE mTLS. They are disabled by default and are enabled per SPIRE agent in the Helm values.

Event types

Each event has exactly one type.

workload_attested

Workload attestation succeeded and selectors were computed. The event is emitted before any identity is issued, once per FetchJWTSVID call and once per FetchX509SVID stream.

workload_attestation_failed

Workload attestation failed. The event carries the error reported by the agent, where one was available.

identity_delivered

An SVID was delivered to the workload. One event is emitted per delivered SVID, so a response carrying three X.509-SVIDs produces three events. The event carries the registration entry ID, the SPIFFE ID, and details of the SVID itself: serial number and validity window for an X.509-SVID, or audience, issue time and expiry for a JWT-SVID.

no_identity

The workload attested successfully but received no SVID, either because no registration entries matched its selectors or because all candidate identities were filtered out.

When events are emitted

Not every Workload API call produces an event. Events are emitted only by the two calls that issue an identity, FetchX509SVID and FetchJWTSVID. The calls that return trust bundles alone, FetchX509Bundles and FetchJWTBundles, and the ValidateJWTSVID call, are not recorded.

FetchX509SVID is a long-lived stream, and SPIRE resends the full response whenever anything affecting the workload’s identities changes, including trust bundle updates. Attestation happens once, when the stream opens, so a stream that stays open for a long time produces a single workload_attested event no matter how many responses it carries. A delivery is likewise only reported when the certificate itself is new, keyed on its serial number, so an identity_delivered event means the workload received an SVID that was not previously sent in the same stream. Rotation is still reported, because the serial number changes.

Cofide SPIRE agent closes the stream when no identity is issued. Most SPIFFE client libraries will automatically reconnect, so each retry attests again and produces a further pair of events. A misconfigured workload left running can therefore generate events continuously, which is worth bearing in mind alongside the buffer and retention behaviour described in Limitations.

Event fields

Alongside the type-specific detail above, every event carries:

• id - a unique identifier for the event
• observed_timestamp - when the agent observed the event
• agent_spiffe_id - the identity of the SPIRE agent that published the event
• org_id, trust_zone_id, cluster_id - the scope the event belongs to, taken from the publishing agent’s authenticated identity rather than from the event itself
• workload_id - a link to the workload inventory entry the event relates to, where Connect could resolve one
• caller_pid - the process ID of the workload that opened the Workload API connection, where the runtime exposes it
• selectors - the selectors observed during attestation
• selectors_incomplete - set when an attestor plugin failed, indicating that the selector set may not be exhaustive

Events are stored as an audit record and are kept when the workload, cluster or trust zone they refer to is deleted. Deleting a workload drops the link from its events to the inventory entry, but the events themselves, including their selectors and SPIFFE IDs, are retained.

Enabling workload events

Publishing is enabled per agent in the Helm values for its Cofide SPIRE agent deployment. See Deploy Cofide SPIRE for the required configuration. Enable it on every agent deployment you want events from, including those on nodes outside the cluster the SPIRE server runs in.

Viewing workload events

Events for a cluster are shown on the cluster detail page in the Connect UI, and events across your estate are shown on the Workloads page.

The ListWorkloadEvents RPC on the workload service returns the same data. See the API reference for the full message definitions.

Filters are combined with a logical AND, and each filter matches any of the values given for it:

• org_ids, trust_zone_ids, cluster_ids - restrict results to particular organizations, trust zones or clusters
• agent_spiffe_ids - restrict results to events published by particular SPIRE agents
• workload_ids - restrict results to events linked to particular workloads
• spiffe_ids, entry_ids - restrict results to identity_delivered events for particular SPIFFE IDs or registration entries
• event_types - restrict results to particular event types
• observed_after, observed_before - restrict results to a time range, inclusive of the lower bound and exclusive of the upper

Filters narrow results within what the caller is already permitted to see; they never widen it.

Results are ordered by observed timestamp, most recent first, and are paginated. The page size defaults to 100 and is capped at 1000. Pass the next_page_token from a response as the page_token of the following request to retrieve the next page.

Access control

Reading workload events is cluster-scoped and uses the ListWorkloadEvents action. Both the Cluster-owner and Cluster-viewer predefined roles include it, so anyone who can view a cluster’s workloads can also view its workload events.

Because events include SPIFFE IDs, registration entry IDs, selectors and caller process IDs, treat read access to them as equivalent to read access to the workload inventory.

Limitations

Publishing is at-most-once. Agents buffer events in memory and send them in batches over a long-lived stream, and a batch that has been handed to the transport can still be lost if the stream breaks before Connect processes it. If the agent produces events faster than they can be published, or cannot reach Connect for an extended period, the buffer fills and further events are dropped rather than queued indefinitely. Workload events are therefore a record of observed activity and not a guaranteed-complete ledger.

Events are not currently pruned, so the volume stored grows with Workload API activity.

Linking an event to a workload inventory entry is supported only for workloads reported by the Cofide Observer. Events published by SPIRE agents running on Kubernetes clusters without the Cofide Observer or outside Kubernetes are stored and are queryable by every other field, but never resolve to a workload.