OSDOCS-9437: adds audit log config 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: Configuring audit logging policies
+  File: microshift-audit-logs-config
 ---
 Name: Networking
 Dir: microshift_networking

microshift_configuring/microshift-audit-logs-config.adoc

@@ -0,0 +1,18 @@
+:_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 control audit log file rotation and retention by using configuration values.
+
+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]
+
+include::modules/microshift-audit-logs-troubleshoot.adoc[leveloffset=+1]

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

@@ -0,0 +1,30 @@
+// 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
+
+Controlling the rotation and retention of the audit log file by using configuration values helps keep the limited storage capacities of far-edge devices from being exceeded. On such devices, logging data accumulation can limit host system or cluster workloads, potentially causing the device stop working. Setting audit log policies can help ensure that critical processing space is continually available.
+
+The values you set to limit audit logs 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:
+
+* `maxFileSize`: 200Mb
+* `maxFiles`: 10 files
+* `maxFileAge`: 0, This value means that no default age limit is set.
+* `profile`: Default, This profile logs only metadata for read and write requests.
+
+The maximum default storage usage for audit log retention is 2000Mb, provided that there are 10 or fewer files.
+
+If you do not specify a value for a field, the default value is used. If you remove a previously set field value, the default value is restored after the next {microshift-short} service restart.

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

@@ -0,0 +1,63 @@
+// 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
+
+You can configure audit log settings by using the {microshift-short} service configuration file.
+
+.Procedure
+
+. Make a copy of the provided `config.yaml.default` file in the `/etc/microshift/` directory, renaming it `config.yaml`. Keep the new {microshift-short} `config.yaml` you create in the `/etc/microshift/` directory. The new `config.yaml` is read whenever the {microshift-short} service starts. After you create it, the `config.yaml` file takes precedence over built-in settings.
+
+. Replace the default values in the `auditLog` section of the YAML with your desired valid values.
++
+.Example default `auditLog` configuration
+[source,yaml]
+----
+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, the file is rotated as soon as the live log reaches the 200 MB limit.
+<2> The maximum number of rotated audit log files retained. After the limit is reached, the log files in order from oldest to newest are deleted. 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 are deleted. If 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 files are deleted regardless of whether or not the live log has reached the maximum file size specified in the `maxFileSize` field. File age is determined by the timestamp written in the name of the rotated log file, for example, `audit-2024-05-16T17-03-59.994.log`.
+<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.
+
+. Optional: To specify a new directory for logs, you can stop {microshift-short}, and then move the `/var/log/kube-apiserver` directory to your desired location:
+
+.. Stop {microshift-short} by running the following command:
++
+[source,terminal]
+----
+$ sudo systemctl stop microshift
+----
+.. Move the `/var/log/kube-apiserver` directory to your desired location by running the following command:
++
+[source,terminal]
+----
+$ sudo mv /var/log/kube-apiserver <~/kube-apiserver> <1>
+----
+<1> Replace _<~/kube-apiserver>_ with the path to the directory that you want to use.
+
+.. If you specified a new directory for logs, create a symlink to your custom directory at `/var/log/kube-apiserver` by running the following command:
++
+[source,terminal]
+----
+$ sudo ln -s <~/kube-apiserver> /var/log/kube-apiserver <1>
+----
+<1> Replace _<~/kube-apiserver>_ with the path to the directory that you want to use. This enables the collection of logs in sos reports.
+
+. 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-audit-logs-troubleshoot.adoc

@@ -0,0 +1,57 @@
+// Text snippet included in the following assemblies:
+//
+// * microshift_configuring/microshift-audit-logs-config.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="microshift-troubleshooting-audit-logs_{context}"]
+= Troubleshooting audit log configuration
+
+Use the following steps to troubleshoot custom audit log settings and file locations.
+
+.Procedure
+
+* Check the current values that are configured by running the following command:
++
+[source,terminal]
+----
+$ sudo microshift show-config --mode effective
+----
++
+.Example output
+[source,yaml]
+----
+auditLog:
+    maxFileSize: 200
+    maxFiles: 1
+    maxFileAge: 7
+    profile: AllRequestBodies
+----
+
+* Check the `audit.log` file permissions by running the following command:
++
+[source,terminal]
+----
+$ sudo ls -ltrh /var/log/kube-apiserver/audit.log
+----
++
+.Example output
+[source,terminal]
+----
+-rw-------. 1 root root 46M Mar 12 09:52 /var/log/kube-apiserver/audit.log
+----
+
+* List the contents of the current log directory by running the following command:
++
+[source,terminal]
+----
+$ sudo ls -ltrh /var/log/kube-apiserver/
+----
++
+.Example output
+[source,terminal]
+----
+total 6.0M
+-rw-------. 1 root root 2.0M Mar 12 10:56 audit-2024-03-12T14-56-16.267.log
+-rw-------. 1 root root 2.0M Mar 12 10:56 audit-2024-03-12T14-56-49.444.log
+-rw-------. 1 root root 962K Mar 12 10:57 audit.log
+----

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}.
+At start up, {microshift-short} checks the system-wide `/etc/microshift/` directory for a configuration file named `config.yaml`. If the configuration file does not exist in the directory, the built-in default values are used to start the service.
 
 [id="microshift-yaml-custom_{context}"]
 == Custom settings
@@ -16,3 +16,8 @@ To create custom configurations, you must create a `config.yaml` file in the `/e
 ====
 Restart {microshift-short} after changing any configuration settings to have them take effect. The `config.yaml` file is read only when {microshift-short} starts.
 ====
+
+[TIP]
+====
+If you add all of the configurations you need at the same time, you can minimize system restarts.
+====

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"]
 |===
@@ -24,18 +37,33 @@ Audit log profiles define how to log requests that come to the OpenShift API ser
 |`AllRequestBodies`
 |In addition to logging metadata for all requests, logs request bodies for  every read and write request to the API servers (`get`, `list`, `create`, `update`, `patch`). This profile has the most resource overhead. ^[1]^
 
+ifndef::microshift[]
+|`None`
+|No requests are logged, including OAuth access token requests and OAuth authorize token requests. Custom rules are ignored when this profile is set.
+endif::microshift[]
+
+ifdef::microshift[]
 |`None`
-|No requests are logged; even OAuth access token requests and OAuth authorize token requests are not logged. Custom rules are ignored when this profile is set.
+|No requests are logged, including OAuth access token requests and OAuth authorize token requests.
+endif::microshift[]
 
 [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 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 as 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 as CPU, memory, and I/O.
+endif::microshift[]