docs: Update mental model and documentation for tool responsibilities

- Add MENTALMODEL.md documenting architecture and tool responsibilities
- Clarify Salt is for ongoing configuration management and automation
- Clarify Ansible is for ComplianceAsCode deployment from github.com/ComplianceAsCode/content
- Update README.md to reflect correct understanding of tool purposes
- Update decision matrix for when to use each tool
- Document migration path and future service plans (Beszel, Netbird via Salt)

Establishes clear separation of concerns across the configuration management ecosystem.

💘 Generated with Crush

Assisted-by: GLM-4.6 via Crush <crush@charm.land>
This commit is contained in:
2026-01-21 11:51:56 -05:00
parent afe61cae9d
commit c5a504f9c8
2 changed files with 85 additions and 13 deletions

View File

@@ -2,13 +2,13 @@
This repository contains the KNEL server configuration management system implemented with the FetchApply framework.
**NOTE:** This is a one-time provisioning system. For ongoing configuration management, this will be replaced by:
- Ansible playbooks for configuration management
- Salt for system orchestration
**NOTE:** This is a one-time provisioning system. For ongoing configuration management, this uses:
- Salt for system configuration and automation
- Ansible for ComplianceAsCode deployment
## Overview
The KNEL FetchApply system provides automated server provisioning for Linux servers. It uses the FetchApply framework to apply initial configurations and then serves as a foundation for migrating to Ansible/Salt-based management.
The KNEL FetchApply system provides automated server provisioning for Linux servers. It uses the FetchApply framework to apply initial configurations and then serves as a foundation for Salt/Ansible-based management.
## Repository Structure
@@ -83,7 +83,7 @@ The system automatically detects:
### Core Setup
- **system-setup** - System detection and variable setup
- **packages** - Package installation with conditional logic (includes ansible-core, salt-minion, tailscale)
- **packages** - Package installation with conditional logic (includes ansible-core for ComplianceAsCode, salt-minion for ongoing management, tailscale for VPN)
- **user-configuration** - Shell settings and user preferences
### Configuration
@@ -91,7 +91,7 @@ The system automatically detects:
- **ssh-hardening** - SSH security hardening
- **ssh-keys** - Deploy SSH authorized keys
- **postfix** - Configure email delivery
- **salt-client** - Configure Salt minion for configuration management
- **salt-client** - Configure Salt minion for ongoing configuration management
### Security
- **2fa** - Set up Google Authenticator for 2FA
@@ -103,12 +103,20 @@ The system automatically detects:
## Configuration Management Tools
The system installs clients for future configuration management:
The system installs clients for specific management purposes:
- **Ansible Core** - Already installed for ad-hoc automation tasks
- **Salt Minion** - Configured and ready for Salt master connection
- **Ansible Core** - For deploying ComplianceAsCode content from https://github.com/ComplianceAsCode/content
- **Salt Minion** - For ongoing system configuration, automation, and orchestration
- **Tailscale** - VPN connectivity for secure remote access
## Tool Responsibilities
| Tool | Primary Responsibility | When Used |
|-------|-------------------|-----------|
| FetchApply | Initial server provisioning | Once at deployment |
| Salt | Ongoing configuration & automation | Continuously |
| Ansible | ComplianceAsCode deployment | Periodically/on-demand |
## Security Features
- SSH key-based authentication only
@@ -119,11 +127,20 @@ The system installs clients for future configuration management:
## Migration Path
This system is designed as an initial provisioning step. Future migration plans:
This system provides the foundation for comprehensive management:
1. **Ansible Playbooks** - Replace initializers with Ansible roles for configuration management
2. **Salt Configuration** - Use Salt master for ongoing configuration orchestration
3. **Vault Integration** - Centralized secrets management
1. **FetchApply** - Initial server provisioning (this repo)
2. **Salt Master** - Ongoing configuration management and automation
3. **Ansible Playbooks** - ComplianceAsCode deployment and management
4. **Future Services** - Beszel monitoring and Netbird networking via Salt
## Compliance Management
Ansible will be used specifically to deploy and manage:
- Compliance frameworks from https://github.com/ComplianceAsCode/content
- Security baselines and hardening rules
- Compliance validation and reporting
- Documentation generation
## Troubleshooting