Skip to main content
Glama

k8s-traps

Kubernetes manifest traps that pass the linters and still break production, packaged as a CLI and an MCP server so AI agents can check YAML before it ships.

Generic scanners (Kubescape, kube-linter, Trivy, Checkov) are good at baseline hygiene: resource limits, privileged containers, image tags. Use them. This project covers a different gap: configuration that is valid, lints clean, and fails silently. Each trap here comes from a real incident on a small production K3s cluster.

ID

Trap

Default severity

T01

Service-link env vars (<SVC>_PORT=tcp://…) collide with the app's own settings

high

T02

ServiceMonitor selects nothing (pod labels instead of Service labels, or an unnamed port)

high

T03

Namespace has workloads but no NetworkPolicy

medium

T04

ConfigMap/Secret mounted with subPath never updates

low

T05

Two hostnames route to the same backend (a dead route serves another app with 200)

medium

T06

Replicas only prefer to spread across nodes

medium

T07

Secret value written in plain text (the value is never echoed back)

high

Full explanations, including the incident behind each trap: docs/traps.md.

Scope and limits

  • Offline and read-only. It parses the YAML you give it and never contacts a cluster.

  • Judged from the input only. For example, T03 cannot see a NetworkPolicy that lives in another repo. Feed it a whole helm template render when you can.

  • Heuristics. T01's same-name rule and T07's name patterns can raise false positives. Each finding says what it is based on.

Related MCP server: kubectl-mcp

CLI

pip install k8s-traps
helm template my-chart | k8s-traps            # stdin
k8s-traps manifests/ --fail-on medium         # files or directories; exit 1 at/above severity
k8s-traps deploy.yaml --json --trap T01 --trap T02
k8s-traps --list

MCP server

The stdio server exposes three read-only tools:

  • audit_manifests(manifests: list[str], traps?: list[str])

  • list_traps()

  • explain_trap(trap_id)

Claude Code:

claude mcp add k8s-traps -- k8s-traps-mcp

Generic MCP client config:

{ "mcpServers": { "k8s-traps": { "command": "k8s-traps-mcp" } } }

Without installing first (this is what the MCP Registry entry runs):

{ "mcpServers": { "k8s-traps": { "command": "uvx", "args": ["k8s-traps", "--mcp"] } } }

Development

python -m venv .venv && .venv/bin/pip install -e '.[test]'
.venv/bin/pytest
.venv/bin/python scripts/gen_docs.py   # after editing the catalog in traps.py

Every trap has at least one test that must flag it and one that must stay clean. New traps are welcome; please describe the real failure each one comes from.


한국어 요약

린터는 통과하는데 운영에서 조용히 깨지는 쿠버네티스 매니페스트 함정을 잡는 CLI와 MCP 서버입니다. AI 에이전트가 YAML을 배포하기 전에 이 서버에 물어볼 수 있습니다.

  • 함정 7개는 모두 실제 K3s 클러스터에서 겪은 장애에서 나왔습니다. 목록은 위 표에 있습니다.

  • 리소스 한도나 권한 같은 기본 점검은 Kubescape나 kube-linter 몫입니다. 이 도구는 그 도구들과 같이 쓰도록 만들었습니다.

  • 입력으로 받은 YAML만 오프라인으로 봅니다. 클러스터에는 접속하지 않습니다.

  • 비밀값을 찾아도 그 값은 출력에 절대 싣지 않습니다.

License

MIT

Available Tools

3 tools
audit_manifestsA
Read-onlyIdempotent

Check Kubernetes YAML for known production traps.

manifests: one or more YAML strings (multi-document --- is fine; helm template output works). traps: optional subset of trap ids such as ["T01", "T02"]; default runs all. Returns findings sorted by severity. Secret values are never echoed back.

Inputs: manifests (required), traps.

explain_trapA
Read-onlyIdempotent

Explain one trap: what goes wrong, the incident it came from, and how to fix it.

Inputs: trap_id (required).

list_trapsA
Read-onlyIdempotent

List every trap this server checks, with id, title and default severity.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: list_traps enumerates available checks, audit_manifests executes the checks, and explain_trap provides detailed breakdowns. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (list_traps, audit_manifests, explain_trap). The naming is predictable and immediately conveys the action and target.

    Tool Count5/5

    With only 3 tools, the server is tightly scoped but each tool is essential: discovery, execution, and explanation. This is an appropriate minimal set for a specialized trap-checking utility.

    Completeness5/5

    The domain is well-covered: users can enumerate available traps, run the audit, and understand any trap's rationale and fix. No obvious gaps remain for the server's stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to safely observe and troubleshoot Kubernetes workloads, with limited recovery actions like pod deletion and Helm rollbacks, while preventing dangerous modifications.
      18
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Lets AI agents inspect Kubernetes clusters in plain English, exposing read-only tools for pods, deployments, services, events, and logs, with mock and real backend support.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to inspect Kubernetes pods and cluster events, query Prometheus and Loki, and diagnose pod health with suggested actions through MCP tools.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to safely inspect Kubernetes cluster inventory through read-only tools for listing nodes and pods, without exposing secrets or mutation operations.
      1
      MIT