Skip to main content
Version: v2.12

Enabling the API Audit Log to Record System Events

You can enable the API audit log to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. When you enable this feature, all requests to the Rancher API and all responses from it are written to a log.

You can enable API Auditing during Rancher installation or upgrade.

Enabling API Audit Log

The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation.

API Audit Log Options

The usage below defines rules about what the audit log should record and what data it should include:

ParameterDescription
AUDIT_LOG_ENABLEDfalse - Disables the audit log (default setting).
true - Enables the audit log.
AUDIT_LEVEL0 - Log request and response metadata (default setting).
1 - Log request and response headers.
2 - Log request body.
3 - Log response body. Each log level is cumulative and each subsequent level logs the previous level data. Each log transaction for a request/response pair uses the same auditID value.

See Audit Level Logging for a table that displays what each setting logs.
AUDIT_LOG_PATHLog path for Rancher Server API. Default path is /var/log/auditlog/rancher-api-audit.log. You can mount the log directory to host.

Usage Example: AUDIT_LOG_PATH=/my/custom/path/
AUDIT_LOG_MAXAGEDefined the maximum number of days to retain old audit log files. Default is 10 days.
AUDIT_LOG_MAXBACKUPDefines the maximum number of audit log files to retain. Default is 10.
AUDIT_LOG_MAXSIZEDefines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M.

Audit Log Levels

The following table displays what parts of API transactions are logged for each AUDIT_LEVEL setting.

AUDIT_LEVEL SettingMetadataRequest HeadersResponse HeadersRequest BodyResponse Body
0
1
2
3

Audit Log policies

Audit log policies allow end users to configure redactions using AuditPolicy cluster-scoped CRs in addition to the default redactions and filters.

All configured audit log policies are additive.

Redaction policies for headers utilize a regular expression (regex) engine to redact headers, while a JSONPath engine is used to redact request/response headers.

The JSONPath engine does not support the script or filter expressions. For getting started with JSONPath expressions, a good resource to consult is Stafan Goessner's article on JSONPath.

The structure of an audit policy CR is as follows:

apiVersion: auditlog.cattle.io/v1
kind: AuditPolicy
spec:
enabled : true # true/false
# list of API request filters
filters:
- action: allow # allow/deny
# would allow logs sent to "/foo/some/endpoint" but not "/foo" or "/foobar".
requestURI: "/foo/.*"
# additionalRedactions allows configuration of redactions on headers using `jsonpath` expressions
additionalRedactions:
# redacts headers based on regex expressions
- headers:
- "Cache.*"
# paths redacts information from request and response bodies based on json path expressions
paths:
- "$.gitCommit"
verbosity:
level : 0 # matches the levels in the above audit log table
# request allows fine-grained control over which request data
# gets included. This overrides the behaviour of the generic verbosity.level
request:
headers : true # true/false
body : true # true/false
# response allows fine-grained control over which response data
# gets included. This overrides the behaviour of the generic verbosity.level
response:
headers : true # true/false
body: true # true/false

Examples

The following example shows only logging requests containing login in the request path to the audit log path:

apiVersion: auditlog.cattle.io/v1
kind: AuditPolicy
metadata:
name: filters
spec:
filters:
- action: deny
requestUri: ".*"
- action: allow
requestUri: ".*login.*"

The following example shows how to redact specific fields containing gitCommint in request/response bodies:

apiVersion: auditlog.cattle.io/v1
kind: AuditPolicy
metadata:
name: redactions
spec:
additionalRedactions:
- paths:
- "$.gitCommit"

Default redactions & filters

The audit log controller comes with default built-in redactions for common sensitive information.

Redacted headers

Generic headers:

  • Cookie
  • Set-Cookie
  • X-Api-Set-Cookie-Header
  • Authorization
  • X-Api-Tunnel-Params
  • X-Api-Tunnel-Token
  • X-Api-Auth-Header
  • X-Amz-Security-Token

Redacted body fields

Generic body fields:

  • credentials
  • applicationSecret
  • oauthCredential
  • serviceAccountCredential
  • spKey
  • spCert
  • certificate
  • privateKey
  • secretsEncryptionConfig
  • manifestUrl
  • insecureWindowsNodeCommand
  • insecureNodeCommand
  • insecureCommand
  • command
  • nodeCommand
  • windowsNodeCommand
  • clientRandom

Generic body regex redactor:

  • ".*([pP]assword|[Kk]ube[Cc]onfig|[Tt]oken).*"

Cluster Driver

By default, any API request with fields tied to cluster drivers will have any non public* or optional* fields redacted by the audit log controller.

Redacted URIs

Any endpoint containing secrets or configmaps will have relevant fields stripped from both the request and response bodies. Additionally, any endpoint containing /v3/imports/* will have its URI redacted.

Viewing API Audit Logs

Docker Install

Share the AUDIT_LOG_PATH directory (Default: /var/log/auditlog) with the host system. The log can be parsed by standard CLI tools or forwarded on to a log collection tool like Fluentd, Filebeat, Logstash, etc.

Kubernetes Install

Enabling the API Audit Log with the Helm chart install will create a rancher-audit-log sidecar container in the Rancher pod. This container will stream the log to standard output (stdout). You can view the log as you would any container log.

The rancher-audit-log container is part of the rancher pod in the cattle-system namespace.

CLI

kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log

Shipping the Audit Log

You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See Rancher Tools - Logging for details.

Audit Log Samples

After you enable auditing, each API request or response is logged by Rancher in the form of JSON. Each of the following code samples provide examples of how to identify each API transaction.

Metadata Level

If you set your AUDIT_LEVEL to 0, Rancher logs the metadata header for every API request, but neither the body nor the request and response headers. The metadata provides basic information about the API transaction, such as the transaction ID, the initiator of the transaction, the time it occurred, etc.

{
"auditID": "40bd4e40-875b-4020-933e-4c4f4c4db366",
"requestURI": "/v3/schemas",
"user": {
"name": "user-6j5s6",
"group": [
"system:authenticated",
"system:cattle:authenticated"
],
"extra": {
"principalid": [
"local://user-6j5s6"
],
"requesthost": [
"localhost:8443"
],
"requesttokenid": [
"token-zs42h"
],
"username": [
"admin"
]
}
},
"method": "GET",
"remoteAddr": "127.0.0.1:58652",
"responseCode": 200,
"requestTimestamp": "2025-06-30T11:13:25-04:00",
"responseTimestamp": "2025-06-30T11:13:25-04:00"
}

Metadata and headers level

If you set your AUDIT_LEVEL to 1, Rancher logs the metadata and the request and response headers for every API request.

{
"auditID": "f8c83dc6-a080-4e2e-ab43-552bddf01716",
"requestURI": "/v1/apps.deployments?page=1&pagesize=100&sort=metadata.name&filter=metadata.namespace!=p-npsl5&filter=metadata.namespace!=p-nzp6c&filter=metadata.namespace!=cattle-fleet-clusters-system&filter=metadata.namespace!=cattle-fleet-system&filter=metadata.namespace!=cattle-global-data&filter=metadata.namespace!=cattle-impersonation-system&filter=metadata.namespace!=cattle-provisioning-capi-system&filter=metadata.namespace!=cattle-system&filter=metadata.namespace!=cattle-ui-plugin-system&filter=metadata.namespace!=cluster-fleet-local-local-1a3d67d0a899&filter=metadata.namespace!=fleet-default&filter=metadata.namespace!=fleet-local&filter=metadata.namespace!=kube-node-lease&filter=metadata.namespace!=kube-public&filter=metadata.namespace!=kube-system&exclude=metadata.managedFields",
"user": {
"name": "user-6j5s6",
"group": [
"system:authenticated",
"system:cattle:authenticated"
],
"extra": {
"principalid": [
"local://user-6j5s6"
],
"requesthost": [
"localhost:8443"
],
"requesttokenid": [
"token-zs42h"
],
"username": [
"admin"
]
}
},
"method": "GET",
"remoteAddr": "127.0.0.1:58833",
"responseCode": 200,
"requestTimestamp": "2025-06-30T11:17:04-04:00",
"responseTimestamp": "2025-06-30T11:17:04-04:00",
"requestHeader": {
"Accept": [
"application/json"
],
"Accept-Encoding": [
"gzip, deflate, br, zstd"
],
"Accept-Language": [
"en-US,en;q=0.5"
],
"Connection": [
"keep-alive"
],
"Cookie": [
"[redacted]"
],
"Referer": [
"https://localhost:8443/dashboard/c/local/explorer/apps.deployment"
],
"Sec-Fetch-Dest": [
"empty"
],
"Sec-Fetch-Mode": [
"cors"
],
"Sec-Fetch-Site": [
"same-origin"
],
"User-Agent": [
"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0"
],
"X-Api-Csrf": [
"fccc690cab7b0c169b3fc6527edadef3"
]
},
"responseHeader": {
"Cache-Control": [
"no-cache, no-store, must-revalidate"
],
"Content-Encoding": [
"gzip"
],
"Content-Type": [
"application/json"
],
"Expires": [
"Wed 24 Feb 1982 18:42:00 GMT"
],
"X-Api-Cattle-Auth": [
"true"
],
"X-Api-Schemas": [
"https://localhost:8443/v1/schemas"
],
"X-Content-Type-Options": [
"nosniff"
]
}
}

Metadata, headers and Request Body Level

If you set your AUDIT_LEVEL to 2, Rancher logs the metadata, the request and response headers and the request body for every API request.

The code sample below depicts an API request, with both its metadata, headers and request body.

{
"auditID": "d1088a09-2a13-4450-970e-0d44bd2c49ee",
"requestURI": "/v3/projects",
"user": {
"name": "user-6j5s6",
"group": [
"system:authenticated",
"system:cattle:authenticated"
],
"extra": {
"principalid": [
"local://user-6j5s6"
],
"requesthost": [
"localhost:8443"
],
"requesttokenid": [
"token-zs42h"
],
"username": [
"admin"
]
}
},
"method": "POST",
"remoteAddr": "127.0.0.1:49966",
"responseCode": 201,
"requestTimestamp": "2025-06-30T12:32:13-04:00",
"responseTimestamp": "2025-06-30T12:32:13-04:00",
"requestHeader": {
"Accept": [
"application/json"
],
"Accept-Encoding": [
"gzip, deflate, br, zstd"
],
"Accept-Language": [
"en-US,en;q=0.5"
],
"Connection": [
"keep-alive"
],
"Content-Length": [
"214"
],
"Content-Type": [
"application/json"
],
"Cookie": [
"[redacted]"
],
"Impersonate-Extra-Principalid": [
"local://user-6j5s6"
],
"Impersonate-Extra-Requesthost": [
"localhost:8443"
],
"Impersonate-Extra-Requesttokenid": [
"token-zs42h"
],
"Impersonate-Extra-Username": [
"admin"
],
"Impersonate-Group": [
"system:authenticated",
"system:cattle:authenticated"
],
"Impersonate-User": [
"user-6j5s6"
],
"Origin": [
"https://localhost:8443"
],
"Priority": [
"u=0"
],
"Referer": [
"https://localhost:8443/dashboard/c/local/explorer/management.cattle.io.project/create"
],
"Sec-Fetch-Dest": [
"empty"
],
"Sec-Fetch-Mode": [
"cors"
],
"Sec-Fetch-Site": [
"same-origin"
],
"User-Agent": [
"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0"
],
"X-Api-Csrf": [
"fccc690cab7b0c169b3fc6527edadef3"
]
},
"responseHeader": {
"Cache-Control": [
"no-cache, no-store, must-revalidate"
],
"Content-Encoding": [
"gzip"
],
"Content-Type": [
"application/json"
],
"Expires": [
"Wed 24 Feb 1982 18:42:00 GMT"
],
"X-Api-Cattle-Auth": [
"true"
],
"X-Api-Schemas": [
"https://localhost:8443/v3/project/schemas"
],
"X-Content-Type-Options": [
"nosniff"
]
},
"requestBody": {
"annotations": {},
"clusterId": "local",
"containerDefaultResourceLimit": {},
"creatorId": "local://user-6j5s6",
"labels": {},
"name": "example-project",
"namespaceDefaultResourceQuota": {},
"resourceQuota": {},
"type": "project"
}
}

Metadata, Headers, Request Body and Response Body Level

If you set your AUDIT_LEVEL to 3, Rancher logs the metadata, request and response headers and request body and response.

The code sample below depicts an example of an API request with that information logged.

{
"auditID": "a9549a5b-4351-4bd5-adcd-12f7ec667a6b",
"requestURI": "/v3/projects",
"user": {
"name": "user-6j5s6",
"group": [
"system:authenticated",
"system:cattle:authenticated"
],
"extra": {
"principalid": [
"local://user-6j5s6"
],
"requesthost": [
"localhost:8443"
],
"requesttokenid": [
"token-zs42h"
],
"username": [
"admin"
]
}
},
"method": "POST",
"remoteAddr": "127.0.0.1:50454",
"responseCode": 201,
"requestTimestamp": "2025-06-30T12:42:24-04:00",
"responseTimestamp": "2025-06-30T12:42:24-04:00",
"requestHeader": {
"Accept": [
"application/json"
],
"Accept-Encoding": [
"gzip, deflate, br, zstd"
],
"Accept-Language": [
"en-US,en;q=0.5"
],
"Connection": [
"keep-alive"
],
"Content-Length": [
"214"
],
"Content-Type": [
"application/json"
],
"Cookie": [
"[redacted]"
],
"Impersonate-Extra-Principalid": [
"local://user-6j5s6"
],
"Impersonate-Extra-Requesthost": [
"localhost:8443"
],
"Impersonate-Extra-Requesttokenid": [
"token-zs42h"
],
"Impersonate-Extra-Username": [
"admin"
],
"Impersonate-Group": [
"system:authenticated",
"system:cattle:authenticated"
],
"Impersonate-User": [
"user-6j5s6"
],
"Origin": [
"https://localhost:8443"
],
"Priority": [
"u=0"
],
"Referer": [
"https://localhost:8443/dashboard/c/local/explorer/management.cattle.io.project/create"
],
"Sec-Fetch-Dest": [
"empty"
],
"Sec-Fetch-Mode": [
"cors"
],
"Sec-Fetch-Site": [
"same-origin"
],
"User-Agent": [
"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0"
],
"X-Api-Csrf": [
"fccc690cab7b0c169b3fc6527edadef3"
]
},
"responseHeader": {
"Cache-Control": [
"no-cache, no-store, must-revalidate"
],
"Content-Encoding": [
"gzip"
],
"Content-Type": [
"application/json"
],
"Expires": [
"Wed 24 Feb 1982 18:42:00 GMT"
],
"X-Api-Cattle-Auth": [
"true"
],
"X-Api-Schemas": [
"https://localhost:8443/v3/project/schemas"
],
"X-Content-Type-Options": [
"nosniff"
]
},
"requestBody": {
"annotations": {},
"clusterId": "local",
"containerDefaultResourceLimit": {},
"creatorId": "local://user-6j5s6",
"labels": {},
"name": "example-project",
"namespaceDefaultResourceQuota": {},
"resourceQuota": {},
"type": "project"
},
"responseBody": {
"actions": {
"exportYaml": "https://localhost:8443/v3/projects/local:p-qt6tq?action=exportYaml"
},
"annotations": {
"authz.management.cattle.io/creator-role-bindings": "{\"required\":[\"project-owner\"]}"
},
"backingNamespace": "local-p-qt6tq",
"baseType": "project",
"clusterId": "local",
"containerDefaultResourceLimit": {
"type": "/v3/schemas/containerResourceLimit"
},
"created": "2025-06-30T16:42:24Z",
"createdTS": 1751301744000,
"creatorId": "user-6j5s6",
"id": "local:p-qt6tq",
"labels": {
"cattle.io/creator": "norman"
},
"links": {
"basicAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/basicauths",
"certificates": "https://localhost:8443/v3/projects/local:p-qt6tq/certificates",
"configMaps": "https://localhost:8443/v3/projects/local:p-qt6tq/configmaps",
"cronJobs": "https://localhost:8443/v3/projects/local:p-qt6tq/cronjobs",
"daemonSets": "https://localhost:8443/v3/projects/local:p-qt6tq/daemonsets",
"deployments": "https://localhost:8443/v3/projects/local:p-qt6tq/deployments",
"dnsRecords": "https://localhost:8443/v3/projects/local:p-qt6tq/dnsrecords",
"dockerCredentials": "https://localhost:8443/v3/projects/local:p-qt6tq/dockercredentials",
"horizontalPodAutoscalers": "https://localhost:8443/v3/projects/local:p-qt6tq/horizontalpodautoscalers",
"ingresses": "https://localhost:8443/v3/projects/local:p-qt6tq/ingresses",
"jobs": "https://localhost:8443/v3/projects/local:p-qt6tq/jobs",
"namespacedBasicAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedbasicauths",
"namespacedCertificates": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedcertificates",
"namespacedDockerCredentials": "https://localhost:8443/v3/projects/local:p-qt6tq/namespaceddockercredentials",
"namespacedSecrets": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedsecrets",
"namespacedServiceAccountTokens": "[redacted]",
"namespacedSshAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/namespacedsshauths",
"persistentVolumeClaims": "https://localhost:8443/v3/projects/local:p-qt6tq/persistentvolumeclaims",
"pods": "https://localhost:8443/v3/projects/local:p-qt6tq/pods",
"projectNetworkPolicies": "https://localhost:8443/v3/projects/local:p-qt6tq/projectnetworkpolicies",
"projectRoleTemplateBindings": "https://localhost:8443/v3/projects/local:p-qt6tq/projectroletemplatebindings",
"remove": "https://localhost:8443/v3/projects/local:p-qt6tq",
"replicaSets": "https://localhost:8443/v3/projects/local:p-qt6tq/replicasets",
"replicationControllers": "https://localhost:8443/v3/projects/local:p-qt6tq/replicationcontrollers",
"secrets": "https://localhost:8443/v3/projects/local:p-qt6tq/secrets",
"self": "https://localhost:8443/v3/projects/local:p-qt6tq",
"serviceAccountTokens": "[redacted]",
"services": "https://localhost:8443/v3/projects/local:p-qt6tq/services",
"sshAuths": "https://localhost:8443/v3/projects/local:p-qt6tq/sshauths",
"statefulSets": "https://localhost:8443/v3/projects/local:p-qt6tq/statefulsets",
"subscribe": "https://localhost:8443/v3/projects/local:p-qt6tq/subscribe",
"update": "https://localhost:8443/v3/projects/local:p-qt6tq",
"workloads": "https://localhost:8443/v3/projects/local:p-qt6tq/workloads"
},
"name": "example-project",
"namespaceDefaultResourceQuota": {
"limit": {
"type": "/v3/schemas/resourceQuotaLimit"
},
"type": "/v3/schemas/namespaceResourceQuota"
},
"namespaceId": null,
"resourceQuota": {
"limit": {
"type": "/v3/schemas/resourceQuotaLimit"
},
"type": "/v3/schemas/projectResourceQuota",
"usedLimit": {
"type": "/v3/schemas/resourceQuotaLimit"
}
},
"state": "active",
"transitioning": "no",
"transitioningMessage": "",
"type": "project",
"uuid": "b582603b-7826-4302-8393-792df2611265"
}
}