k8stools: Instructions file for Claude Code

k8stools

Kubernetes monitoring tools for AI agents, exposed as direct Python functions or via an MCP server.

Project layout

src/k8stools/
  k8s_tools.py   - Core tools: Kubernetes API wrappers with Pydantic return types
  composites.py  - Logic of the composite tools (get_namespace_health, get_workload_report)
  mock_state.py  - MockState: loads a capture file and serves it to the tool queries
  capture.py     - `k8s-capture-state` CLI: snapshots a live cluster to a capture file
  itbench.py     - `--from-itbench`: serves one pull of an ITBench-Lite snapshot to capture_state
  mock_tools.py  - Mock versions of all tools; thin delegates to MockState
  redaction.py   - Secret-redaction pass applied at the MCP server output boundary
  mcp_server.py  - MCP server (stdio or streamable-http transport)
  mcp_client.py  - MCP client used for manual testing
  fixtures/
    otel-demo.json - Built-in capture served by `--mock` (hand-maintained, modeled on Minikube + OTel Demo)
tests/
  fixtures/itbench-33-excerpt/ - Trimmed ITBench-Lite Scenario-33 (two pulls); made by fixtures/make_itbench_excerpt.py
  test_k8s_tools.py          - Unit tests for the original tools (mocked K8s API)
  test_new_tools.py          - Unit tests for the 1.1.0 tools (ConfigMaps, CronJobs/Jobs, PVCs, StatefulSets, events, log enhancements)
  test_replicaset_tool.py    - Unit tests for get_replicaset_summaries (1.2.0), incl. mock-data consistency
  test_redaction.py          - Unit tests for the secret-redaction pass
  test_mock_state.py         - Unit tests for MockState (filters, replicaset ordering, logs, replay clock)
  test_capture.py            - Capture serialization round-trip and capture-time redaction
  test_k8s_tools_realk8s.py  - Integration tests (real cluster, auto-skipped if unreachable)
  test_live_writes.py        - Integration tests that create the failure they check, in their own namespace (opt-in: K8STOOLS_LIVE_WRITE=1)
  test_mock_tools.py         - Tests for mock_tools module (incl. parity with k8s_tools.TOOLS)
  test_events.py             - Event aggregation (count/first_seen), incl. the events.k8s.io fallback
  test_cluster_binding.py    - Cluster selection: configure(), the shared binding, get_cluster_info, server flags
  test_node_conditions.py    - NodeSummary.conditions_since (condition transition times), incl. capture replay
  test_workloads.py          - get_daemonset_summaries and PodSummary.owner, incl. capture replay
  test_builtin_fixture.py    - The built-in fixture describes a cluster that could exist (owners, images, ages, log windows, histories)
  test_workload_history.py   - get_workload_history: template diffs, revisions, config refs, no env values or Secret reads, replay
  test_toolsets.py           - Toolsets: named subsets, include/exclude, server flags
  test_notes.py              - Description budgets, notes on results and logs, notes in replay
  test_composites.py         - get_namespace_health / get_workload_report: semantics, grouping, bounds
  test_init_containers.py    - Init containers and native sidecars: the pod model, composites, capture, older captures
  test_stuck_rollouts.py     - Unscheduled pods and failing Deployment conditions make a workload unhealthy (#27)
  test_itbench.py            - ITBench import: pulls, not-recorded kinds, events at the pull, log attribution, Scenario-33 regression
  test_hooks.py              - pinned_clock and use_api_client: one clock, every reader through the supplied client, restored (#30)
  test_not_recorded.py       - What a capture didn't record replays as not recorded: missing kinds, unrecorded logs, composites (#30)
  test_placement.py          - Composites' placement: nodeSelector/required affinity/tolerations against the nodes (#29)
  test_hpa.py                - get_hpa_summaries: metrics, conditions, at-max note, replay, composites
  test_endpoints.py          - get_endpoint_summaries and ServiceSummary endpoint counts
  test_metrics.py            - get_container_metrics / get_node_metrics: units, notes, the three replay cases
  test_ingress.py            - get_ingress_summaries: backend resolution, readiness, TLS by name
  test_spec_resources.py     - Requests/limits from the pod spec when the status has none (pre-1.33, ITBench), live and replay (#32)
  test_networkpolicy.py      - get_networkpolicy_summaries: stated effects by the API's rules, selected pods, composites, replay (#31)
  test_forbidden.py          - A 403 is K8sForbidden; capture records an unreadable kind and carries on; replay and composites say so (#33)
  test_log_search.py         - get_log_pattern_summary, grep before tail, where a log starts: live, capture and replay (#34); the capture's byte cap (#36)
  test_report_logs.py        - The workload report reads every pod's log; a cut line keeps its match; lines_from/log_starts (#35)
  test_custom_resources.py   - CRDs and custom-resource conditions; per-type permissions in capture
  test_log_decoding.py       - Log decoding at the API boundary (bytes vs str), `previous` plumbing, log redaction
  test_mcp_client.py         - MCP client tests
  test_mcp_errors.py         - Anticipated failures reach MCP clients with their reason; crashes stay generic; one-line API errors
  test_version.py            - Asserts pyproject and package __version__ agree