dsh-kubernetes
为 DeepSeek Harness 提供安全的 Kubernetes 能力：工作负载检查、受限日志/事件查看、故障诊断，以及默认采用 dry-run 并需审批的变更。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-kubernetes@0.1.0Kubernetes 以 dsh-kubernetes 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
dsh-kubernetesgives 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
readOnly: true out of the box. Real writes require explicit opt-in and survive the DSH approval gate.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.tailLines / sinceSeconds / container / previous / maxChars with hard caps. Logs are UNTRUSTED DATA: secret-shaped values are redacted, ANSI/control characters stripped.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.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.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';
The plugin resolves kubeconfig with standard priority: explicit kubeconfigPath → KUBECONFIG env → ~/.kube/config → in-cluster service account. Context is never switched silently.
| Option | Default | Description |
|---|---|---|
readOnly | true | Read-only mode. Disables real writes even if allowWrite is true. |
allowWrite | false | Master switch for write operations. Real applies additionally require approval. |
context | – | Explicit kubeconfig context override. |
namespace | context namespace / default | Default namespace override. |
kubeconfigPath | – | Explicit kubeconfig file path. |
maxLogChars | 8000 | Hard cap of characters per log excerpt (500–20000). |
maxLogTailLines | 200 | Hard cap of tail lines per log request (1–500). |
maxLogSinceSeconds | 3600 | Hard cap of the log time window in seconds (10–21600). |
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
| Tool | Access | What it does |
|---|---|---|
k8s_context | read | Active context, cluster server, effective namespace, capabilities, all contexts (no credentials). |
k8s_namespaces | read | Namespaces with phase. |
k8s_workloads | read | Deployments/StatefulSets/DaemonSets with replicas + health, unhealthy-first. |
k8s_pods | read | Pods with phase, health, restarts, container waiting reasons (cap 200). |
k8s_describe | read | Sanitized resource describe. Secrets: metadata/type/data keys only. |
k8s_logs | read | Bounded, sanitized, de-duplicated pod logs. |
k8s_events | read | Events (optionally scoped to a resource), sanitized + bounded. |
k8s_diagnose | read | Structured DiagnosisEvidence with likely failure categories. |
k8s_rollout | read | Rollout status for a workload. |
k8s_apply | gated | Server-side dry-run apply by default; real apply needs allowWrite and approval. |
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)
prod/production/prd raise the risk level in the approval reason (string match is a hint, never proof of safety).delete, exec, port-forward, scale, restart or rollback tools in v1 — by design.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.
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." }
| Component | Tested with |
|---|---|
| DeepSeek Harness plugin API | @deepseek-ai/dsh-tools 0.1.0-rc.6 |
| Cordis runtime | @deepseek-ai/cordis 4.0.1 |
| Kubernetes client | @kubernetes/client-node 1.4.0 |
| Kubernetes cluster | kind v1.32.2 (E2E), standard API groups core/v1, apps/v1 |
| Node.js | ≥ 18.18 (tested on 22.x) |
k8s_apply performs server-side apply for create/update; no delete, no exec, no port-forward, no scale/rollback tools.unknown.k8s_workloads (core workload kinds only); k8s_describe works for arbitrary kinds.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.
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