107 lines
2.9 KiB
Markdown
107 lines
2.9 KiB
Markdown
|
# Homelab GitOps Repository
|
||
|
|
|
||
|
|
This repository contains the declarative configuration for my Kubernetes homelab, managed using FluxCD v2 and SOPS-encrypted secrets.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
The repository is organized into three layers:
|
||
|
|
|
||
|
|
### Layer 0 - Infrastructure
|
||
|
|
Core cluster infrastructure that other applications depend on:
|
||
|
|
- **cert-manager**: TLS certificate management
|
||
|
|
- **ingress-nginx**: Ingress controller for HTTP/HTTPS routing
|
||
|
|
- **storage**: Persistent volume provisioning
|
||
|
|
|
||
|
|
### Layer 1 - Platform
|
||
|
|
Platform services that support applications:
|
||
|
|
- **gitea**: Self-hosted Git server
|
||
|
|
- **harbor**: Container registry
|
||
|
|
- **n8n**: Workflow automation
|
||
|
|
- **mcp-servers**: Model Context Protocol servers with gateway
|
||
|
|
- **gotify**: Push notifications
|
||
|
|
- **prometheus**: Monitoring and alerting
|
||
|
|
|
||
|
|
### Layer 2 - Apps
|
||
|
|
User-facing applications:
|
||
|
|
- **media**: Audiobookshelf, Media-Servarr stack, MPD
|
||
|
|
- **ai**: Ollama, Open WebUI
|
||
|
|
- **file-sharing**: Firefox Send, Pairdrop, Pingvin Share, PsiTransfer
|
||
|
|
- **utilities**: BentoPDF, Stirling PDF, Minecraft
|
||
|
|
|
||
|
|
## Secrets Management
|
||
|
|
|
||
|
|
All secrets are encrypted using [SOPS](https://github.com/getsops/sops) with [age](https://github.com/FiloSottile/age) encryption.
|
||
|
|
|
||
|
|
### Decrypting Secrets
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Decrypt a single file
|
||
|
|
sops -d infrastructure/cert-manager/secrets.enc.yaml > secrets.yaml
|
||
|
|
|
||
|
|
# Edit encrypted file in-place
|
||
|
|
sops infrastructure/cert-manager/secrets.enc.yaml
|
||
|
|
```
|
||
|
|
|
||
|
|
### Encrypting New Secrets
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Encrypt a new secret file
|
||
|
|
sops -e secrets.yaml > secrets.enc.yaml
|
||
|
|
```
|
||
|
|
|
||
|
|
## Deployment
|
||
|
|
|
||
|
|
This repository is deployed using FluxCD v2:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Bootstrap Flux (already done)
|
||
|
|
flux bootstrap git \
|
||
|
|
--url=http://192.168.1.49:13001/admin/homelab.git \
|
||
|
|
--branch=main \
|
||
|
|
--path=clusters/production
|
||
|
|
|
||
|
|
# Check Flux status
|
||
|
|
flux get all
|
||
|
|
```
|
||
|
|
|
||
|
|
## Environment
|
||
|
|
|
||
|
|
- **Platform**: K3s on ARM (Raspberry Pi)
|
||
|
|
- **OS**: Termux on Android
|
||
|
|
- **GitOps**: FluxCD v2
|
||
|
|
- **Secrets**: SOPS + Age encryption
|
||
|
|
- **Registry**: Harbor (self-hosted)
|
||
|
|
|
||
|
|
## Directory Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
.
|
||
|
|
├── bootstrap/ # Flux bootstrap manifests
|
||
|
|
├── infrastructure/ # Layer 0: Core infrastructure
|
||
|
|
├── platform/ # Layer 1: Platform services
|
||
|
|
├── apps/ # Layer 2: Applications
|
||
|
|
├── clusters/ # Cluster-specific configurations
|
||
|
|
│ └── production/ # Production cluster Kustomizations
|
||
|
|
└── docs/ # Additional documentation
|
||
|
|
```
|
||
|
|
|
||
|
|
## Maintenance
|
||
|
|
|
||
|
|
### Updating Applications
|
||
|
|
|
||
|
|
1. Edit the HelmRelease or Kustomization in the appropriate directory
|
||
|
|
2. Commit and push changes to Gitea
|
||
|
|
3. Flux will automatically reconcile within 1 minute (or force with `flux reconcile`)
|
||
|
|
|
||
|
|
### Adding New Applications
|
||
|
|
|
||
|
|
1. Create directory in appropriate layer (infrastructure/platform/apps)
|
||
|
|
2. Add namespace.yaml, helmrelease.yaml, and kustomization.yaml
|
||
|
|
3. If secrets needed, create secrets.enc.yaml using SOPS
|
||
|
|
4. Add reference to layer's kustomization.yaml
|
||
|
|
5. Commit and push
|
||
|
|
|
||
|
|
## Contact
|
||
|
|
|
||
|
|
Maintained by CaffeineTux
|