AKS Audit Logs
Ingests Kubernetes API server audit logs from Azure Kubernetes Service (AKS) clusters, read from either a Log Analytics workspace or an Azure event hub. Audit logs record every request made to the Kubernetes control plane (who did what, to which object, and whether it was allowed), which makes them essential for security monitoring, compliance, and incident investigation.
Sync Type: Incremental
Overview
AKS does not expose audit logs through an API of its own. Instead, a diagnostic setting on the cluster routes the kube-audit or kube-audit-admin log category to a destination you choose. This input reads from one of two destinations:
| Source | How Monad reads it | Latency | Best for |
|---|---|---|---|
| Log Analytics | Queries the AKSAuditAdmin or AKSAudit table with KQL | Minutes (Log Analytics ingestion delay) | Clusters already sending diagnostics to a workspace |
| Event Hubs | Reads every partition of the event hub the diagnostic setting streams to | Seconds | Real-time collection; avoiding Log Analytics ingestion costs |
Whichever source you choose, Monad emits the same record: the native Kubernetes audit event plus an aks object identifying the cluster, category and source. See Output Format.
How It Works
- A diagnostic setting on the AKS cluster sends
kube-audit-admin(orkube-audit) logs to a Log Analytics workspace or an event hub. - Monad polls the configured source at regular intervals:
- Log Analytics: queries rows by ingestion time, in pages of 1,000, from the last checkpoint up to now minus the configured ingestion delay.
- Event Hubs: reads each partition from its last checkpointed position up to the newest event present when the sync started.
- Records from other categories, and (when a cluster is configured) other clusters, are skipped.
- Progress is checkpointed so each sync resumes where the previous one stopped.
Requirements
1. Choose a log category
| Category | Contains | Volume |
|---|---|---|
kube-audit-admin (recommended) | Every audit event except get and list requests: creates, updates, patches, deletes, exec, and so on | Lower |
kube-audit | Every API request, including get and list | Much higher |
Reads of Kubernetes secrets are get requests, so they only appear in kube-audit. Choose it if you need to know who read which secret, and account for the higher volume.
2. Create a diagnostic setting on the cluster
Using the Azure Portal:
- Open your AKS cluster and go to Monitoring → Diagnostic settings → Add diagnostic setting.
- Under Logs, select Kubernetes Audit Admin Logs (
kube-audit-admin) or Kubernetes Audit (kube-audit). - Under Destination details, choose one:
- Send to Log Analytics workspace: select the workspace, and set Destination table to Resource specific.
- Stream to an event hub: select the namespace and event hub.
- Click Save.
Using the Azure CLI (Log Analytics):
Code
Using the Azure CLI (Event Hubs):
Code
Logs can take up to 90 minutes to start flowing after a diagnostic setting is created.
For Log Analytics, the destination table must be Resource specific. In the legacy Azure diagnostics mode, AKS writes audit logs to the shared AzureDiagnostics table, which this input does not read.
3. Register an application and grant access
This input authenticates as a Microsoft Entra ID application (service principal) with a client secret.
- In Microsoft Entra ID → App registrations, click New registration, name it, and register it. No API permissions are needed.
- From the app's Overview, copy the Application (client) ID and Directory (tenant) ID.
- Under Certificates & secrets, create a New client secret and copy its Value (it is only shown once).
- Assign the app a role on the destination, under Access control (IAM) → Add role assignment:
| Source | Scope | Role |
|---|---|---|
| Log Analytics | The Log Analytics workspace | Log Analytics Reader |
| Event Hubs | The Event Hubs namespace (or the event hub) | Azure Event Hubs Data Receiver |
Role assignments can take several minutes to take effect.
4. Event Hubs only: network access
The Event Hubs source connects over AMQP on TCP port 5671. If the namespace restricts network access, add Monad egress IP addresses to its firewall under Networking.
We also recommend creating a dedicated consumer group for Monad (event hub → Consumer groups; requires the Standard tier or higher), so Monad's reads do not compete with other consumers of the same hub.
Configuration
Settings
| Setting | Type | Required | Default | Description |
|---|---|---|---|---|
source | object | Yes | - | Where the cluster's diagnostic setting sends its audit logs. Set source.type to log_analytics or event_hubs, and fill in the matching object below. |
cluster_resource_id | string | No | - | Full resource ID of one AKS cluster to collect from, e.g. /subscriptions/{id}/resourceGroups/{rg}/providers/Microsoft.ContainerService/managedClusters/{name}. Leave empty to collect from every cluster sending to this workspace or event hub. |
log_category | string | Yes | kube-audit-admin | The diagnostic log category to collect. Allowed values: kube-audit-admin, kube-audit. See Choose a log category. |
tenant_id | string | Yes | - | The tenant ID of the Entra ID directory associated with your Azure subscription. |
client_id | secret | Yes | - | The client ID of the Entra ID application. |
client_secret | secret | Yes | - | The client secret of the Entra ID application. |
backfill_start_time | date | No | - | Date to start fetching data from, in ISO 8601 format. If not specified, collection starts from the time the input is created. Limited by the source's retention. |
use_synthetic_data | bool | No | false | Generate synthetic data for testing, instead of connecting to a real data source. |
Source: Log Analytics (source.log_analytics)
| Setting | Type | Required | Default | Description |
|---|---|---|---|---|
workspace_id | string | Yes | - | The workspace ID (GUID) of the Log Analytics workspace the diagnostic setting writes to, from the workspace's Overview page. |
ingestion_delay | number | No | 60 | Seconds to hold back the newest rows, so rows that become queryable late are not skipped. Unset or 0 uses the default of 60. See Ingestion Delay. |
Source: Event Hubs (source.event_hubs)
| Setting | Type | Required | Default | Description |
|---|---|---|---|---|
namespace | string | Yes | - | The fully qualified namespace, e.g. your-namespace.servicebus.windows.net (no sb:// prefix or path). |
event_hub_name | string | Yes | - | The event hub the diagnostic setting streams to. |
consumer_group | string | Yes | $Default | The consumer group to read with. A dedicated consumer group is recommended. |
Output Format
Each record is a native Kubernetes audit event, with an added aks object:
Code
aks field | Description |
|---|---|
cluster_resource_id | Resource ID of the cluster that produced the event, as delivered by the source. Its letter case can differ between sources (Event Hubs delivers it in upper case), so compare it case-insensitively. |
category | The configured log category. |
source | log_analytics or event_hubs. |
pod_name | The API server pod that emitted the event. |
Audit events have one record per stage of a request (for example ResponseStarted and ResponseComplete), all sharing the same auditID. Use auditID together with stage to identify a record uniquely.
Details
Incremental Syncing
Log Analytics
- Rows are read in order of their ingestion time into the workspace (not the event time), so rows that arrive late are still collected.
- First sync: starts at Backfill Start Time, or at the time the input was created. History is limited by the workspace's retention.
- Subsequent syncs: resume from the last checkpointed ingestion time. Rows already emitted within the same second are not emitted again.
Event Hubs
- Monad keeps its own read position for each partition; it does not use the event hub's checkpoint store, so other consumers are unaffected.
- First sync: each partition starts at Backfill Start Time, or at the time the input was created.
- Subsequent syncs: each partition resumes right after the last event Monad read, including events whose records were all filtered out.
- Retention: events stay in an event hub only for its configured retention period: at most 1 day on the Basic tier, and 1 hour by default (up to 7 days) on the Standard tier. Premium and Dedicated allow up to 90 days. If an input is paused for longer than the retention period, the events in between are lost; Monad logs a warning naming the missing range. Set the retention longer than any downtime you expect.
Filtering
- Category: only records of the configured
log_categoryare collected. Event hubs often carry diagnostic logs from other resources too; these are skipped. - Cluster: when
cluster_resource_idis set, only that cluster's records are collected (case-insensitive). When empty, records from every AKS cluster sending to the workspace or event hub are collected, andaks.cluster_resource_idtells them apart. - Malformed events (Event Hubs): events that are not diagnostic-log envelopes, or whose audit event is not valid JSON, are skipped with a warning instead of stopping the pipeline.
Differences Between Sources
impersonatedUser: the Log Analytics audit tables have no column for it, so records from the Log Analytics source never includeimpersonatedUser. The Event Hubs source passes the full audit event through, includingimpersonatedUserwhen a request used impersonation.- Large objects: when a request or response object is too large, AKS records the string
skipped-too-big-size-objectin its place in Log Analytics; this input drops that placeholder, sorequestObject/responseObjectare absent for those events.
Ingestion Delay (Log Analytics)
Monad reads rows in order of their ingestion time and only moves forward. Log Analytics ingests data in batches, and a batch can become queryable slightly after a newer one. Without a delay, Monad could read the newer batch, move its checkpoint past the older one, and never read it.
The Ingestion Delay prevents this: each sync only reads rows ingested at least that many seconds ago, giving every batch time to become queryable before Monad moves past it. The cost is that much extra latency on every event.
How to choose a value:
- Leave it unset to use the default of
60seconds, which suits most workspaces. The default applies however the input is created (UI, API or Terraform), and an explicit0also means the default. - Raise it if you notice gaps in collected audit events, for example after a period of heavy cluster activity.
Test Connection
- Log Analytics: verifies the credentials and that the configured table (
AKSAuditAdminorAKSAudit) exists in the workspace and is readable. Azure creates the table only when the first audit logs arrive, so the test fails until then, which can take up to 90 minutes after the diagnostic setting is created. The table may be empty. - Event Hubs: verifies the credentials, network access and that the event hub has partitions.
Related Articles
- Monitor AKS: resource logs
- Diagnostic settings in Azure Monitor
- AKSAuditAdmin table reference
- AKSAudit table reference
- Kubernetes Audit Event Specification
Sync frequency
By default this input polls approximately every 10 seconds, with each sync beginning after the previous one completes. A cron schedule configured on the pipeline overrides this cadence. See Input Sync Frequency for details.