Moves setup files into embedded package.

2025-10-11 22:06:39 +00:00
parent 92032202f4
commit 89c6a7aa80
112 changed files with 337 additions and 0 deletions
--- a/internal/setup/cluster-services/README.md
+++ b/internal/setup/cluster-services/README.md
@@ -0,0 +1,102 @@
+# Wild Cloud Cluster Services
+
+Creates a fully functional personal cloud infrastructure on a bare metal Kubernetes cluster that provides:
+
+1. **External access** to services via configured domain names (using ${DOMAIN})
+2. **Internal-only access** to admin interfaces (via internal.${DOMAIN} subdomains)
+3. **Secure traffic routing** with automatic TLS
+4. **Reliable networking** with proper load balancing
+
+## Service Management
+
+Wild Cloud uses a streamlined per-service setup approach:
+
+**Primary Command**: `wild-service-setup <service> [options]`
+- **Default**: Configure and deploy service using existing templates
+- **`--fetch`**: Fetch fresh templates before setup (for updates)
+- **`--no-deploy`**: Configure only, skip deployment (for planning)
+
+**Master Orchestrator**: `wild-setup-services`
+- Sets up all services in proper dependency order
+- Each service validates its prerequisites before deployment
+- Fail-fast approach with clear recovery instructions
+
+## Architecture
+
+```
+Internet → External DNS → MetalLB LoadBalancer → Traefik → Kubernetes Services
+                                    ↑
+                                 Internal DNS
+                                    ↑
+                              Internal Network
+```
+
+## Key Components
+
+- **[MetalLB](metallb/README.md)** - Provides load balancing for bare metal clusters
+- **[Traefik](traefik/README.md)** - Handles ingress traffic, TLS termination, and routing
+- **[cert-manager](cert-manager/README.md)** - Manages TLS certificates
+- **[CoreDNS](coredns/README.md)** - Provides DNS resolution for services
+- **[ExternalDNS](externaldns/README.md)** - Automatic DNS record management
+- **[Longhorn](longhorn/README.md)** - Distributed storage system for persistent volumes
+- **[NFS](nfs/README.md)** - Network file system for shared media storage (optional)
+- **[Kubernetes Dashboard](kubernetes-dashboard/README.md)** - Web UI for cluster management (accessible via https://dashboard.internal.${DOMAIN})
+- **[Docker Registry](docker-registry/README.md)** - Private container registry for custom images
+- **[Utils](utils/README.md)** - Cluster utilities and debugging tools
+
+## Common Usage Patterns
+
+### Complete Infrastructure Setup
+```bash
+# All services with fresh templates (recommended for first-time setup)
+wild-setup-services --fetch
+
+# All services using existing templates (fastest)
+wild-setup-services
+
+# Configure all services but don't deploy (for planning)
+wild-setup-services --no-deploy
+```
+
+### Individual Service Management
+```bash
+# Most common - reconfigure and deploy existing service
+wild-service-setup cert-manager
+
+# Get fresh templates and deploy (for updates)
+wild-service-setup cert-manager --fetch
+
+# Configure only, don't deploy (for planning)
+wild-service-setup cert-manager --no-deploy
+
+# Fresh templates + configure + deploy
+wild-service-setup cert-manager --fetch
+```
+
+### Service Dependencies
+Services are automatically deployed in dependency order:
+1. **metallb** → Load balancing foundation
+2. **traefik** → Ingress (requires metallb)
+3. **cert-manager** → TLS certificates (requires traefik)
+4. **externaldns** → DNS automation (requires cert-manager)
+5. **kubernetes-dashboard** → Admin UI (requires cert-manager)
+
+Each service validates its dependencies before deployment.
+
+## Idempotent Design
+
+All setup is designed to be idempotent and reliable:
+
+- **Atomic Operations**: Each service handles its complete lifecycle
+- **Dependency Validation**: Services check prerequisites before deployment
+- **Error Recovery**: Failed services can be individually fixed and re-run
+- **Safe Retries**: Operations can be repeated without harm
+- **Incremental Updates**: Configuration changes applied cleanly
+
+Example recovery from cert-manager failure:
+```bash
+# Fix the issue, then resume
+wild-service-setup cert-manager --fetch
+# Continue with remaining services
+wild-service-setup externaldns --fetch
+```