Skip to content

Configuration Section Reorganization Summary

This document summarizes the reorganization of the Configuration section in the documentation.

Overview

The Configuration section has been completely reorganized to improve usability, maintainability, and logical structure. The reorganization follows the established pattern used in other sections of breaking down large documents into focused subdirectories with dedicated content files.

Previous Structure

The previous structure consisted of:

  • configuration/index.md - Focused on kubeconfig generation
  • configuration/inventory.md - Directory inventory
  • configuration/advanced/ - Subdirectory for advanced configuration
    • advanced/index.md - Overview of advanced configuration
    • advanced/thresholds.md - Threshold configuration documentation
    • advanced/plugin-modifications.md - Plugin modification documentation
    • advanced/saf-cli-integration.md - SAF CLI integration documentation
    • advanced/inventory.md - Advanced directory inventory

This structure had several limitations:

  1. Mixed different configuration concerns in single files
  2. Inconsistent organization with some topics at root level and others in subdirectories
  3. Limited scalability for adding new configuration topics
  4. No clear organization by functional area

New Structure

The new structure organizes content by functional area into focused subdirectories:

  • configuration/ - Root directory
    • index.md - Overview of configuration options
    • inventory.md - Directory inventory
    • kubeconfig/ - Kubernetes authentication configuration
      • index.md - Overview of kubeconfig configuration
      • inventory.md - Directory inventory
      • generation.md - Kubeconfig generation documentation
      • management.md - Kubeconfig management documentation
      • security.md - Kubeconfig security documentation
      • dynamic.md - Dynamic kubeconfig generation documentation
    • thresholds/ - Compliance threshold configuration
      • index.md - Overview of threshold configuration
      • inventory.md - Directory inventory
      • basic.md - Basic threshold configuration
      • advanced.md - Advanced threshold configuration
      • examples.md - Example threshold configurations
      • cicd.md - CI/CD integration for thresholds
    • plugins/ - Plugin customization
      • index.md - Overview of plugin customization
      • inventory.md - Directory inventory
      • distroless.md - Distroless container support
      • implementation.md - Implementation guide
      • testing.md - Testing guide
    • integration/ - Integration configuration
      • index.md - Overview of integration configuration
      • inventory.md - Directory inventory
      • saf-cli.md - SAF CLI integration
      • github.md - GitHub Actions integration
      • gitlab.md - GitLab CI integration
    • security/ - Security configuration
      • index.md - Overview of security configuration
      • inventory.md - Directory inventory
      • hardening.md - Security hardening
      • credentials.md - Credential management
      • rbac.md - RBAC configuration
    • advanced/ - Legacy directory (with redirects to new locations)
      • index.md - Redirects to main configuration overview
      • thresholds.md - Redirects to thresholds section
      • plugin-modifications.md - Redirects to plugins section
      • saf-cli-integration.md - Redirects to integration section
      • inventory.md - Legacy directory inventory

Content Extraction and Enhancement

The reorganization involved:

  1. Content Extraction: Extracting content from existing files into focused topic files
  2. Content Enhancement: Adding new content to cover gaps and provide more detailed documentation
  3. Cross-referencing: Maintaining and enhancing cross-references between related topics
  4. Redirects: Adding redirects from legacy files to new locations to maintain backward compatibility

The navigation in mkdocs.yml has been updated to reflect the new structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
- Configuration:
  - Overview: configuration/index.md
  - Directory Contents: configuration/inventory.md
  - Kubeconfig:
    - Overview: configuration/kubeconfig/index.md
    - Directory Contents: configuration/kubeconfig/inventory.md
    - Generation: configuration/kubeconfig/generation.md
    - Management: configuration/kubeconfig/management.md
    - Security: configuration/kubeconfig/security.md
    - Dynamic Configuration: configuration/kubeconfig/dynamic.md
  - Thresholds:
    - Overview: configuration/thresholds/index.md
    - Directory Contents: configuration/thresholds/inventory.md
    - Basic Configuration: configuration/thresholds/basic.md
    - Advanced Configuration: configuration/thresholds/advanced.md
    - Example Configurations: configuration/thresholds/examples.md
    - CI/CD Integration: configuration/thresholds/cicd.md
  - Plugin Customization:
    - Overview: configuration/plugins/index.md
    - Directory Contents: configuration/plugins/inventory.md
    - Distroless Support: configuration/plugins/distroless.md
    - Implementation Guide: configuration/plugins/implementation.md
    - Testing Guide: configuration/plugins/testing.md
  - Integration:
    - Overview: configuration/integration/index.md
    - Directory Contents: configuration/integration/inventory.md
    - SAF CLI Integration: configuration/integration/saf-cli.md
    - GitHub Actions: configuration/integration/github.md
    - GitLab CI: configuration/integration/gitlab.md
  - Security:
    - Overview: configuration/security/index.md
    - Directory Contents: configuration/security/inventory.md
    - Hardening: configuration/security/hardening.md
    - Credential Management: configuration/security/credentials.md
    - RBAC Configuration: configuration/security/rbac.md
  - Legacy:
    - Advanced Configuration: configuration/advanced/index.md
    - Scanning Thresholds: configuration/advanced/thresholds.md
    - Plugin Modifications: configuration/advanced/plugin-modifications.md
    - SAF CLI Integration: configuration/advanced/saf-cli-integration.md
    - Directory Contents: configuration/advanced/inventory.md

Benefits of the New Structure

The reorganization provides several benefits:

  1. Logical Organization: Content is now organized by functional area
  2. Improved Discoverability: Users can more easily find related configuration topics
  3. Enhanced Maintainability: Focused files are easier to maintain and update
  4. Better Scalability: New configuration topics can be added to the appropriate subdirectory
  5. Consistent Structure: Follows the same pattern used in other sections (approaches, security)
  6. Progressive Disclosure: Users can start with high-level overview and drill down into details
  7. Enhanced Navigation: Clearer navigation structure in the sidebar

Backward Compatibility

To ensure backward compatibility:

  1. Legacy files include redirects to their new locations
  2. Legacy files are still accessible in the navigation under the "Legacy" section
  3. Cross-references from other sections have been updated to point to the new locations

Next Steps

With the Configuration section reorganization complete, the focus will shift to:

  1. Reorganizing the Architecture section
  2. Reorganizing the Integration section
  3. Continuing Phase 4 (review and refinement) of documentation refactoring
  4. Addressing remaining documentation gaps
  5. Implementing documentation validation tools