diff --git a/MENTALMODEL.md b/MENTALMODEL.md new file mode 100644 index 0000000..e97c234 --- /dev/null +++ b/MENTALMODEL.md @@ -0,0 +1,55 @@ +# KNEL Configuration Management Mental Model + +## Architecture Overview + +### FetchApply - One-Time Provisioning +- **Purpose:** Initial server setup and basic configuration +- **When:** Runs once at first boot of newly provisioned system +- **What:** System detection, package installation, security hardening, basic monitoring setup + +### Salt - Ongoing Configuration Management & Automation +- **Purpose:** Day-to-day system configuration, automation, and orchestration +- **When:** Continuously via Salt master/minion relationship +- **What:** + - Configuration management (file distribution, service management) + - Ad-hoc automation tasks + - System orchestration + - Application deployment + - Beszel client configuration and management + - Netbird client configuration and management (future) + +### Ansible - ComplianceAsCode Deployment +- **Purpose:** Deploy and manage compliance as code content +- **When:** Periodically or on-demand compliance deployment +- **What:** + - Deploy https://github.com/ComplianceAsCode/content + - Apply compliance frameworks (CIS, STIG, etc.) + - Compliance validation and remediation + - Documentation generation + +### Network Services +- **Tailscale:** Currently active VPN overlay network +- **Netbird:** Future replacement (to be deployed via Salt) +- **Beszel:** Future monitoring replacement (to be deployed via Salt) + +## Migration Path + +1. **Current State:** FetchApply + Manual Management +2. **Transition State:** FetchApply + Salt + Ansible +3. **Future State:** Salt + Ansible (FetchApply deprecated) + +## Tool Responsibilities + +| Tool | Primary Responsibility | Secondary Responsibilities | +|-------|-------------------|------------------------| +| FetchApply | Initial provisioning | Foundation setup | +| Salt | Ongoing configuration | Automation, orchestration, client deployment | +| Ansible | Compliance deployment | Documentation, validation | + +## Decision Matrix + +- **Use Salt for:** System configuration, automation, deployment, ongoing management +- **Use Ansible for:** Compliance as code, security frameworks, documentation +- **Use FetchApply for:** Initial server setup (temporary, to be replaced) + +This model ensures clear separation of concerns while providing comprehensive coverage of system lifecycle management. \ No newline at end of file diff --git a/README.md b/README.md index 3fdfdcd..b9a6a5b 100644 --- a/README.md +++ b/README.md @@ -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