provisioning/templates/workspace/example/README.md

# Example Infrastructure Template

This is a complete, ready-to-deploy example of a simple web application stack.

## What's Included

- **2 Web servers** - Load-balanced frontend
- **1 Database server** - Backend database
- **Complete configuration** - Ready to deploy with minimal changes
- **Usage instructions** - Step-by-step deployment guide

## Architecture

```
┌─────────────────────────────────────────┐
│         Internet / Load Balancer        │
└─────────────┬───────────────────────────┘
              │
      ┌───────┴───────┐
      │               │
┌─────▼─────┐   ┌────▼──────┐
│ demo-web-01│   │demo-web-02│
│  (Public)  │   │  (Public) │
└─────┬──────┘   └────┬──────┘
      │               │
      └───────┬───────┘
              │
              │ Private Network
              │
        ┌─────▼──────┐
        │ demo-db-01 │
        │  (Private) │
        └────────────┘
```

## Quick Start

### 1. Load Required Provider

```bash
cd infra/<your-infra-name>

# Load your cloud provider
provisioning mod load providers . upcloud
# OR
provisioning mod load providers . aws
```

### 2. Configure Provider Settings

Edit `servers.k` and uncomment provider-specific settings:

**UpCloud example:**
```kcl
plan = "1xCPU-2GB"      # Web servers
# plan = "2xCPU-4GB"    # Database server (larger)
storage_size = 25        # Disk size in GB
```

**AWS example:**
```kcl
instance_type = "t3.small"  # Web servers
# instance_type = "t3.medium" # Database server
storage_size = 25
```

### 3. Load Optional Task Services

```bash
# For container support
provisioning mod load taskservs . containerd

# For additional services
provisioning mod load taskservs . docker redis nginx
```

### 4. Deploy

```bash
# Test configuration first
kcl run servers.k

# Dry-run to see what will be created
provisioning s create --infra <name> --check

# Deploy the infrastructure
provisioning s create --infra <name>

# Monitor deployment
watch provisioning s list --infra <name>
```

### 5. Verify Deployment

```bash
# List all servers
provisioning s list --infra <name>

# SSH into web server
provisioning s ssh demo-web-01

# Check database server
provisioning s ssh demo-db-01
```

## Configuration Details

### Web Servers (demo-web-01, demo-web-02)
- **Networking**: Public IPv4 + Private IPv4
- **Purpose**: Frontend application servers
- **Load balancing**: Configure externally
- **Resources**: Minimal (1-2 CPU, 2-4GB RAM)

### Database Server (demo-db-01)
- **Networking**: Private IPv4 only (no public access)
- **Purpose**: Backend database
- **Security**: Isolated on private network
- **Resources**: Medium (2-4 CPU, 4-8GB RAM)

## Next Steps

### Application Deployment
1. **Deploy application code** - Use SSH or CI/CD
2. **Configure web servers** - Set up Nginx/Apache
3. **Set up database** - Install PostgreSQL/MySQL
4. **Configure connectivity** - Connect web servers to database

### Security Hardening
1. **Firewall rules** - Lock down server access
2. **SSH keys** - Disable password auth
3. **Database access** - Restrict to web servers only
4. **SSL certificates** - Set up HTTPS

### Monitoring & Backup
1. **Monitoring** - Set up metrics collection
2. **Logging** - Configure centralized logging
3. **Backups** - Set up database backups
4. **Alerts** - Configure alerting

### Scaling
1. **Add more web servers** - Copy web-02 definition
2. **Database replication** - Add read replicas
3. **Load balancer** - Configure external LB
4. **Auto-scaling** - Set up scaling policies

## Customization

### Change Server Count
```kcl
# Add more web servers
{
    hostname = "demo-web-03"
    # ... copy configuration from web-01
}
```

### Change Resource Sizes
```kcl
# Web servers
plan = "2xCPU-4GB"      # Increase resources

# Database
plan = "4xCPU-8GB"      # More resources for DB
storage_size = 100       # Larger disk
```

### Add Task Services
```kcl
taskservs = [
    { name = "containerd", profile = "default" }
    { name = "docker", profile = "default" }
    { name = "redis", profile = "default" }
]
```

## Common Issues

### Deployment Fails
- Check provider credentials
- Verify network configuration
- Check resource quotas

### Can't SSH
- Verify SSH key is loaded
- Check firewall rules
- Ensure server is running

### Database Connection
- Verify private network
- Check firewall rules between web and DB
- Test connectivity from web servers

## Template Characteristics

- **Complexity**: Medium
- **Servers**: 3 (2 web + 1 database)
- **Pre-configured modules**: Provider only
- **Best for**: Quick demos, learning deployments, testing infrastructure code