kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[zh]Sync content/zh/docs/tasks/debug/debug-cluster/audit.md

pull/33329/head
wei.wang 2022-04-30 03:02:03 +08:00
parent 9c710f7f7b
commit be918fc2b3
1 changed files with 453 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

453
content/zh/docs/tasks/debug/debug-cluster/audit.md Normal file
View File

@ -0,0 +1,453 @@
---
title: 审计
content_type: concept
---
<!--
reviewers:
- soltysh
- sttts
- ericchiang
content_type: concept
title: Auditing
-->
<!-- overview -->
{{< feature-state state="beta" >}}
<!--
Kubernetes _auditing_ provides a security-relevant, chronological set of records documenting
the sequence of actions in a cluster. The cluster audits the activities generated by users,
by applications that use the Kubernetes API, and by the control plane itself.
Auditing allows cluster administrators to answer the following questions:
-->
Kubernetes _审计（Auditing）_ 功能提供了与安全相关的、按时间顺序排列的记录集，
记录每个用户、使用 Kubernetes API 的应用以及控制面自身引发的活动。
审计功能使得集群管理员能够回答以下问题：
<!--
- 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?
-->
- 发生了什么？
- 什么时候发生的？
- 谁触发的？
- 活动发生在哪个（些）对象上？
- 在哪观察到的？
- 它从哪触发的？
- 活动的后续处理行为是什么？
<!-- body -->
<!--
Audit records begin their lifecycle inside the
[kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/)
component. Each request on each stage
of its execution generates an audit event, which is then pre-processed according to
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.
-->
审计记录最初产生于
[kube-apiserver](/zh/docs/reference/command-line-tools-reference/kube-apiserver/)
内部。每个请求在不同执行阶段都会生成审计事件；这些审计事件会根据特定策略
被预处理并写入后端。策略确定要记录的内容和用来存储记录的后端。
当前的后端支持日志文件和 webhook。
<!--
Each request can be recorded with an associated _stage_. The defined 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.
-->
每个请求都可被记录其相关的 _阶段（stage）_。已定义的阶段有：
- `RequestReceived` - 此阶段对应审计处理器接收到请求后，并且在委托给
其余处理器之前生成的事件。
- `ResponseStarted` - 在响应消息的头部发送后，响应消息体发送前生成的事件。
只有长时间运行的请求（例如 watch）才会生成这个阶段。
- `ResponseComplete` - 当响应消息体完成并且没有更多数据需要传输的时候。
- `Panic` - 当 panic 发生时生成。
<!--
The configuration of an
[Audit Event configuration](/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Event)
is different from the
[Event](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#event-v1-core)
API object.
-->
{{< note >}}
[审计事件配置](/zh/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Event)
的配置与 [Event](/zh/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#event-v1-core)
API 对象不同。
{{< /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.
-->
审计日志记录功能会增加 API server 的内存消耗，因为需要为每个请求存储审计所需的某些上下文。
此外，内存消耗取决于审计日志记录的配置。
<!--
## Audit Policy
Audit policy defines rules about what events should be recorded and what data
they should include. The audit policy object structure is defined in the
[`audit.k8s.io` API group](/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Policy).
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 defined audit levels are:
-->
## 审计策略 {#audit-policy}
审计政策定义了关于应记录哪些事件以及应包含哪些数据的规则。
审计策略对象结构定义在
[`audit.k8s.io` API 组](/zh/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Policy)
处理事件时，将按顺序与规则列表进行比较。第一个匹配规则设置事件的
_审计级别（Audit Level）_。已定义的审计级别有：
<!--
- `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.
-->
- `None` - 符合这条规则的日志将不会记录。
- `Metadata` - 记录请求的元数据（请求的用户、时间戳、资源、动词等等），
但是不记录请求或者响应的消息体。
- `Request` - 记录事件的元数据和请求的消息体，但是不记录响应的消息体。
这不适用于非资源类型的请求。
- `RequestResponse` - 记录事件的元数据，请求和响应的消息体。这不适用于非资源类型的请求。
<!--
You can pass a file with the policy to `kube-apiserver`
using the `--audit-policy-file` flag. If the flag is omitted, no events are logged.
Note that the `rules` field __must__ be provided in the audit policy file.
A policy with no (0) rules is treated as illegal.
Below is an example audit policy file:
-->
你可以使用 `--audit-policy-file` 标志将包含策略的文件传递给 `kube-apiserver`。
如果不设置该标志，则不记录事件。
注意 `rules` 字段 __必须__ 在审计策略文件中提供。没有（0）规则的策略将被视为非法配置。
以下是一个审计策略文件的示例：
{{< codenew file="audit/audit-policy.yaml" >}}
<!--
You can use a minimal audit policy file to log all requests at the `Metadata` level:
-->
你可以使用最低限度的审计策略文件在 `Metadata` 级别记录所有请求：
```yaml
# 在 Metadata 级别为所有请求生成日志
apiVersion: audit.k8s.io/v1beta1
kind: Policy
rules:
- level: Metadata
```
<!--
If you're crafting your own audit profile, you can use the audit profile for Google Container-Optimized OS as a starting point. You can check the
[configure-helper.sh](https://github.com/kubernetes/kubernetes/blob/master/cluster/gce/gci/configure-helper.sh)
script, which generates the audit policy file. You can see most of the audit policy file by looking directly at the script.
You can also refer to the [`Policy` configuration reference](/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Policy)
for details about the fields defined.
-->
如果你在打磨自己的审计配置文件，你可以使用为 Google Container-Optimized OS
设计的审计配置作为出发点。你可以参考
[configure-helper.sh](https://github.com/kubernetes/kubernetes/blob/master/cluster/gce/gci/configure-helper.sh)
脚本，该脚本能够生成审计策略文件。你可以直接在脚本中看到审计策略的绝大部份内容。
你也可以参考 [`Policy` 配置参考](/zh/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Policy)
以获取有关已定义字段的详细信息。
<!--
## Audit backends
Audit backends persist audit events to an external storage.
Out of the box, the kube-apiserver provides two backends:
- Log backend, which writes events into the filesystem
- Webhook backend, which sends events to an external HTTP API
In all cases, audit events follow a structure defined by the Kubernetes API in the
[`audit.k8s.io` API group](/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Event).
-->
## 审计后端 {#audit-backends}
审计后端实现将审计事件导出到外部存储。`Kube-apiserver` 默认提供两个后端：
- Log 后端，将事件写入到文件系统
- Webhook 后端，将事件发送到外部 HTTP API
在这所有情况下，审计事件均遵循 Kubernetes API 在
[`audit.k8s.io` API 组](/zh/docs/reference/config-api/apiserver-audit.v1/#audit-k8s-io-v1-Event)
中定义的结构。
<!--
In case of patches, request body is a JSON array with patch operations, not a JSON object
with an appropriate Kubernetes API object. For example, the following request body is a valid patch
request to `/apis/batch/v1/namespaces/some-namespace/jobs/some-job-name`.
-->
{{< note >}}
对于 patch 请求，请求的消息体需要是设定 patch 操作的 JSON 所构成的一个串，
而不是一个完整的 Kubernetes API 对象 JSON 串。
例如，以下的示例是一个合法的 patch 请求消息体，该请求对应
`/apis/batch/v1/namespaces/some-namespace/jobs/some-job-name`。
```json
[
{
"op": "replace",
"path": "/spec/parallelism",
"value": 0
},
{
"op": "remove",
"path": "/spec/template/spec/containers/0/terminationMessagePolicy"
}
]
```
{{< /note >}}
<!--
### Log backend
The log backend writes audit events to a file in [JSONlines](https://jsonlines.org/) format.
You can configure the log audit backend using the following `kube-apiserver` flags:
Log backend writes audit events to a file in JSON format. You can configure
log audit backend using the following [kube-apiserver][kube-apiserver] flags:
-->
### Log 后端
Log 后端将审计事件写入 [JSONlines](https://jsonlines.org/) 格式的文件。
你可以使用以下 `kube-apiserver` 标志配置 Log 审计后端：
<!--
- `--audit-log-path` specifies the log file path that log backend uses to write
audit events. Not specifying this flag disables log backend. `-` means standard out
- `--audit-log-maxage` defined the maximum number of days to retain old audit log files
- `--audit-log-maxbackup` defines the maximum number of audit log files to retain
- `--audit-log-maxsize` defines the maximum size in megabytes of the audit log file before it gets rotated
-->
- `--audit-log-path` 指定用来写入审计事件的日志文件路径。不指定此标志会禁用日志后端。`-` 意味着标准化
- `--audit-log-maxage` 定义保留旧审计日志文件的最大天数
- `--audit-log-maxbackup` 定义要保留的审计日志文件的最大数量
- `--audit-log-maxsize` 定义审计日志文件的最大大小（兆字节）
<!--
If your cluster's control plane runs the kube-apiserver as a Pod, remember to mount the `hostPath`
to the location of the policy file and log file, so that audit records are persisted. For example:
-->
如果你的集群控制面以 Pod 的形式运行 kube-apiserver，记得要通过 `hostPath`
卷来访问策略文件和日志文件所在的目录，这样审计记录才会持久保存下来。例如：
```shell
--audit-policy-file=/etc/kubernetes/audit-policy.yaml
--audit-log-path=/var/log/kubernetes/audit/audit.log
```
接下来挂载数据卷：
```yaml
volumeMounts:
- mountPath: /etc/kubernetes/audit-policy.yaml
name: audit
readOnly: true
- mountPath: /var/log/kubernetes/audit/
name: audit-log
readOnly: false
```
<!--
and finally configure the `hostPath`:
-->
最后配置 `hostPath`：
```yaml
...
volumes:
- name: audit
hostPath:
path: /etc/kubernetes/audit-policy.yaml
type: File
- name: audit-log
hostPath:
path: /var/log/kubernetes/audit/
type: DirectoryOrCreate
```
<!--
### Webhook backend
The webhook audit backend sends audit events to a remote web API, which is assumed to
be a form of the Kubernetes API, including means of authentication. You can configure
a webhook audit backend using the following kube-apiserver flags:
-->
### Webhook 后端 {#webhook-backend}
Webhook 后端将审计事件发送到远程 Web API，该远程 API 应该暴露与 `kube-apiserver`
形式相同的 API，包括其身份认证机制。你可以使用如下 kube-apiserver 标志来配置
Webhook 审计后端：
<!--
- `--audit-webhook-config-file` specifies the path to a file with a webhook
configuration. The webhook configuration is effectively a specialized
[kubeconfig](/docs/tasks/access-application-cluster/configure-access-multiple-clusters).
- `--audit-webhook-initial-backoff` specifies the amount of time to wait after the first failed
request before retrying. Subsequent requests are retried with exponential backoff.
The webhook config file uses the kubeconfig format to specify the remote address of
the service and credentials used to connect to it.
-->
- `--audit-webhook-config-file` 设置 Webhook 配置文件的路径。Webhook 配置文件实际上是一个
[kubeconfig 文件](/zh/docs/concepts/configuration/organize-cluster-access-kubeconfig/)。
- `--audit-webhook-initial-backoff` 指定在第一次失败后重发请求等待的时间。随后的请求将以指数退避重试。
Webhook 配置文件使用 kubeconfig 格式指定服务的远程地址和用于连接它的凭据。
<!--
## Event batching {#batching}
Both log and webhook backends support batching. Using webhook as an example, here's the list of
available flags. To get the same flag for log backend, replace `webhook` with `log` in the flag
name. By default, batching is enabled in `webhook` and disabled in `log`. Similarly, by default
throttling is enabled in `webhook` and disabled in `log`.
-->
## 事件批处理 {#batching}
日志和 Webhook 后端都支持批处理。以 Webhook 为例，以下是可用参数列表。要获取日志
后端的同样参数，请在参数名称中将 `webhook` 替换为 `log`。
默认情况下，在 `webhook` 中批处理是被启用的，在 `log` 中批处理是被禁用的。
同样，默认情况下，在 `webhook` 中启用带宽限制，在 `log` 中禁用带宽限制。
<!--
- `--audit-webhook-mode` defines the buffering strategy. One of the following:
- `batch` - buffer events and asynchronously process them in batches. This is the default.
- `blocking` - block API server responses on processing each individual event.
- `blocking-strict` - Same as blocking, but when there is a failure during audit logging at the
RequestReceived stage, the whole request to the kube-apiserver fails.
-->
- `--audit-webhook-mode` 定义缓存策略，可选值如下：
- `batch` - 以批处理缓存事件和异步的过程。这是默认值。
- `blocking` - 在 API 服务器处理每个单独事件时，阻塞其响应。
- `blocking-strict` - 与 `blocking` 相同，不过当审计日志在 RequestReceived 阶段
失败时，整个 API 服务请求会失效。
<!--
The following flags are used only in the `batch` mode.
- `--audit-webhook-batch-buffer-size` defines the number of events to buffer before batching.
If the rate of incoming events overflows the buffer, events are dropped.
- `--audit-webhook-batch-max-size` defines the maximum number of events in one batch.
- `--audit-webhook-batch-max-wait` defines the maximum amount of time to wait before unconditionally
batching events in the queue.
- `--audit-webhook-batch-throttle-qps` defines the maximum average number of batches generated
per second.
- `--audit-webhook-batch-throttle-burst` defines the maximum number of batches generated at the same
moment if the allowed QPS was underutilized previously.
-->
以下参数仅用于 `batch` 模式。
- `--audit-webhook-batch-buffer-size` 定义 batch 之前要缓存的事件数。
如果传入事件的速率溢出缓存区，则会丢弃事件。
- `--audit-webhook-batch-max-size` 定义一个 batch 中的最大事件数。
- `--audit-webhook-batch-max-wait` 无条件 batch 队列中的事件前等待的最大事件。
- `--audit-webhook-batch-throttle-qps` 每秒生成的最大批次数。
- `--audit-webhook-batch-throttle-burst` 在达到允许的 QPS 前，同一时刻允许存在的最大 batch 生成数。
<!--
## Parameter tuning
Parameters should be set to accommodate the load on the API server.
For example, if kube-apiserver receives 100 requests each second, and each request is audited only
on `ResponseStarted` and `ResponseComplete` stages, you should account for ≅200 audit
events being generated each second. Assuming that there are up to 100 events in a batch,
you should set throttling level at least 2 queries per second. Assuming that the backend can take up to
5 seconds to write events, you should set the buffer size to hold up to 5 seconds of events;
that is: 10 batches, or 1000 events.
-->
## 参数调整 {#parameter-tuning}
需要设置参数以适应 API 服务器上的负载。
例如，如果 kube-apiserver 每秒收到 100 个请求，并且每个请求仅在 `ResponseStarted`
和 `ResponseComplete` 阶段进行审计，则应该考虑每秒生成约 200 个审计事件。
假设批处理中最多有 100 个事件，则应将限制级别设置为每秒至少 2 个查询。
假设后端最多需要 5 秒钟来写入事件，你应该设置缓冲区大小以容纳最多 5 秒的事件，
即 10 个 batch，即 1000 个事件。
<!--
In most cases however, the default parameters should be sufficient and you don't have to worry about
setting them manually. You can look at the following Prometheus metrics exposed by kube-apiserver
and in the logs to monitor the state of the auditing subsystem.
- `apiserver_audit_event_total` metric contains the total number of audit events exported.
- `apiserver_audit_error_total` metric contains the total number of events dropped due to an error
during exporting.
-->
但是，在大多数情况下，默认参数应该足够了，你不必手动设置它们。
你可以查看 kube-apiserver 公开的以下 Prometheus 指标，并在日志中监控审计子系统的状态。
- `apiserver_audit_event_total` 包含所有暴露的审计事件数量的指标。
- `apiserver_audit_error_total` 在暴露时由于发生错误而被丢弃的事件的数量。
<!--
### Log entry truncation {#truncate}
Both log and webhook backends support limiting the size of events that are logged.
As an example, the following is the list of flags available for the log backend:
-->
### 日志条目截断 {#truncate}
日志后端和 Webhook 后端都支持限制所输出的事件的尺寸。
例如，下面是可以为日志后端配置的标志列表：
<!--
- `audit-log-truncate-enabled` whether event and batch truncating is enabled.
- `audit-log-truncate-max-batch-size` maximum size in bytes of the batch sent to the underlying backend.
- `audit-log-truncate-max-event-size` maximum size in bytes of the audit event sent to the underlying backend.
-->
- `audit-log-truncate-enabled`：是否弃用事件和批次的截断处理。
- `audit-log-truncate-max-batch-size`：向下层后端发送的各批次的最大尺寸字节数。
- `audit-log-truncate-max-event-size`：向下层后端发送的审计事件的最大尺寸字节数。
<!--
By default truncate is disabled in both `webhook` and `log`, a cluster administrator should set
`audit-log-truncate-enabled` or `audit-webhook-truncate-enabled` to enable the feature.
-->
默认情况下，截断操作在 `webhook` 和 `log` 后端都是被禁用的，集群管理员需要设置
`audit-log-truncate-enabled` 或 `audit-webhook-truncate-enabled` 标志来启用此操作。
## {{% heading "whatsnext" %}}
<!--
* Learn about [Mutating webhook auditing annotations](/docs/reference/access-authn-authz/extensible-admission-controllers/#mutating-webhook-auditing-annotations).
-->
* 了解 [Mutating webhook 审计注解](/zh/docs/reference/access-authn-authz/extensible-admission-controllers/#mutating-webhook-auditing-annotations)。