diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md index 29dfca82b7..7315d27fbb 100644 --- a/content/en/docs/reference/_index.md +++ b/content/en/docs/reference/_index.md @@ -52,7 +52,9 @@ client libraries: * [kubelet](/docs/reference/command-line-tools-reference/kubelet/) - The primary agent that runs on each node. The kubelet takes a set of PodSpecs and ensures that the described containers are running and healthy. -* [kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/) - REST API that validates and configures data for API objects such as pods, services, replication controllers. +* [kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/) - + REST API that validates and configures data for API objects such as pods, + services, replication controllers. * [kube-controller-manager](/docs/reference/command-line-tools-reference/kube-controller-manager/) - Daemon that embeds the core control loops shipped with Kubernetes. * [kube-proxy](/docs/reference/command-line-tools-reference/kube-proxy/) - Can do simple TCP/UDP stream forwarding or round-robin TCP/UDP forwarding across @@ -64,13 +66,15 @@ client libraries: ## Config APIs +This section hosts the documentation for "unpublished" APIs which are used to +configure kubernetes components or tools. Most of these APIs are not exposed +by the API server in a RESTful way though they are essential for a user or an +operator to use or manage a cluster. + +* [kubelet configuration (v1beta1)](/docs/reference/config-api/kubelet-config.v1beta1/) +* [kube-scheduler configuration (v1beta1)](/docs/reference/config-api/kube-scheduler-config.v1beta1/) * [kube-proxy configuration (v1alpha1)](/docs/reference/config-api/kube-proxy-config.v1alpha1/) -* [kube-scheduler config (v1beta1)](/docs/reference/config-api/kube-scheduler-config.v1beta1/) - - -## Config APIs - -* [kubelet config (v1beta1)](/docs/reference/config-api/kubelet-config.v1beta1/) +* [`audit.k8s.io/v1` API](/docs/reference/config-api/apiserver-audit.v1/) ## Design Docs diff --git a/content/en/docs/reference/config-api/apiserver-audit.v1.md b/content/en/docs/reference/config-api/apiserver-audit.v1.md new file mode 100644 index 0000000000..f0f36c2344 --- /dev/null +++ b/content/en/docs/reference/config-api/apiserver-audit.v1.md @@ -0,0 +1,620 @@ +--- +title: kube-apiserver Audit Configuration (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} + + + + +**Appears in:** + +- [EventList](#audit-k8s-io-v1-EventList) + + +Event captures all the information that can be included in an API audit log. + +
| Field | Description |
|---|---|
apiVersionstring | audit.k8s.io/v1 |
kindstring | Event |
level [Required]+ Level
+ |
++ AuditLevel at which event was generated | +
auditID [Required]+ k8s.io/apimachinery/pkg/types.UID
+ |
++ Unique audit ID, generated for each request. | +
stage [Required]+ Stage
+ |
++ Stage of the request handling when this event instance was generated. | +
requestURI [Required]+ string
+ |
++ RequestURI is the request URI as sent by the client to a server. | +
verb [Required]+ 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
+ |
++ Authenticated user information. | +
impersonatedUser+ 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
+ |
++ 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 +(possibly re-encoded as JSON), prior to version conversion, defaulting, admission or +merging. It is an external versioned object type, and may not be a valid object on its own. +Omitted for non-resource requests. Only logged at Request Level and higher. | +
responseObject+ k8s.io/apimachinery/pkg/runtime.Unknown
+ |
++ API object returned in the response, in JSON. The ResponseObject is recorded after conversion +to the external type, and serialized as JSON. Omitted for non-resource requests. Only logged +at Response Level. | +
requestReceivedTimestamp+ meta/v1.MicroTime
+ |
++ Time the request reached the apiserver. | +
stageTimestamp+ 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. | +
| Field | Description |
|---|---|
apiVersionstring | audit.k8s.io/v1 |
kindstring | EventList |
metadata+ meta/v1.ListMeta
+ |
++ No description provided. + | +
items [Required]+ []Event
+ |
++ No description provided. + | +
| Field | Description |
|---|---|
apiVersionstring | audit.k8s.io/v1 |
kindstring | Policy |
metadata+ 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]+ []PolicyRule
+ |
++ Rules specify the audit Level a request should be recorded at. +A request may match multiple rules, in which case the FIRST matching rule is used. +The default audit level is None, but can be overridden by a catch-all rule at the end of the list. +PolicyRules are strictly ordered. | +
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. | +
| Field | Description |
|---|---|
apiVersionstring | audit.k8s.io/v1 |
kindstring | PolicyList |
metadata+ meta/v1.ListMeta
+ |
++ No description provided. + | +
items [Required]+ []Policy
+ |
++ No description provided. + | +
| Field | Description |
|---|---|
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. + +For example: +'pods' matches pods. +'pods/log' matches the log subresource of pods. +'∗' matches all resources and their subresources. +'pods/∗' matches all subresources of pods. +'∗/scale' matches all scale subresources. + +If wildcard is present, the validation rule will ensure resources do not +overlap with each other. + +An empty list implies all resources and subresources in this API groups apply. | +
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. | +
| Field | Description |
|---|---|
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. + | +
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. + | +
| Field | Description |
|---|---|
level [Required]+ 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. | +