diff --git a/docs/admin/audit.md b/docs/admin/audit.md new file mode 100644 index 0000000000..c3a6fda6da --- /dev/null +++ b/docs/admin/audit.md @@ -0,0 +1,69 @@ +--- +assignees: +- soltysh +- sttts + +--- + +* TOC +{:toc} + +## Audit in Kubernetes + +Kubernetes Audit provides a security-relevant chronological set of records documenting +the sequence of activities that have affected system by individual users, administrators +or other components of the system. It allows cluster administrator to +answer the following questions: + - what happened? + - when did it happen? + - who initiated it? + - on what did it happen? + - where was it observed? + - from where was it initiated? + - to where was it going? + +NOTE: Currently, Kubernetes provides only basic audit capabilities, there is still a lot +of work going on to provide fully featured auditing capabilities (see https://github.com/kubernetes/features/issues/22). + +Kubernetes audit is part of [kube-apiserver](/docs/admin/kube-apiserver) logging all requests +coming to the server. Each audit log contains two entries: + +1. The request line containing: + - unique id allowing to match the response line (see 2) + - source ip of the request + - HTTP method being invoked + - original user invoking the operation + - impersonated user for the operation + - namespace of the request or + - URI as requested +2. The response line containing: + - the unique id from 1 + - response code + +Example output for user `admin` asking for a list of pods: + +``` +2016-09-07T13:03:57.400333046Z AUDIT: id="5c3b8227-4af9-4322-8a71-542231c3887b" ip="127.0.0.1" method="GET" user="admin" as="" namespace="default" uri="/api/v1/namespaces/default/pods" +2016-09-07T13:03:57.400710987Z AUDIT: id="5c3b8227-4af9-4322-8a71-542231c3887b" response="200" +``` + +NOTE: The audit capabilities are available *only* for the secured endpoint of the API server. + +## Configuration + +[Kube-apiserver](/docs/admin/kube-apiserver) provides following options which are responsible +for configuring where and how audit logs are handled: + +- `audit-log-path` - enables the audit log pointing to a file where the requests are being logged to. +- `audit-log-maxage` - specifies maximum number of days to retain old audit log files based on the timestamp encoded in their filename. +- `audit-log-maxbackup` - specifies maximum number of old audit log files to retain. +- `audit-log-maxsize` - specifies maximum size in megabytes of the audit log file before it gets rotated. Defaults to 100MB + +If an audit log file already exists, Kubernetes appends new audit logs to that file. +Otherwise, Kubernetes creates an audit log file at the location you specified in +`audit-log-path`. If the audit log file exceeds the size you specify in `audit-log-maxsize`, +Kubernetes will rename the current log file by appending the current timestamp on +the file name (before the file extension) and create a new audit log file. +Kubernetes may delete old log files when creating a new log file; you can configure +how many files are retained and how old they can be by specifying the `audit-log-maxbackup` +and `audit-log-maxage` options. diff --git a/docs/admin/index.md b/docs/admin/index.md index a573ec2e5d..47f47f8116 100644 --- a/docs/admin/index.md +++ b/docs/admin/index.md @@ -79,6 +79,8 @@ project](/docs/admin/salt). * **Authorization** [authorization](/docs/admin/authorization) -* **Admission Controllers** [admission_controllers](/docs/admin/admission-controllers) +* **Admission Controllers** [admission controllers](/docs/admin/admission-controllers) * **Sysctls** [sysctls](/docs/admin/sysctls.md) + +* **Audit** [audit](/docs/admin/audit)