Skip to content

Commit 5880156

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #75233 from ShaunaDiaz/OSDOCS-9437
OSDOCS-9437: adds custom audit log policies MicroShift
2 parents d824edb + cb65519 commit 5880156

7 files changed

+209
-6
lines changed

‎_topic_maps/_topic_map_ms.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -397,6 +397,8 @@ Topics:
397397
File: microshift-custom-ca
398398
- Name: Checking the status of Greenboot health checks
399399
File: microshift-greenboot-checking-status
400+
- Name: Configuring audit logging policies
401+
File: microshift-audit-logs-config
400402
---
401403
Name: Networking
402404
Dir: microshift_networking

‎microshift_configuring/microshift-audit-logs-config.adoc

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="microshift-audit-logs-config"]
3+
= Customizing audit logging policies
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-audit-logs-config
6+
7+
toc::[]
8+
9+
You can control audit log file rotation and retention by using configuration values.
10+
11+
include::modules/microshift-audit-logs-config-intro.adoc[leveloffset=+1]
12+
13+
// About audit log profiles; OCP module, edit with conditionals and care
14+
include::modules/nodes-nodes-audit-config-about.adoc[leveloffset=+1]
15+
16+
include::modules/microshift-audit-logs-config-proc.adoc[leveloffset=+1]
17+
18+
include::modules/microshift-audit-logs-troubleshoot.adoc[leveloffset=+1]

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Text snippet included in the following assemblies:
2+
//
3+
// * microshift_configuring/microshift-audit-logs-config.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="microshift-audit-logs-config-intro_{context}"]
7+
= About setting limits on audit log files
8+
9+
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.
10+
11+
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.
12+
13+
You can set fields in combination to define a maximum storage limit for retained logs. For example:
14+
15+
* Set both `maxFileSize` and `maxFiles` to create a log storage upper limit.
16+
* Set a `maxFileAge` value to automatically delete files older than the timestamp in the file name, regardless of the `maxFiles` value.
17+
18+
[id="Default-audit-log-values_{context}"]
19+
== Default audit log values
20+
21+
{microshift-short} includes the following default audit log rotation values:
22+
23+
* `maxFileSize`: 200Mb
24+
* `maxFiles`: 10 files
25+
* `maxFileAge`: 0, This value means that no default age limit is set.
26+
* `profile`: Default, This profile logs only metadata for read and write requests.
27+
28+
The maximum default storage usage for audit log retention is 2000Mb, provided that there are 10 or fewer files.
29+
30+
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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
// Text snippet included in the following assemblies:
2+
//
3+
// * microshift_configuring/microshift-audit-logs-config.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-configuring-audit-log-values_{context}"]
7+
= Configuring audit log values
8+
9+
You can configure audit log settings by using the {microshift-short} service configuration file.
10+
11+
.Procedure
12+
13+
. 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.
14+
15+
. Replace the default values in the `auditLog` section of the YAML with your desired valid values.
16+
+
17+
.Example default `auditLog` configuration
18+
[source,yaml]
19+
----
20+
apiServer:
21+
# ....
22+
auditLog:
23+
maxFileSize: 200 # <1>
24+
maxFiles: 1 # <2>
25+
maxFileAge: 7 # <3>
26+
profile: Default # <4>
27+
# ....
28+
----
29+
<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.
30+
<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.
31+
<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`.
32+
<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.
33+
34+
. 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:
35+
36+
.. Stop {microshift-short} by running the following command:
37+
+
38+
[source,terminal]
39+
----
40+
$ sudo systemctl stop microshift
41+
----
42+
.. Move the `/var/log/kube-apiserver` directory to your desired location by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ sudo mv /var/log/kube-apiserver <~/kube-apiserver> <1>
47+
----
48+
<1> Replace _<~/kube-apiserver>_ with the path to the directory that you want to use.
49+
50+
.. 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:
51+
+
52+
[source,terminal]
53+
----
54+
$ sudo ln -s <~/kube-apiserver> /var/log/kube-apiserver <1>
55+
----
56+
<1> Replace _<~/kube-apiserver>_ with the path to the directory that you want to use. This enables the collection of logs in sos reports.
57+
58+
. If you are configuring audit log policies on a running instance, restart {microshift-short} by entering the following command:
59+
+
60+
[source,terminal]
61+
----
62+
$ sudo systemctl restart microsohift
63+
----

‎modules/microshift-audit-logs-troubleshoot.adoc

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// Text snippet included in the following assemblies:
2+
//
3+
// * microshift_configuring/microshift-audit-logs-config.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-troubleshooting-audit-logs_{context}"]
7+
= Troubleshooting audit log configuration
8+
9+
Use the following steps to troubleshoot custom audit log settings and file locations.
10+
11+
.Procedure
12+
13+
* Check the current values that are configured by running the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ sudo microshift show-config --mode effective
18+
----
19+
+
20+
.Example output
21+
[source,yaml]
22+
----
23+
auditLog:
24+
maxFileSize: 200
25+
maxFiles: 1
26+
maxFileAge: 7
27+
profile: AllRequestBodies
28+
----
29+
30+
* Check the `audit.log` file permissions by running the following command:
31+
+
32+
[source,terminal]
33+
----
34+
$ sudo ls -ltrh /var/log/kube-apiserver/audit.log
35+
----
36+
+
37+
.Example output
38+
[source,terminal]
39+
----
40+
-rw-------. 1 root root 46M Mar 12 09:52 /var/log/kube-apiserver/audit.log
41+
----
42+
43+
* List the contents of the current log directory by running the following command:
44+
+
45+
[source,terminal]
46+
----
47+
$ sudo ls -ltrh /var/log/kube-apiserver/
48+
----
49+
+
50+
.Example output
51+
[source,terminal]
52+
----
53+
total 6.0M
54+
-rw-------. 1 root root 2.0M Mar 12 10:56 audit-2024-03-12T14-56-16.267.log
55+
-rw-------. 1 root root 2.0M Mar 12 10:56 audit-2024-03-12T14-56-49.444.log
56+
-rw-------. 1 root root 962K Mar 12 10:57 audit.log
57+
----

‎modules/microshift-config-yaml.adoc

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
// Module included in the following assemblies:
22
//
3-
// * microshift/using-config-tools.adoc
3+
// * microshift_configuring/using-config-tools.adoc
44

55
:_mod-docs-content-type: CONCEPT
66
[id="microshift-config-yaml_{context}"]
77
= Using a YAML configuration file
88

9-
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}.
9+
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.
1010

1111
[id="microshift-yaml-custom_{context}"]
1212
== Custom settings
@@ -16,3 +16,8 @@ To create custom configurations, you must create a `config.yaml` file in the `/e
1616
====
1717
Restart {microshift-short} after changing any configuration settings to have them take effect. The `config.yaml` file is read only when {microshift-short} starts.
1818
====
19+
20+
[TIP]
21+
====
22+
If you add all of the configurations you need at the same time, you can minimize system restarts.
23+
====

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

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,27 @@
11
// Module included in the following assemblies:
22
//
33
// * security/audit-log-policy-config.adoc
4+
// * microshift_configuring/microshift-audit-logs-config.adoc
45

56
:_mod-docs-content-type: CONCEPT
67
[id="about-audit-log-profiles_{context}"]
78
= About audit log policy profiles
89

10+
ifndef::microshift[]
911
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.
12+
endif::microshift[]
1013

14+
ifdef::microshift[]
15+
Audit log profiles define how to log requests that come to the OpenShift API server and the Kubernetes API server.
16+
endif::microshift[]
17+
18+
ifndef::microshift[]
1119
{product-title} provides the following predefined audit policy profiles:
20+
endif::microshift[]
21+
22+
ifdef::microshift[]
23+
{microshift-short} supports the following predefined audit policy profiles:
24+
endif::microshift[]
1225

1326
[cols="1,2a",options="header"]
1427
|===
@@ -24,18 +37,33 @@ Audit log profiles define how to log requests that come to the OpenShift API ser
2437
|`AllRequestBodies`
2538
|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]^
2639

40+
ifndef::microshift[]
41+
|`None`
42+
|No requests are logged, including OAuth access token requests and OAuth authorize token requests. Custom rules are ignored when this profile is set.
43+
endif::microshift[]
44+
45+
ifdef::microshift[]
2746
|`None`
28-
|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.
47+
|No requests are logged, including OAuth access token requests and OAuth authorize token requests.
48+
endif::microshift[]
2949

3050
[WARNING]
3151
====
32-
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.
52+
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.
3353
====
3454

3555
|===
3656
[.small]
3757
--
38-
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.
58+
1. Sensitive resources, such as `Secret`, `Route`, and `OAuthClient` objects, are only logged at the metadata level.
59+
ifndef::microshift[]
60+
OpenShift OAuth server events are only logged at the metadata level.
61+
endif::microshift[]
3962
--
63+
ifndef::microshift[]
64+
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.
65+
endif::microshift[]
4066

41-
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).
67+
ifdef::microshift[]
68+
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.
69+
endif::microshift[]

0 commit comments

Comments
 (0)