public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-05-05 04:33:18 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
e30e3a4d18d8dfe9b972442e508eb666e0e58df7
rancher-docs/versioned_docs/version-2.13/how-to-guides/advanced-user-guides/enable-api-audit-log.md
T
Billy Tat 51a03551a5 Add v2.13 preview docs
2025-10-24 16:06:44 -07:00

685 lines
25 KiB
Markdown
Raw Blame History

---
title: Enabling the API Audit Log to Record System Events
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/enable-api-audit-log"/>
</head>
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.
- [Docker Install](../../reference-guides/single-node-rancher-in-docker/advanced-options.md#api-audit-log)
- [Kubernetes Install](../../getting-started/installation-and-upgrade/installation-references/helm-chart-options.md#api-audit-log)
## API Audit Log Options
The usage below defines rules about what the audit log should record and what data it should include:
| Parameter | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AUDIT_LOG_ENABLED` | `false` - Disables the audit log (default setting).<br/>`true` - Enables the audit log. |
| `AUDIT_LEVEL` | `0` - Log request and response metadata (default setting).<br/>`1` - Log request and response headers.<br/>`2` - Log request body.<br/>`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.<br/><br/>See [Audit Level Logging](#audit-log-levels) for a table that displays what each setting logs. |
| `AUDIT_LOG_PATH` | Log path for Rancher Server API. Default path is `/var/log/auditlog/rancher-api-audit.log`. You can mount the log directory to host. <br/><br/>Usage Example: `AUDIT_LOG_PATH=/my/custom/path/`<br/> |
| `AUDIT_LOG_MAXAGE` | Defined the maximum number of days to retain old audit log files. Default is 10 days. |
| `AUDIT_LOG_MAXBACKUP` | Defines the maximum number of audit log files to retain. Default is 10. |
| `AUDIT_LOG_MAXSIZE` | Defines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M. |
<br/>
### Audit Log Levels
The following table displays what parts of API transactions are logged for each [`AUDIT_LEVEL`](#api-audit-log-options) setting.
| `AUDIT_LEVEL` Setting | Metadata | Request Headers | Response Headers | Request Body | Response 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](#default-redactions--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](https://goessner.net/articles/JsonPath/).
The structure of an audit policy CR is as follows:
```yaml
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:
```yaml
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:
```yaml
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
```bash
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](../../integrations-in-rancher/logging/logging.md) 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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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"
}
}
```
Reference in New Issue View Git Blame Copy Permalink