Dokumentation

Das Backend stellt eine GraphQL-API bereit. REST wird ausschließlich für Authentifizierung und Kubeconfig-Upload genutzt; alle übrigen Operationen laufen über GraphQL.

Sämtliche Queries und Mutations werden per POST /query abgesetzt. In Nicht-Release-Umgebungen ist unter GET /playground ein interaktiver GraphQL-Playground verfügbar.

curl -X POST https://api.konductly.io/query \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{"query":"{ health }"}'

• Queries: health, clusters, pods, costReport, dockerContainers, me
• Mutations: addCluster, removeCluster, deletePod, restartDeployment, scalePods, startContainer, stopContainer, restartContainer, createUser
• Autorisierung über Directives: @auth (gültiges Access-Token) und @hasRole(role: ADMIN) für privilegierte Felder

Die Anmeldung erfolgt per POST /auth/login und liefert ein kurzlebiges Access-Token (HS256, 15 Minuten) sowie ein Refresh-Token. Passwörter werden serverseitig mit bcrypt gehasht.

curl -X POST https://api.konductly.io/auth/login \  -H "Content-Type: application/json" \  -d '{"email":"admin@example.com","password":"••••••"}'

• Access-Token im Header senden: Authorization: Bearer <token>
• Refresh über POST /auth/refresh — das Refresh-Token (7 Tage, in Redis) wird dabei rotiert
• Rollenmodell: ADMIN (voller Zugriff) und VIEWER (read-only)

Echtzeit-Updates laufen über GraphQL-Subscriptions per WebSocket auf GET /query (Protokoll graphql-transport-ws). Die Authentifizierung wird im Init-Payload geprüft — der Upgrade findet erst nach erfolgreicher Prüfung statt.

subscriptionsubscription ClusterMetrics($id: ID!) {  clusterMetrics(clusterId: $id) {    nodeCount    nodesReady  }}

• clusterMetrics(clusterId): Node-Anzahl und Node-Status eines Clusters
• costUpdated(clusterId): aktualisierter Cost Report
• podStatusChanged(clusterId, namespace): Pod-Status-Events aus dem K8s-Watch

Die API ist gegen Resource-Exhaustion abgesichert. Limits gelten pro Identität (authentifiziert per Nutzer-ID, sonst per IP).

• Rate-Limiting: standardmäßig 60 Requests pro Minute (Fixed-Window, Redis-basiert)
• GraphQL-Depth-Limit: maximale Verschachtelungstiefe 8 (Code DEPTH_LIMIT_EXCEEDED)
• GraphQL-Complexity-Limit: maximale Query-Komplexität 100

Cluster werden über addCluster mit einer Base64-kodierten Kubeconfig angelegt; alternativ lässt sich die Kubeconfig per POST /clusters/:id/kubeconfig hochladen. Zugangsdaten werden mit AES-256-GCM verschlüsselt gespeichert und erst zur Laufzeit im Arbeitsspeicher entschlüsselt — nie im Klartext geloggt.

mutationmutation AddCluster($name: String!, $kubeconfig: String!) {  addCluster(inputinput: { name: $name, kubeconfig: $kubeconfig }) {    id    name  }}

• Unterstützte Auth-Typen: Kubeconfig, ServiceAccount-Token, Bearer-Token
• Pro Request wird ein dynamischer Kubernetes-Client aus den entschlüsselten Zugangsdaten gebaut
• Nur Admins können Cluster hinzufügen oder entfernen

Über die GraphQL-Mutations lassen sich Workloads steuern. Mutierende Aktionen sind Admins vorbehalten; Viewer haben ausschließlich Lesezugriff.

• deletePod(clusterId, namespace, name): Pod löschen
• restartDeployment(clusterId, namespace, name): Deployment neu starten
• scalePods(clusterId, namespace, name, replicas): Replica-Anzahl anpassen
• Docker-Container: startContainer / stopContainer / restartContainer (idempotent, mit Audit-Log)

costReport(clusterId) liefert die monatlichen Gesamtkosten, eine Effizienzkennzahl und konkrete Optimierungsvorschläge. Die Preisbasis ist eine fixe Preisliste (on-prem/Hetzner, kein Cloud-Pricing-API).

queryquery Cost($id: ID!) {  costReport(clusterId: $id) {    totalPerMonth    efficiency    recommendations {      typetype      target    }  }}

• Node-Kosten: 50 % CPU / 50 % Memory
• Pod-Kosten: (CPU-Request × Cost-per-Core) + (Memory-Request × Cost-per-GB)
• Felder: totalPerMonth, efficiency, recommendations

Waste Detection misst die Differenz zwischen angeforderten (Requested) und tatsächlich genutzten (Actual) Ressourcen und leitet daraus Empfehlungen ab.

• Waste % = (Requested − Actual) / Requested × 100
• Über 50 % Waste → Empfehlung RIGHTSIZE
• Weitere Empfehlungstypen: IDLE (ungenutzt) und DOWNSCALE (überdimensioniert)

Kubeconfigs und Cluster-Zugangsdaten werden mit AES-256-GCM verschlüsselt gespeichert und ausschließlich zur Laufzeit entschlüsselt. Der Schlüssel stammt aus dem Secret-Management und liegt nie im Repository oder in Images.

• JWT: Access-Token HS256, 15 Minuten; Refresh-Token 7 Tage in Redis, Rotation bei Refresh
• Passwörter: bcrypt (Cost ≥ 10)
• GraphQL: Depth-Limit 8, Complexity-Limit 100, Rate-Limiting pro Identität
• WebSocket: Auth-Check vor dem Upgrade; nur autorisierte Cluster/Namespaces/Pods

Alle veröffentlichten Releases — was neu ist und was behoben wurde — werden auf der Changelog-Seite gepflegt (Keep a Changelog). Geplante Funktionen stehen auf der Roadmap.

• Changelog: vollständige Versionshistorie unter /changelog
• Roadmap: geplante Funktionen unter /roadmap