ec9659d0cb
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
Major documentation cleanup after VLAN migration completion: - Archive 12 VLAN project docs to archive/vlan-migration/ - Archive 5 done WIP docs (VLAN proposals, AI stack, Fossorial, DNS backup) - Create standing reference docs 08-DNS-ARCHITECTURE and 09-TAILSCALE-VPN - Renumber docs to clean 01-09 sequence with merged CHANGELOG - Update all active docs from stale 192.168.31.x to current VLAN 10 IPs - Fix CSS1 (.10.9→.10.3) and ZX1 (.10.7→.10.4) IPs in hardware inventory - Clean 06-VLAN-DEVICE-ASSIGNMENT: remove migration columns/sections, fix VLAN 25 subnet Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
181 lines
4.2 KiB
Markdown
181 lines
4.2 KiB
Markdown
# GitOps for Container Management
|
|
|
|
**Status:** 💡 IDEA
|
|
**Depends On:** Hardware upgrade completion
|
|
**Author:** Kaloyan
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Version control all container configurations to:
|
|
1. Track changes over time
|
|
2. Maintain consistency between XTRM-N5 and XTRM-N1
|
|
3. Enable automated deployments via Woodpecker CI
|
|
4. Recover from disasters quickly
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
infrastructure/
|
|
├── configs/
|
|
│ ├── common/ # Shared configs
|
|
│ │ ├── traefik/
|
|
│ │ │ └── dynamic.yml
|
|
│ │ └── authentik/
|
|
│ │ └── blueprints/
|
|
│ │
|
|
│ ├── xtrm-n5/ # Production server
|
|
│ │ ├── docker/
|
|
│ │ │ ├── compose/ # docker-compose files
|
|
│ │ │ │ ├── netbox.yml
|
|
│ │ │ │ ├── gitea.yml
|
|
│ │ │ │ └── ...
|
|
│ │ │ ├── templates/ # Unraid XML templates
|
|
│ │ │ └── env/ # Environment files (.env.example)
|
|
│ │ ├── network/
|
|
│ │ │ └── docker-networks.json
|
|
│ │ └── unraid/
|
|
│ │ ├── shares.json
|
|
│ │ └── users.json
|
|
│ │
|
|
│ └── xtrm-n1/ # Survival node
|
|
│ ├── docker/
|
|
│ │ └── compose/
|
|
│ │ ├── adguard.yml
|
|
│ │ ├── vaultwarden.yml
|
|
│ │ └── authentik-replica.yml
|
|
│ └── proxmox/
|
|
│ └── vm-configs/
|
|
│
|
|
└── .woodpecker.yml
|
|
```
|
|
|
|
---
|
|
|
|
## Workflow
|
|
|
|
### 1. Change Detection
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A[Edit config in Git] --> B[Push to main]
|
|
B --> C[Woodpecker CI triggers]
|
|
C --> D{Validate configs}
|
|
D -->|Pass| E[Deploy to target server]
|
|
D -->|Fail| F[Notify & block]
|
|
```
|
|
|
|
### 2. Drift Detection
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A[Scheduled job] --> B[Export current state]
|
|
B --> C{Compare to Git}
|
|
C -->|Match| D[All good]
|
|
C -->|Drift| E[Alert + PR with diff]
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 2.1: Export Current State
|
|
|
|
1. Export all docker-compose files
|
|
2. Export Unraid container templates (XML → YAML)
|
|
3. Export network configurations
|
|
4. Create initial commit
|
|
|
|
### Phase 2.2: CI Pipeline
|
|
|
|
```yaml
|
|
# .woodpecker.yml
|
|
pipeline:
|
|
validate:
|
|
image: docker:latest
|
|
commands:
|
|
- docker compose -f configs/xtrm-n5/docker/compose/*.yml config
|
|
|
|
deploy-n5:
|
|
image: alpine/ssh
|
|
when:
|
|
path: configs/xtrm-n5/**
|
|
commands:
|
|
- ssh root@192.168.10.20 "cd /path && docker compose up -d"
|
|
secrets: [ssh_key]
|
|
|
|
deploy-n1:
|
|
image: alpine/ssh
|
|
when:
|
|
path: configs/xtrm-n1/**
|
|
commands:
|
|
- ssh root@xtrm-n1 "cd /path && docker compose up -d"
|
|
secrets: [ssh_key]
|
|
```
|
|
|
|
### Phase 2.3: Drift Detection
|
|
|
|
Scheduled Woodpecker job:
|
|
1. SSH to each server
|
|
2. Export current docker/network state
|
|
3. Compare to Git configs
|
|
4. Create issue/PR if drift detected
|
|
|
|
### Phase 2.4: Unraid GUI Sync
|
|
|
|
**Challenge:** Changes made in Unraid GUI need to sync to Git
|
|
|
|
**Solution Options:**
|
|
|
|
| Option | Pros | Cons |
|
|
|--------|------|------|
|
|
| **A: Webhook on change** | Real-time sync | Complex, needs Unraid plugin |
|
|
| **B: Scheduled export** | Simple, reliable | Delay between change and commit |
|
|
| **C: Prohibit GUI changes** | Clean workflow | User friction |
|
|
|
|
**Recommended:** Option B with daily scheduled exports
|
|
|
|
```bash
|
|
# Cron job on Unraid
|
|
0 4 * * * /boot/config/scripts/export-docker-config.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Secrets Management
|
|
|
|
**Options:**
|
|
|
|
| Tool | Integration | Complexity |
|
|
|------|-------------|------------|
|
|
| Woodpecker Secrets | Native | Low |
|
|
| Vaultwarden API | Via script | Medium |
|
|
| HashiCorp Vault | Enterprise | High |
|
|
|
|
**Recommended:** Woodpecker Secrets for CI, `.env.example` in Git
|
|
|
|
```yaml
|
|
# In docker-compose
|
|
services:
|
|
app:
|
|
env_file:
|
|
- .env # Not in Git, created from .env.example + secrets
|
|
```
|
|
|
|
---
|
|
|
|
## Rollback Strategy
|
|
|
|
1. **Git revert** - Revert commit, CI redeploys previous version
|
|
2. **Tagged releases** - Deploy specific tag
|
|
3. **Manual override** - SSH and docker compose down/up
|
|
|
|
---
|
|
|
|
## Related Documents
|
|
|
|
- `UPGRADE-2026-HARDWARE.md` - Hardware prerequisite
|