dsh-tool-kubernetes
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#mainOr 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-kubernetesRequires @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:
- teamFull example: examples/cordis.yml.
Tools
Read-only
| Tool | Description |
|---|---|
k8s_get_config |
Current context, kubeconfig contexts, API server, default namespace |
k8s_list_namespaces |
Namespace phase and creation time |
k8s_list_nodes |
Node readiness, roles, kubelet version, internal IP |
k8s_list_pods |
Pods with phase, ready containers, restarts, node, containers |
k8s_get_pod |
One pod with phase and container state |
k8s_read_pod_logs |
Tail pod logs with container/timestamps/previous options |
k8s_list_deployments |
Replica and rollout counts for all deployments in a namespace |
k8s_get_deployment |
One deployment with images and rollout counts |
k8s_rollout_status_deployment |
Progressing condition, revision, ready/updated/available replicas |
k8s_list_statefulsets |
StatefulSets with desired/ready replicas |
k8s_get_statefulset |
One StatefulSet with images and replica state |
k8s_list_services |
Service type, cluster IP, external IP, ports |
k8s_get_service |
One service with selectors and exposed ports |
k8s_list_ingresses |
Ingress hosts and load balancer address |
k8s_list_configmaps |
ConfigMap key names and creation time |
k8s_get_configmap |
One ConfigMap with key names |
k8s_list_secrets |
Secret names/types/key names only, never values |
k8s_get_secret |
One Secret with key names only |
k8s_list_events |
Recent events with source, involved object, reason, count |
Write
| Tool | Description |
|---|---|
k8s_scale_deployment |
Scale a deployment |
k8s_scale_statefulset |
Scale a StatefulSet |
k8s_restart_deployment |
Add a restartedAt annotation to a deployment pod template |
k8s_update_deployment_image |
Update one container image in a deployment |
k8s_rollout_undo_deployment |
Roll a deployment back to a previous ReplicaSet revision |
k8s_apply_manifest |
Create or patch one or more YAML/JSON manifests |
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. WhenwriteNamespacesis set, it acts as a namespace allowlist. k8s_apply_manifestapplies the same write gate to every object, including cluster-scoped manifests such as Namespace or Node.k8s_list_secretsandk8s_get_secretintentionally 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).
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
- Ensure
npm run typecheck,npm test, andnpm run buildall pass. - Publish with
npm publish --access public. - Add the
dsh-plugintopic to the GitHub repository for ecosystem discovery.