OSDOCS-9437: adds custom audit log policies MicroShift

_topic_maps/_topic_map_ms.yml

@@ -395,6 +395,8 @@ Topics:
   File: microshift-cluster-access-kubeconfig
 - Name: Checking the status of Greenboot health checks
   File: microshift-greenboot-checking-status
+- Name: Customizing audit logging policies
+  File: microshift-audit-logs-config
 ---
 Name: Networking
 Dir: microshift_networking

microshift_configuring/microshift-audit-logs-config.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="microshift-audit-logs-config"]
+= Customizing audit logging policies
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-audit-logs-config
+
+toc::[]
+
+You can use configuration values to control audit log file rotation and retention.
+
+include::modules/microshift-audit-logs-config-intro.adoc[leveloffset=+1]
+
+// About audit log profiles; OCP module, edit with conditionals and care
+include::modules/nodes-nodes-audit-config-about.adoc[leveloffset=+1]
+
+include::modules/microshift-audit-logs-config-proc.adoc[leveloffset=+1]

modules/microshift-audit-logs-config-intro.adoc

@@ -0,0 +1,27 @@
+// Text snippet included in the following assemblies:
+//
+// * microshift_configuring/microshift-audit-logs-config.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="microshift-audit-logs-config-intro_{context}"]
+= About setting limits on audit log files
+
+Using configuration values to control audit log file rotation and retention can help keep far-edge devices from exceeding limited storage capacities. On such devices, logging data accumulation can limit host system or cluster workloads, potentially bricking a device. Setting audit log policies can help ensure that critical processing space is continually available.
+
+Together, the values specified in a customized audit log policy enable you to enforce the size, number, and age limits of audit log backups. Field values are processed independently of one another and without prioritization. You can set fields in combination to define a maximum storage limit for retained logs. For example:
+
+* Set both `maxFileSize` and `maxFiles` to create a log storage upper limit.
+* Set a `maxFileAge` value to automatically delete files older than the timestamp in the file name, regardless of the `maxFiles` value.
+
+[id="Default-audit-log-values_{context}"]
+== Default audit log values
+
+{microshift-short} includes the following default audit log rotation values:
+
+The `maxFileSize` default is 200Mb.
+The `maxFiles` default is 10 files.
+The `maxFileAge` default is 0, disabling the age limit.
+
+Therefore, the default maximum storage consumption of audit logs is 2000Mb, provided that all files are less than 10 days old.
+
+If you do not specify a value for a field, the default value is used. If you remove a field previously set, the default value is restored after the next {microshift-short} service restart.

modules/microshift-audit-logs-config-proc.adoc

@@ -0,0 +1,40 @@
+// Text snippet included in the following assemblies:
+//
+// * microshift_configuring/microshift-audit-logs-config.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="microshift-configuring-audit-log-values_{context}"]
+= Configuring audit log values
+
+Use the {microshift-short} service configuration file to implement custom audit log settings.
+
+.Procedure
+
+. Add the following `apiServer` stanza to your {microshift-short} configuration file. If you need to make the file, run the following command:
++
+[source,terminal]
+----
+$ sudo cat /etc/microshift/config.yaml
+----
++
+.Example configuration
+[source,terminal]
+----
+apiServer:
+  auditLog:
+    maxFileSize: 200 <1>
+    maxFiles: 1 <2>
+    maxFileAge: 7 <3>
+    profile: Default <4>
+----
+<1> The maximum audit log file size in megabytes. If the value is 0, the limit is disabled. In this example, if the live log reaches the 200Mb limit, it is rotated, causing any existing log backup to be deleted.
+<2> The maximum number of rotated audit log files to retain. After the limit is reached, the log files in order from oldest to newest are deleted until the specified limits are reached. When the value is 0, the limit is disabled. In this example, the value `1` results in only 1 file of size `maxFileSize` being retained in addition to the current active log.
+<3> Specifies the maximum time in days that log files are kept. Files older than this limit will be deleted. When the value is 0, the limit is disabled. In this example, after a log file is more than 7 days old, it is deleted. The deletion happens regardless of whether the live log has reached the maximum file size as give in the `maxFileSize` field value.
+<4> Logs only metadata for read and write requests; does not log request bodies except for OAuth access token requests. If you do not specify this field, the Default profile is used.
+
+. If you are configuring audit log policies on a running instance, restart {microshift-short} by entering the following command:
++
+[source,terminal]
+----
+$ sudo systemctl restart microsohift
+----

modules/microshift-config-yaml.adoc

@@ -1,12 +1,12 @@
 // Module included in the following assemblies:
 //
-// * microshift/using-config-tools.adoc
+// * microshift_configuring/using-config-tools.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="microshift-config-yaml_{context}"]
 = Using a YAML configuration file
 
-On start up, {microshift-short} searches the system-wide `/etc/microshift/` directory for a configuration file named `config.yaml`. To use custom configurations, you must create the configuration file and specify any settings that are expected to override the defaults before starting {microshift-short}.
+On start up, {microshift-short} searches the system-wide `/etc/microshift/` directory for a configuration file named `config.yaml`. If the configuration file is not present, built-in default values are uses to start the service.
 
 [id="microshift-yaml-custom_{context}"]
 == Custom settings

modules/nodes-nodes-audit-config-about.adoc

@@ -1,14 +1,27 @@
 // Module included in the following assemblies:
 //
 // * security/audit-log-policy-config.adoc
+// * microshift_configuring/microshift-audit-logs-config.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="about-audit-log-profiles_{context}"]
 = About audit log policy profiles
 
+ifndef::microshift[]
 Audit log profiles define how to log requests that come to the OpenShift API server, Kubernetes API server, OpenShift OAuth API server, and OpenShift OAuth server.
+endif::microshift[]
 
+ifdef::microshift[]
+Audit log profiles define how to log requests that come to the OpenShift API server and the Kubernetes API server.
+endif::microshift[]
+
+ifndef::microshift[]
 {product-title} provides the following predefined audit policy profiles:
+endif::microshift[]
+
+ifdef::microshift[]
+{microshift-short} supports the following predefined audit policy profiles:
+endif::microshift[]
 
 [cols="1,2a",options="header"]
 |===
@@ -29,13 +42,21 @@ Audit log profiles define how to log requests that come to the OpenShift API ser
 
 [WARNING]
 ====
-It is not recommended to disable audit logging by using the `None` profile unless you are fully aware of the risks of not logging data that can be beneficial when troubleshooting issues. If you disable audit logging and a support situation arises, you might need to enable audit logging and reproduce the issue in order to troubleshoot properly.
+Do not disable audit logging by using the `None` profile unless you are fully aware of the risks of not logging data that can be beneficial when troubleshooting issues. If you disable audit logging and a support situation arises, you might need to enable audit logging and reproduce the issue to troubleshoot properly.
 ====
 
 |===
 [.small]
 --
-1. Sensitive resources, such as `Secret`, `Route`, and `OAuthClient` objects, are only ever logged at the metadata level. OpenShift OAuth server events are only ever logged at the metadata level.
+1. Sensitive resources, such as `Secret`, `Route`, and `OAuthClient` objects, are only logged at the metadata level.
+ifndef::microshift[]
+OpenShift OAuth server events are only ever logged at the metadata level.
+endif::microshift[]
 --
+ifndef::microshift[]
+By default, {product-title} uses the `Default` audit log profile. You can use another audit policy profile that also logs request bodies, but be aware of the increased resource usage such CPU, memory, and I/O.
+endif::microshift[]
 
-By default, {product-title} uses the `Default` audit log profile. You can use another audit policy profile that also logs request bodies, but be aware of the increased resource usage (CPU, memory, and I/O).
+ifdef::microshift[]
+By default, {microshift-short} uses the `Default` audit log profile. You can use another audit policy profile that also logs request bodies, but be aware of the increased resource usage such CPU, memory, and I/O.
+endif::microshift[]