refactored formatting to fit #1555 template changes

enhancements/microshift/audit-log-configuration-options.md

@@ -87,7 +87,21 @@ apiServer:
     maxFileAge: STRING
 ```
 
-### Implementation Details
+### Topology Considerations
+
+#### Hypershift / Hosted Control Planes
+
+- N/A
+
+#### Standalone Clusters
+
+- N/A
+
+#### Single-node Deployments or MicroShift
+
+- This EP is specific to MicroShift only.
+
+### Implementation Details/Notes/Constraints
 
 **Passing User Provided Options to the API Server**
 MicroShift embeds a default API server config, written to disk during boot at `/var/lib/microshift/resources/kube-apiserver-audit-policies/default.yaml`. The file is structured as a `KubeAPIServerConfig` custom resource, provided by the `kubecontrolplane.config.openshift.io/v1` API group. During boot, the kube-apiserver service-manager collects kube-apiserver options from hardcoded defaults and merges these into the kube-apiserver config data structure.  The override values are iteratively patch onto the embedded default config.  The order of precedence is from first to last, such that field paths appearing later in the queue override data fields from previous iterations.  The logic which handles the overriding is [here](https://github.com/openshift/microshift/blob/ba79f993070111ae3b6e35c3abb3141e95901874/pkg/controllers/kube-apiserver.go#L226-L250). Thus, to pass user-defined audit configuration options to the API server, MicroShift will append the user-specified options to `overrides` array. This minimizes the complexity of the option-passing and allows for MicroShift defaults to continue to be specified as they are now.  This also provides an elegant fallback behavior for user-facing fields. If a user does not specify a value for a field, the default value will be used, just as it is now.  Should a user remove a field they previously set, then at next restart, the field will no longer be overridden, thus passing the default. All audit logging configuration fields must be optional. If not specified, the existing default audit logging policy will be used.
@@ -164,9 +178,7 @@ Note that "omitStages" is determines the point at which a message is logged. For
 
 - N/A
 
-## Design Details
-
-### Open Questions
+## Open Questions
 
 - Custom log paths: Can sos collect reports from dynamic paths? If not, can we symlink the log directory to as a means of faking a static path while writing logs to a custom location?  If so, can sos follow these symlinks?
 
@@ -176,60 +188,52 @@ Note that "omitStages" is determines the point at which a message is logged. For
 
     - Providing additional fields and internal handling logic is outside the scope of this EP. If this is a useful feature, it should be documented in a bespoke EP.
 
-### Test Plan
+## Test Plan
 
 * Unit tests to validate new config APIs
 * Integration tests to verify configured audit logging policies are applied properly
 
-### Graduation Criteria
+## Graduation Criteria
 
 * Upstream code, tests, docs merged
 * Downstream builds, docs updated
 * Automated CI coverage for new functionality
 * QE test plans defined
 
-#### Dev Preview -> Tech Preview
+### Dev Preview -> Tech Preview
 
 - Ability to utilize the enhancement end to end
 - End user documentation completed and published
 - Sufficient test coverage
 - Gather feedback from users
 - Available by default
 
-#### Tech Preview -> GA
+### Tech Preview -> GA
 
 - Sufficient time for feedback
 - End-to-end tests
 
-#### Removing a deprecated feature
+### Removing a deprecated feature
 
 - Announce deprecation and support policy of the existing feature
 - Deprecate the feature
 
-### Upgrade / Downgrade Strategy
+## Upgrade / Downgrade Strategy
 
 - The API must be backwards compatible for y-stream version
 
-### Operational Aspects of API Extensions
-
-- N/A
-
-#### Failure Modes
+## Operational Aspects of API Extensions
 
 - **Disk capacity exceeded**: MicroShift and the apiserver do not assess existing storage capacity for any logs, including audit logs.  As audit logs can grow quite quickly, this creates the potential for maxing out a storage device and hindering system performance.  Users must therefore consider their total storage needs, in addition to how and how often to transfer logs off-device.
 
-#### Support Procedures
+## Support Procedures
 
 - On startup, MicroShift should log the apiserver values and free remaining diskspace on the device containing the log files.  If the product of `maxFileSize` and `maxFiles` is greater than free storage, a warning message should be logged. 
 
 ### Version Skew Strategy
 
 - N/A
 
-## Implementation History
-
-- N/A
-
 ## Alternatives
 
 * Continue using hardcoded audit logging policy