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

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:

plan = "1xCPU-2GB"      # Web servers
# plan = "2xCPU-4GB"    # Database server (larger)
storage_size = 25        # Disk size in GB

AWS example:

instance_type = "t3.small"  # Web servers
# instance_type = "t3.medium" # Database server
storage_size = 25

3. Load Optional Task Services

# For container support
provisioning mod load taskservs . containerd

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

4. Deploy

# 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

# 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

# Add more web servers
{
    hostname = "demo-web-03"
    # ... copy configuration from web-01
}

Change Resource Sizes

# Web servers
plan = "2xCPU-4GB"      # Increase resources

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

Add Task Services

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