// Module included in the following assemblies:
//
// * nodes/nodes-audit-log.adoc

[id="nodes-nodes-audit-log-advanced_{context}"]
= Advanced Audit  

*DEPRECATED for the moment*

The advanced audit feature provides several improvements over the
basic audit functionality, including fine-grained events filtering and multiple output back ends.

To enable the advanced audit feature, provide the following values in the
`openshift_master_audit_config` parameter:

----
openshift_master_audit_config={"enabled": true, "auditFilePath": "/var/lib/origin/oscp-audit.log", "maximumFileRetentionDays": 14, "maximumFileSizeMegabytes": 500, "maximumRetainedFiles": 5, "policyFile": "/etc/origin/master/adv-audit.yaml", "logFormat":"json"}
----

[IMPORTANT]
====
The policy file *_/etc/origin/master/adv-audit.yaml_* must be available on each control plane node.
====


The following table contains additional options you can use.

.Advanced Audit Configuration Parameters

[cols="3a,6a",options="header"]
|===
| Parameter Name | Description

|`policyFile`
|Path to the file that defines the audit policy configuration.

|`policyConfiguration`
|An embedded audit policy configuration.

|`logFormat`
|Specifies the format of the saved audit logs. Allowed values are `legacy` (the
format used in basic audit), and `json`.

|`webHookKubeConfig`
|Path to a `.kubeconfig`-formatted file that defines the audit webhook
configuration, where the events are sent to.

|`webHookMode`
|Specifies the strategy for sending audit events. Allowed values are `block`
(blocks processing another event until the previous has fully processed) and
`batch` (buffers events and delivers in batches).
|===

[IMPORTANT]
====
To enable the advanced audit feature, you must provide either `policyFile` *or*
`policyConfiguration` describing the audit policy rules:
====

.Sample Audit Policy Configuration
[source,yaml]
----
apiVersion: audit.k8s.io/v1beta1
kind: Policy
rules:

  # Do not log watch requests by the "system:kube-proxy" on endpoints or services
  - level: None <1>
    users: ["system:kube-proxy"] <2>
    verbs: ["watch"] <3>
    resources: <4>
    - group: ""
      resources: ["endpoints", "services"]

  # Do not log authenticated requests to certain non-resource URL paths.
  - level: None
    userGroups: ["system:authenticated"] <5>
    nonResourceURLs: <6>
    - "/api*" # Wildcard matching.
    - "/version"

  # Log the request body of configmap changes in kube-system.
  - level: Request
    resources:
    - group: "" # core API group
      resources: ["configmaps"]
    # This rule only applies to resources in the "kube-system" namespace.
    # The empty string "" can be used to select non-namespaced resources.
    namespaces: ["kube-system"] <7>

  # Log configmap and secret changes in all other namespaces at the metadata level.
  - level: Metadata
    resources:
    - group: "" # core API group
      resources: ["secrets", "configmaps"]

  # Log all other resources in core and extensions at the request level.
  - level: Request
    resources:
    - group: "" # core API group
    - group: "extensions" # Version of group should NOT be included.

  # A catch-all rule to log all other requests at the Metadata level.
  - level: Metadata <1>

  # Log login failures from the web console or CLI. Review the logs and refine your policies.
  - level: Metadata
    nonResourceURLs:
    - /login* <8>
    - /oauth* <9>
----
<1> There are four possible levels every event can be logged at:
+
* `None` - Do not log events that match this rule.
+
* `Metadata` - Log request metadata (requesting user, time stamp, resource, verb,
etc.), but not request or response body. This is the same level as the one used
in basic audit.
+
* `Request` - Log event metadata and request body, but not response body.
+
* `RequestResponse` - Log event metadata, request, and response bodies.
<2> A list of users the rule applies to. An empty list implies every user.
<3> A list of verbs this rule applies to. An empty list implies every verb. This is
 Kubernetes verb associated with API requests (including `get`, `list`, `watch`,
 `create`, `update`, `patch`, `delete`, `deletecollection`, and `proxy`).
<4> A list of resources the rule applies to. An empty list implies every resource.
Each resource is specified as a group it is assigned to (for example, an empty for
Kubernetes core API, batch, build.openshift.io, etc.), and a resource list from
that group.
<5> A list of groups the rule applies to. An empty list implies every group.
<6> A list of non-resources URLs the rule applies to.
<7> A list of namespaces the rule applies to. An empty list implies every namespace.
<8> Endpoint used by the web console.
<9> Endpoint used by the CLI.

For more information on advanced audit, see the
link:https://kubernetes.io/docs/tasks/debug-application-cluster/audit[Kubernetes
documentation]