From 26b54b06fb3f03767b283d1a6edddb74c3507307 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Sat, 11 Dec 2021 16:33:34 +0800 Subject: [PATCH] [zh] Translate audit API reference --- .../config-api/apiserver-audit.v1.md | 572 ++++++++++-------- 1 file changed, 315 insertions(+), 257 deletions(-) diff --git a/content/zh/docs/reference/config-api/apiserver-audit.v1.md b/content/zh/docs/reference/config-api/apiserver-audit.v1.md index c2e4a37704..245096e999 100644 --- a/content/zh/docs/reference/config-api/apiserver-audit.v1.md +++ b/content/zh/docs/reference/config-api/apiserver-audit.v1.md @@ -1,145 +1,171 @@ --- -title: kube-apiserver Audit Configuration (v1) +title: kube-apiserver Audit 配置 (v1) content_type: tool-reference package: audit.k8s.io/v1 auto_generated: true --- + + +## 资源类型 {#resource-types} - [Event](#audit-k8s-io-v1-Event) - [EventList](#audit-k8s-io-v1-EventList) - [Policy](#audit-k8s-io-v1-Policy) - [PolicyList](#audit-k8s-io-v1-PolicyList) - - - ## `Event` {#audit-k8s-io-v1-Event} - - - + +**出现在：** - [EventList](#audit-k8s-io-v1-EventList) - + +Event 结构包含可出现在 API 审计日志中的所有信息。 - + - - - - + + 生成事件所对应的审计级别。 + - - + + 为每个请求所生成的唯一审计 ID。 + - - + + 生成此事件时请求的处理阶段。 + - - + + requestURI 是客户端发送到服务器端的请求 URI。 + - + + verb 是与请求对应的 Kubernetes 动词。对于非资源请求，此字段为 HTTP 方法的小写形式。 + - - + + 关于认证用户的信息。 + - - + + + 关于所伪装（impersonated）的用户的信息。 + - - + + + 发起请求和中间代理的源 IP 地址。 + - - + + + + userAgent 中记录客户端所报告的用户代理（User Agent）字符串。 + 注意 userAgent 信息是由客户端提供的，一定不要信任。 + - - + + + 此请求所指向的对象引用。对于 List 类型的请求或者非资源请求，此字段可忽略。 + - - + + + 响应的状态，当 responseObject 不是 Status 类型时被赋值。 + 对于成功的请求，此字段仅包含 code 和 statusSuccess。 + 对于非 Status 类型的错误响应，此字段会被自动赋值为出错信息。 + - - + @@ -147,470 +173,502 @@ Omitted for non-resource requests. Only logged at Request Level and higher.k8s.io/apimachinery/pkg/runtime.Unknown - - + + + 请求到达 API 服务器时的时间。 + - - + + + 请求到达当前审计阶段时的时间。 + - - + + + annotations 是一个无结构的键-值映射，其中保存的是一个审计事件。 + 该事件可以由请求处理链路上的插件来设置，包括身份认证插件、鉴权插件以及 + 准入控制插件等。 + 注意这些注解是针对审计事件本身的，与所提交的对象中的 metadata.annotations + 之间不存在对应关系。 + 映射中的键名应该唯一性地标识生成该事件的组件，从而避免名字上的冲突 + （例如 podsecuritypolicy.admission.k8s.io/policy）。 + 映射中的键值应该比较简洁。 + 当审计级别为 Metadata 时会包含 annotations 字段。 + - -
FieldDescription
字段描述
apiVersion
string		audit.k8s.io/v1
kind
string		Event
level [Required]
+
level [必需]
Level 		- AuditLevel at which event was generated
auditID [Required]
+
auditID [必需]
k8s.io/apimachinery/pkg/types.UID 		- Unique audit ID, generated for each request.
stage [Required]
+
stage [必需]
Stage 		- Stage of the request handling when this event instance was generated.
requestURI [Required]
+
requestURI [必需]
string 		- RequestURI is the request URI as sent by the client to a server.
verb [Required]
+
verb [必需]
string 		- Verb is the kubernetes verb associated with the request. -For non-resource requests, this is the lower-cased HTTP method.
user [Required]
-authentication/v1.UserInfo +
user [必需]
+authentication/v1.UserInfo 		- Authenticated user information.
impersonatedUser
-authentication/v1.UserInfo +authentication/v1.UserInfo 		- Impersonated user information.
sourceIPs
[]string 		- Source IPs, from where the request originated and intermediate proxies.
userAgent
string 		- UserAgent records the user agent string reported by the client. -Note that the UserAgent is provided by the client, and must not be trusted.
objectRef
ObjectReference 		- Object reference this request is targeted at. -Does not apply for List-type requests, or non-resource requests.
responseStatus
-meta/v1.Status +meta/v1.Status 		- The response status, populated even when the ResponseObject is not a Status type. -For successful responses, this will only include the Code and StatusSuccess. -For non-status type error responses, this will be auto-populated with the error Message.
requestObject
k8s.io/apimachinery/pkg/runtime.Unknown 		- API object from the request, in JSON format. The RequestObject is recorded as-is in the request + + 来自请求的 API 对象，以 JSON 格式呈现。requestObject 在请求中按原样记录 + （可能会采用 JSON 重新编码），之后会进入版本转换、默认值填充、准入控制以及 + 配置信息合并等阶段。此对象为外部版本化的对象类型，甚至其自身可能并不是一个 + 合法的对象。对于非资源请求，此字段被忽略。 + 只有当审计级别为 Request 或更高的时候才会记录。 +
- API object returned in the response, in JSON. The ResponseObject is recorded after conversion + + 响应中包含的 API 对象，以 JSON 格式呈现。requestObject 是在被转换为外部类型 + 并序列化为 JSON 格式之后才被记录的。 + 对于非资源请求，此字段会被忽略。 + 只有审计级别为 Response 时才会记录。 +
requestReceivedTimestamp
-meta/v1.MicroTime +meta/v1.MicroTime 		- Time the request reached the apiserver.
stageTimestamp
-meta/v1.MicroTime +meta/v1.MicroTime 		- Time the request reached current audit stage.
annotations
map[string]string 		- Annotations is an unstructured key value map stored with an audit event that may be set by -plugins invoked in the request serving chain, including authentication, authorization and -admission plugins. Note that these annotations are for the audit event, and do not correspond -to the metadata.annotations of the submitted object. Keys should uniquely identify the informing -component to avoid name collisions (e.g. podsecuritypolicy.admission.k8s.io/policy). Values -should be short. Annotations are included in the Metadata level.
- - ## `EventList` {#audit-k8s-io-v1-EventList} - - - - + +EventList 是审计事件（Event）的列表。 - + - + - - - - - - - -
FieldDescription
字段描述
apiVersion
string		audit.k8s.io/v1
kind
string		EventList
metadata
-meta/v1.ListMeta +meta/v1.ListMeta 		- No description provided. + 列表结构元数据
items [Required]
+ +
items [必需]
[]Event 		- No description provided. + 事件对象列表
- - ## `Policy` {#audit-k8s-io-v1-Policy} - - - + +**出现在：** - [PolicyList](#audit-k8s-io-v1-PolicyList) - + +Policy 定义的是审计日志的配置以及不同类型请求的日志记录规则。 - + - + - - - + + 包含 metadata 字段是为了便于与 API 基础设施之间实现互操作。 + 参考 Kubernetes API 文档了解 metadata 字段的详细信息。 + - - - - - + + + 字段 omitStages 是一个阶段（Stage）列表，其中包含无须生成事件的阶段。 + 注意这一选项也可以通过每条规则来设置。 + 审计组件最终会忽略出现在 omitStages 中阶段，也会忽略规则中的阶段。 + - -
FieldDescription
字段描述
apiVersion
string		audit.k8s.io/v1
kind
string		Policy
metadata
-meta/v1.ObjectMeta +meta/v1.ObjectMeta 		- ObjectMeta is included for interoperability with API infrastructure.Refer to the Kubernetes API documentation for the fields of the metadata field.
rules [Required]
+ +
rules [必需]
[]PolicyRule 		- Rules specify the audit Level a request should be recorded at. + + 字段 rules 设置请求要被记录的审计级别（level）。 + 每个请求可能会与多条规则相匹配；发生这种状况时遵从第一条匹配规则。 + 默认的审计级别是 None，不过可以在列表的末尾使用一条全抓（catch-all）规则 + 重载其设置。 + 列表中的规则（PolicyRule）是严格有序的。 +
omitStages
[]Stage 		- OmitStages is a list of stages for which no events are created. Note that this can also -be specified per rule in which case the union of both are omitted.
- - ## `PolicyList` {#audit-k8s-io-v1-PolicyList} - - - - + +PolicyList 是由审计策略（Policy）组成的列表。 - + - - - - - - - -
FieldDescription
字段描述
apiVersion
string		audit.k8s.io/v1
kind
string		PolicyList
metadata
-meta/v1.ListMeta +meta/v1.ListMeta 		- No description provided. + 列表结构元数据。
items [Required]
+ +
items [必需]
[]Policy 		- No description provided. + 策略（Policy）对象列表。
- - ## `GroupResources` {#audit-k8s-io-v1-GroupResources} - - - + +**出现在：** - [PolicyRule](#audit-k8s-io-v1-PolicyRule) - + +GroupResources 代表的是某 API 组中的资源类别。 - + - - + + 字段 group 给出包含资源的 API 组的名称。 + 空字符串代表 core API 组。 + - - + - - + + + 字段 resourceNames 是策略将匹配的资源实例名称列表。 + 使用此字段时，resources 必须指定。 + 空的 resourceNames 列表意味着资源的所有实例都会匹配到此策略。 + - -
FieldDescription
字段描述
group
string 		- Group is the name of the API group that contains the resources. -The empty string represents the core API group.
resources
[]string 		- Resources is a list of resources this rule applies to. + + 字段 resources 是此规则所适用的资源的列表。
+ 例如：
+ 'pods' 匹配 Pods；
+ 'pods/log' 匹配 Pods 的 log 子资源；
+ '∗' 匹配所有资源及其子资源；
+ 'pods/∗' 匹配 Pods 的所有子资源；
+ '∗/scale' 匹配所有的 scale 子资源。

-If wildcard is present, the validation rule will ensure resources do not -overlap with each other. + + 如果存在通配符，则合法性检查逻辑会确保 resources 中的条目不会彼此重叠。
+ 空的列表意味着规则适用于该 API 组中的所有资源及其子资源。 +
resourceNames
[]string 		- ResourceNames is a list of resource instance names that the policy matches. -Using this field requires Resources to be specified. -An empty list implies that every instance of the resource is matched.
- - ## `Level` {#audit-k8s-io-v1-Level} - + + +string 数据类型的别名。 - + +**出现在：** - [Event](#audit-k8s-io-v1-Event) - - [PolicyRule](#audit-k8s-io-v1-PolicyRule) - + +Level 定义的是审计过程中在日志内记录的信息量。 ## `ObjectReference` {#audit-k8s-io-v1-ObjectReference} - - - + +**出现在：** - [Event](#audit-k8s-io-v1-Event) - + +ObjectReference 包含的是用来检查或修改所引用对象时将需要的全部信息。 - + - - - - + - - + - - + - - + + + 字段 apiGroup 给出包含所引用对象的 API 组的名称。 + 空字符串代表 core API 组。 + - - + + + 字段 apiVersion 是包含所引用对象的 API 组的版本。 + - - + - - + - -
FieldDescription
字段描述
resource
string 		- No description provided. + 资源类别。
namespace
string 		- No description provided. + 资源对象所在名字空间。
name
string 		- No description provided. + 资源对象名称。
uid
k8s.io/apimachinery/pkg/types.UID 		- No description provided. + 资源对象的唯一标识（UID）。
apiGroup
string 		- APIGroup is the name of the API group that contains the referred object. -The empty string represents the core API group.
apiVersion
string 		- APIVersion is the version of the API group that contains the referred object.
resourceVersion
string 		- No description provided. + 资源对象自身的版本值。
subresource
string 		- No description provided. + 子资源的类别。
- - ## `PolicyRule` {#audit-k8s-io-v1-PolicyRule} - - - + +**出现在：** - [Policy](#audit-k8s-io-v1-Policy) - + +PolicyRule 包含一个映射，基于元数据将请求映射到某审计级别。 +请求必须与每个字段所定义的规则都匹配（即 rules 的交集）才被视为匹配。 - + - - - + + 与此规则匹配的请求所对应的日志记录级别（Level）。 + - - + + + 根据身份认证所确定的用户名的列表，给出此规则所适用的用户。 + 空列表意味着适用于所有用户。 + - - + + + 此规则所适用的用户组的列表。如果用户是所列用户组中任一用户组的成员，则视为匹配。 + 空列表意味着适用于所有用户组。 + - - + + + 此规则所适用的动词（verb）列表。 + 空列表意味着适用于所有动词。 + - - + + + 此规则所适用的资源类别列表。 + 空列表意味着适用于 API 组中的所有资源类别。 + - - + + + + 此规则所适用的名字空间列表。 + 空字符串（""）意味着适用于非名字空间作用域的资源。 + 空列表意味着适用于所有名字空间。 - - + + + 字段 nonResourceURLs 给出一组需要被审计的 URL 路径。 + 允许使用 ∗，但只能作为路径中最后一个完整分段。
+ 例如：
+ "/metrics" - 记录对 API 服务器度量值（metrics）的所有请求；
+ "/healthz∗" - 记录所有健康检查请求。 + - - + + + 字段 omitStages 是一个阶段（Stage）列表，针对所列的阶段服务器不会生成审计事件。 + 注意这一选项也可以在策略（Policy）级别指定。服务器审计组件会忽略 + omitStages 中给出的阶段，也会忽略策略中给出的阶段。 + 空列表意味着不对阶段作任何限制。 + - -
FieldDescription
字段描述
level [Required]
+
level [必需]
Level 		- The Level that requests matching this rule are recorded at.
users
[]string 		- The users (by authenticated user name) this rule applies to. -An empty list implies every user.
userGroups
[]string 		- The user groups this rule applies to. A user is considered matching -if it is a member of any of the UserGroups. -An empty list implies every user group.
verbs
[]string 		- The verbs that match this rule. -An empty list implies every verb.
resources
[]GroupResources 		- Resources that this rule matches. An empty list implies all kinds in all API groups.
namespaces
[]string 		- Namespaces that this rule matches. -The empty string "" matches non-namespaced resources. -An empty list implies every namespace.
nonResourceURLs
[]string 		- NonResourceURLs is a set of URL paths that should be audited. -∗s are allowed, but only as the full, final step in the path. -Examples: - "/metrics" - Log requests for apiserver metrics - "/healthz∗" - Log all health checks
omitStages
[]Stage 		- OmitStages is a list of stages for which no events are created. Note that this can also -be specified policy wide in which case the union of both are omitted. -An empty list means no restrictions will apply.
- - ## `Stage` {#audit-k8s-io-v1-Stage} - + + +string 数据类型的别名。 - + +**出现在：** - [Event](#audit-k8s-io-v1-Event) - - [Policy](#audit-k8s-io-v1-Policy) - - [PolicyRule](#audit-k8s-io-v1-PolicyRule) - + +Stage 定义在请求处理过程中可以生成审计事件的阶段。 +