啟用 API 稽核日誌以記錄系統事件

您可以啟用 API 稽核日誌來記錄個別使用者發起的系統事件序列。您可以知道發生了什麼、何時發生、誰發起的，以及影響了哪個叢集。當您啟用此功能時，對 Rancher API 的所有請求和來自它的所有回應都會寫入日誌。

您可以在 Rancher 安裝或升級期間啟用 API 稽核。

啟用 API 稽核日誌

稽核日誌透過將環境變數傳遞給 Rancher 伺服器容器來啟用和設定。請參閱以下內容以在您的安裝上啟用。

API 稽核日誌選項

以下用法定義了有關稽核日誌應記錄什麼以及應包含哪些資料的規則：

參數	說明
`AUDIT_LOG_ENABLED`	`false` - 停用稽核日誌（預設設定）。 `true` - 啟用稽核日誌。
`AUDIT_LEVEL`	`0` - 記錄請求和回應中繼資料（預設設定）。 `1` - 記錄請求和回應標頭。 `2` - 記錄請求主體。 `3` - 記錄回應主體。每個日誌級別都是累積的，每個後續級別都會記錄前一級別的資料。請求/回應對的每個日誌交易使用相同的 `auditID` 值。有關顯示每個設定記錄內容的表格，請參閱稽核日誌級別。
`AUDIT_LOG_PATH`	Rancher 伺服器 API 的日誌路徑。預設路徑為 `/var/log/auditlog/rancher-api-audit.log`。您可以將日誌目錄掛載到主機。使用範例：`AUDIT_LOG_PATH=/my/custom/path/`
`AUDIT_LOG_MAXAGE`	定義保留舊稽核日誌檔案的最大天數。預設為 10 天。
`AUDIT_LOG_MAXBACKUP`	定義要保留的稽核日誌檔案的最大數量。預設為 10。
`AUDIT_LOG_MAXSIZE`	定義稽核日誌檔案在輪換前的最大大小（以 MB 為單位）。預設大小為 100M。

稽核日誌級別

下表顯示了針對每個 AUDIT_LEVEL 設定記錄 API 交易的哪些部分。

`AUDIT_LEVEL` 設定	中繼資料	請求標頭	回應標頭	請求主體	回應主體
0	✓
1	✓	✓	✓
2	✓	✓	✓	✓
3	✓	✓	✓	✓	✓

稽核日誌政策

稽核日誌政策允許終端使用者除了預設修訂和過濾器之外，還可以使用 AuditPolicy 叢集範圍的 CR 來設定修訂。

所有設定的稽核日誌政策都是累加的。

標頭的修訂政策使用正規表示式（regex）引擎來修訂標頭，而 JSONPath 引擎則用於修訂請求/回應標頭。

JSONPath 引擎不支援腳本或過濾器表達式。要開始使用 JSONPath 表達式，可以參考 Stafan Goessner 關於 JSONPath 的文章。

稽核政策 CR 的結構如下：

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

範例

以下範例顯示僅將請求路徑中包含 login 的請求記錄到稽核日誌路徑：

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

以下範例顯示如何修訂請求/回應主體中包含 gitCommint 的特定欄位：

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

預設修訂與過濾器

稽核日誌控制器預設內建了對常見敏感資訊的修訂。

已修訂的標頭

通用標頭：

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

已修訂的主體欄位

通用主體欄位：

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

通用主體正規表示式修訂器：

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

叢集驅動程式

預設情況下，任何與叢集驅動程式相關欄位的 API 請求都會由稽核日誌控制器修訂任何非 public* 或 optional* 欄位。

已修訂的 URI

任何包含 secrets 或 configmaps 的端點都會從請求和回應主體中剝離相關欄位。此外，任何包含 /v3/imports/* 的端點都會修訂其 URI。

查看 API 稽核日誌

Docker 安裝

與主機系統共享 AUDIT_LOG_PATH 目錄（預設：/var/log/auditlog）。日誌可以透過標準 CLI 工具解析，或轉發到日誌收集工具（如 Fluentd、Filebeat、Logstash 等）。

Kubernetes 安裝

使用 Helm chart 安裝啟用 API 稽核日誌將在 Rancher pod 中建立 rancher-audit-log sidecar 容器。此容器會將日誌串流到標準輸出（stdout）。您可以像查看任何容器日誌一樣查看日誌。

rancher-audit-log 容器是 cattle-system 命名空間中 rancher pod 的一部分。

CLI

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

傳送稽核日誌

您可以啟用 Rancher 內建的日誌收集和傳送功能，將稽核和其他服務日誌傳送到支援的收集端點。有關詳細資訊，請參閱 Rancher 工具 - 日誌記錄。

稽核日誌範例

啟用稽核後，Rancher 會以 JSON 格式記錄每個 API 請求或回應。以下每個程式碼範例都提供了如何識別每個 API 交易的範例。

中繼資料級別

如果您將 AUDIT_LEVEL 設定為 0，Rancher 會記錄每個 API 請求的中繼資料標頭，但不會記錄主體或請求和回應標頭。中繼資料提供有關 API 交易的基本資訊，例如交易 ID、交易發起者、發生時間等。

{
    "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"
}

中繼資料和標頭級別

如果您將 AUDIT_LEVEL 設定為 1，Rancher 會記錄每個 API 請求的中繼資料以及請求和回應標頭。

{
    "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"
        ]
    }
}

中繼資料、標頭和請求主體級別

如果您將 AUDIT_LEVEL 設定為 2，Rancher 會記錄每個 API 請求的中繼資料、請求和回應標頭以及請求主體。

以下程式碼範例描述了一個 API 請求，包含其中繼資料、標頭和請求主體。

{
    "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"
    }
}

中繼資料、標頭、請求主體和回應主體級別

如果您將 AUDIT_LEVEL 設定為 3，Rancher 會記錄中繼資料、請求和回應標頭以及請求主體和回應。

以下程式碼範例描述了記錄該資訊的 API 請求範例。

{
    "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"
    }
}