Panel sterowania zatwierdzeniami dla agenta naprawczego Kubernetes: FastAPI i React
Stwórz backend FastAPI z listą dozwolonych zadań kubectl oraz panel kontrolny w React, aby agent naprawczy oparty na LLM mógł naprawiać incydenty tylko po tym, jak osoba ludzka kliknie „Zatwierdź”.
Źródła: Self-Healing Kubernetes: Wiring OpenTelemetry, SigNoz, and a Groq-Powered Remediation Agent (PART 6)
Agent naprawczy z poprzedniego etapu może już rozpoznać trzy rodzaje incydentów i poprosić Groq o diagnozę. Następnie próbuje umieścić kartę incydentu w backendzie, który jeszcze nie istnieje. W tym etapie budowany jest ten backend wraz z panelami sterowania React, co zamyka pętlę. Gdy występuje incydent, SigNoz go rejestruje, agent go diagnozuje, na panelu pojawia się karta, operator kliknie „Zatwierdź”, a naprawa zostanie przeprowadzona na klastrze. Po początkowej konfiguracji nie jest potrzebny żaden terminal.
Jak ze sobą łączą się poszczególne elementy
Agent naprawczy wysyła karty incydentów do backendu za pomocą żądania POST /api/incidents. Serwis FastAPI przechowuje te karty, weryfikuje polecenia kubectl i stosuje zatwierdzone naprawy za pośrednictwem narzędzi Kubernetes. Dashboard React odczytuje listę za pomocą żądania GET /api/incident i podejmuje działania w odniesieniu do danej karty poprzez żądania POST /api/incidents/{id}/approve lub /reject. Na ekranie pokazuje się karty incydentów, przyciski „Zatwierdź” i „Odrzuć”, odznaka pewności oraz rejestr audytu.
W klastrze działają dwa kontenery. Aplikacja React to statyczna budowa serwowana przez nginx, natomiast backend FastAPI jest jedynym komponentem, który ma dostęp do API Kubernetes.
Krok 1: Stworzenie folderów
Oba te elementy znajdują się w katalogu dashboard w projekcie:
cd ~/k8s-aiops-blog
mkdir -p dashboard/backend dashboard/frontend
Krok 2: Backend FastAPI
Backend pełni cztery funkcje. Przechowuje przychodzące karty w pamięci, co wystarcza do demonstracji, ponieważ nie jest używana żadna baza danych. Dostarcza te karty do frontendu oraz obsługuje kliknięcia „Zatwierdź” i „Odrzuć”. Po zatwierdzeniu weryfikuje proponowany polecenie kubectl, a następnie je wykonuje. Zacznij w folderze backendu:
cd ~/k8s-aiops-blog/dashboard/backend
Następnie utwórz plik main.py:
cat > main.py <<'EOF'
"""
Approval dashboard backend.
Receives incident cards from the remediation agent, serves them to the
React frontend, and applies approved kubectl commands via the Kubernetes
Python client.
"""
import logging
import shlex
import subprocess
import time
from typing import Literal
from uuid import uuid4from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModellogging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(name)s — %(message)s",
)
log = logging.getLogger("dashboard")app = FastAPI(title="Approval Dashboard")app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)# ---------------------------------------------------------------------------
# In-memory store. Fine for a demo; swap for SQLite or Redis in production.
# ---------------------------------------------------------------------------
INCIDENTS: dict[str, dict] = {}# ---------------------------------------------------------------------------
# kubectl command allowlist.
# The LLM proposes a fix. We only execute it if it matches one of these
# safe prefixes. Nothing with delete, drain, or --all gets through.
# ---------------------------------------------------------------------------
ALLOWED_PREFIXES = (
"kubectl set env",
"kubectl rollout restart",
"kubectl scale",
"kubectl set resources",
)BLOCKED_TERMS = ("delete", "drain", "--all", "cluster-admin", "exec", "cp")
# ---------------------------------------------------------------------------
# Models
# ---------------------------------------------------------------------------
class IncidentCard(BaseModel):
id: str
timestamp: int
service: str
signals: dict
diagnosis: dict
status: Literal["pending", "approved", "rejected"] = "pending"
class ActionRequest(BaseModel):
actor: str = "operator"
# ---------------------------------------------------------------------------
# Routes
# ---------------------------------------------------------------------------
@app.get("/healthz")
def healthz():
return {"ok": True}
@app.post("/api/incidents", status_code=201)
def receive_incident(card: IncidentCard):
INCIDENTS[card.id] = card.dict()
log.info("incident received: id=%s type=%s", card.id, card.diagnosis.get("incident_type"))
return {"id": card.id}
@app.get("/api/incidents")
def list_incidents():
# Most recent first
return sorted(INCIDENTS.values(), key=lambda c: c["timestamp"], reverse=True)
@app.get("/api/incidents/{incident_id}")
def get_incident(incident_id: str):
if incident_id not in INCIDENTS:
raise HTTPException(status_code=404, detail="not found")
return INCIDENTS[incident_id]
@app.post("/api/incidents/{incident_id}/approve")
def approve_incident(incident_id: str, req: ActionRequest):
card = INCIDENTS.get(incident_id)
if not card:
raise HTTPException(status_code=404, detail="not found")
if card["status"] != "pending":
raise HTTPException(status_code=409, detail=f"incident already {card['status']}") proposed = card["diagnosis"].get("proposed_fix", "")
log.info("approve requested: id=%s fix=%r actor=%s", incident_id, proposed, req.actor) # Validate against allowlist
allowed = any(proposed.startswith(p) for p in ALLOWED_PREFIXES)
blocked = any(term in proposed for term in BLOCKED_TERMS) if not allowed or blocked:
log.error("REJECTED by allowlist: %r", proposed)
raise HTTPException(
status_code=400,
detail=f"proposed command did not pass allowlist validation: {proposed!r}",
) # Apply the fix
try:
args = shlex.split(proposed)
result = subprocess.run(
args,
capture_output=True,
text=True,
timeout=30,
)
if result.returncode != 0:
log.error("kubectl failed: %s", result.stderr)
raise HTTPException(status_code=500, detail=f"kubectl error: {result.stderr}") log.info("kubectl succeeded: %s", result.stdout.strip())
card["status"] = "approved"
card["applied_at"] = int(time.time())
card["applied_by"] = req.actor
card["kubectl_output"] = result.stdout.strip()
INCIDENTS[incident_id] = card
return {"status": "approved", "kubectl_output": result.stdout.strip()} except subprocess.TimeoutExpired:
raise HTTPException(status_code=504, detail="kubectl timed out")
@app.post("/api/incidents/{incident_id}/reject")
def reject_incident(incident_id: str, req: ActionRequest):
card = INCIDENTS.get(incident_id)
if not card:
raise HTTPException(status_code=404, detail="not found")
if card["status"] != "pending":
raise HTTPException(status_code=409, detail=f"incident already {card['status']}") card["status"] = "rejected"
card["rejected_at"] = int(time.time())
card["rejected_by"] = req.actor
INCIDENTS[incident_id] = card
log.info("incident rejected: id=%s actor=%s", incident_id, req.actor)
return {"status": "rejected"}
EOF
Warto przyjrzeć się bliżej sprawdzeniu listy dozwolonych operacji. ALLOWED_PREFIXES zapewnia, że polecenie zaczyna się od jednej z zatwierdzonych, bezpiecznych operacji. BLOCKED_TERMS to drugi filtr, który odrzuca wszystko, co zawiera słowa, których nigdy nie powinno się wykonywać, niezależnie od prefiksu. Oba filtry muszą zostać przekroczone, więc polecenie zaczynające się od kubectl set env z parametrem --all nadal zostaje odrzucone.
Dla uproszczenia i ułatwienia audytu kod wykorzystuje subprocess.run zamiast SDK Pythona do Kubernetes, co ułatwia rejestrowanie dokładnego wykonywanego polecenia. W środowisku produkcyjnym lepiej sprawdziłoby się CoreV1Api lub AppsV1Api z SDK, które omijają tworzenie podprocesu i zwracają ustrukturyzowane błędy.
Krok 3: Ustalenie wersji zależności
Dokładne wersje są umieszczane w pliku requirements.txt:
cat > requirements.txt <<'EOF'
fastapi==0.115.0
uvicorn[standard]==0.32.0
pydantic==2.9.2
httpx==0.27.2
EOF
Krok 4: Dockerfile backendu
Zaczyna się od lekkiego obrazu Pythona:
cat > Dockerfile <<'EOF'
FROM python:3.11-slim
Pozostała część instaluje kubectl, aby backend mógł zastosować poprawki, a następnie konfiguruje aplikację:
# Install kubectl so the backend can apply fixes
RUN apt-get update && apt-get install -y curl && \
curl -LO "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && \
install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl && \
rm kubectl && \
apt-get cleanWORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY main.py .EXPOSE 9000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "9000"]
EOF
Krok 5: Frontend w React
Frontend to zwykły plik HTML, który pobiera React i Tailwind z CDN, więc nie ma nic do skompilowania, a plik Dockerfile pozostaje prosty. Najpierw przejdź do folderu frontend:
cd ~/k8s-aiops-blog/dashboard/frontend
Następnie napisz index.html:
cat > index.html <<'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>SRE Approval Dashboard</title>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react/18.2.0/umd/react.production.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react-dom/18.2.0/umd/react-dom.production.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/babel-standalone/7.23.2/babel.min.js"></script>
<link href="https://cdnjs.cloudflare.com/ajax/libs/tailwindcss/2.2.19/tailwind.min.css" rel="stylesheet"/>
</head>
<body class="bg-gray-950 text-gray-100 min-h-screen">
<div id="root"></div><script type="text/babel">
const API = "http://localhost:9000";const SEVERITY_COLOR = {
critical: "bg-red-600",
high: "bg-orange-500",
medium: "bg-yellow-500",
low: "bg-blue-500",
};const TYPE_LABEL = {
crash_loop: "Crash Loop",
oom_kill: "OOM Kill",
latency_spike: "Latency Spike",
token_spike: "Token Spike",
unknown: "Unknown",
};function ConfidenceBadge({ value }) {
const pct = Math.round((value || 0) * 100);
const color = pct >= 80 ? "text-green-400" : pct >= 50 ? "text-yellow-400" : "text-red-400";
return (
<span className={`text-xs font-mono font-bold ${color}`}>
{pct}% confidence
</span>
);
}function IncidentCard({ card, onAction }) {
const d = card.diagnosis || {};
const sev = d.severity || "low";
const isPending = card.status === "pending"; return (
<div className="bg-gray-900 border border-gray-700 rounded-xl p-5 mb-4 shadow-lg">
{/* Header row */}
<div className="flex items-center justify-between mb-3">
<div className="flex items-center gap-2">
<span className={`text-xs font-bold px-2 py-0.5 rounded-full text-white ${SEVERITY_COLOR[sev] || "bg-gray-600"}`}>
{sev.toUpperCase()}
</span>
<span className="font-semibold text-white">
{TYPE_LABEL[d.incident_type] || d.incident_type}
</span>
<span className="text-gray-400 text-sm">— {card.service}</span>
</div>
<div className="flex items-center gap-3">
<ConfidenceBadge value={d.confidence} />
<span className="text-xs text-gray-500">
{new Date(card.timestamp * 1000).toLocaleTimeString()}
</span>
</div>
</div> {/* Root cause */}
<p className="text-sm text-gray-300 mb-3">
<span className="text-gray-500 mr-1">Root cause:</span>
{d.root_cause}
</p> {/* Proposed fix */}
<div className="bg-gray-800 rounded-lg px-4 py-2 mb-4 font-mono text-sm text-green-300 flex items-center gap-2">
<span className="text-gray-500 select-none">lt;/span>
{d.proposed_fix}
</div> {/* Low confidence warning */}
{(d.confidence || 0) < 0.6 && isPending && (
<div className="bg-yellow-900 border border-yellow-600 rounded-lg px-3 py-2 mb-3 text-yellow-300 text-xs">
⚠ Low confidence — review signals carefully before approving.
</div>
)} {/* Action buttons or status badge */}
{isPending ? (
<div className="flex gap-3 mt-2">
<button
onClick={() => onAction(card.id, "approve")}
className="bg-green-600 hover:bg-green-500 text-white text-sm font-semibold px-5 py-2 rounded-lg transition"
>
✓ Approve
</button>
<button
onClick={() => onAction(card.id, "reject")}
className="bg-red-700 hover:bg-red-600 text-white text-sm font-semibold px-5 py-2 rounded-lg transition"
>
✗ Reject
</button>
</div>
) : (
<div className={`inline-block text-xs font-bold px-3 py-1 rounded-full mt-1 ${
card.status === "approved" ? "bg-green-800 text-green-300" : "bg-red-900 text-red-300"
}`}>
{card.status === "approved" ? "✓ Approved" : "✗ Rejected"}
{card.applied_by && ` by ${card.applied_by}`}
</div>
)} {/* kubectl output on approved cards */}
{card.kubectl_output && (
<div className="mt-3 bg-gray-800 rounded-lg px-4 py-2 font-mono text-xs text-gray-400">
{card.kubectl_output}
</div>
)}
</div>
);
}function App() {
const [incidents, setIncidents] = React.useState([]);
const [loading, setLoading] = React.useState(true);
const [error, setError] = React.useState(null);
const [acting, setActing] = React.useState(null); const fetchIncidents = () => {
fetch(`${API}/api/incidents`)
.then(r => r.json())
.then(data => { setIncidents(data); setLoading(false); setError(null); })
.catch(e => { setError(e.message); setLoading(false); });
}; React.useEffect(() => {
fetchIncidents();
const id = setInterval(fetchIncidents, 10000); // poll every 10s
return () => clearInterval(id);
}, []); const handleAction = async (id, action) => {
setActing(id);
try {
const r = await fetch(`${API}/api/incidents/${id}/${action}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ actor: "operator" }),
});
if (!r.ok) {
const err = await r.json();
alert(`Action failed: ${err.detail}`);
}
fetchIncidents();
} catch (e) {
alert(`Network error: ${e.message}`);
} finally {
setActing(null);
}
}; const pending = incidents.filter(c => c.status === "pending");
const resolved = incidents.filter(c => c.status !== "pending"); return (
<div className="max-w-3xl mx-auto px-4 py-8">
{/* Header */}
<div className="mb-8">
<h1 className="text-2xl font-bold text-white">SRE Approval Dashboard</h1>
<p className="text-gray-400 text-sm mt-1">
Human-in-the-loop remediation — review every fix before it runs
</p>
</div> {loading && <p className="text-gray-500">Loading incidents…</p>}
{error && <p className="text-red-400">Could not reach backend: {error}</p>} {/* Pending */}
{pending.length > 0 && (
<section className="mb-8">
<h2 className="text-sm font-semibold text-gray-400 uppercase tracking-widest mb-3">
Awaiting Review ({pending.length})
</h2>
{pending.map(c => (
<IncidentCard key={c.id} card={c} onAction={handleAction} />
))}
</section>
)} {pending.length === 0 && !loading && (
<div className="bg-gray-900 border border-gray-700 rounded-xl p-8 text-center text-gray-500 mb-8">
No pending incidents. The cluster looks healthy.
</div>
)} {/* Resolved */}
{resolved.length > 0 && (
<section>
<h2 className="text-sm font-semibold text-gray-400 uppercase tracking-widest mb-3">
Resolved ({resolved.length})
</h2>
{resolved.map(c => (
<IncidentCard key={c.id} card={c} onAction={handleAction} />
))}
</section>
)}
</div>
);
}ReactDOM.createRoot(document.getElementById("root")).render(<App />);
</script>
</body>
</html>
EOF
Krok 6: Dockerfile frontendu
Obraz nginx serwuje stronę statyczną:
cat > Dockerfile <<'EOF'
FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html
EXPOSE 80
EOF
Krok 7: Tworzenie obrazów i ich ładowanie do Kind
Każdy obraz jest tworzony, a następnie ładowany do lokalnego klastra, począwszy od warstwy backend:
cd ~/k8s-aiops-blog/dashboard/backend
docker build -t approval-backend:v1 .
kind load docker-image approval-backend:v1 --name aiops
a potem frontend:
cd ~/k8s-aiops-blog/dashboard/frontend
docker build -t approval-frontend:v1 .
kind load docker-image approval-frontend:v1 --name aiops
Krok 8: Manifesty Kubernetes
Jeden plik dashboard.yaml zawiera informacje o Deployments i Services dla obu części:
cat > ~/k8s-aiops-blog/k8s/dashboard.yaml <<'EOF'
# ── Backend ────────────────────────────────────────────────────────────────
apiVersion: apps/v1
kind: Deployment
metadata:
name: approval-backend
namespace: apps
spec:
replicas: 1
selector:
matchLabels:
app: approval-backend
template:
metadata:
labels:
app: approval-backend
spec:
containers:
- name: backend
image: approval-backend:v1
imagePullPolicy: IfNotPresent
ports:
- containerPort: 9000
readinessProbe:
httpGet:
path: /healthz
port: 9000
initialDelaySeconds: 5
periodSeconds: 10
resources:
requests:
memory: "128Mi"
cpu: "100m"
limits:
memory: "256Mi"
cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
name: approval-dashboard
namespace: apps
spec:
selector:
app: approval-backend
ports:
- port: 9000
targetPort: 9000
---
# ── Frontend ───────────────────────────────────────────────────────────────
apiVersion: apps/v1
kind: Deployment
metadata:
name: approval-frontend
namespace: apps
spec:
replicas: 1
selector:
matchLabels:
app: approval-frontend
template:
metadata:
labels:
app: approval-frontend
spec:
containers:
- name: frontend
image: approval-frontend:v1
imagePullPolicy: IfNotPresent
ports:
- containerPort: 80
resources:
requests:
memory: "64Mi"
cpu: "50m"
limits:
memory: "128Mi"
cpu: "200m"
---
apiVersion: v1
kind: Service
metadata:
name: approval-frontend-svc
namespace: apps
spec:
selector:
app: approval-frontend
ports:
- port: 3000
targetPort: 80
EOF
Zastosuj to, a następnie poczekaj, aż oba wdrożenia się zakończą:
kubectl apply -f ~/k8s-aiops-blog/k8s/dashboard.yaml
kubectl rollout status deployment/approval-backend -n apps
kubectl rollout status deployment/approval-frontend -n apps
Krok 9: Otwórz panel sterowania
Potrzebne są jeszcze dwa port-forwardy, po jednym w nowej karcie terminala. Pierwszy umożliwia dostęp do backendu:
kubectl port-forward -n apps svc/approval-dashboard 9000:9000
Drugi pokazuje interfejs użytkownika:
kubectl port-forward -n apps svc/approval-frontend-svc 3000:3000
Przejdź na http://localhost:3000. Strona pokazuje puste stanie „Brak bieżących incydentów”, co na razie jest poprawne.
Krok 10: Uruchom cały pętlę
Tutaj wszystko się łączy, więc użyj czterech kart terminala obok siebie. Pierwsza pokazuje logi agenta:
kubectl logs -n apps deployment/remediation-agent --tail=5 -f
Drugi nadzoruje kapsuły usługi sumującej:
kubectl get pods -n apps -w
Trzeci powoduje pętlę awarii:
kubectl set env deployment/summarizer -n apps KILL_ME=true
curl -s http://localhost:8000/crash
Czwarty to przeglądarka na http://localhost:3000.
W ciągu około trzydziestu sekund agent rejestruje sygnał błędu w pętli, oznacza tę anomalię, wywołuje Groq i zapisuje diagnozę wraz z proponowanym rozwiązaniem:
... WARNING crash loop signal: error_rate=1.00
... INFO anomaly detected: crash_loop — calling Groq for diagnosis
... INFO diagnosis: type=crash_loop severity=critical confidence=0.91
fix=kubectl set env deployment/summarizer -n apps KILL_ME-
... INFO incident posted: id=<uuid> type=crash_loop
Panel sterowania odświeża się co dziesięć sekund, a pojawia się karta incydentu:
CRITICAL Crash Loop — summarizer 91% confidence
Root cause: The KILL_ME environment variable is set to true, causing the process to exit immediately on each start.
$ kubectl set env deployment/summarizer -n apps KILL_ME-
[ ✓ Approve ] [ ✗ Reject ]
Kliknięcie przycisku „Zatwierdź” powoduje, że serwer sprawdza polecenie w liście dostępnych, uruchamia je i aktualizuje kartę:
✓ Approved by operator
deployment.apps/summarizer env updated
W zakładce obserwacji kontenerów narzędzie do generowania streszczeń uruchamia się poprawnie i przechodzi do stanu „Running 1/1”, bez powrotu do błędu CrashLoopBackOff. Pętla została zamknięta.
Utrzymywanie listy uprawnień w czystości
Lista jest celowo konserwatywna. W rzeczywistym środowisku powinna zostać rozszerzona o procedury, których zespół już się trzyma. Jeśli standardowym rozwiązaniem w przypadku wycieku pamięci jest zawsze kubectl rollout restart, należy to dodać. Jeśli czasami potrzebne jest kubectl scale, również należy je dodać.
Nie dodawaj niczego destruktywnego. Model językowy AI rzadko ma wystarczająco dużo racji, by można mu było powierzyć zadanie wykonywania polecenia kubectl delete. Krok zatwierdzenia istnieje dlatego, że to właśnie 9 procent przypadków, w których model się myli przy 91 procent pewności, budzi ludzi o 3 nad ranem.
Co pozostało
Następują kilka dodatkowych rozszerzeń. Pełny przegląd pętli awarii, zamykania procesu z powodu braku pamięci oraz gwałtownego wzrostu liczby tokenów pokazałby wykresy czasowe SigNoz dla każdego z tych przypadków. Magazyn incydentów w pamięci powinien zostać zastąpiony prawdziwą bazą danych, Slack mógłby informować o każdej nowej karcie, a ekosystem CNCF oferuje projekty godne zbadania pod kątem użycia w produkcji.