Audit Logging

3 minute read

Audit logging records all requests to the Kubernetes API server. Since PSKE 1.35, the auditing extension is available and configured via the Shoot manifest.

Shoot Manifest Configuration

The extension is enabled under spec.extensions. The audit backend and audit policy are referenced at the same time:

spec:
  extensions:
    - type: auditing
      providerConfig:
        apiVersion: auditing.extensions.gardener.cloud/v1alpha1
        kind: AuditConfiguration
        backends:
          - http:
              url: https://audit-backend.example.com/audit
              tls:
                secretReferenceName: audit-mtls-creds
            deliveryMode: Guaranteed
  resources:
    - name: audit-mtls-creds
      resourceRef:
        apiVersion: v1
        kind: Secret
        name: mtls-credentials
  kubernetes:
    kubeAPIServer:
      auditConfig:
        auditPolicy:
          configMapRef:
            name: audit-policy

Backend Configuration

Audit events are forwarded from the API server to an HTTP(S) endpoint. The supported backend type is http; the endpoint must support HTTPS with mTLS.

Field	Type	Description
`http.url`	string	HTTPS URL of the backend
`http.tls.secretReferenceName`	string	Reference to an entry in `spec.resources`
`http.compression`	string	Optional: `gzip`
`deliveryMode`	string	`Guaranteed` or `BestEffort`. When using multiple backends, exactly one must be `Guaranteed`.

mTLS Secret

The referenced secret must contain the following fields:

apiVersion: v1
kind: Secret
metadata:
  name: mtls-credentials
  namespace: garden-<project-name>-<id>
data:
  ca.crt: <base64>    # Optional: validate server certificate
  client.crt: <base64>
  client.key: <base64>

Multiple Backends

backends:
  - http:
      url: https://primary-backend.example.com/audit
    deliveryMode: Guaranteed
  - http:
      url: https://secondary-backend.example.com/audit
    deliveryMode: BestEffort

Audit Policy

The audit policy defines which API requests are logged and at what level of detail. It is created as a ConfigMap and referenced in the Shoot manifest.

apiVersion: v1
kind: ConfigMap
metadata:
  name: audit-policy
  namespace: garden-<project-name>-<id>
data:
  policy: |
    apiVersion: audit.k8s.io/v1
    kind: Policy
    rules:
      # Do not log read-only requests on non-sensitive resources
      - level: None
        verbs: ["get", "list", "watch"]
        resources:
          - group: ""
            resources: ["endpoints", "services", "configmaps"]

      # Log all other requests at metadata level
      - level: Metadata

Audit Levels

Level	Description
`None`	Do not log
`Metadata`	HTTP method, URL, user, timestamp — no body
`Request`	Additionally includes the request body
`RequestResponse`	Request and response body — generates very large amounts of data

Complete Example

The following three resources must be created in the Gardener project namespace (garden-<project-name>-<id>) before the extension becomes active.

Step 1 — Create the mTLS secret:

apiVersion: v1
kind: Secret
metadata:
  name: mtls-credentials
  namespace: garden-myproject-abc12
data:
  ca.crt: <base64 PEM CA bundle>
  client.crt: <base64 PEM client certificate>
  client.key: <base64 PEM client key>

Step 2 — Create the audit policy ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: audit-policy
  namespace: garden-myproject-abc12
data:
  policy: |
    apiVersion: audit.k8s.io/v1
    kind: Policy
    rules:
      - level: None
        verbs: ["get", "list", "watch"]
        resources:
          - group: ""
            resources: ["endpoints", "services", "configmaps"]
      - level: Metadata

Step 3 — Update the Shoot manifest:

apiVersion: core.gardener.cloud/v1beta1
kind: Shoot
metadata:
  name: my-cluster
  namespace: garden-myproject-abc12
spec:
  extensions:
    - type: auditing
      providerConfig:
        apiVersion: auditing.extensions.gardener.cloud/v1alpha1
        kind: AuditConfiguration
        backends:
          - http:
              url: https://audit-backend.example.com/audit
              tls:
                secretReferenceName: audit-mtls-creds
            deliveryMode: Guaranteed
  resources:
    - name: audit-mtls-creds
      resourceRef:
        apiVersion: v1
        kind: Secret
        name: mtls-credentials
  kubernetes:
    kubeAPIServer:
      auditConfig:
        auditPolicy:
          configMapRef:
            name: audit-policy

Notes

The audit policy ConfigMap must be created in the Gardener project namespace (garden-<project-name>-<id>), not in the cluster itself.
The auditlog-forwarder enriches each event with Gardener metadata (shoot name, seed name, etc.) before forwarding to the backend.
Verbose policies (RequestResponse applied broadly) can slow down the API server.

Last modified 29.04.2026: Correntcions (d9f3dab)