From 610b82aaa99d99c9118cbabd0bde7adc54d98214 Mon Sep 17 00:00:00 2001 From: Qiming Date: Mon, 9 Apr 2018 23:47:09 +0800 Subject: [PATCH] Add back audit stages and audit levels (#8025) Documentation about audit stages and audit levels was somehow lost recently. This PR adds them back. Closes: #7907 --- docs/tasks/debug-application-cluster/audit.md | 60 +++++++++++++------ 1 file changed, 41 insertions(+), 19 deletions(-) diff --git a/docs/tasks/debug-application-cluster/audit.md b/docs/tasks/debug-application-cluster/audit.md index 749d8a89ae..2bdfeabab3 100644 --- a/docs/tasks/debug-application-cluster/audit.md +++ b/docs/tasks/debug-application-cluster/audit.md @@ -26,28 +26,49 @@ answer the following questions: [Kube-apiserver][kube-apiserver] performs auditing. Each request on each stage of its execution generates an event, which is then pre-processed according to -a certain policy and written to a backend. You can find more details about the -pipeline in the [design proposal][auditing-proposal]. +a certain policy and written to a backend. The policy determines what's recorded +and the backends persist the records. The current backend implementations +include logs files and webhooks. -**Note,** that audit logging feature increases apiserver memory consumption, since some context -required for auditing is stored for each request. Additionally, memory consumption depends on the -audit logging configuration. +Each request can be recorded with an associated "stage". The known stages are: + +- `RequestReceived` - The stage for events generated as soon as the audit + handler receives the request, and before it is delegated down the handler + chain. +- `ResponseStarted` - Once the response headers are sent, but before the + response body is sent. This stage is only generated for long-running requests + (e.g. watch). +- `ResponseComplete` - The response body has been completed and no more bytes + will be sent. +- `Panic` - Events generated when a panic occurred. + +**Note** The audit logging feature increases the memory consumption of the API +server because some context required for auditing is stored for each request. +Additionally, memory consumption depends on the audit logging configuration. +{: .note} ## Audit Policy Audit policy defines rules about what events should be recorded and what data -they should include. When an event is processed, it's compared against the list -of rules in order. The first matching rule sets the [audit level][auditing-level] -of the event. The audit policy object structure is defined in the -[`audit.k8s.io` API group][auditing-api]. +they should include. The audit policy object structure is defined in the +[`audit.k8s.io` API group][auditing-api]. When an event is processed, it's +compared against the list of rules in order. The first matching rule sets the +"audit level" of the event. The known audit levels are: + +- `None` - don't log events that match this rule. +- `Metadata` - log request metadata (requesting user, timestamp, resource, + verb, etc.) but not request or response body. +- `Request` - log event metadata and request body but not response body. + This does not apply for non-resource requests. +- `RequestResponse` - log event metadata, request and response bodies. + This does not apply for non-resource requests. You can pass a file with the policy to [kube-apiserver][kube-apiserver] using the `--audit-policy-file` flag. If the flag is omitted, no events are logged. -__Note:__ `kind` and `apiVersion` fields along with `rules` __must__ be provided -in the audit policy file. A policy with no (0) rules, or a policy that doesn't -provide valid `apiVersion` and `kind` values is treated as illegal. +Note that the `rules` field __must__ be provided in the audit policy file. +A policy with no (0) rules is treated as illegal. -Some example audit policy files: +Below is an example audit policy file: {% include code.html language="yaml" file="audit-policy.yaml" ghlink="/docs/tasks/debug-application-cluster/audit-policy.yaml" %} @@ -66,7 +87,7 @@ admins constructing their own audit profiles. ## Audit backends -Audit backends implement exporting audit events to an external storage. +Audit backends persist audit events to an external storage. [Kube-apiserver][kube-apiserver] out of the box provides two backends: - Log backend, which writes events to a disk @@ -320,9 +341,9 @@ plugin which supports full-text search and analytics. ## Legacy Audit -__Note:__ Legacy Audit is deprecated and is disabled by default since Kubernetes 1.8. Legacy Audit -will be removed in 1.12. To fallback to this legacy audit, disable the advanced auditing feature -using the `AdvancedAuditing` feature gate in [kube-apiserver][kube-apiserver]: +__Note:__ Legacy Audit is deprecated and is disabled by default since 1.8 and +will be removed in 1.12. To fallback to this legacy audit, disable the advanced +auditing feature using the `AdvancedAuditing` feature gate in [kube-apiserver][kube-apiserver]: ``` --feature-gates=AdvancedAuditing=false @@ -330,7 +351,9 @@ using the `AdvancedAuditing` feature gate in [kube-apiserver][kube-apiserver]: In legacy format, each audit log entry contains two lines: -1. The request line containing a unique ID to match the response and request metadata, such as the source IP, requesting user, impersonation information, resource being requested, etc. +1. The request line containing a unique ID to match the response and request + metadata, such as the source IP, requesting user, impersonation information, + resource being requested, etc. 2. The response line containing a unique ID matching the request line and the response code. Example output for `admin` user listing pods in the `default` namespace: @@ -361,7 +384,6 @@ and `audit-log-maxage` options. [kube-apiserver]: /docs/admin/kube-apiserver [auditing-proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/auditing.md -[auditing-level]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/auditing.md#levels [auditing-api]: https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/staging/src/k8s.io/apiserver/pkg/apis/audit/v1beta1/types.go [gce-audit-profile]: https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/cluster/gce/gci/configure-helper.sh#L735 [kubeconfig]: https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/