# 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](#output-format). ### How It Works 1. A diagnostic setting on the AKS cluster sends `kube-audit-admin` (or `kube-audit`) logs to a Log Analytics workspace or an event hub. 2. 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. 3. Records from other categories, and (when a cluster is configured) other clusters, are skipped. 4. 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:** 1. Open your AKS cluster and go to **Monitoring** → **Diagnostic settings** → **Add diagnostic setting**. 2. Under **Logs**, select **Kubernetes Audit Admin Logs** (`kube-audit-admin`) or **Kubernetes Audit** (`kube-audit`). 3. 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. 4. Click **Save**. **Using the Azure CLI (Log Analytics):** ```bash az monitor diagnostic-settings create \ --name aks-audit-to-monad \ --resource \ --logs '[{"category":"kube-audit-admin","enabled":true}]' \ --workspace \ --export-to-resource-specific true ``` **Using the Azure CLI (Event Hubs):** ```bash az monitor diagnostic-settings create \ --name aks-audit-to-monad \ --resource \ --logs '[{"category":"kube-audit-admin","enabled":true}]' \ --event-hub \ --event-hub-rule /authorizationRules/RootManageSharedAccessKey ``` Logs can take **up to 90 minutes** to start flowing after a diagnostic setting is created. :::warning 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. 1. In **Microsoft Entra ID** → **App registrations**, click **New registration**, name it, and register it. No API permissions are needed. 2. From the app's **Overview**, copy the **Application (client) ID** and **Directory (tenant) ID**. 3. Under **Certificates & secrets**, create a **New client secret** and copy its **Value** (it is only shown once). 4. 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](../../guides/egress-ip-addresses.mdx) 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](#1-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](#ingestion-delay-log-analytics). | #### 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](https://kubernetes.io/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Event), with an added `aks` object: ```json { "kind": "Event", "apiVersion": "audit.k8s.io/v1", "level": "Metadata", "auditID": "5f0e7c2a-9b1d-4e3f-8a6c-2d4b1e9f7a30", "stage": "ResponseComplete", "requestURI": "/api/v1/namespaces/payments/secrets/db-credentials", "verb": "delete", "user": { "username": "user@example.com", "groups": ["system:authenticated"] }, "sourceIPs": ["203.0.113.42"], "userAgent": "kubectl/v1.31.2 (darwin/arm64) kubernetes/5864a46", "objectRef": { "resource": "secrets", "namespace": "payments", "name": "db-credentials", "apiVersion": "v1" }, "responseStatus": { "metadata": {}, "code": 200 }, "requestReceivedTimestamp": "2026-11-05T10:14:22.104512Z", "stageTimestamp": "2026-11-05T10:14:22.118930Z", "annotations": { "authorization.k8s.io/decision": "allow", "authorization.k8s.io/reason": "RBAC: allowed by ClusterRoleBinding \"cluster-admin\" of ClusterRole \"cluster-admin\"" }, "aks": { "cluster_resource_id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-example/providers/Microsoft.ContainerService/managedClusters/aks-example", "category": "kube-audit-admin", "source": "event_hubs", "pod_name": "kube-apiserver-7d9f8b6c5-abcde" } } ``` | `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_category` are collected. Event hubs often carry diagnostic logs from other resources too; these are skipped. - **Cluster:** when `cluster_resource_id` is 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, and `aks.cluster_resource_id` tells 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 include `impersonatedUser`. The Event Hubs source passes the full audit event through, including `impersonatedUser` when a request used impersonation. - **Large objects:** when a request or response object is too large, AKS records the string `skipped-too-big-size-object` in its place in Log Analytics; this input drops that placeholder, so `requestObject`/`responseObject` are 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 `60` seconds, which suits most workspaces. The default applies however the input is created (UI, API or Terraform), and an explicit `0` also 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 (`AKSAuditAdmin` or `AKSAudit`) 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](https://learn.microsoft.com/en-us/azure/aks/monitor-aks-reference#resource-logs) - [Diagnostic settings in Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/platform/diagnostic-settings) - [AKSAuditAdmin table reference](https://learn.microsoft.com/en-us/azure/azure-monitor/reference/tables/aksauditadmin) - [AKSAudit table reference](https://learn.microsoft.com/en-us/azure/azure-monitor/reference/tables/aksaudit) - [Kubernetes Audit Event Specification](https://kubernetes.io/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Event) ## 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](/docs/guides/sync-frequency) for details.