Simplifies cluster service setup.

setup/README.md

@@ -6,13 +6,7 @@ Follow the instructions to [set up a dnsmasq machine](./dnsmasq/README.md).
 
 Follow the instructions to [set up cluster nodes](./cluster-nodes/README.md).
 
-Set up cluster services:
-
-```bash
-wild-cluster-services-fetch
-wild-cluster-services-configure
-wild-cluster-services-up
-```
+Follow the instruction to set up [cluster services](./cluster-services/README.md).
 
 Now make sure everything works:
 

setup/cluster-services/README.md

@@ -1,4 +1,4 @@
-# Infrastructure setup scripts
+# Wild Cloud Cluster Services
 
 Creates a fully functional personal cloud infrastructure on a bare metal Kubernetes cluster that provides:
 
@@ -7,6 +7,20 @@ Creates a fully functional personal cloud infrastructure on a bare metal Kuberne
 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
 
 ```
@@ -30,14 +44,53 @@ Internet → External DNS → MetalLB LoadBalancer → Traefik → Kubernetes Se
 - **[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
+```
+
+### 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 scripts are designed to be idempotent:
+All setup is designed to be idempotent and reliable:
 
-- Scripts can be run multiple times without causing harm
-- Each script checks for existing resources before creating new ones
-- Configuration updates are applied cleanly without duplication
-- Failed or interrupted setups can be safely retried
-- Changes to configuration will be properly applied on subsequent runs
+- **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
 
-This idempotent approach ensures consistent, reliable infrastructure setup and allows for incremental changes without requiring a complete teardown and rebuild.
+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
+```