Skip to content

Commit 081fd95

Browse files
ry-opsclaude
ry-ops
and
claude
committed
Add UniFi Layer Fabric with Cortex integration
Serverless AI architecture for UniFi network management with: - Scale-to-zero layers via KEDA (reasoning, execution, telemetry) - Always-on activator with keyword routing + LLM fallback - Redis Streams integration with Cortex master - Agent registration, heartbeats, and task/result streaming - Helm charts for all 7 layers with ArgoCD ApplicationSet - HTTP API preserved for standalone operation Architecture: - Cortex Master → Redis Streams → Activator → Internal HTTP → Layers - Capabilities: unifi_network, client_management, device_management, network_diagnostics, firewall_management, wifi_management Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 108f4b7 commit 081fd95

38 files changed

Lines changed: 5536 additions & 0 deletions

File tree

‎services/unifi-layer-fabric/.github/workflows/build-images.yaml‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
name: Build and Push Container Images
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'src/**'
8+
- '.github/workflows/build-images.yaml'
9+
pull_request:
10+
branches: [main]
11+
workflow_dispatch:
12+
13+
env:
14+
REGISTRY: ghcr.io
15+
IMAGE_PREFIX: ${{ github.repository_owner }}
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
strategy:
21+
matrix:
22+
component:
23+
- name: cortex-activator
24+
context: src/activator
25+
- name: unifi-action-engine
26+
context: src/action-engine
27+
- name: unifi-ssh-gateway
28+
context: src/ssh-gateway
29+
- name: cortex-telemetry
30+
context: src/telemetry
31+
32+
permissions:
33+
contents: read
34+
packages: write
35+
36+
steps:
37+
- name: Checkout
38+
uses: actions/checkout@v4
39+
40+
- name: Set up Docker Buildx
41+
uses: docker/setup-buildx-action@v3
42+
43+
- name: Log in to Container Registry
44+
if: github.event_name != 'pull_request'
45+
uses: docker/login-action@v3
46+
with:
47+
registry: ${{ env.REGISTRY }}
48+
username: ${{ github.actor }}
49+
password: ${{ secrets.GITHUB_TOKEN }}
50+
51+
- name: Extract metadata
52+
id: meta
53+
uses: docker/metadata-action@v5
54+
with:
55+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}/${{ matrix.component.name }}
56+
tags: |
57+
type=sha,prefix=
58+
type=ref,event=branch
59+
type=semver,pattern={{version}}
60+
type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
61+
62+
- name: Build and push
63+
uses: docker/build-push-action@v5
64+
with:
65+
context: ${{ matrix.component.context }}
66+
push: ${{ github.event_name != 'pull_request' }}
67+
tags: ${{ steps.meta.outputs.tags }}
68+
labels: ${{ steps.meta.outputs.labels }}
69+
cache-from: type=gha
70+
cache-to: type=gha,mode=max
71+
72+
update-helm:
73+
needs: build
74+
runs-on: ubuntu-latest
75+
if: github.event_name != 'pull_request'
76+
77+
steps:
78+
- name: Checkout
79+
uses: actions/checkout@v4
80+
81+
- name: Update image tags in Helm values
82+
run: |
83+
SHA=$(echo ${{ github.sha }} | cut -c1-7)
84+
85+
# Update each chart's values.yaml with new image tag
86+
for chart in charts/*/; do
87+
if [ -f "$chart/values.yaml" ]; then
88+
sed -i "s/tag: \"v0.1.0\"/tag: \"$SHA\"/g" "$chart/values.yaml"
89+
fi
90+
done
91+
92+
- name: Commit and push
93+
run: |
94+
git config user.name "GitHub Actions"
95+
git config user.email "actions@github.com"
96+
git add charts/*/values.yaml
97+
git diff --staged --quiet || git commit -m "chore: update image tags to ${{ github.sha }}"
98+
git push

‎services/unifi-layer-fabric/CLAUDE_CODE_HANDOFF.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Claude Code Handoff: UniFi Layer Fabric Deployment
2+
3+
## Context
4+
5+
You're continuing a design session where we built a **serverless AI layer fabric** for UniFi network management. The architecture treats every capability (routing, reasoning, execution, memory) as an independent Kubernetes layer that scales to zero via KEDA.
6+
7+
This replaces the traditional "one big LLM" approach with composable layers that wake on demand.
8+
9+
## What's Been Built
10+
11+
The `unifi-layer-fabric/` directory contains:
12+
13+
```
14+
unifi-layer-fabric/
15+
├── README.md # Architecture overview
16+
├── docs/
17+
│ └── QUICKSTART.md # Deployment guide
18+
├── argocd/
19+
│ ├── applicationset.yaml # GitOps deployment
20+
│ └── secrets.yaml # Credential templates
21+
└── charts/
22+
├── cortex-activator/ # Always-on query router
23+
├── cortex-qdrant/ # Always-on vector memory
24+
├── reasoning-classifier/ # Qwen2-0.5B (fast classification)
25+
├── reasoning-slm/ # Phi-3-3.8B (tool calling)
26+
├── execution-unifi-api/ # UniFi API operations
27+
├── execution-unifi-ssh/ # SSH failover/diagnostics
28+
└── cortex-telemetry/ # Metrics, audit, learning
29+
```
30+
31+
## What Needs To Be Done
32+
33+
### 1. Build Container Images
34+
35+
The Helm charts reference these images that need source code + Dockerfiles:
36+
37+
| Image | Purpose | Language |
38+
|-------|---------|----------|
39+
| `ghcr.io/ry-ops/cortex-activator` | Query routing, layer orchestration | Python/FastAPI or Go |
40+
| `ghcr.io/ry-ops/unifi-action-engine` | UniFi API wrapper | Python |
41+
| `ghcr.io/ry-ops/unifi-ssh-gateway` | SSH command execution | Python |
42+
| `ghcr.io/ry-ops/cortex-telemetry` | Metrics collection, Qdrant writes | Python |
43+
44+
### 2. Push to GitHub
45+
46+
Create repo: `github.com/ry-ops/unifi-layer-fabric`
47+
48+
Structure:
49+
```
50+
unifi-layer-fabric/
51+
├── src/
52+
│ ├── activator/ # Cortex Activator source
53+
│ ├── action-engine/ # UniFi Action Engine source
54+
│ ├── ssh-gateway/ # SSH Gateway source
55+
│ └── telemetry/ # Telemetry collector source
56+
├── charts/ # Helm charts (already built)
57+
├── argocd/ # ArgoCD manifests
58+
├── .github/workflows/ # CI/CD for building images
59+
└── environments/
60+
└── production/ # Production value overrides
61+
```
62+
63+
### 3. Configure ArgoCD
64+
65+
```bash
66+
# Add the ApplicationSet to ArgoCD
67+
kubectl apply -f argocd/applicationset.yaml
68+
```
69+
70+
### 4. Create Secrets
71+
72+
```bash
73+
kubectl create namespace cortex-unifi
74+
75+
kubectl create secret generic unifi-credentials \
76+
--namespace cortex-unifi \
77+
--from-literal=api-key="SITE_MANAGER_API_KEY" \
78+
--from-literal=controller-host="https://UDM_PRO_IP" \
79+
--from-literal=controller-username="admin" \
80+
--from-literal=controller-password="CONTROLLER_PASSWORD" \
81+
--from-literal=ssh-host="UDM_PRO_IP" \
82+
--from-literal=ssh-username="root" \
83+
--from-literal=ssh-password="SSH_PASSWORD"
84+
```
85+
86+
### 5. Monitor Deployment
87+
88+
```bash
89+
# Watch ArgoCD sync
90+
argocd app list | grep unifi
91+
92+
# Watch pods
93+
kubectl get pods -n cortex-unifi -w
94+
95+
# Check KEDA ScaledObjects
96+
kubectl get scaledobjects -n cortex-unifi
97+
```
98+
99+
### 6. Test
100+
101+
```bash
102+
# Port forward to activator
103+
kubectl port-forward svc/cortex-activator -n cortex-unifi 8080:8080
104+
105+
# Test query
106+
curl -X POST http://localhost:8080/query \
107+
-H "Content-Type: application/json" \
108+
-d '{"query": "List all clients on the network"}'
109+
```
110+
111+
## Architecture Summary
112+
113+
```
114+
┌─────────────────────────────────────────────────────────────────────────┐
115+
│ USER QUERY │
116+
└─────────────────────────────┬───────────────────────────────────────────┘
117+
│
118+
▼
119+
┌─────────────────────────────────────────────────────────────────────────┐
120+
│ CORTEX ACTIVATOR (Always On, ~128MB) │
121+
│ 1. Keyword match → direct to execution layer (90% of queries) │
122+
│ 2. Ambiguous → wake classifier layer │
123+
│ 3. Complex → wake SLM reasoning layer │
124+
└─────────────────────────────┬───────────────────────────────────────────┘
125+
│
126+
┌─────────────────────┼─────────────────────┐
127+
▼ ▼ ▼
128+
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
129+
│ REASONING │ │ QDRANT │ │ EXECUTION │
130+
│ (Scale 0→1) │ │ (Always On) │ │ (Scale 0→1) │
131+
├───────────────┤ ├───────────────┤ ├───────────────┤
132+
│ • Classifier │ │ • Operations │ │ • UniFi API │
133+
│ (0.5B) │ │ • Configs │ │ • SSH Gateway │
134+
│ • SLM (3.8B) │ │ • Patterns │ │ │
135+
└───────────────┘ └───────────────┘ └───────────────┘
136+
```
137+
138+
## Memory Profile
139+
140+
| State | Memory | What's Running |
141+
|-------|--------|----------------|
142+
| **Idle** | ~640MB | Activator + Qdrant |
143+
| **Simple Query** | ~1GB | + Execution layer |
144+
| **Complex Query** | ~4GB | + SLM reasoning |
145+
| **Full Active** | ~4.5GB | All layers warm |
146+
147+
## Key Files to Review
148+
149+
1. `charts/cortex-activator/values.yaml` - Routing rules, layer endpoints
150+
2. `charts/reasoning-slm/values.yaml` - Model config, system prompt
151+
3. `charts/execution-unifi-api/values.yaml` - Action definitions
152+
4. `charts/execution-unifi-ssh/values.yaml` - Allowed SSH commands
153+
5. `argocd/applicationset.yaml` - GitOps deployment config
154+
155+
## Environment Details
156+
157+
- **Cluster**: k3s on Proxmox (7 nodes)
158+
- **RAM**: 64GB total, ~8-12GB available for Cortex
159+
- **CPU**: 20 cores
160+
- **GPU**: None (CPU inference only)
161+
- **Storage**: Longhorn CSI
162+
- **GitOps**: ArgoCD
163+
- **UniFi**: 1 site, UDM Pro
164+
165+
## After Deployment: Blog Post
166+
167+
Once running, create a blog post for ry-ops.dev covering:
168+
169+
1. **The Journey** - From monolithic LLM to composable layers
170+
2. **Why Serverless AI** - Cost savings, resource efficiency
171+
3. **Architecture Deep Dive** - How layers communicate
172+
4. **Real Performance** - Cold start times, memory usage
173+
5. **Learning Loop** - How it improves over time
174+
6. **What's Next** - Extending to other MCP servers
175+
176+
## Questions for Ryan
177+
178+
Before deploying, confirm:
179+
1. UDM Pro IP address for controller-host and ssh-host
180+
2. Site Manager API key (from ui.com account)
181+
3. Controller admin credentials
182+
4. SSH credentials for UDM Pro
183+
5. GitHub repo name (suggested: `ry-ops/unifi-layer-fabric`)
184+
6. Container registry (suggested: `ghcr.io/ry-ops/`)

0 commit comments

Comments
 (0)