sudacode/dotfiles
1
0
Fork 0
mirror of https://github.com/ksyasuda/dotfiles.git synced 2026-03-20 06:11:27 -07:00
Code Issues Packages Projects Releases Wiki Activity

update skills

Browse Source
This commit is contained in:
Kyle Yasuda
2026-03-17 16:53:22 -07:00
parent 0b0783ef8e
commit f9a530667e
389 changed files with 54512 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
.agents/skills/cloudflare-deploy/references/spectrum/README.md Normal file
View File

@@ -0,0 +1,52 @@
# Cloudflare Spectrum Skill Reference
## Overview
Cloudflare Spectrum provides security and acceleration for ANY TCP or UDP-based application. It's a global Layer 4 (L4) reverse proxy running on Cloudflare's edge nodes that routes MQTT, email, file transfer, version control, games, and more through Cloudflare to mask origins and protect from DDoS attacks.
**When to Use Spectrum**: When your protocol isn't HTTP/HTTPS (use Cloudflare proxy for HTTP). Spectrum handles everything else: SSH, gaming, databases, MQTT, SMTP, RDP, custom protocols.
## Plan Capabilities
| Capability | Pro/Business | Enterprise |
|------------|--------------|------------|
| TCP protocols | Selected ports only | All ports (1-65535) |
| UDP protocols | Selected ports only | All ports (1-65535) |
| Port ranges | ❌ | ✅ |
| Argo Smart Routing | ✅ | ✅ |
| IP Firewall | ✅ | ✅ |
| Load balancer origins | ✅ | ✅ |
## Decision Tree
**What are you trying to do?**
1. **Create/manage Spectrum app**
- Via Dashboard → See [Cloudflare Dashboard](https://dash.cloudflare.com)
- Via API → See [api.md](api.md) - REST endpoints
- Via SDK → See [api.md](api.md) - TypeScript/Python/Go examples
- Via IaC → See [configuration.md](configuration.md) - Terraform/Pulumi
2. **Protect specific protocol**
- SSH → See [patterns.md](patterns.md#1-ssh-server-protection)
- Gaming (Minecraft, etc) → See [patterns.md](patterns.md#2-game-server)
- MQTT/IoT → See [patterns.md](patterns.md#3-mqtt-broker)
- SMTP/Email → See [patterns.md](patterns.md#4-smtp-relay)
- Database → See [patterns.md](patterns.md#5-database-proxy)
- RDP → See [patterns.md](patterns.md#6-rdp-remote-desktop)
3. **Choose origin type**
- Direct IP (single server) → See [configuration.md](configuration.md#direct-ip-origin)
- CNAME (hostname) → See [configuration.md](configuration.md#cname-origin)
- Load balancer (HA/failover) → See [configuration.md](configuration.md#load-balancer-origin)
## Reading Order
1. Start with [patterns.md](patterns.md) for your specific protocol
2. Then [configuration.md](configuration.md) for your origin type
3. Check [gotchas.md](gotchas.md) before going to production
4. Use [api.md](api.md) for programmatic access
## See Also
- [Cloudflare Docs](https://developers.cloudflare.com/spectrum/)

181
.agents/skills/cloudflare-deploy/references/spectrum/api.md Normal file
View File

@@ -0,0 +1,181 @@
## REST API Endpoints
```
GET /zones/{zone_id}/spectrum/apps # List apps
POST /zones/{zone_id}/spectrum/apps # Create app
GET /zones/{zone_id}/spectrum/apps/{app_id} # Get app
PUT /zones/{zone_id}/spectrum/apps/{app_id} # Update app
DELETE /zones/{zone_id}/spectrum/apps/{app_id} # Delete app
GET /zones/{zone_id}/spectrum/analytics/aggregate/current
GET /zones/{zone_id}/spectrum/analytics/events/bytime
GET /zones/{zone_id}/spectrum/analytics/events/summary
```
## Request/Response Schemas
### CreateSpectrumAppRequest
```typescript
interface CreateSpectrumAppRequest {
protocol: string; // "tcp/22", "udp/53"
dns: {
type: "CNAME" | "ADDRESS";
name: string; // "ssh.example.com"
};
origin_direct?: string[]; // ["tcp://192.0.2.1:22"]
origin_dns?: { name: string }; // {"name": "origin.example.com"}
origin_port?: number | { start: number; end: number };
proxy_protocol?: "off" | "v1" | "v2" | "simple";
ip_firewall?: boolean;
tls?: "off" | "flexible" | "full" | "strict";
edge_ips?: {
type: "dynamic" | "static";
connectivity: "all" | "ipv4" | "ipv6";
};
traffic_type?: "direct" | "http" | "https";
argo_smart_routing?: boolean;
}
```
### SpectrumApp Response
```typescript
interface SpectrumApp {
id: string;
protocol: string;
dns: { type: string; name: string };
origin_direct?: string[];
origin_dns?: { name: string };
origin_port?: number | { start: number; end: number };
proxy_protocol: string;
ip_firewall: boolean;
tls: string;
edge_ips: { type: string; connectivity: string; ips?: string[] };
argo_smart_routing: boolean;
created_on: string;
modified_on: string;
}
```
## TypeScript SDK
```typescript
import Cloudflare from 'cloudflare';
const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });
// Create
const app = await client.spectrum.apps.create({
zone_id: 'your-zone-id',
protocol: 'tcp/22',
dns: { type: 'CNAME', name: 'ssh.example.com' },
origin_direct: ['tcp://192.0.2.1:22'],
ip_firewall: true,
tls: 'off',
});
// List
const apps = await client.spectrum.apps.list({ zone_id: 'your-zone-id' });
// Get
const appDetails = await client.spectrum.apps.get({ zone_id: 'your-zone-id', app_id: app.id });
// Update
await client.spectrum.apps.update({ zone_id: 'your-zone-id', app_id: app.id, tls: 'full' });
// Delete
await client.spectrum.apps.delete({ zone_id: 'your-zone-id', app_id: app.id });
// Analytics
const analytics = await client.spectrum.analytics.aggregate({
zone_id: 'your-zone-id',
metrics: ['bytesIngress', 'bytesEgress'],
since: new Date(Date.now() - 3600000).toISOString(),
});
```
## Python SDK
```python
from cloudflare import Cloudflare
client = Cloudflare(api_token="your-api-token")
# Create
app = client.spectrum.apps.create(
zone_id="your-zone-id",
protocol="tcp/22",
dns={"type": "CNAME", "name": "ssh.example.com"},
origin_direct=["tcp://192.0.2.1:22"],
ip_firewall=True,
tls="off",
)
# List
apps = client.spectrum.apps.list(zone_id="your-zone-id")
# Get
app_details = client.spectrum.apps.get(zone_id="your-zone-id", app_id=app.id)
# Update
client.spectrum.apps.update(zone_id="your-zone-id", app_id=app.id, tls="full")
# Delete
client.spectrum.apps.delete(zone_id="your-zone-id", app_id=app.id)
# Analytics
analytics = client.spectrum.analytics.aggregate(
zone_id="your-zone-id",
metrics=["bytesIngress", "bytesEgress"],
since=datetime.now() - timedelta(hours=1),
)
```
## Go SDK
```go
import "github.com/cloudflare/cloudflare-go"
api, _ := cloudflare.NewWithAPIToken("your-api-token")
// Create
app, _ := api.CreateSpectrumApplication(ctx, "zone-id", cloudflare.SpectrumApplication{
Protocol: "tcp/22",
DNS: cloudflare.SpectrumApplicationDNS{Type: "CNAME", Name: "ssh.example.com"},
OriginDirect: []string{"tcp://192.0.2.1:22"},
IPFirewall: true,
ArgoSmartRouting: true,
})
// List
apps, _ := api.SpectrumApplications(ctx, "zone-id")
// Delete
_ = api.DeleteSpectrumApplication(ctx, "zone-id", app.ID)
```
## Analytics API
**Metrics:**
- `bytesIngress` - Bytes received from clients
- `bytesEgress` - Bytes sent to clients
- `count` - Number of connections
- `duration` - Connection duration (seconds)
**Dimensions:**
- `event` - Connection event type
- `appID` - Spectrum application ID
- `coloName` - Datacenter name
- `ipVersion` - IPv4 or IPv6
**Example:**
```bash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/spectrum/analytics/aggregate/current?metrics=bytesIngress,bytesEgress,count&dimensions=appID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```
## See Also
- [configuration.md](configuration.md) - Terraform/Pulumi
- [patterns.md](patterns.md) - Protocol examples

194
.agents/skills/cloudflare-deploy/references/spectrum/configuration.md Normal file
View File

@@ -0,0 +1,194 @@
## Origin Types
### Direct IP Origin
Use when origin is a single server with static IP.
**TypeScript SDK:**
```typescript
const app = await client.spectrum.apps.create({
zone_id: 'your-zone-id',
protocol: 'tcp/22',
dns: { type: 'CNAME', name: 'ssh.example.com' },
origin_direct: ['tcp://192.0.2.1:22'],
ip_firewall: true,
tls: 'off',
});
```
**Terraform:**
```hcl
resource "cloudflare_spectrum_application" "ssh" {
zone_id = var.zone_id
protocol = "tcp/22"
dns {
type = "CNAME"
name = "ssh.example.com"
}
origin_direct = ["tcp://192.0.2.1:22"]
ip_firewall = true
tls = "off"
argo_smart_routing = true
}
```
### CNAME Origin
Use when origin is a hostname (not static IP). Spectrum resolves DNS dynamically.
**TypeScript SDK:**
```typescript
const app = await client.spectrum.apps.create({
zone_id: 'your-zone-id',
protocol: 'tcp/3306',
dns: { type: 'CNAME', name: 'db.example.com' },
origin_dns: { name: 'db-primary.internal.example.com' },
origin_port: 3306,
tls: 'full',
});
```
**Terraform:**
```hcl
resource "cloudflare_spectrum_application" "database" {
zone_id = var.zone_id
protocol = "tcp/3306"
dns {
type = "CNAME"
name = "db.example.com"
}
origin_dns {
name = "db-primary.internal.example.com"
}
origin_port = 3306
tls = "full"
argo_smart_routing = true
}
```
### Load Balancer Origin
Use for high availability and failover.
**Terraform:**
```hcl
resource "cloudflare_load_balancer" "game_lb" {
zone_id = var.zone_id
name = "game-lb.example.com"
default_pool_ids = [cloudflare_load_balancer_pool.game_pool.id]
}
resource "cloudflare_load_balancer_pool" "game_pool" {
name = "game-primary"
origins { name = "game-1"; address = "192.0.2.1" }
monitor = cloudflare_load_balancer_monitor.tcp_monitor.id
}
resource "cloudflare_load_balancer_monitor" "tcp_monitor" {
type = "tcp"; port = 25565; interval = 60; timeout = 5
}
resource "cloudflare_spectrum_application" "game" {
zone_id = var.zone_id
protocol = "tcp/25565"
dns { type = "CNAME"; name = "game.example.com" }
origin_dns { name = cloudflare_load_balancer.game_lb.name }
origin_port = 25565
}
```
## TLS Configuration
| Mode | Description | Use Case | Origin Cert |
|------|-------------|----------|-------------|
| `off` | No TLS | Non-encrypted (SSH, gaming) | No |
| `flexible` | TLS client→CF, plain CF→origin | Testing | No |
| `full` | TLS end-to-end, self-signed OK | Production | Yes (any) |
| `strict` | Full + valid cert verification | Max security | Yes (CA) |
**Example:**
```typescript
const app = await client.spectrum.apps.create({
zone_id: 'your-zone-id',
protocol: 'tcp/3306',
dns: { type: 'CNAME', name: 'db.example.com' },
origin_direct: ['tcp://192.0.2.1:3306'],
tls: 'strict', // Validates origin certificate
});
```
## Proxy Protocol
Forwards real client IP to origin. Origin must support parsing.
| Version | Protocol | Use Case |
|---------|----------|----------|
| `off` | - | Origin doesn't need client IP |
| `v1` | TCP | Most TCP apps (SSH, databases) |
| `v2` | TCP | High-performance TCP |
| `simple` | UDP | UDP applications |
**Compatibility:**
- **v1**: HAProxy, nginx, SSH, most databases
- **v2**: HAProxy 1.5+, nginx 1.11+
- **simple**: Cloudflare-specific UDP format
**Enable:**
```typescript
const app = await client.spectrum.apps.create({
// ...
proxy_protocol: 'v1', // Origin must parse PROXY header
});
```
**Origin Config (nginx):**
```nginx
stream {
server {
listen 22 proxy_protocol;
proxy_pass backend:22;
}
}
```
## IP Access Rules
Enable `ip_firewall: true` then configure zone-level firewall rules.
```typescript
const app = await client.spectrum.apps.create({
// ...
ip_firewall: true, // Applies zone firewall rules
});
```
## Port Ranges (Enterprise Only)
```hcl
resource "cloudflare_spectrum_application" "game_cluster" {
zone_id = var.zone_id
protocol = "tcp/25565-25575"
dns {
type = "CNAME"
name = "games.example.com"
}
origin_direct = ["tcp://192.0.2.1"]
origin_port {
start = 25565
end = 25575
}
}
```
## See Also
- [patterns.md](patterns.md) - Protocol-specific examples
- [api.md](api.md) - REST/SDK reference

145
.agents/skills/cloudflare-deploy/references/spectrum/gotchas.md Normal file
View File

@@ -0,0 +1,145 @@
## Common Issues
### Connection Timeouts
**Problem:** Connections fail or timeout
**Cause:** Origin firewall blocking Cloudflare IPs, origin service not running, incorrect DNS
**Solution:**
1. Verify origin firewall allows Cloudflare IP ranges
2. Check origin service running on correct port
3. Ensure DNS record is CNAME (not A/AAAA)
4. Verify origin IP/hostname is correct
```bash
# Test connectivity
nc -zv app.example.com 22
dig app.example.com
```
### Client IP Showing Cloudflare IP
**Problem:** Origin logs show Cloudflare IPs not real client IPs
**Cause:** Proxy Protocol not enabled or origin not configured
**Solution:**
```typescript
// Enable in Spectrum app
const app = await client.spectrum.apps.create({
// ...
proxy_protocol: 'v1', // TCP: v1/v2; UDP: simple
});
```
**Origin config:**
- **nginx**: `listen 22 proxy_protocol;`
- **HAProxy**: `bind :22 accept-proxy`
### TLS Errors
**Problem:** TLS handshake failures, 525 errors
**Cause:** TLS mode mismatch
| Error | TLS Mode | Problem | Solution |
|-------|----------|---------|----------|
| Connection refused | `full`/`strict` | Origin not TLS | Use `tls: "off"` or enable TLS |
| 525 cert invalid | `strict` | Self-signed cert | Use `tls: "full"` or valid cert |
| Handshake timeout | `flexible` | Origin expects TLS | Use `tls: "full"` |
**Debug:**
```bash
openssl s_client -connect app.example.com:443 -showcerts
```
### SMTP Reverse DNS
**Problem:** Email servers reject SMTP via Spectrum
**Cause:** Spectrum IPs lack PTR (reverse DNS) records
**Impact:** Many mail servers require valid rDNS for anti-spam
**Solution:**
- Outbound SMTP: NOT recommended through Spectrum
- Inbound SMTP: Use Cloudflare Email Routing
- Internal relay: Whitelist Spectrum IPs on destination
### Proxy Protocol Compatibility
**Problem:** Connection works but app behaves incorrectly
**Cause:** Origin doesn't support Proxy Protocol
**Solution:**
1. Verify origin supports version (v1: widely supported, v2: HAProxy 1.5+/nginx 1.11+)
2. Test with `proxy_protocol: 'off'` first
3. Configure origin to parse headers
**nginx TCP:**
```nginx
stream {
server {
listen 22 proxy_protocol;
proxy_pass backend:22;
}
}
```
**HAProxy:**
```
frontend ft_ssh
bind :22 accept-proxy
```
### Analytics Data Retention
**Problem:** Historical data not available
**Cause:** Retention varies by plan
| Plan | Real-time | Historical |
|------|-----------|------------|
| Pro | Last hour | ❌ |
| Business | Last hour | Limited |
| Enterprise | Last hour | 90+ days |
**Solution:** Query within retention window or export to external system
### Enterprise-Only Features
**Problem:** Feature unavailable/errors
**Cause:** Requires Enterprise plan
**Enterprise-only:**
- Port ranges (`tcp/25565-25575`)
- All TCP/UDP ports (Pro/Business: selected only)
- Extended analytics retention
- Advanced load balancing
### IPv6 Considerations
**Problem:** IPv6 clients can't connect or origin doesn't support IPv6
**Solution:** Configure `edge_ips.connectivity`
```typescript
const app = await client.spectrum.apps.create({
// ...
edge_ips: {
type: 'dynamic',
connectivity: 'ipv4', // Options: 'all', 'ipv4', 'ipv6'
},
});
```
**Options:**
- `all`: Dual-stack (default, requires origin support both)
- `ipv4`: IPv4 only (use if origin lacks IPv6)
- `ipv6`: IPv6 only (rare)
## Limits
| Resource | Pro/Business | Enterprise |
|----------|--------------|------------|
| Max apps | ~10-15 | 100+ |
| Protocols | Selected | All TCP/UDP |
| Port ranges | ❌ | ✅ |
| Analytics | ~1 hour | 90+ days |
## See Also
- [patterns.md](patterns.md) - Protocol examples
- [configuration.md](configuration.md) - TLS/Proxy setup

196
.agents/skills/cloudflare-deploy/references/spectrum/patterns.md Normal file
View File

@@ -0,0 +1,196 @@
## Common Use Cases
### 1. SSH Server Protection
**Terraform:**
```hcl
resource "cloudflare_spectrum_application" "ssh" {
zone_id = var.zone_id
protocol = "tcp/22"
dns {
type = "CNAME"
name = "ssh.example.com"
}
origin_direct = ["tcp://10.0.1.5:22"]
ip_firewall = true
argo_smart_routing = true
}
```
**Benefits:** Hide origin IP, DDoS protection, IP firewall, Argo reduces latency
### 2. Game Server
**TypeScript (Minecraft):**
```typescript
const app = await client.spectrum.apps.create({
zone_id: 'your-zone-id',
protocol: 'tcp/25565',
dns: { type: 'CNAME', name: 'mc.example.com' },
origin_direct: ['tcp://192.168.1.10:25565'],
proxy_protocol: 'v1', // Preserves player IPs
argo_smart_routing: true,
});
```
**Benefits:** DDoS protection, hide origin IP, Proxy Protocol for player IPs/bans, Argo reduces latency
### 3. MQTT Broker
IoT device communication.
**TypeScript:**
```typescript
const mqttApp = await client.spectrum.apps.create({
zone_id: 'your-zone-id',
protocol: 'tcp/8883', // Use 1883 for plain MQTT
dns: { type: 'CNAME', name: 'mqtt.example.com' },
origin_direct: ['tcp://mqtt-broker.internal:8883'],
tls: 'full', // Use 'off' for plain MQTT
});
```
**Benefits:** DDoS protection, hide broker IP, TLS termination at edge
### 4. SMTP Relay
Email submission (port 587). **WARNING**: See [gotchas.md](gotchas.md#smtp-reverse-dns)
**Terraform:**
```hcl
resource "cloudflare_spectrum_application" "smtp" {
zone_id = var.zone_id
protocol = "tcp/587"
dns {
type = "CNAME"
name = "smtp.example.com"
}
origin_direct = ["tcp://mail-server.internal:587"]
tls = "full" # STARTTLS support
}
```
**Limitations:**
- Spectrum IPs lack reverse DNS (PTR records)
- Many mail servers reject without valid rDNS
- Best for internal/trusted relay only
### 5. Database Proxy
MySQL/PostgreSQL. **Use with caution** - security critical.
**PostgreSQL:**
```typescript
const postgresApp = await client.spectrum.apps.create({
zone_id: 'your-zone-id',
protocol: 'tcp/5432',
dns: { type: 'CNAME', name: 'postgres.example.com' },
origin_dns: { name: 'db-primary.internal.example.com' },
origin_port: 5432,
tls: 'strict', // REQUIRED
ip_firewall: true, // REQUIRED
});
```
**MySQL:**
```hcl
resource "cloudflare_spectrum_application" "mysql" {
zone_id = var.zone_id
protocol = "tcp/3306"
dns {
type = "CNAME"
name = "mysql.example.com"
}
origin_dns {
name = "mysql-primary.internal.example.com"
}
origin_port = 3306
tls = "strict"
ip_firewall = true
}
```
**Security:**
- ALWAYS use `tls: "strict"`
- ALWAYS use `ip_firewall: true`
- Restrict to known IPs via zone firewall
- Use strong DB authentication
- Consider VPN or Cloudflare Access instead
### 6. RDP (Remote Desktop)
**Requires IP firewall.**
**Terraform:**
```hcl
resource "cloudflare_spectrum_application" "rdp" {
zone_id = var.zone_id
protocol = "tcp/3389"
dns {
type = "CNAME"
name = "rdp.example.com"
}
origin_direct = ["tcp://windows-server.internal:3389"]
tls = "off" # RDP has own encryption
ip_firewall = true # REQUIRED
}
```
**Security:** ALWAYS `ip_firewall: true`, whitelist admin IPs, RDP is DDoS/brute-force target
### 7. Multi-Origin Failover
High availability with load balancer.
**Terraform:**
```hcl
resource "cloudflare_load_balancer" "database_lb" {
zone_id = var.zone_id
name = "db-lb.example.com"
default_pool_ids = [cloudflare_load_balancer_pool.db_primary.id]
fallback_pool_id = cloudflare_load_balancer_pool.db_secondary.id
}
resource "cloudflare_load_balancer_pool" "db_primary" {
name = "db-primary-pool"
origins { name = "db-1"; address = "192.0.2.1" }
monitor = cloudflare_load_balancer_monitor.postgres_monitor.id
}
resource "cloudflare_load_balancer_pool" "db_secondary" {
name = "db-secondary-pool"
origins { name = "db-2"; address = "192.0.2.2" }
monitor = cloudflare_load_balancer_monitor.postgres_monitor.id
}
resource "cloudflare_load_balancer_monitor" "postgres_monitor" {
type = "tcp"; port = 5432; interval = 30; timeout = 5
}
resource "cloudflare_spectrum_application" "postgres_ha" {
zone_id = var.zone_id
protocol = "tcp/5432"
dns { type = "CNAME"; name = "postgres.example.com" }
origin_dns { name = cloudflare_load_balancer.database_lb.name }
origin_port = 5432
tls = "strict"
ip_firewall = true
}
```
**Benefits:** Automatic failover, health monitoring, traffic distribution, zero-downtime deployments
## See Also
- [configuration.md](configuration.md) - Origin type setup
- [gotchas.md](gotchas.md) - Protocol limitations
- [api.md](api.md) - SDK reference