xxiaoxiong/dsh-kubernetes

dsh-kubernetes

dsh-kubernetes gives DeepSeek Harness a safe Kubernetes capability: inspect workloads, retrieve bounded logs and events, diagnose common failures, and perform approval-gated changes.

A community plugin for DeepSeek Harness (DSH). It is not a kubectl wrapper — it turns Kubernetes into a structured, Agent-friendly runtime capability with a read-first security model.

DSH Agent
   ↓
Generic Kubernetes Tools (10)
   ↓
ctx.kubernetes capability service
   ↓
KubernetesService (policy · diagnosis · bounding)
   ↓
KubernetesClientProvider (@kubernetes/client-node)
   ↓
Kubernetes API

Highlights

• Read-first by default — readOnly: true out of the box. Real writes require explicit opt-in and survive the DSH approval gate.
• 10 structured tools — every tool returns JSON with a schema plus a compact text rendering; no fragile CLI output parsing.
• k8s_diagnose evidence engine — walks Deployment/StatefulSet → Pods → containers → events → bounded logs and classifies likely failure categories (CrashLoopBackOff, ImagePullBackOff, OOMKilled, probe failures, …). No inner LLM: the plugin collects evidence, the DSH Agent reasons.
• Bounded, sanitized logs — tailLines / sinceSeconds / container / previous / maxChars with hard caps. Logs are UNTRUSTED DATA: secret-shaped values are redacted, ANSI/control characters stripped.
• Secrets never leak — k8s_describe secret returns metadata, type and data keys only. Credential-shaped fields (token, password, client-key-data, service-account tokens, container env secrets, …) are redacted everywhere.
• Controlled k8s_apply — server-side dry-run by default; real applies are denied under read-only policy, or escalated to approval (ask) when writes are enabled, with cluster/namespace context and production-risk warnings in the reason.

Installation

dsh plugin add dsh-kubernetes          # from npm (once published)
# or from a packed tarball:
npm pack
dsh plugin add ./dsh-kubernetes-0.1.0.tgz

Library use outside DSH also works — the package exports a host-agnostic API:

import { KubernetesClientProvider, DiagnosisEngine, KubernetesService } from 'dsh-kubernetes';

Configuration

The plugin resolves kubeconfig with standard priority: explicit kubeconfigPath → KUBECONFIG env → ~/.kube/config → in-cluster service account. Context is never switched silently.

Profile example — the plugin’s bundled cordis.patch.yml inserts itself with safe defaults automatically; override by id in your own profile layer if needed:

- id: dsh-kubernetes
  config:
    readOnly: true
    allowWrite: false

Tools

Security model

readOnly=true (default)      readOnly=false + allowWrite=true
────────────────────────     ─────────────────────────────────
get/list/describe  ✓         get/list/describe          ✓
logs/events        ✓         logs/events                ✓
apply dryRun=true  ✓         apply dryRun=true          ✓
apply dryRun=false ✗ deny    apply dryRun=false         → approval (ask)

• Write operations bind explicitly to context / cluster / namespace / resource and show them before approval.
• Contexts named like prod/production/prd raise the risk level in the approval reason (string match is a hint, never proof of safety).
• No delete, exec, port-forward, scale, restart or rollback tools in v1 — by design.
• kubeconfig contents, tokens, client keys and certificates never enter tool results or the session.

Diagnosis demo

User: Why does production/order-service keep restarting?

Agent → k8s_diagnose(Deployment/order-service)

Evidence:
- deployment: 3 desired / 1 ready — progressing
- pods: 3 total; 2× CrashLoopBackOff (unhealthy)
- containers: last termination OOMKilled (exit 137), restarts 14
- memory limit: 512Mi on all containers
- relevant events: BackOff ×14 (Warning)
- bounded logs (tail 40, redacted): "OOMkilled while serving traffic"
- likelyCategories: ["crash-loop", "oom-killed"]

The plugin marks categories as likely, never as certain facts — final reasoning stays with the DSH Agent.

Dry-run / approval demo

Agent → k8s_apply(manifest, dryRun=true)
Result: applied (server-side dry-run): ConfigMap/order-service-config (namespace default)

User: looks good, apply it for real

Agent → k8s_apply(manifest, dryRun=false)
Approval request (ask):
  k8s_apply with dryRun=false targets context "kind-dsh-e2e" (namespace "default").
  Approve to perform the real change.

Under the default read-only policy the same call is denied outright:

{ kind: "deny", reason: "real apply denied: plugin is read-only (readOnly=true, allowWrite=false). Set allowWrite=true and readOnly=false to enable approval-gated writes." }

Compatibility

Known limitations

• v1 targets standard Kubernetes only (OpenShift / EKS/GKE/AKS-specific auth flows untested; standard kubeconfig works).
• k8s_apply performs server-side apply for create/update; no delete, no exec, no port-forward, no scale/rollback tools.
• Rollout status is computed for Deployment/StatefulSet/DaemonSet; other kinds return unknown.
• Log redaction uses pattern heuristics — exhaustive secret detection is not guaranteed.
• CRDs are not listed by k8s_workloads (core workload kinds only); k8s_describe works for arbitrary kinds.

Uninstall

dsh plugin remove dsh-kubernetes

All service/tool registrations are attached to the plugin fiber — removal rolls them back completely, with no residual listeners or processes.

Development

npm install
npm run lint        # tsc --noEmit
npm test            # 105 unit + mock-API + contract + cordis tests
npm run build

# Real-cluster E2E (throwaway cluster only):
kind create cluster --name dsh-e2e
DSH_K8S_E2E=1 npm run test:e2e

License

MIT