From 29e2644f755603c679b18397277340679719eeb9 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Tue, 26 Jan 2021 17:18:29 +0800 Subject: [PATCH] [zh] sync audit task page --- .../tasks/debug-application-cluster/audit.md | 407 +++++------------- 1 file changed, 107 insertions(+), 300 deletions(-) diff --git a/content/zh/docs/tasks/debug-application-cluster/audit.md b/content/zh/docs/tasks/debug-application-cluster/audit.md index a5f0271128e08..1e8f12388c24d 100644 --- a/content/zh/docs/tasks/debug-application-cluster/audit.md +++ b/content/zh/docs/tasks/debug-application-cluster/audit.md @@ -15,14 +15,16 @@ title: Auditing {{< feature-state state="beta" >}} -Kubernetes 审计功能提供了与安全相关的按时间顺序排列的记录集，记录每个用户、管理员 -或系统其他组件影响系统的活动顺序。 -它能帮助集群管理员处理以下问题： +Kubernetes _审计（Auditing）_ 功能提供了与安全相关的、按时间顺序排列的记录集， +记录每个用户、使用 Kubernetes API 的应用以及控制面自身引发的活动。 + +审计功能使得集群管理员能够回答以下问题： -每个请求都可以用相关的 "stage" 记录。已知的 stage 有： +每个请求都可被记录其相关的 _阶段（stage）_。已定义的阶段有： -- `RequestReceived` - 事件的 stage 将在审计处理器接收到请求后，并且在委托给其余处理器之前生成。 -- `ResponseStarted` - 在响应消息的头部发送后，但是响应消息体发送前。 - 这个阶段仅为长时间运行的请求生成（例如 watch）。 +- `RequestReceived` - 此阶段对应审计处理器接收到请求后，并且在委托给 + 其余处理器之前生成的事件。 +- `ResponseStarted` - 在响应消息的头部发送后，响应消息体发送前生成的事件。 + 只有长时间运行的请求（例如 watch）才会生成这个阶段。 - `ResponseComplete` - 当响应消息体完成并且没有更多数据需要传输的时候。 - `Panic` - 当 panic 发生时生成。 {{< note >}} @@ -96,7 +99,7 @@ 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][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: +_audit level_ of the event. The defined audit levels are: --> ## 审计策略 {#audit-policy} @@ -104,7 +107,7 @@ compared against the list of rules in order. The first matching rule sets the 审计策略对象结构定义在 [`audit.k8s.io` API 组](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/staging/src/k8s.io/apiserver/pkg/apis/audit/v1/types.go) 处理事件时，将按顺序与规则列表进行比较。第一个匹配规则设置事件的 -"审计级别"。已知的审计级别有： +_审计级别（Audit Level）_。已定义的审计级别有： -管理员构建自己的审计配置文件时，可参考 +如果你在打磨自己的审计配置文件，你可以使用为 Google Container-Optimized OS +设计的审计配置作为出发点。你可以参考 [configure-helper.sh](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/cluster/gce/gci/configure-helper.sh) -脚本，该脚本生成审计策略文件。你可以直接在脚本中看到审计策略的绝大部份内容。 -[]。 +脚本，该脚本能够生成审计策略文件。你可以直接在脚本中看到审计策略的绝大部份内容。 + ## 审计后端 {#audit-backends} 审计后端实现将审计事件导出到外部存储。`Kube-apiserver` 默认提供两个后端： -- Log 后端，将事件写入到磁盘 -- Webhook 后端，将事件发送到外部 API +- Log 后端，将事件写入到文件系统 +- Webhook 后端，将事件发送到外部 HTTP API 在这两种情况下，审计事件结构均由 `audit.k8s.io` API 组中的 API 定义。 -当前版本的 API 是 +对于 Kubernetes {{< param "fullversion" >}}，该 API 的当前版本是 [`v1`](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/staging/src/k8s.io/apiserver/pkg/apis/audit/v1/types.go). {{< note >}} -在 patch 请求的情况下，请求的消息体需要是一个 JSON 串指定 patch 操作， +对于 patch 请求，请求的消息体需要是设定 patch 操作的 JSON 所构成的一个串， 而不是一个完整的 Kubernetes API 对象 JSON 串。 例如，以下的示例是一个合法的 patch 请求消息体，该请求对应 `/apis/batch/v1/namespaces/some-namespace/jobs/some-job-name`。 @@ -214,13 +219,16 @@ request to `/apis/batch/v1/namespaces/some-namespace/jobs/some-job-name`. ### Log 后端 -Log 后端将审计事件写入 JSON 格式的文件。你可以使用以下 `kube-apiserver` 标志配置 -Log 审计后端： +Log 后端将审计事件写入 [JSONlines](https://jsonlines.org/) 格式的文件。 +你可以使用以下 `kube-apiserver` 标志配置 Log 审计后端： - `--audit-log-path` 指定用来写入审计事件的日志文件路径。不指定此标志会禁用日志后端。`-` 意味着标准化 -- `--audit-log-maxage` 定义了保留旧审计日志文件的最大天数 -- `--audit-log-maxbackup` 定义了要保留的审计日志文件的最大数量 +- `--audit-log-maxage` 定义保留旧审计日志文件的最大天数 +- `--audit-log-maxbackup` 定义要保留的审计日志文件的最大数量 - `--audit-log-maxsize` 定义审计日志文件的最大大小（兆字节） -如果 `kube-apiserver` 被配置为运行在 Pod 中，请记得将包含策略文件和日志文件的 -位置用 `hostPath` 挂载到 Pod 中。例如， +如果你的集群控制面以 Pod 的形式运行 kube-apiserver，记得要通过 `hostPath` +卷来访问策略文件和日志文件所在的目录，这样审计记录才会持久保存下来。例如： -``` ---audit-policy-file=/etc/kubernetes/audit-policy.yaml ---audit-log-path=/var/log/audit.log +```shell + --audit-policy-file=/etc/kubernetes/audit-policy.yaml + --audit-log-path=/var/log/audit.log ``` 接下来挂载数据卷： -``` +```yaml volumeMounts: - mountPath: /etc/kubernetes/audit-policy.yaml name: audit @@ -262,10 +266,12 @@ volumeMounts: readOnly: false ``` - -下面是 hostPath 卷本身。 + +最后配置 `hostPath`： -``` +```yaml - name: audit hostPath: path: /etc/kubernetes/audit-policy.yaml @@ -275,56 +281,59 @@ volumeMounts: hostPath: path: /var/log/audit.log type: FileOrCreate - ``` ### Webhook 后端 {#webhook-backend} -Webhook 后端将审计事件发送到远程 API，该远程 API 应该暴露与 `kube-apiserver` 相同的API。 -你可以使用如下 kube-apiserver 标志来配置 webhook 审计后端： +Webhook 后端将审计事件发送到远程 Web API，该远程 API 应该暴露与 `kube-apiserver` +形式相同的 API，包括其身份认证机制。你可以使用如下 kube-apiserver 标志来配置 +Webhook 审计后端： -- `--audit-webhook-config-file` webhook 配置文件的路径。Webhook 配置文件实际上是一个 - [kubeconfig 文件](/zh/docs/concepts/configuration/organize-cluster-access-kubeconfig/) +- `--audit-webhook-config-file` 设置 Webhook 配置文件的路径。Webhook 配置文件实际上是一个 + [kubeconfig 文件](/zh/docs/concepts/configuration/organize-cluster-access-kubeconfig/)。 - `--audit-webhook-initial-backoff` 指定在第一次失败后重发请求等待的时间。随后的请求将以指数退避重试。 -webhook 配置文件使用 kubeconfig 格式指定服务的远程地址和用于连接它的凭据。 +Webhook 配置文件使用 kubeconfig 格式指定服务的远程地址和用于连接它的凭据。 -### 批处理 {#batching} +## 事件批处理 {#batching} -log 和 webhook 后端都支持批处理。以 webhook 为例，以下是可用参数列表。要获取 log 后端的同样参数， -请在参数名称中将 `webhook` 替换为 `log`。 -默认情况下，在 `webhook` 中启用批处理，在 `log` 中禁用批处理。 +日志和 Webhook 后端都支持批处理。以 Webhook 为例，以下是可用参数列表。要获取日志 +后端的同样参数，请在参数名称中将 `webhook` 替换为 `log`。 +默认情况下，在 `webhook` 中批处理是被启用的，在 `log` 中批处理是被禁用的。 同样，默认情况下，在 `webhook` 中启用带宽限制，在 `log` 中禁用带宽限制。 + - `--audit-webhook-mode` 定义缓存策略，可选值如下： - `batch` - 以批处理缓存事件和异步的过程。这是默认值。 - `blocking` - 在 API 服务器处理每个单独事件时，阻塞其响应。 @@ -354,25 +363,26 @@ The following flags are used only in the `batch` mode. - `--audit-webhook-batch-throttle-burst` 在达到允许的 QPS 前，同一时刻允许存在的最大 batch 生成数。 -#### 参数调整 - -需要设置参数以适应 apiserver 上的负载。 +## 参数调整 {#parameter-tuning} +需要设置参数以适应 API 服务器上的负载。 -例如，如果 kube-apiserver 每秒收到 100 个请求，并且每个请求仅在 `ResponseStarted` 和 `ResponseComplete` 阶段进行审计，则应该考虑每秒生成约 200 个审计事件。 -假设批处理中最多有 100 个事件，则应将限制级别设置为至少 2 个 QPS。 -假设后端最多需要 5 秒钟来写入事件，你应该设置缓冲区大小以容纳最多 5 秒的事件，即 10 个 batch，即 1000 个事件。 +例如，如果 kube-apiserver 每秒收到 100 个请求，并且每个请求仅在 `ResponseStarted` +和 `ResponseComplete` 阶段进行审计，则应该考虑每秒生成约 200 个审计事件。 +假设批处理中最多有 100 个事件，则应将限制级别设置为每秒至少 2 个查询。 +假设后端最多需要 5 秒钟来写入事件，你应该设置缓冲区大小以容纳最多 5 秒的事件， +即 10 个 batch，即 1000 个事件。 -## 多 API 服务器的配置 - -如果你通过[聚合层](/zh/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) -对 Kubernetes API 进行扩展，那么你也可以为聚合的 API 服务器设置审计日志。 -想要这么做，你需要以上述的格式给聚合的 API 服务器配置参数，并且配置日志管道以采用审计日志。 -不同的 API 服务器可以配置不同的审计配置和策略。 - - -## 日志收集器示例 - -### 使用 fluentd 从日志文件中选择并且分发审计日志 - -[Fluentd](https://www.fluentd.org/) 是一个开源的数据采集器，可以从统一的日志层中采集。 -在以下示例中，我们将使用 fluentd 来按照命名空间划分审计事件。 - - -{{< note >}} -`fluent-plugin-forest` 和 `fluent-plugin-rewrite-tag-filter` fluentd 的插件。 -你可以在 [fluentd plugin-management](https://docs.fluentd.org/v1.0/articles/plugin-management) -了解安装插件相关的细节。 -{{< /note >}} - - -1. 在 kube-apiserver 节点上安装 [`fluentd`](https://docs.fluentd.org/v1.0/articles/quickstart#step-1:-installing-fluentd)、 -, `fluent-plugin-forest` 和 `fluent-plugin-rewrite-tag-filter`。 - -1. 为 fluentd 创建一个配置文件 - - ```none - $ cat < /etc/fluentd/config - # fluentd 运行在 kube-apiserver 相同的主机上 - - @type tail - # kube-apiserver 审计日志路径 - path /var/log/audit - pos_file /var/log/audit.pos - format json - time_key time - time_format %Y-%m-%dT%H:%M:%S.%N%z - tag audit - - - - #https://github.com/fluent/fluent-plugin-rewrite-tag-filter/issues/13 - type record_transformer - enable_ruby - - namespace ${record["objectRef"].nil? ? "none":(record["objectRef"]["namespace"].nil? ? "none":record["objectRef"]["namespace"])} - - - - - # 根据上下文中的名字空间元素对审计进行路由 - @type rewrite_tag_filter - rewriterule1 namespace ^(.+) ${tag}.$1 - - - - @type record_transformer - remove_keys namespace - - - - @type forest - subtype file - remove_prefix audit - - - ``` - - -3. 启动 fluentd - - ```shell - fluentd -c /etc/fluentd/config -vv - ``` +### Log entry truncation {#truncate} - -4. 给 kube-apiserver 配置以下参数并启动： +### 日志条目截断 {#truncate} - ```shell - --audit-policy-file=/etc/kubernetes/audit-policy.yaml --audit-log-path=/var/log/kube-audit --audit-log-format=json - ``` +日志后端和 Webhook 后端都支持限制所输出的事件的尺寸。 +例如，下面是可以为日志后端配置的标志列表： -5. 在 `/var/log/audit-*.log` 文件中检查不同命名空间的审计事件 +- `audit-log-truncate-enabled`：是否弃用事件和批次的截断处理。 +- `audit-log-truncate-max-batch-size`：向下层后端发送的各批次的最大尺寸字节数。 +- `audit-log-truncate-max-event-size`：向下层后端发送的审计事件的最大尺寸字节数。 -### 使用 logstash 采集并分发 webhook 后端的审计事件 - -[Logstash](https://www.elastic.co/products/logstash) 是一个开源的、服务器端的数据处理工具。 -在下面的示例中，我们将使用 logstash 采集 webhook 后端的审计事件，并且将来自不同用户的事件存入不同的文件。 - -1. 安装 [logstash](https://www.elastic.co/guide/en/logstash/current/installing-logstash.html) - -1. 为 logstash 创建配置文件 - - ```none - cat < /etc/logstash/config - input{ - http{ - #TODO, figure out a way to use kubeconfig file to authenticate to logstash - #https://www.elastic.co/guide/en/logstash/current/plugins-inputs-http.html#plugins-inputs-http-ssl - port=>8888 - } - } - filter{ - split{ - # Webhook 审计后端与 EventList 一起发送若干事件 - # 对事件进行分割 - field=>[items] - # 我们只需要 event 子元素，去掉其他元素 - remove_field=>[headers, metadata, apiVersion, "@timestamp", kind, "@version", host] - } - mutate{ - rename => {items=>event} - } - } - output{ - file{ - # 来自不同用户的审计事件会被保存到不同文件中 - path=>"/var/log/kube-audit-%{[event][user][username]}/audit" - } - } - ``` - - -3. 启动 logstash - - ```shell - bin/logstash -f /etc/logstash/config --path.settings /etc/logstash/ - ``` - - -4. 为 kube-apiserver webhook 审计后端创建一个 - [kubeconfig 文件](/zh/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)： - - ```bash - cat < /etc/kubernetes/audit-webhook-kubeconfig - apiVersion: v1 - clusters: - - cluster: - server: http://:8888 - name: logstash - contexts: - - context: - cluster: logstash - user: "" - name: default-context - current-context: default-context - kind: Config - preferences: {} - users: [] - EOF - ``` - - -5. 为 kube-apiserver 配置以下参数并启动： - - ```shell - --audit-policy-file=/etc/kubernetes/audit-policy.yaml --audit-webhook-config-file=/etc/kubernetes/audit-webhook-kubeconfig - ``` - - -6. 在 logstash 节点的 `/var/log/kube-audit-*/audit` 目录中检查审计事件 - -请注意，除了文件输出插件外，logstash 还有其它多种输出可以让用户路由不同的数据。 -例如，用户可以将审计事件发送给支持全文搜索和分析的 elasticsearch 插件。 +默认情况下，截断操作在 `webhook` 和 `log` 后端都是被禁用的，集群管理员需要设置 +`audit-log-truncate-enabled` 或 `audit-webhook-truncate-enabled` 标志来启用此操作。 ## {{% heading "whatsnext" %}} - -了解 [Mutating webhook 审计注解](/zh/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)。