k3s/.claude/skills/caddy/SKILL.md

---
name: caddy-ssl-termination
description: 专门用于 Traefik 前置 Caddy 进行 SSL 卸载的架构配置，适用于 K3s 环境。
---


# Caddy SSL Termination Skill

## Architecture Overview

**Setup**: Traefik (routing) → Caddy (HTTPS/SSL termination) → HTTP backend

- **Caddy**: Handles HTTPS (443) with automatic SSL certificates, forwards to Traefik on HTTP (80)
- **Traefik**: Routes HTTP traffic to appropriate backend services
- **Flow**: Internet → Caddy:443 (HTTPS) → Traefik:80 (HTTP) → Backend Pods

## Quick Configuration Template

### 1. Basic Caddyfile Structure

```caddy
# /etc/caddy/Caddyfile

# Domain configuration
example.com {
    reverse_proxy traefik-service:80
}

# Multiple domains
app1.example.com {
    reverse_proxy traefik-service:80
}

app2.example.com {
    reverse_proxy traefik-service:80
}

# Wildcard subdomain (requires DNS wildcard)
*.example.com {
    reverse_proxy traefik-service:80
}
```

### 2. ConfigMap for Caddyfile

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: caddy-config
  namespace: default
data:
  Caddyfile: |
    # Global options
    {
        email your-email@example.com
        # Use Let's Encrypt staging for testing
        # acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
    }

    # Your domains
    example.com {
        reverse_proxy traefik-service:80 {
            header_up Host {host}
            header_up X-Real-IP {remote}
            header_up X-Forwarded-For {remote}
            header_up X-Forwarded-Proto {scheme}
        }
    }
```

### 3. Caddy Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: caddy
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: caddy
  template:tadata:
      labels:
        app: caddy
    spec:
      containers:
      - name: caddy
        image: caddy:latest
        ports:
        - containerPort: 80
        - containerPort: 443
        - containerPort: 2019  # Admin API
        volumeMounts:
        - name: config
          mountPath: /etc/caddy
        - name: data
          mountPath: /data
        - name: config-cache
          mountPath: /config
      volumes:
      - name: config
        configMap:
          name: caddy-config
      - name: data
        persistentVolumeClaim:
          claimName: caddy-data
      - name: config-cache
        emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: caddy
  namespace: default
spec:
  type: LoadBalancer  # or NodePort
  ports:
  - name: http
    port: 80
    targetPort: 80
  - name: https
    port: 443
    targetPort: 443
  selector:
    app: caddy
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: caddy-data
  namespace: default
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
```

## Common Operations

### Reload Configuration

After updating the ConfigMap:

```bash
# Method 1: Reload via exec (preserves connections)
kubectl exec -n default deployment/caddy -- caddy reload --config /etc/caddy/Caddyfile

# Method 2: Restart pod (brief downtime)
kubectl rollout restart deployment/caddy -n default

# Method 3: Delete pod (auto-recreates)
kubectl delete pod -n default -l app=caddy
```

### Update Caddyfile

```bash
# Edit ConfigMap
kubectl edit configmap caddy-config -n default

# Or apply updated file
kubectl apply -f caddy-configmap.yaml

# Then reload
kubectl exec -n default deployment/caddy -- caddy reload --config /etc/caddy/Caddyfile
```

### View Logs

```bash
# Follow logs
kubectl logs -n default -f deployment/caddy

# Check SSL certificate issues
kubectl logs -n default deployment/caddy | grep -i "certificate\|acme\|tls"
```

### Check Configuration

```bash
# Validate Caddyfile syntax
kubectl exec -n default deployment/caddy -- caddy validate --config /etc/caddy/Caddyfile

# View current config via API
kubectl exec -n default deployment/caddy -- curl localhost:2019/config/
```

## Adding New Domain

### Step-by-step Process

1. **Update DNS**: Point new domain to Caddy's LoadBalancer IP
   ```bash
   kubectl get svc caddy -n default -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
   ```

2. **Update ConfigMap**: Add new domain block
   ```bash
   kubectl edit configmap caddy-config -n default
   ```

   Add:
   ```caddy
   newapp.example.com {
       reverse_proxy traefik-service:80 {
           header_up Host {host}
           header_up X-Real-IP {remote}
           header_up X-Forwarded-For {remote}
           header_up X-Forwarded-Proto {scheme}
       }
   }
   ```

3. **Reload Caddy**:
   ```bash
   kubectl exec -n default deployment/caddy -- caddy reload --config /etc/caddy/Caddyfile
   ```

4. **Verify**: Check logs for certificate acquisition
   ```bash
   kubectl logs -n default deployment/caddy | tail -20
   ```

## Traefik Integration

### Traefik IngressRoute Example

```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: myapp
  namespace: default
spec:
  entryPoints:
    - web  # HTTP only, Caddy handles HTTPS
  routes:
  - match: Host(`myapp.example.com`)
    kind: Rule
    services:
    - name: myapp-service
      port: 8080
```

### Important Notes

- Traefik should listen on HTTP (80) only
- Caddy handles all HTTPS/SSL
- Use `Host()` matcher in Traefik to route by domain
- Caddy forwards the original `Host` header to Traefik

## Troubleshooting

### SSL Certificate Issues

```bash
# Check certificate status
kubectl exec -n default deployment/caddy -- caddy list-certificates

# View ACME logs
kubectl logs -n default deployment/caddy | grep -i acme

# Common issues:
# - Port 80/443 not accessible from internet
# - DNS not pointing to correct IP
# - Rate limit hit (use staging CA for testing)
```

### Configuration Errors

```bash
# Test config before reload
kubectl exec -n default deployment/caddy -- caddy validate --config /etc/caddy/Caddyfile

# Check for syntax errors
kubectl logs -n default deployment/caddy | grep -i error
```

### Connection Issues

```bash
# Test from inside cluster
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- curl -v http://traefik-service:80

# Check if Caddy can reach Traefik
kubectl exec -n default deployment/caddy -- curl -v http://traefik-service:80
```

## Advanced Configurations

### Custom TLS Settings

```caddy
example.com {
    tls {
        protocols tls1.2 tls1.3
        ciphers TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    }
    reverse_proxy traefik-service:80
}
```

### Rate Limiting

```caddy
example.com {
    rate_limit {
        zone dynamic {
            key {remote_host}
            events 100
            window 1m
        }
    }
    reverse_proxy traefik-service:80
}
```

### Custom Error Pages

```caddy
example.com {
    handle_errors {
        respond "{err.status_code} {err.status_text}"
    }
    reverse_proxy traefik-service:80
}
```

### Health Checks

```caddy
example.com {
    reverse_proxy traefik-service:80 {
        health_uri /health
        health_interval 10s
        health_timeout 5s
    }
}
```

## Quick Reference Commands

```bash
# Get Caddy pod name
kubectl get pods -n default -l app=caddy

# Reload config
kubectl exec -n default deployment/caddy -- caddy reload --config /etc/caddy/Caddyfile

# View current config
kubectl exec -n default deployment/caddy -- cat /etc/caddy/Caddyfile

# Check certificates
kubectl exec -n default deployment/caddy -- caddy list-certificates

# Restart Caddy
kubectl rollout restart deployment/caddy -n default

# Watch logs
kubectl logs -n default -f deployment/caddy

# Get LoadBalancer IP
kubectl get svc caddy -n default -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```

## Checklist for New Service

- [ ] DNS A/AAAA record points to Caddy LoadBalancer IP
- [ ] Domain added to Caddy ConfigMap
- [ ] Caddy reloaded successfully
- [ ] Traefik IngressRoute created (HTTP only)
- [ ] Backend service accessible from Traefik
- [ ] SSL certificate acquired (check logs)
- [ ] HTTPS access working from browser
- [ ] HTTP redirects to HTTPS (Caddy default behavior)

## Notes

- Caddy automatically obtains and renews SSL certificates
- Certificates stored in `/data` volume (must be persistent)
- Reload is graceful - no connection drops
- Caddy handles HTTP→HTTPS redirect automatically
- Use staging CA for testing to avoid rate limits
- Wildcard certificates require DNS challenge (more complex setup)