rblundon/homelab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README for mk-labs architecture

Browse Source
This commit is contained in:
Ryan Blundon
2026-02-25 20:55:38 -06:00
parent 6350cb681f
commit 63b9a8fd13
4 changed files with 75 additions and 212 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
README.md
View File

@@ -1,239 +1,102 @@
# A Homelab based on Red Hat Technologies
# mk-labs
A comprehensive homelab for learning advanced concepts primarily based on Red Hat OpenShift. In addition to providing services, it is an area to incorporate container technologies, and enterprise integration scenarios.
Automated infrastructure provisioning and configuration for a personal homelab, built on GitOps practices with clear tool responsibility boundaries.
This implementation is built on easily accessible consumer based hardware and will focus heavily on GitOps practices and automation will be used wherever possible.
## Architecture
## 🎯 Project Goals
- **Kubernetes cluster for applications**
- **IAM integration testing**
- **GitOps and automation workflows**
## 📋 Documentation (Priority Order)
### Phase 1: Foundation
1. **[Overview & Hardware Allocation](./docs/01-overview.md)** - Complete architecture overview
2. **[Networking Plan](./docs/02-networking.md)** - VLAN strategy and network design
3. **[Core Services Setup](./docs/03-core-services.md)** *(TBD)* - Ansible, DNS, monitoring
4. **[Storage Configuration](./docs/04-storage.md)** *(TBD)* - Synology, democratic-csi
### Phase 2: Proxmox Platform
5. **[Proxmox Installation](./docs/11-vsphere-setup.md)** *(TBD)* - Dell 7050 virtualization
6. **[VM Templates & Automation](./docs/13-vm-automation.md)** *(TBD)* - Template creation
### Phase 3: Infrastructure Services
7. **[Recursive DNS]
8. **[Authoritative DNS]
9. **[Identity Management](./docs/10-acm-setup.md)** *(TBD)*
10. **[Matchbox] (Depreciated?)
### Phase 4: OpenShift Clusters (Depreciated)
8. **[OpenShift SNO + Worker](./docs/09-openshift-sno.md)** *(TBD)* - ACM Hub Cluster
9. **[OpenShift Cluster](./docs/08-openshift-compact.md)** *(TBD)* - 3 Master/3 Worker node (production-like)
10. **[ACM Configuration](./docs/10-acm-setup.md)** *(TBD)* - Multi-cluster management
11. **[HCP Cluster](./docs/10-acm-setup.md)** *(TBD)* - External app cluster
### Phase 5: Kubernetes Container Platform
5. **[Container Registry Setup](./docs/05-container-registry.md)** *(TBD)* - Harbor deployment
6. **[Git Repository Setup](./docs/06-git-repository.md)** *(TBD)* - Gitea/GitLab on Synology
7. **[Artifact Repository](./docs/07-artifact-repository.md)** *(TBD)* - Nexus/Artifactory
### Phase 6: Advanced Services
14. **[Monitoring & Observability](./docs/14-monitoring.md)** *(TBD)* - Prometheus, Grafana, Splunk
15. **[Security & Compliance](./docs/15-security.md)** *(TBD)* - ACS, certificates, auditing
16. **[Backup & DR](./docs/16-backup-dr.md)** *(TBD)* - Backup strategies
## 🚀 Quick Start Deployment
### Prerequisites
- Ubiquiti UDM Pro configured
- Hardware powered and networked
- Initial VLAN setup (see [networking plan](./docs/02-networking.md))
### Ansible Collections
- ansible-galaxy collection install freeipa.ansible_freeipa
### Deployment Scripts
```bash
source ~/venv-ansible/bin/activate
# Phase 1: Foundation
./scripts/01-network-setup.sh
./scripts/02-core-services-deploy.sh
# Phase 2: Container Platform
./deployment/synology/docker-compose.yml # Git repo, Harbor, Nexus
./scripts/03-storage-setup.sh
# Phase 3: OpenShift
./deployment/openshift/compact-cluster/
./deployment/openshift/sno-cluster/
# Phase 4: Proxmox
./deployment/proxmox/
A single operator action — setting a VM record's status to **Staged** in NetBox — triggers a fully automated provisioning pipeline:
```
NetBox (webhook) → n8n (validate & orchestrate) → Terraform (create VM + DHCP)
→ Ansible (OS config + DNS + status update)
```
## 📁 Repository Structure
| Tool | Host | IP | Responsibility |
|------|------|----|---------------|
| NetBox | fire-station | 10.1.71.102 | Source of truth — VM records, IP allocation, VLAN data |
| n8n | tiki-room | 10.1.71.23 | Event orchestration, validation, pipeline sequencing |
| Terraform | city-hall | 10.1.71.35 | Proxmox VM lifecycle, Unifi DHCP reservations |
| Ansible / Semaphore | imagineering | 10.1.71.22 | OS configuration, DNS records, NetBox status updates |
| Proxmox | fantasyland | 10.1.71.13 | Target hypervisor |
All systems on the Server Trusted VLAN (10.1.71.0/24).
## Repository Structure
```
homelab/
├── README.md # This file
├── docs/ # Documentation (numbered by priority)
│ ├── 01-overview.md
│ ├── 02-networking.md
│ └── ...
├── ansible/ # Directory structure for Ansible
├── deployment/ # Deployment
configurations
│ ├── synology/ # Docker Compose files for Synology
│ ├── k0s/ # k0s cluster manifests
│ ├── openshift/ # OpenShift installation configs
│ └── proxmox/ # Proxmox automation
├── scripts/ # Automation scripts
└── .gitignore # Excludes sensitive data
├── ansible/
│ ├── inventory/ # NetBox dynamic inventory + static
│ ├── playbooks/ # Runnable playbooks (vm-provision, DNS, OS updates)
│ ├── roles/ # vm-baseline, dns-manager, common, haproxy, n8n, observer, etc.
│ ├── tasks/ # Shared includable task files
│ ├── group_vars/ # Group variable definitions
│ ├── host_vars/ # Per-host variable definitions
│ ├── templates/ # Jinja2 templates
│ └── ansible.cfg
│
├── terraform/
│ ├── proxmox/vm/ # bpg/proxmox provider — VM creation from templates
│ ├── unifi/dhcp/ # Unifi provider — DHCP static reservations on UDM Pro
│ └── dns/ # DNS record management
│
├── packer/
│ ├── ubuntu-24.04/ # Ubuntu 24.04 VM template (small → xlarge-plus sizes)
│ └── fedora-42/ # Fedora 42 VM template
│
├── n8n/
│ └── workflows/ # Exported n8n workflow JSON (vm-provisioning)
│
├── netbox/
│ └── initializers/ # Custom fields, VLANs, IP prefixes as code
│
└── docs/
└── decisions/ # Architecture decision records
```
## 🔧 Technology Stack
## Pipeline Flow
### Infrastructure
- **Networking**: Ubiquiti UDM Pro
- **Storage**: Synology DS1621+, Ubiquiti UNAS Pro
- **Compute**: 3x Minisforum TH60, 2x Minisforum MS01, 7x Dell 7050 SFF
| # | System | Action |
|---|--------|--------|
| 1 | NetBox | Operator sets VM status to Staged → webhook fires |
| 2 | n8n | Validates payload (hostname, IP, VLAN, template, proxmox_node) |
| 3 | n8n → city-hall | SSH + `terraform apply` — creates VM on Proxmox |
| 4 | n8n | Queries Proxmox API for MAC address |
| 5 | n8n → NetBox | Writes MAC to VM interface record |
| 6 | n8n → city-hall | SSH + `terraform apply` — creates DHCP reservation on UDM Pro |
| 7 | n8n → imagineering | Triggers Ansible via Semaphore API |
| 8 | Ansible | OS baseline, SSH hardening, Technitium DNS A record |
| 9 | Ansible → NetBox | Sets VM status to Active |
### Container Platforms
- **k8s**: Core services cluster
- **Proxmox**: VM workloads
### Core Services
- **Container Registry**: Harbor
- **Git Repository**: Gitea/GitLab CE
- **Artifact Repository**: Nexus/Artifactory
- **Monitoring**: Prometheus + Grafana
- **Logging**: Splunk Enterprise
- **DNS**: CoreDNS
- **Load Balancing**: MetalLB + HAProxy
## 🔐 Security Notes
- **No sensitive data** is stored in this repository
- **Secrets management** via external-secrets-operator
- **Certificate management** via cert-manager
- **Network segmentation** via VLANs and firewall rules
## 🤝 Contributing
This is a personal homelab project, but feel free to:
- Submit issues for questions or suggestions
- Fork for your own homelab adaptations
- Share improvements via pull requests
## 📞 Next Steps
1. **Create GitHub repository** for version control
2. **Start with Phase 1** foundation setup
3. **Build deployment automation** as we go
4. **Document lessons learned** for future reference
---
**Status**: 🚧 Planning & Initial Development
**Last Updated**: June 2025
This repo is a mono-repo that is broken up into three sections:
- infra-config
- apps
- cluster
On any failure, NetBox status is set to **Failed**. No auto-retry — operator investigates.
## Hardware
- Dell 7050 SFF (7)
- Minisforum TH60 (3)
- Minisforum MS01 (2)
- Synology 1621+
- 7× Dell 7050 SFF
- 3× Minisforum TH60
- 2× Minisforum MS01
- Synology DS1621+
- Ubiquiti UDM Pro
## Software
## Software Stack
- Proxmox (Virtualization)
- Cloudflare (Domain Hosting, Public DNS)
- Unbound (Recursive DNS)
- FreeIPA (Identity management, Authoritive DNS)
- Matchbox (iPXE)
- Red Hat OpenShift
- OpenShift Agent Based Installer (Install OpenShift)
- [Red Hat Advanced Cluster Management for Kubernetes](https://www.redhat.com/en/technologies/management/advanced-cluster-management)
- [Vault](https://www.hashicorp.com/en/products/vault)
- [OpenShift GitOps (ArgoCD)](https://www.redhat.com/en/technologies/cloud-computing/openshift/gitops)
- [Red Hat Ansible Automation Platform](https://www.redhat.com/en/technologies/management/ansible)
## Prerequisites
- Ansible user created
- Ansible configured
- [Networking](docs/networks.md)
- [Proxmox](docs/proxmox.md) (In my homelab, internal DNS, identity manangement, and ipxe are hosted here.)
- Matchbox
- DNS
- Domain Registration
## Assumptions
There are a dozen different architectures you could use to deploy OpenShift in every which way.
For the sake of this documentation we'll assume the following:
- **Virtualization**: Proxmox
- **Automation**: Terraform, Ansible, n8n, Semaphore
- **DNS**: Technitium (authoritative), Unbound (recursive)
- **IPAM/DCIM**: NetBox
- **Networking**: Ubiquiti UDM Pro
- **Templates**: Packer (Ubuntu 24.04, Fedora 42)
## Getting Started
[Step-by-Step Walkthrough](step-by-step.md)
See [docs/decisions/vm-provisioning-flow.md](docs/decisions/vm-provisioning-flow.md) for the full architecture decision record.
### Hub Cluster
Previous OpenShift/ACM/Fastpass content is preserved in the `archive/pre-mk-labs` branch.
You'll need an OpenShift "Hub Cluster" with access to persistant storage.
A Single Node OpenShift (SNO) instance, installed on bare metal, will act as a Hub cluster and run:
## Security
- Advanced Cluster Management
- Ansible Automation Platform
- Vault
- ~~OpenShift GitOps~~
#### Network Prerequisites
The prerequisites for OpenShift in traditional and HCP patterns are largely the same - it just kind of depends on where your DNS records go to.
| Cluster | Endpoint | VIP | DNS A Record | Notes |
|------------------|-------------|---------------|-----------------------------------|----------------------------------|
| Hub Cluster (SNO) | App Ingress | 192.168.0.10 | *.apps.hub-cluster.example.com | SNO App VIP goes to IP of node |
| Hub Cluster (SNO) | API | 192.168.0.10 | api.hub-cluster.example.com | SNO API goes to IP of node |
These DNS entries should be put in your Authoratitive DNS.
#### ACM & GitOps Configuration
Before you start creating clusters you may want to create some Policies, integrate ACM and ArgoCD, etc. This step is optional in case you're just interested in trying out Hosted Control Planes or copy/paste around a cluster for testing purposes.
Find additional details in the ./02-rhacm-config folder.
#### Creating a Cluster
With everything in its right place, you can now start to declaratively create clusters
./05-clusters/hcp-bmh - HCP to Bare Metal Hosts
### Internal Cluster
Two additional bare metal nodes, to be added to Advanced Cluster Management (ACM) running on the SNO Hub. These will be used to create another HCP cluster.
These servers have a BMC interface with Redfish - if not, then you'll need to manually manage the boot and installation of those servers.
This makes it to where you just need 3 bare metal nodes. You could run one HCP Bare Metal cluster with both of the other nodes, but then you have a shared storage requirement that can't be satisfied by ODF since that needs at least 3 nodes.
### External Cluster
You'll also either need you just need at least 2 bare metal nodes.
No sensitive data is stored in this repository. Secrets are managed via Ansible Vault and environment variables on pipeline hosts.
---
## Credits
**Status**: 🚧 Active Development — VM Provisioning Pipeline
- Ken Moini - As I used his [repo](https://github.com/kenmoini/ztp-for-you-and-me) as the baseline for this project.
- Ryan Etten
- Andrew Potozniak
**Last Updated**: February 2026

0
terraform/dns/.gitkeep Normal file
View File

0
terraform/proxmox/vm/.gitkeep Normal file
View File

0
terraform/unifi/dhcp/.gitkeep Normal file
View File