Demo 1: Standalone Overwatch

This is the simplest OpenGSLB deployment: a single Overwatch node performing external health checks on nginx backend servers. No agents, no clustering.

What You’ll Learn

Basic DNS-based load balancing
Health check configuration
Round-robin traffic distribution
Failure detection and recovery

Architecture

                ┌─────────────────────────────────────────┐
                │           DNS Clients                   │
                │         dig app.demo.local              │
                └───────────────┬─────────────────────────┘
                                │
                                ▼
                ┌─────────────────────────────────────────┐
                │           Overwatch                     │
                │         10.10.0.10                      │
                │                                         │
                │   DNS:53  API:8080  Metrics:9090        │
                │                                         │
                │   - Serves DNS queries                  │
                │   - Performs health checks              │
                │   - Returns only healthy backends       │
                └───────────────┬─────────────────────────┘
                                │
                ┌───────────────┼───────────────┐
                │               │               │
                ▼               ▼               ▼
        ┌───────────┐   ┌───────────┐   ┌───────────┐
        │  webapp1  │   │  webapp2  │   │  webapp3  │
        │ 10.10.0.21│   │ 10.10.0.22│   │ 10.10.0.23│
        │   :80     │   │   :80     │   │   :80     │
        └───────────┘   └───────────┘   └───────────┘

Network Layout

Service	IP Address	Ports
overwatch	10.10.0.10	DNS:53, API:8080, Metrics:9090
webapp1	10.10.0.21	HTTP:80
webapp2	10.10.0.22	HTTP:80
webapp3	10.10.0.23	HTTP:80
client	10.10.0.100	(test container)

Host Port Mappings

Host Port	Container Port	Service
2222	22	Client SSH access
8080	8080	API
9090	9090	Metrics
8081	80	webapp1 nginx
8082	80	webapp2 nginx
8083	80	webapp3 nginx

Note

DNS (port 53) is internal to the Docker network. SSH into the client container to query DNS.

Quick Start

1. Build the OpenGSLB Binary

# From the repository root - build a static binary for Alpine Linux
CGO_ENABLED=0 go build -o opengslb ./cmd/opengslb

# Copy to demo directory
cp opengslb demos/demo-1-standalone/bin/

2. Start the Demo

cd demos/demo-1-standalone

# Interactive demo with explanations
./scripts/demo.sh demo

# Or just start the environment
./scripts/demo.sh start

3. SSH into the Client

ssh -p 2222 root@localhost
# Password: demo

You’ll see a welcome banner with available commands. The client uses Overwatch as its DNS server, so you can query app.demo.local directly.

4. Stop the Demo

./scripts/demo.sh stop

Demo Scenarios

1. DNS Round-Robin

SSH into the client and query DNS multiple times to see round-robin:

# SSH in first
ssh -p 2222 root@localhost

# Query 6 times - see different IPs each time
for i in {1..6}; do dig app.demo.local +short; done

Expected output:

10.0.21
10.0.22
10.0.23
10.0.21
10.0.22
10.0.23

2. Failure Detection

Stop a backend and watch it leave DNS rotation:

# From your host terminal - stop webapp2
docker stop webapp2

# Wait 10-15 seconds for health checks to fail, then check health
curl http://localhost:8080/api/v1/health/servers | jq

# From your SSH session in the client - query DNS (webapp2 should be gone)
for i in {1..4}; do dig app.demo.local +short; done

3. Recovery

Restart the backend and watch it return:

# From your host terminal - start webapp2
docker start webapp2

# Wait 5-10 seconds, then check health
curl http://localhost:8080/api/v1/health/servers | jq

# From your SSH session - all 3 IPs should be back
for i in {1..6}; do dig app.demo.local +short; done

4. API Exploration

# Liveness check
curl http://localhost:8080/api/v1/live

# Readiness check
curl http://localhost:8080/api/v1/ready

# List all backends with health status
curl http://localhost:8080/api/v1/health/servers | jq

# Get healthy servers only
curl http://localhost:8080/api/v1/health/servers | jq '.servers[] | select(.healthy == true)'

5. Metrics

# View all OpenGSLB metrics
curl http://localhost:9090/metrics | grep opengslb

# DNS query count
curl -s http://localhost:9090/metrics | grep opengslb_dns_queries_total

# Health check results
curl -s http://localhost:9090/metrics | grep opengslb_health_check

Configuration Details

Setting	Value	Purpose
DNS Zone	demo.local	Domain suffix for GSLB
Domain	app.demo.local	Load-balanced endpoint
Routing	round-robin	Rotate through backends
Health Check	HTTP /health	Check backend health
Check Interval	5s	How often to check
Check Timeout	2s	Max time for check
Failure Threshold	2	Failures before unhealthy
Success Threshold	1	Successes before healthy
DNS TTL	5s	Low for demo visibility

Commands Cheat Sheet

Action	Command
Start environment	`docker-compose up -d`
Stop environment	`docker-compose down`
SSH to client	`ssh -p 2222 root@localhost` (password: demo)
Query DNS	`dig app.demo.local +short`
Check API health	`curl http://localhost:8080/api/v1/health/servers \| jq`
View metrics	`curl http://localhost:9090/metrics \| grep opengslb`
View logs	`docker-compose logs -f overwatch`
Stop a backend	`docker stop webapp2`
Start a backend	`docker start webapp2`
Full reset	`docker-compose down -v && docker-compose up -d --build`

Troubleshooting

Config permission errors

If you see “config file has insecure permissions” errors:

# Rebuild the overwatch container to apply config with correct permissions
docker-compose build overwatch
docker-compose up -d

DNS queries fail

# Check if Overwatch is running
docker-compose ps

# Check Overwatch logs
docker-compose logs overwatch

# Verify DNS port is listening
docker-compose exec overwatch netstat -tulpn | grep 53

Backends always unhealthy

# Test health endpoint directly
curl http://localhost:8081/health
curl http://localhost:8082/health
curl http://localhost:8083/health

# Check backend logs
docker-compose logs webapp1

Next Steps

After exploring this standalone demo, continue to Demo 2: Agent-Overwatch to learn about distributed health checking.