dsh-tool-kubernetes

dsh-tool-kubernetes

English | 中文

A Cordis tool plugin that gives DeepSeek Harness (dsh) Kubernetes workflows: cluster/context inspection, namespace and workload discovery, pod logs, replica scaling, deployment rollouts, ConfigMaps, Secrets, Services, and manifest application.

The plugin registers 25 tools with the official ctx.tools.register(defineTool(...)) contract. It uses the official Kubernetes JavaScript client for kubeconfig loading and API calls, keeps write operations disabled by default, and returns stable business values for missing configuration and missing resources.

Install

Install directly from GitHub (no npm publish needed):

npm install github:LJH-snow/dsh-tool-kubernetes
# or a specific branch/tag
npm install github:LJH-snow/dsh-tool-kubernetes#main

Or from a local checkout:

git clone https://github.com/LJH-snow/dsh-tool-kubernetes
cd dsh-tool-kubernetes
npm install && npm run build   # builds to lib/
npm install /path/to/dsh-tool-kubernetes

Requires @deepseek-ai/cordis (^4.0.1) and @deepseek-ai/dsh-tools (^0.1.0-rc.6) as peer dependencies, provided by the host dsh runtime.

Configuration

Load the plugin in a dsh composition config (cordis.yml):

- name: 'dsh-tool-kubernetes'
  config:
    # Optional kubeconfig path. Defaults to $KUBECONFIG or ~/.kube/config.
    # kubeconfig: '/Users/you/.kube/config'
    # Optional kubeconfig context. Defaults to current-context.
    # context: 'prod'
    # Optional default namespace. Context namespace is used when omitted.
    namespace: 'team'
    # Write tools are off unless this is true.
    allowWrite: true
    # Optional namespace allowlist. Empty means every namespace is allowed when allowWrite is true.
    writeNamespaces:
      - team
    # Optional kind allowlist. Required to opt in to cluster-scoped, RBAC, Secret, or ServiceAccount writes.
    # writeKinds: [Deployment, StatefulSet]
    # Optional client-side pod log limits.
    # logMaxLines: 1000
    # logMaxBytes: 131072
    # logTimeoutMs: 15000

Full example: examples/cordis.yml.

Tools

Read-only

Write

Behavior contract

• Kubernetes access comes from a kubeconfig path, $KUBECONFIG, ~/.kube/config, or in-cluster service account files resolved by the official Kubernetes client.
• Missing configuration returns { connected: false, reason } instead of throwing during normal tool calls.
• Missing resources return { found: false }; write operations return { ok: false, reason } for gating or API failures.
• Write tools are disabled unless allowWrite: true. When writeNamespaces is set, it acts as a namespace allowlist; writeKinds is an explicit kind allowlist.
• Cluster-scoped, RBAC, Secret, and ServiceAccount writes are denied by default. Add the exact kind to writeKinds to opt in.
• k8s_apply_manifest validates the namespace and kind gate before any API request, including cluster-scoped manifests such as Namespace or Node.
• k8s_list_secrets and k8s_get_secret intentionally return key names only; Secret values are not returned.
• List limits are clamped to 1-100 (default 20). Pod log tail lines are clamped to 1-500 (default 200), then the client applies a 15-second timeout, redacts credentials, and caps output by logMaxLines/logMaxBytes (defaults 1000/128 KiB).

Development

npm install
npm run typecheck   # type check
npm test            # unit tests (vitest)
npm run build       # build to lib/

See DEVELOPMENT.md for technical notes and decisions.

Publishing

1. Ensure npm run typecheck, npm test, and npm run build all pass.
2. Publish with npm publish --access public.
3. Add the dsh-plugin topic to the GitHub repository for ecosystem discovery.

License

MIT