k8stools 4.2.0__tar.gz → 4.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. {k8stools-4.2.0 → k8stools-4.4.0}/CHANGELOG.md +134 -0
  2. {k8stools-4.2.0 → k8stools-4.4.0}/CLAUDE.md +50 -0
  3. {k8stools-4.2.0 → k8stools-4.4.0}/PKG-INFO +72 -5
  4. {k8stools-4.2.0 → k8stools-4.4.0}/README.md +71 -4
  5. {k8stools-4.2.0 → k8stools-4.4.0}/docs/TOOL_REFERENCE.md +62 -5
  6. {k8stools-4.2.0 → k8stools-4.4.0}/pyproject.toml +1 -1
  7. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/__init__.py +1 -1
  8. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/capture.py +61 -1
  9. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/composites.py +277 -33
  10. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/fixtures/otel-demo.json +1 -0
  11. k8stools-4.4.0/src/k8stools/itbench.py +560 -0
  12. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/k8s_tools.py +366 -30
  13. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/mock_state.py +73 -18
  14. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/mock_tools.py +7 -0
  15. k8stools-4.4.0/tests/fixtures/itbench-33-excerpt/k8s_events_raw.tsv +73 -0
  16. k8stools-4.4.0/tests/fixtures/itbench-33-excerpt/k8s_objects_raw.tsv +79 -0
  17. k8stools-4.4.0/tests/fixtures/itbench-33-excerpt/otel_logs_raw.tsv +61 -0
  18. k8stools-4.4.0/tests/fixtures/make_itbench_excerpt.py +97 -0
  19. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_capture.py +1 -0
  20. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_composites.py +2 -1
  21. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_custom_resources.py +3 -2
  22. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_endpoints.py +3 -2
  23. k8stools-4.4.0/tests/test_hooks.py +135 -0
  24. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_hpa.py +3 -2
  25. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_ingress.py +2 -1
  26. k8stools-4.4.0/tests/test_itbench.py +350 -0
  27. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_live_writes.py +6 -0
  28. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_metrics.py +1 -1
  29. k8stools-4.4.0/tests/test_networkpolicy.py +285 -0
  30. k8stools-4.4.0/tests/test_not_recorded.py +172 -0
  31. k8stools-4.4.0/tests/test_placement.py +195 -0
  32. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_workloads.py +3 -2
  33. {k8stools-4.2.0 → k8stools-4.4.0}/uv.lock +1 -1
  34. {k8stools-4.2.0 → k8stools-4.4.0}/.claude/settings.local.json +0 -0
  35. {k8stools-4.2.0 → k8stools-4.4.0}/.github/workflows/unit-tests.yml +0 -0
  36. {k8stools-4.2.0 → k8stools-4.4.0}/.gitignore +0 -0
  37. {k8stools-4.2.0 → k8stools-4.4.0}/.python-version +0 -0
  38. {k8stools-4.2.0 → k8stools-4.4.0}/.vscode/mcp.json +0 -0
  39. {k8stools-4.2.0 → k8stools-4.4.0}/.vscode/settings.json +0 -0
  40. {k8stools-4.2.0 → k8stools-4.4.0}/LICENSE +0 -0
  41. {k8stools-4.2.0 → k8stools-4.4.0}/chat-with-cluster.png +0 -0
  42. {k8stools-4.2.0 → k8stools-4.4.0}/designs/mock-state-capture.md +0 -0
  43. {k8stools-4.2.0 → k8stools-4.4.0}/docs/ROADMAP.md +0 -0
  44. {k8stools-4.2.0 → k8stools-4.4.0}/envrc.template +0 -0
  45. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/mcp_client.py +0 -0
  46. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/mcp_server.py +0 -0
  47. {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/redaction.py +0 -0
  48. {k8stools-4.2.0 → k8stools-4.4.0}/tests/conftest.py +0 -0
  49. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_builtin_fixture.py +0 -0
  50. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_cluster_binding.py +0 -0
  51. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_duration_format.py +0 -0
  52. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_events.py +0 -0
  53. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_init_containers.py +0 -0
  54. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_k8s_tools.py +0 -0
  55. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_k8s_tools_realk8s.py +0 -0
  56. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_log_decoding.py +0 -0
  57. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_mcp_client.py +0 -0
  58. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_mcp_errors.py +0 -0
  59. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_mock_state.py +0 -0
  60. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_mock_tools.py +0 -0
  61. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_new_tools.py +0 -0
  62. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_node_conditions.py +0 -0
  63. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_notes.py +0 -0
  64. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_redaction.py +0 -0
  65. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_replicaset_tool.py +0 -0
  66. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_stuck_rollouts.py +0 -0
  67. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_toolsets.py +0 -0
  68. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_version.py +0 -0
  69. {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_workload_history.py +0 -0
@@ -3,6 +3,140 @@
3
3
  All notable changes to k8stools. Versions follow [semantic versioning](https://semver.org/);
4
4
  dates are release-tag dates.
5
5
 
6
+ ## 4.4.0 — 2026-10-28
7
+
8
+ ### Issues fixed
9
+ - [#30](https://github.com/BenedatLLC/k8stools/issues/30): Import path: an
10
+ ITBench-Lite snapshot to a capture, at a chosen pull.
11
+ - [#31](https://github.com/BenedatLLC/k8stools/issues/31): A NetworkPolicy tool
12
+ that states what each policy allows.
13
+
14
+ ### Added
15
+ - **`get_networkpolicy_summaries(namespace)`**: each NetworkPolicy's pod
16
+ selector and the pods it selects, its rules, and what it allows per
17
+ direction in plain words ("allows all ingress", "denies all egress",
18
+ "allows ingress only from pods with app=web in this namespace on TCP
19
+ 8080"), by the API's rules rather than the policy's name: ITBench-Lite
20
+ Scenario-31's `frontend-block-all-ports` allows everything. Default
21
+ `policyTypes`, `[{}]` against `[{podSelector: {}}]`, and one peer with two
22
+ selectors (both) against two peers (either) are each stated distinctly;
23
+ notes say when a selector matches no pod and when no egress rule allows
24
+ DNS. In the `investigate` toolset. Captured and replayed; a capture without
25
+ them says they're not recorded. **Needs `list` on
26
+ `networking.k8s.io/networkpolicies`** (added to the README's ClusterRole);
27
+ without it the composites say so and carry on.
28
+ - `get_workload_report` gains `network_policies`: the policies selecting the
29
+ workload's pods, combined per direction ("ingress: allows all ingress
30
+ (NetworkPolicy/frontend-block-all-ports)"), or "no NetworkPolicy
31
+ (networking.k8s.io) selects these pods", with policy kinds installed as
32
+ custom resources (Cilium, Calico, AdminNetworkPolicy) named in a note.
33
+ `get_namespace_health` gains `network_policies`, one line per policy.
34
+ - **`k8s-capture-state --from-itbench DIR [--at PULL]`** imports one pull of an
35
+ ITBench-Lite scenario directory (default: the last) as a capture, and
36
+ `--list-pulls` lists them with the kinds each has. The pull is served to the
37
+ real tools and capture code (`k8stools.itbench`), so it replays under the
38
+ same rules as a live capture, and what the snapshot doesn't hold is not
39
+ recorded: kinds a pull has no batch of, HPAs, CronJobs, StatefulSet and
40
+ DaemonSet revisions, previous-instance logs, and the logs of containers with
41
+ no records. Metrics and custom resource instances say ITBench didn't collect
42
+ them. Logs are the services' OpenTelemetry records, each line with its
43
+ time, severity, body (templates filled in) and attributes, and every
44
+ replayed log says in a note that they aren't the container's output. Events
45
+ are those that existed at the pull; Endpoints are served as EndpointSlices.
46
+ All 11 scenarios at hand import (7-18 s each); Scenario-33's matches k8srca's
47
+ earlier conversion on everything that had, and adds owners, the scheduler's
48
+ reasons, Deployment conditions, endpoints and the template change that
49
+ caused it.
50
+ - `K8sNotRecorded`, a `K8sApiError` raised only on replay, when the capture
51
+ doesn't record what was asked for. Like any `K8sApiError`, an MCP client
52
+ receives its message.
53
+ - `k8s_tools.pinned_clock(at)`: every tool computes ages as of `at` within the
54
+ block. Every age the tools compute now reads one clock (`_now()`).
55
+ - `k8s_tools.use_api_client(api_client, context=, server=)`: bind every tool to
56
+ an `ApiClient` of your own within the block, then restore the binding. All
57
+ API groups, the metrics and custom-resource readers and `get_cluster_info`
58
+ (which reports `source: "supplied"`) go through it, so a converter can serve
59
+ a recorded snapshot to the real tools and capture by giving the client a
60
+ `rest_client` that answers from it.
61
+
62
+ ### Changed
63
+ - **A kind a capture has no list of is now "not recorded" on replay, not
64
+ none.** Its tool raises `K8sNotRecorded`, saying the kind is unknown rather
65
+ than absent; it used to return `[]`, telling the agent none existed. This
66
+ covers namespaces, nodes, pods, Deployments, ReplicaSets, Services,
67
+ endpoints, Ingresses, ConfigMaps, StatefulSets, DaemonSets, HPAs, CronJobs,
68
+ Jobs, PVCs and events (`get_configmap` too), and custom resource definitions
69
+ in a capture made before 3.0.0. `get_namespace_health` and
70
+ `get_workload_report` don't fail: they name those kinds in one note, "Not
71
+ recorded in this capture, so unknown rather than absent: ...", and use
72
+ nothing from them. A report asked for a workload of a kind that wasn't
73
+ recorded raises `K8sNotRecorded`.
74
+ - **A container log a capture didn't record is now "not recorded", not
75
+ empty.** `get_logs_for_pod_and_container` raised nothing and returned `''`
76
+ for a container missing from the pod's logs (unreadable when captured, or
77
+ `--no-logs`); it now raises `K8sNotRecorded`, and in `get_workload_report`
78
+ that tail has `available: false` with the reason. A log recorded as an empty
79
+ string still replays as empty. With `previous=True`, a container that
80
+ restarted but whose previous log wasn't captured is "not recorded"; one that
81
+ never restarted is "not found", as live. A container the pod doesn't have
82
+ is an error, as live, rather than an empty log.
83
+ - In k8srca's captures this changes (the rest replay as before):
84
+ - `itbench-33-invalid-node-selector` and `jvm-oom-on-startup`: DaemonSets,
85
+ HPAs, endpoints and Ingresses read "not recorded", in the composites' note
86
+ and from their own tools. Neither has custom resources, now "not
87
+ recorded" rather than none. Scenario-33 also has no workload histories
88
+ (rebuilt from its ReplicaSets with a note, as before), and neither has
89
+ metrics ("predates resource metrics", as before).
90
+ - `image-pull-typo`: `email-754859f94c-4x46m`'s `email` log is not recorded
91
+ (the capture has no entry for it), so it is "not recorded", not empty.
92
+ - In seven of them (all but `checkout-gc-pressure`, `itbench-33` and
93
+ `jvm-oom-on-startup`), completed init containers that restarted (e.g.
94
+ `accounting-...-9pczq/wait-for-kafka`, 16 restarts) have no captured
95
+ previous log, by design: `previous=True` on them reads "not recorded",
96
+ not "not found".
97
+ - Scenario-33's 8 containers stored as `''` still replay as empty; only
98
+ re-importing changes them.
99
+ - **A container that never started has no start time.** One that failed with
100
+ `StartError` (the runtime couldn't run it) reports its start as Go's zero
101
+ time, 1970-01-01, which `ContainerStateTerminated` took literally:
102
+ `ran_for` was 55 years, and `get_workload_report` gave that as the instance's
103
+ lifetime. `started_at` and `ran_for` are now None for it. (Found in
104
+ ITBench-Lite Scenario-105, a CrashLoopBackOff on an invalid command.)
105
+ - **A capture's ages are as of its `captured_at`.** `k8s-capture-state` pins
106
+ the clock for the whole capture, so an object read a minute in is no longer
107
+ aged a minute more than the file's timestamp says (replay shifted it by that
108
+ much). `captured_at` is now whole seconds.
109
+
110
+ ## 4.3.0 — 2026-10-24
111
+
112
+ ### Issues fixed
113
+ - [#29](https://github.com/BenedatLLC/k8stools/issues/29): Composites: say how
114
+ many nodes an unscheduled pod's nodeSelector and required affinity admit.
115
+
116
+ ### Added
117
+ - `WorkloadHealth.placement` and `WorkloadReport.placement`: for each pod with
118
+ no node, how many nodes its nodeSelector and required node affinity admit,
119
+ out of all nodes, and how many of those have a NoSchedule or NoExecute taint
120
+ it doesn't tolerate, e.g. "ad-x: 0 of 5 nodes match its nodeSelector and
121
+ required node affinity". The scheduler's FailedScheduling message names only
122
+ the first filter that rejected each node, so a node it reports as tainted
123
+ may not match the selector either; answering that took `get_pod_spec` and
124
+ `get_node_summaries` together. The count is k8stools' own evaluation, and a
125
+ note says so. The composites read the nodes once per call, only when some
126
+ pod is unscheduled; when the nodes can't be read (a namespace-scoped role),
127
+ the line says "not evaluated" and why. Replays compute it from the
128
+ captured node labels and pod specs, so existing captures have it.
129
+
130
+ ### Changed
131
+ - `get_namespace_health` and `get_workload_report` on the `--mock` fixture
132
+ have a `placement` line for each of the two unscheduled pods (`checkout`,
133
+ `quote`), and the namespace view a note. Tests that pin the mock's output
134
+ will see them.
135
+
136
+ ### Fixed
137
+ - `get_pod_spec`'s error for a failure other than 404 carried the client
138
+ exception's whole text (headers and raw JSON) instead of its one sentence.
139
+
6
140
  ## 4.2.0 — 2026-10-24
7
141
 
8
142
  ### Issues fixed
@@ -10,6 +10,7 @@ src/k8stools/
10
10
  composites.py - Logic of the composite tools (get_namespace_health, get_workload_report)
11
11
  mock_state.py - MockState: loads a capture file and serves it to the tool queries
12
12
  capture.py - `k8s-capture-state` CLI: snapshots a live cluster to a capture file
13
+ itbench.py - `--from-itbench`: serves one pull of an ITBench-Lite snapshot to capture_state
13
14
  mock_tools.py - Mock versions of all tools; thin delegates to MockState
14
15
  redaction.py - Secret-redaction pass applied at the MCP server output boundary
15
16
  mcp_server.py - MCP server (stdio or streamable-http transport)
@@ -17,6 +18,7 @@ src/k8stools/
17
18
  fixtures/
18
19
  otel-demo.json - Built-in capture served by `--mock` (hand-maintained, modeled on Minikube + OTel Demo)
19
20
  tests/
21
+ fixtures/itbench-33-excerpt/ - Trimmed ITBench-Lite Scenario-33 (two pulls); made by fixtures/make_itbench_excerpt.py
20
22
  test_k8s_tools.py - Unit tests for the original tools (mocked K8s API)
21
23
  test_new_tools.py - Unit tests for the 1.1.0 tools (ConfigMaps, CronJobs/Jobs, PVCs, StatefulSets, events, log enhancements)
22
24
  test_replicaset_tool.py - Unit tests for get_replicaset_summaries (1.2.0), incl. mock-data consistency
@@ -37,10 +39,15 @@ tests/
37
39
  test_composites.py - get_namespace_health / get_workload_report: semantics, grouping, bounds
38
40
  test_init_containers.py - Init containers and native sidecars: the pod model, composites, capture, older captures
39
41
  test_stuck_rollouts.py - Unscheduled pods and failing Deployment conditions make a workload unhealthy (#27)
42
+ test_itbench.py - ITBench import: pulls, not-recorded kinds, events at the pull, log attribution, Scenario-33 regression
43
+ test_hooks.py - pinned_clock and use_api_client: one clock, every reader through the supplied client, restored (#30)
44
+ test_not_recorded.py - What a capture didn't record replays as not recorded: missing kinds, unrecorded logs, composites (#30)
45
+ test_placement.py - Composites' placement: nodeSelector/required affinity/tolerations against the nodes (#29)
40
46
  test_hpa.py - get_hpa_summaries: metrics, conditions, at-max note, replay, composites
41
47
  test_endpoints.py - get_endpoint_summaries and ServiceSummary endpoint counts
42
48
  test_metrics.py - get_container_metrics / get_node_metrics: units, notes, the three replay cases
43
49
  test_ingress.py - get_ingress_summaries: backend resolution, readiness, TLS by name
50
+ test_networkpolicy.py - get_networkpolicy_summaries: stated effects by the API's rules, selected pods, composites, replay (#31)
44
51
  test_custom_resources.py - CRDs and custom-resource conditions; per-type permissions in capture
45
52
  test_log_decoding.py - Log decoding at the API boundary (bytes vs str), `previous` plumbing, log redaction
46
53
  test_mcp_client.py - MCP client tests
@@ -200,6 +207,14 @@ otherwise assembles from five or six. Rules that keep them trustworthy:
200
207
  The unbound claims an unscheduled pod mounts go in `claims`, with the claim's
201
208
  newest event: the scheduler's "unbound immediate PersistentVolumeClaims" says
202
209
  nothing of why. Claims are read only when some pod is unscheduled.
210
+ - **Count the nodes a pod's constraints admit** (#29): the scheduler's message
211
+ names only each node's first failing filter, so a cited taint may be on a node
212
+ the selector rejects too. `placement` counts, per unscheduled pod, the nodes
213
+ its nodeSelector and required node affinity admit and how many of those have
214
+ an untolerated NoSchedule/NoExecute taint, by the API's matching rules
215
+ (`NOTE_PLACEMENT` says it's k8stools' evaluation). Nodes are read once, only
216
+ when some pod is unscheduled; unreadable nodes or spec say "not evaluated",
217
+ never drop the line.
203
218
  - **Init containers apart** (#24): a completed init container (exit 0) is never
204
219
  a termination; one that hasn't completed makes the workload unhealthy and is
205
220
  named. `WorkloadReport.init_containers` is always serialized (`_keep_empty`), so
@@ -207,6 +222,15 @@ otherwise assembles from five or six. Rules that keep them trustworthy:
207
222
  - **Bounded:** healthy workloads are a one-line string each; compact models
208
223
  (`_Compact` drops empty fields; the server sends a result twice), at most 20 events and 100 log lines of 300 characters; tests
209
224
  hold the namespace view and reports to budgets on the `--mock` fixture.
225
+ - **A NetworkPolicy is what its rules allow, not what it's called** (#31):
226
+ ITBench's `frontend-block-all-ports` is `ingress: [{}]`, allow-all. Effects
227
+ are derived from the stored rules (`network_policy_effect`, `DERIVED_FIELDS`),
228
+ so a fix reaches old captures; selected pods are stored, matched at capture.
229
+ Keep `[{}]` vs `[{podSelector: {}}]` and one peer with two selectors (both)
230
+ vs two peers (either) worded apart. A workload's policies combine as a union
231
+ per direction. Unrecorded or unreadable policies give no line, never "no
232
+ NetworkPolicy selects these pods"; a role without the permission must not
233
+ fail the report.
210
234
  - New data sources (HPA, endpoints, metrics: #14-#16) extend `WorkloadHealth`
211
235
  and `WorkloadReport` with fields, rather than adding tools to `triage`.
212
236
 
@@ -290,6 +314,14 @@ or lazily on first use. Invariants:
290
314
  The kubernetes client reads `KUBECONFIG` once, at import
291
315
  (`KUBE_CONFIG_DEFAULT_LOCATION`), so setting it at runtime has no effect.
292
316
 
317
+ **Two hooks** let a converter run the real tools against a recorded snapshot
318
+ (#30): `use_api_client(api_client, ...)` swaps the binding (and clears the group
319
+ clients) for a block and restores both; `pinned_clock(at)` sets what `_now()`
320
+ returns. Read the time only through `_now()`, never `datetime.now()`, and build
321
+ any new client from `_binding().api_client`, or an import reads the wrong time or
322
+ reaches a real cluster. `capture_state` pins the clock to its `captured_at` for
323
+ the whole capture.
324
+
293
325
  `get_cluster_info` reports the binding. Its replay counterpart answers from the
294
326
  capture's optional top-level `cluster` record (context, server, server version —
295
327
  never the kubeconfig path) with `source="capture"`.
@@ -382,6 +414,24 @@ Invariants worth preserving when touching this code:
382
414
  `Interval`. Three cases stay distinct and all raise `K8sMetricsUnavailable`
383
415
  with different messages: recorded unavailable (as live), and no `metrics` key
384
416
  (the capture predates them). Never fill in a missing reading.
417
+ - **Not recorded is not none** (#30). A top-level list the capture lacks
418
+ (`_RECORDED_KINDS`) makes its replay tool raise `K8sNotRecorded`, never
419
+ return `[]`: an older capture with no `endpoints` said no Service had a
420
+ backend. The same for a container missing from `logs`, and from
421
+ `previous_logs` when it restarted; a recorded `''` stays empty. One rule for
422
+ every capture, live or imported. The composites read such kinds through
423
+ `_recorded` and name them in one note. Live tools never raise it.
424
+ - **An ITBench import runs the real capture** (#30): `itbench.SnapshotRest`
425
+ answers the API from one pull, under `use_api_client` and `pinned_clock`, and
426
+ `import_snapshot` then removes what the snapshot didn't record and states
427
+ what it never collected, rather than teaching `capture_state` about it. A
428
+ pull lists nothing for a kind with no objects, so a kind missing from the
429
+ pull is not recorded, never none. Logs are OTel SDK records: no container
430
+ name (attribute only to a pod's sole container or one named like the
431
+ service), a `container.id` that matches no container (don't use it), and
432
+ only the current instance's (by start time); replay notes their source
433
+ (`source.logs == "otel"`, `NOTE_LOGS_FROM_OTEL`). Previous-instance logs are
434
+ never imported.
385
435
  - **A pod not in the capture does not exist** for any tool. `mock_tools` no longer
386
436
  synthesizes answers for unknown pod names, and `get_pod_container_statuses`
387
437
  raises for one, as live.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: k8stools
3
- Version: 4.2.0
3
+ Version: 4.4.0
4
4
  Summary: Tools and an MCP server for building Kubernetes agents
5
5
  Project-URL: Homepage, https://github.com/BenedatLLC/k8stools
6
6
  Project-URL: Changelog, https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md
@@ -417,6 +417,7 @@ out-of-memory kill".
417
417
  | `get_service_summaries` | Services, like `kubectl get services`, with selector, labels, annotations, and ready / not-ready endpoint counts | | ✓ |
418
418
  | `get_endpoint_summaries` | Each Service's backends, from its EndpointSlices: every address's ready / serving / terminating state, pod and node | | ✓ |
419
419
  | `get_ingress_summaries` | Ingresses, like `kubectl get ingress` plus `describe`: each host/path rule with its backend Service and port resolved (flagged when the Service or port doesn't exist), TLS hosts and Secret names, load-balancer addresses | | ✓ |
420
+ | `get_networkpolicy_summaries` | NetworkPolicies: the pods each selects, its rules, and what it allows per direction in plain words ("allows all ingress", "denies all egress", "allows ingress only from ..."), by the API's rules rather than the policy's name | | ✓ |
420
421
 
421
422
  ### Configuration and storage
422
423
 
@@ -629,7 +630,7 @@ rules:
629
630
  resources: [pods, nodes]
630
631
  verbs: [get, list]
631
632
  - apiGroups: [networking.k8s.io]
632
- resources: [ingresses]
633
+ resources: [ingresses, networkpolicies]
633
634
  verbs: [get, list]
634
635
  - apiGroups: [apiextensions.k8s.io]
635
636
  resources: [customresourcedefinitions]
@@ -725,6 +726,17 @@ k8s_tools.configure(kubeconfig="~/.kube/prod.yaml", context="prod-eu")
725
726
 
726
727
  The selection is resolved as described in [Selecting a cluster](#selecting-a-cluster).
727
728
 
729
+ To answer from something that isn't a cluster (a converter serving a recorded
730
+ snapshot, say), bind an `ApiClient` whose `rest_client` answers the requests, and
731
+ pin the clock to the snapshot's time. Both apply to every tool and to
732
+ `capture_state`, and are restored at the end of the block:
733
+
734
+ ```python
735
+ with k8s_tools.use_api_client(api, context="snapshot-33"), \
736
+ k8s_tools.pinned_clock(snapshot_time):
737
+ state = capture_state()
738
+ ```
739
+
728
740
  ### Choosing tools in Python
729
741
 
730
742
  `TOOLS` is every tool. The toolsets are in `TOOLSETS`, and `select_tools` builds an
@@ -814,6 +826,7 @@ usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE]
814
826
  [--kubeconfig PATH] [--context NAME] [--no-logs]
815
827
  [--max-log-lines MAX_LOG_LINES] [--no-previous-logs]
816
828
  [--no-redact] [--redact-file FILE]
829
+ [--from-itbench DIR] [--at PULL] [--list-pulls]
817
830
  [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
818
831
 
819
832
  Snapshot a Kubernetes cluster to a JSON file replayable by the k8stools MCP
@@ -849,6 +862,14 @@ options:
849
862
  its compression). Use on captures taken with --no-
850
863
  redact, or before a newer k8stools added redaction
851
864
  rules.
865
+ --from-itbench DIR Instead of capturing, import an ITBench-Lite snapshot
866
+ (a scenario directory with k8s_objects_raw.tsv) as of
867
+ one of its pulls. What it doesn't record replays as
868
+ "not recorded".
869
+ --at PULL With --from-itbench: the pull to import, numbered from
870
+ 1 [default: the last]. --list-pulls shows them.
871
+ --list-pulls With --from-itbench: list the snapshot's pulls and
872
+ exit
852
873
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
853
874
  Log level [default: INFO]
854
875
  ```
@@ -881,9 +902,55 @@ lines was 3.3 MB). Use `--max-log-lines` to trade size against history, or
881
902
  written and read gzipped; see [Compression, and what to check
882
903
  in](#compression-and-what-to-check-in).
883
904
 
884
- Captures made by older versions of k8stools still load. Data they don't have
885
- replays as empty, as unknown (`None`, never 0), or as an error saying the capture
886
- predates it.
905
+ Captures made by older versions of k8stools still load. **What a capture didn't
906
+ record replays as not recorded, never as none**, whether the capture predates it
907
+ or didn't collect it:
908
+
909
+ - A kind the capture has no list of (an older capture has no `endpoints`, say)
910
+ makes its tool raise `K8sNotRecorded`, an error saying the kind is unknown
911
+ rather than absent. `get_namespace_health` and `get_workload_report` name such
912
+ kinds in one note instead of failing.
913
+ - A container log that wasn't recorded (unreadable when captured, or
914
+ `--no-logs`) raises `K8sNotRecorded` too, and so does a previous-instance log
915
+ of a container that restarted, when its previous log wasn't captured. A
916
+ container that never restarted has no previous instance, and says so, as
917
+ live. A log recorded as empty is replayed as empty.
918
+ - A field the capture predates is unknown (`None`, never 0).
919
+
920
+ ### Importing an ITBench-Lite snapshot
921
+
922
+ An [ITBench-Lite](https://huggingface.co/datasets/ibm-research/ITBench-Lite) scenario
923
+ directory holds what an OpenTelemetry collector exported during the incident:
924
+ Kubernetes objects pulled every five minutes (`k8s_objects_raw.tsv`), the event
925
+ stream (`k8s_events_raw.tsv`) and the services' OTel log records
926
+ (`otel_logs_raw.tsv`). `--from-itbench` turns one pull of it into a capture:
927
+
928
+ ```bash
929
+ k8s-capture-state --from-itbench Scenario-33 --list-pulls # numbered, with their kinds
930
+ k8s-capture-state --from-itbench Scenario-33 --at 7 -o s33.json # default: the last pull
931
+ k8s-mcp-server --state-file s33.json --state-time frozen
932
+ ```
933
+
934
+ The importer serves the pull to the real tools, with the clock set to the pull's
935
+ time, and runs the same capture code against it, so an imported capture replays
936
+ under the same rules as any other. What the snapshot doesn't hold replays as not
937
+ recorded:
938
+
939
+ - **Kinds the pull has no batch of.** A pull writes nothing for a kind with no
940
+ objects, so a missing kind may be none or a lost batch; `--list-pulls` and the
941
+ import's report name them. HPAs, CronJobs and ControllerRevisions are never
942
+ pulled, so StatefulSet and DaemonSet revisions are unknown (Deployment history
943
+ comes from the ReplicaSets).
944
+ - **Logs are OpenTelemetry records, not container output.** Every replayed log
945
+ says so in a note: a stack trace a process printed to stderr isn't in them.
946
+ Records carry no container name: a record goes to its pod's only container, or
947
+ the container named like its service, or none (counted). Only the current
948
+ instance's records are kept (those since it started). A container with no
949
+ records at all is not recorded, and previous-instance logs never are.
950
+ - **Metrics and custom resource instances** were never collected, and say so.
951
+ - Events are those that existed at the pull (each recorded twice in the
952
+ snapshot, kept once). Endpoints are the core `Endpoints` objects, served as
953
+ EndpointSlices.
887
954
 
888
955
  ### Compression, and what to check in
889
956
 
@@ -196,6 +196,7 @@ out-of-memory kill".
196
196
  | `get_service_summaries` | Services, like `kubectl get services`, with selector, labels, annotations, and ready / not-ready endpoint counts | | ✓ |
197
197
  | `get_endpoint_summaries` | Each Service's backends, from its EndpointSlices: every address's ready / serving / terminating state, pod and node | | ✓ |
198
198
  | `get_ingress_summaries` | Ingresses, like `kubectl get ingress` plus `describe`: each host/path rule with its backend Service and port resolved (flagged when the Service or port doesn't exist), TLS hosts and Secret names, load-balancer addresses | | ✓ |
199
+ | `get_networkpolicy_summaries` | NetworkPolicies: the pods each selects, its rules, and what it allows per direction in plain words ("allows all ingress", "denies all egress", "allows ingress only from ..."), by the API's rules rather than the policy's name | | ✓ |
199
200
 
200
201
  ### Configuration and storage
201
202
 
@@ -408,7 +409,7 @@ rules:
408
409
  resources: [pods, nodes]
409
410
  verbs: [get, list]
410
411
  - apiGroups: [networking.k8s.io]
411
- resources: [ingresses]
412
+ resources: [ingresses, networkpolicies]
412
413
  verbs: [get, list]
413
414
  - apiGroups: [apiextensions.k8s.io]
414
415
  resources: [customresourcedefinitions]
@@ -504,6 +505,17 @@ k8s_tools.configure(kubeconfig="~/.kube/prod.yaml", context="prod-eu")
504
505
 
505
506
  The selection is resolved as described in [Selecting a cluster](#selecting-a-cluster).
506
507
 
508
+ To answer from something that isn't a cluster (a converter serving a recorded
509
+ snapshot, say), bind an `ApiClient` whose `rest_client` answers the requests, and
510
+ pin the clock to the snapshot's time. Both apply to every tool and to
511
+ `capture_state`, and are restored at the end of the block:
512
+
513
+ ```python
514
+ with k8s_tools.use_api_client(api, context="snapshot-33"), \
515
+ k8s_tools.pinned_clock(snapshot_time):
516
+ state = capture_state()
517
+ ```
518
+
507
519
  ### Choosing tools in Python
508
520
 
509
521
  `TOOLS` is every tool. The toolsets are in `TOOLSETS`, and `select_tools` builds an
@@ -593,6 +605,7 @@ usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE]
593
605
  [--kubeconfig PATH] [--context NAME] [--no-logs]
594
606
  [--max-log-lines MAX_LOG_LINES] [--no-previous-logs]
595
607
  [--no-redact] [--redact-file FILE]
608
+ [--from-itbench DIR] [--at PULL] [--list-pulls]
596
609
  [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
597
610
 
598
611
  Snapshot a Kubernetes cluster to a JSON file replayable by the k8stools MCP
@@ -628,6 +641,14 @@ options:
628
641
  its compression). Use on captures taken with --no-
629
642
  redact, or before a newer k8stools added redaction
630
643
  rules.
644
+ --from-itbench DIR Instead of capturing, import an ITBench-Lite snapshot
645
+ (a scenario directory with k8s_objects_raw.tsv) as of
646
+ one of its pulls. What it doesn't record replays as
647
+ "not recorded".
648
+ --at PULL With --from-itbench: the pull to import, numbered from
649
+ 1 [default: the last]. --list-pulls shows them.
650
+ --list-pulls With --from-itbench: list the snapshot's pulls and
651
+ exit
631
652
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
632
653
  Log level [default: INFO]
633
654
  ```
@@ -660,9 +681,55 @@ lines was 3.3 MB). Use `--max-log-lines` to trade size against history, or
660
681
  written and read gzipped; see [Compression, and what to check
661
682
  in](#compression-and-what-to-check-in).
662
683
 
663
- Captures made by older versions of k8stools still load. Data they don't have
664
- replays as empty, as unknown (`None`, never 0), or as an error saying the capture
665
- predates it.
684
+ Captures made by older versions of k8stools still load. **What a capture didn't
685
+ record replays as not recorded, never as none**, whether the capture predates it
686
+ or didn't collect it:
687
+
688
+ - A kind the capture has no list of (an older capture has no `endpoints`, say)
689
+ makes its tool raise `K8sNotRecorded`, an error saying the kind is unknown
690
+ rather than absent. `get_namespace_health` and `get_workload_report` name such
691
+ kinds in one note instead of failing.
692
+ - A container log that wasn't recorded (unreadable when captured, or
693
+ `--no-logs`) raises `K8sNotRecorded` too, and so does a previous-instance log
694
+ of a container that restarted, when its previous log wasn't captured. A
695
+ container that never restarted has no previous instance, and says so, as
696
+ live. A log recorded as empty is replayed as empty.
697
+ - A field the capture predates is unknown (`None`, never 0).
698
+
699
+ ### Importing an ITBench-Lite snapshot
700
+
701
+ An [ITBench-Lite](https://huggingface.co/datasets/ibm-research/ITBench-Lite) scenario
702
+ directory holds what an OpenTelemetry collector exported during the incident:
703
+ Kubernetes objects pulled every five minutes (`k8s_objects_raw.tsv`), the event
704
+ stream (`k8s_events_raw.tsv`) and the services' OTel log records
705
+ (`otel_logs_raw.tsv`). `--from-itbench` turns one pull of it into a capture:
706
+
707
+ ```bash
708
+ k8s-capture-state --from-itbench Scenario-33 --list-pulls # numbered, with their kinds
709
+ k8s-capture-state --from-itbench Scenario-33 --at 7 -o s33.json # default: the last pull
710
+ k8s-mcp-server --state-file s33.json --state-time frozen
711
+ ```
712
+
713
+ The importer serves the pull to the real tools, with the clock set to the pull's
714
+ time, and runs the same capture code against it, so an imported capture replays
715
+ under the same rules as any other. What the snapshot doesn't hold replays as not
716
+ recorded:
717
+
718
+ - **Kinds the pull has no batch of.** A pull writes nothing for a kind with no
719
+ objects, so a missing kind may be none or a lost batch; `--list-pulls` and the
720
+ import's report name them. HPAs, CronJobs and ControllerRevisions are never
721
+ pulled, so StatefulSet and DaemonSet revisions are unknown (Deployment history
722
+ comes from the ReplicaSets).
723
+ - **Logs are OpenTelemetry records, not container output.** Every replayed log
724
+ says so in a note: a stack trace a process printed to stderr isn't in them.
725
+ Records carry no container name: a record goes to its pod's only container, or
726
+ the container named like its service, or none (counted). Only the current
727
+ instance's records are kept (those since it started). A container with no
728
+ records at all is not recorded, and previous-instance logs never are.
729
+ - **Metrics and custom resource instances** were never collected, and say so.
730
+ - Events are those that existed at the pull (each recorded twice in the
731
+ snapshot, kept once). Endpoints are the core `Endpoints` objects, served as
732
+ EndpointSlices.
666
733
 
667
734
  ### Compression, and what to check in
668
735
 
@@ -29,6 +29,8 @@ notes existed) give the same notes; captures don't store them.
29
29
  | `EndpointSummary` | no ready endpoints | No ready endpoints: traffic sent to this Service has no pod to reach. |
30
30
  | `IngressSummary` | a backend doesn't resolve | A backend doesn't resolve: see the rule's backend_problem. Requests matching that rule can't reach a pod. |
31
31
  | `IngressSummary` | a backend Service has no ready endpoints | A backend Service has no ready endpoints (backend_ready 0): requests matching that rule can't reach a pod. |
32
+ | `NetworkPolicySummary` | its selector matches no pod | Its pod selector matches no pod in the namespace now. It applies to any pod created later with matching labels. |
33
+ | `NetworkPolicySummary` | it restricts egress and no rule allows port 53 (a named port could be 53, so one of those doesn't count) | No egress rule here allows port 53 (DNS). Unless another policy selecting the same pods allows it, they can't look up names. |
32
34
  | `CustomResourceStatus` | `observed_generation` < `generation` | observed_generation < generation: its controller hasn't yet acted on the latest spec change, so the conditions may describe the previous spec. |
33
35
  | `CustomResourceStatus` | no conditions | No status.conditions: this resource reports its state some other way, which this tool doesn't read. |
34
36
  | `ContainerUsage` | no reading | No reading: the container isn't running, or started within about one metrics-server scrape interval. |
@@ -95,7 +97,7 @@ shared by every tool, so all tools answer from this cluster.
95
97
  ClusterInfo
96
98
  An object with the following fields:
97
99
 
98
- - **`source`** (`str`): "kubeconfig" (bound through a kubeconfig context), "in-cluster" (the service account of the pod the server runs in), or "capture" (a recorded snapshot of a cluster being replayed, not a live cluster).
100
+ - **`source`** (`str`): "kubeconfig" (bound through a kubeconfig context), "in-cluster" (the service account of the pod the server runs in), "capture" (a recorded snapshot of a cluster being replayed, not a live cluster), or "supplied" (a Python caller bound a client of its own with `use_api_client`; never from the MCP server).
99
101
  - **`context`** (`Optional[str]`): The kubeconfig context name. None for in-cluster config, and for a capture that did not record one.
100
102
  - **`server`** (`Optional[str]`): URL of the cluster's API server.
101
103
  - **`kubeconfig`** (`Optional[str]`): Path of the kubeconfig file (or ``:``-separated list of files) the binding was read from. None unless source is "kubeconfig".
@@ -120,6 +122,12 @@ by its generated name instead (`<replicaset>-<5 chars>`, `<statefulset>-<n>`,
120
122
  `<job>-<5 chars>`, `<daemonset>-<5 chars>`), and a note says so. A workload none
121
123
  of whose pods can be found reports `restarts` as unknown (absent), not 0.
122
124
 
125
+ From a capture that doesn't record a kind (it predates it, or didn't collect it),
126
+ the kinds read here that weren't recorded are named in one note, "Not recorded in
127
+ this capture, so unknown rather than absent: DaemonSets, Service endpoints.", and
128
+ contribute nothing else: a DaemonSet's pods aren't assessed, and Services have no
129
+ endpoint lines. The tool for such a kind raises `K8sNotRecorded` on replay.
130
+
123
131
  Restart cadence comes from container status, not event counts: event records lag
124
132
  what they count (see `get_events`), so an event-derived rate is an average over
125
133
  the record, not the current rhythm.
@@ -138,7 +146,8 @@ over the pod's age is not a rate, and pointing to metrics
138
146
  - **`workload`** (`str`): "Kind/name", e.g. "Deployment/ad", or "Pod/name" for a pod nothing owns.
139
147
  - **`ready`**, **`desired`** (`int`): ready and desired pods; for a Job, 1/1 once it succeeded. Mid-rollout this counts the pods serving, which may be the old revision's.
140
148
  - **`unscheduled`** (`list[str]`): its pods that have no node, with how long and the scheduler's reason: "ad-7d9f-x2k: not scheduled for 3h12m: Unschedulable: 0/3 nodes are available: 3 node(s) didn't match Pod's node affinity/selector." Such a pod has no containers, so it is in no other field. From a capture made before 4.1.0 the reason reads "reason not recorded"; a pod there counts as unscheduled when it has neither a node nor any container status.
141
- - **`claims`** (`list[str]`): the claims those pods mount that aren't Bound, each with its status, storage class and newest event: 'PersistentVolumeClaim/cache: Pending, storage class fast-ssd; ProvisioningFailed: storageclass.storage.k8s.io "fast-ssd" not found'. The scheduler says only "pod has unbound immediate PersistentVolumeClaims"; why a claim is unbound is in the claim's events. A claim with none reads "no events recorded" (events expire, by default after an hour). Read from `get_pvc_summaries`, only when some pod is unscheduled; empty when claims can't be read or the capture has none.
149
+ - **`claims`** (`list[str]`): the claims those pods mount that aren't Bound, each with its status, storage class and newest event: 'PersistentVolumeClaim/cache: Pending, storage class fast-ssd; ProvisioningFailed: storageclass.storage.k8s.io "fast-ssd" not found'. The scheduler says only "pod has unbound immediate PersistentVolumeClaims"; why a claim is unbound is in the claim's events. A claim with none reads "no events recorded" (events expire, by default after an hour). Read from `get_pvc_summaries`, only when some pod is unscheduled; empty when claims can't be read, and from a capture that doesn't record claims (named in the note on what wasn't recorded).
150
+ - **`placement`** (`list[str]`): for each of those pods, how many nodes its `nodeSelector` and required node affinity admit, out of all nodes, and how many of the admitted nodes have a NoSchedule or NoExecute taint it doesn't tolerate: "ad-7d9f-x2k: 0 of 5 nodes match its nodeSelector and required node affinity", or "...: 2 of 5 nodes match ...; of those, 2 have a NoSchedule or NoExecute taint it doesn't tolerate". A pod with neither constraint reads "no nodeSelector or required node affinity, so all nodes match (5)". The scheduler's message can't answer this: its filters stop at the first that rejects a node, so a node it reports as tainted may not match the selector either. This is k8stools' own evaluation (the result's notes say so), with the API's rules: `nodeSelector` is label equality; `nodeSelectorTerms` are ORed, a term's `matchExpressions` and `matchFields` (`metadata.name`) ANDed, an empty term matches nothing; `Gt`/`Lt` compare integers and don't match a label that isn't one. Resources, ports, volumes, topology spread and pod (anti-)affinity aren't counted; a cordoned node counts through its `node.kubernetes.io/unschedulable` taint. Nodes are read once per call, only when some pod is unscheduled; when they or the pod's spec can't be read, the line says "not evaluated" and why.
142
151
  - **`conditions`** (`list[str]`): a Deployment's failing conditions in its controller's words: `Progressing=False` (e.g. `ProgressDeadlineExceeded`: the rollout made no progress within `progressDeadlineSeconds`, 10 minutes by default) or `ReplicaFailure=True` (e.g. `FailedCreate`: a ResourceQuota or an admission webhook rejected its pods, so there may be no pod to show).
143
152
  - **`restarts`** (`int`): container restarts across the workload's pods; absent when none of its pods could be found.
144
153
  - **`last_termination`** (`Termination`): the most recent termination across its pods and containers:
@@ -157,6 +166,7 @@ over the pod's age is not a rate, and pointing to metrics
157
166
  - **`notes`** (`list[str]`)
158
167
  - **`services_without_ready_endpoints`** (`list[str]`): Services with nowhere to send traffic, e.g. "Service/ad: 0 ready, 1 not ready".
159
168
  - **`ingress_problems`** (`list[str]`): Ingress rules that can't reach a pod: a backend that doesn't resolve, or one with no ready endpoints, e.g. "Ingress/shop: shop.example.com/old -> legacy:80: Service 'legacy' not found".
169
+ - **`network_policies`** (`list[str]`): one line per NetworkPolicy in the namespace, at most 10, with the pods it selects and what it allows, e.g. "NetworkPolicy/frontend-block-all-ports selects 1 pod (frontend-675fd7b5c5-8qrfh): allows all ingress". Listed whether or not the workloads they select are healthy: a policy can be what a healthy workload's callers fail against. `get_workload_report` combines them per workload. When the policies can't be read, a note says why; a capture that didn't record them names them in the not-recorded note.
160
170
  - **`recovering`** (`list[WorkloadHealth]`): workloads that pass the healthy rule (all ready, nothing waiting) but have a container that restarted within the last 24 hours: its last termination finished then, and it is running again. Same fields as `workloads`, with `last_termination` the most recent restart. Most recent first, at most 10. A Job's finished container and a completed init container are not restarts. "Ready" is not "healthy": a workload that restarts and recovers would otherwise be listed as healthy, and answers quote that word.
161
171
  - **`recovering_more`** (`list[str]`): recovering workloads past the first 10, one line each, e.g. "Deployment/w10 1/1, 5 restarts, last terminated 11h0m ago: exit 137 (OOMKilled)".
162
172
  - **`healthy`** (`list[str]`): one line per healthy workload (as defined under `workloads`, and no restart within 24 hours), e.g. "Deployment/cart 3/3", with what's worth knowing about it added: restarts, "HPA at max 3", or "memory at 99.8% of limit" when a container is at 90% or more of its memory limit (with the working-set note in `notes`).
@@ -185,19 +195,20 @@ those tools, so it answers the same way from a replayed capture.
185
195
  #### Returns
186
196
 
187
197
  - **`workload`**, **`ready`**, **`desired`**
188
- - **`unscheduled`**, **`claims`**, **`conditions`** (`list[str]`): as in `get_namespace_health`.
198
+ - **`unscheduled`**, **`claims`**, **`placement`**, **`conditions`** (`list[str]`): as in `get_namespace_health`.
189
199
  - **`containers`** (`list[ContainerEssentials]`): per container of the focus pod: `image`, `requests`, `limits`, and `probes` (e.g. "liveness: httpGet :8080/healthz every 10s, fails after 3", or "none configured"). Native sidecars come after the app containers, with `sidecar: true`.
190
200
  - **`init_containers`** (`list[ContainerEssentials]`): the focus pod's init containers, from its spec. Always present: `[]` means it has none.
191
201
  - **`instances`** (`list[Instance]`): every pod's containers now: `pod_age` (time since the pod was created; when its restarts happened isn't recorded), `state`, `started` (time since the current instance started), `ready`, `restarts`, and `last_termination` as in `get_namespace_health`.
192
202
  - **`init_instances`** (`list[Instance]`): init container instances, in every pod, that haven't completed (exited 0), with a note; omitted when all have. When a capture didn't record init statuses, a note says so rather than this reading as "all completed". The logs of the focus pod's pending init containers are included in `logs`.
193
203
  - **`events`** (`list[EventLine]`): events for the workload, its ReplicaSets and its pods, merged where they differ only in which object they name (`objects` counts them, and `count` sums them), newest first, at most 20. Events for other kinds that share the name (a Service called like the Deployment) are left out.
194
- - **`logs`** (`list[LogTail]`): current and previous log tails of the focus pod, the one most in trouble: a waiting container first, then most restarts. A note line the log tool added (e.g. that a waiting container's log is its last instance's) is moved into the tail's `notes`. When that instance's log file is gone, the tail has `available: false`, `reason` (`LOG_RECLAIMED_REASON`) and no `lines`; `available` is omitted when the log was read.
204
+ - **`logs`** (`list[LogTail]`): current and previous log tails of the focus pod, the one most in trouble: a waiting container first, then most restarts. A note line the log tool added (e.g. that a waiting container's log is its last instance's) is moved into the tail's `notes`. When that instance's log file is gone, the tail has `available: false`, `reason` (`LOG_RECLAIMED_REASON`) and no `lines`; so does a log a replayed capture didn't record, with a reason saying so. `available` is omitted when the log was read.
195
205
  - **`last_change`** (`LastChange`): the current revision from `get_workload_history`: `revision`, `age`, `reused`, `rollout_restart`, and `changes` as "field: before -> after".
196
206
  - **`config`** (`list[ConfigReference]`): the ConfigMaps and Secrets it uses, as in `get_workload_history`.
197
207
  - **`autoscaler`** (`HpaSummary`): its HPA, if one scales it.
198
208
  - **`services`** (`list[EndpointSummary]`): Services sending traffic to its pods, with each backend's state.
199
209
  - **`usage`** (`list[ContainerUsage]`): its containers' current usage, as from `get_container_metrics`. When metrics aren't available, `notes` says why.
200
210
  - **`ingresses`** (`list[str]`): Ingress rules routing to its Services, e.g. "Ingress/shop: shop.example.com/ -> test-service:80 (3 ready)".
211
+ - **`network_policies`** (`list[str]`): the NetworkPolicies selecting its pods, combined per direction, since a pod's allowed traffic is the union of every policy selecting it: "ingress: allows all ingress (NetworkPolicy/frontend-block-all-ports)", "egress: not restricted (no NetworkPolicy selects these pods for egress)", or "egress: denies all egress; none allows port 53, so these pods can't look up names (DNS) (NetworkPolicy/deny-all)". A policy selecting only some of its pods adds "NetworkPolicy/x selects 2 of these 3 pods". When none selects them, the one line "no NetworkPolicy (networking.k8s.io) selects these pods". Empty when the policies weren't recorded or couldn't be read, with a note saying which. Policy kinds installed as custom resources (Cilium, Calico, Antrea, AdminNetworkPolicy) are named in a note: they apply too, and aren't read.
201
212
  - **`notes`** (`list[str]`): including where the event records start ("not necessarily when the problem did"), when the template last changed ("not how long the workload has been healthy"), which pod the containers and logs come from, and an exit code / reason disagreement.
202
213
 
203
214
  Empty fields are left out of the result.
@@ -320,7 +331,7 @@ Each ContainerStatus has the following fields:
320
331
  - **`started`** (`Optional[bool]`): Started indicates whether the container has finished its postStart lifecycle hook and passed its startup probe.
321
332
  - **`stop_signal`** (`Optional[str]`): Stop signal for the container.
322
333
  - **`state`** (`Optional[ContainerState]`): Current state of the container.
323
- - **`last_state`** (`Optional[ContainerState]`): Last state of the container. When Terminated, ``ran_for`` is how long that instance ran (``finished_at - started_at``). It is not the restart interval, which adds the back-off named in a Waiting ``state``'s message, and it is not how much time the container's log covers: a process can stop logging long before it is killed.
334
+ - **`last_state`** (`Optional[ContainerState]`): Last state of the container. When Terminated, ``ran_for`` is how long that instance ran (``finished_at - started_at``). An instance that never started (reason `StartError`: the runtime couldn't run it) has no `started_at` or `ran_for`; the API reports its start as 1970-01-01. It is not the restart interval, which adds the back-off named in a Waiting ``state``'s message, and it is not how much time the container's log covers: a process can stop logging long before it is killed.
324
335
  - **`volume_mounts`** (`list[VolumeMountStatus]`): Status of volume mounts for the container
325
336
  - **`resource_requests`** (`dict[str, str]`): Describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits.
326
337
  - **`resource_limits`** (`dict[str, str]`): Describes the maximum amount of compute resources allowed.
@@ -397,6 +408,8 @@ Retrieves logs from a Kubernetes pod and container.
397
408
 
398
409
  The log may begin with lines starting `[k8stools] note: `, added by the tool rather than the container; see [Notes in results](#notes-in-results).
399
410
 
411
+ Replaying a capture imported from an ITBench-Lite snapshot (`k8s-capture-state --from-itbench`), the lines are the service's OpenTelemetry log records, not the container's output, and a note says so: `These lines are the OpenTelemetry log records the service exported (imported from an ITBench snapshot), not the container's stdout/stderr, which wasn't recorded: a stack trace or error the process printed directly may be missing.` Each line is the record's time, its severity, its body and the attributes the body doesn't show.
412
+
400
413
  #### Parameters
401
414
 
402
415
  - **`pod_name`** (`str`): The name of the pod.
@@ -634,6 +647,50 @@ list of IngressSummary, each with:
634
647
  - **`labels`**, **`annotations`**, **`age`**
635
648
  - **`notes`** (`list[str]`): see [Notes in results](#notes-in-results).
636
649
 
650
+ ### `get_networkpolicy_summaries`
651
+
652
+ ```python
653
+ get_networkpolicy_summaries(namespace: Optional[str] = None) -> list[NetworkPolicySummary]
654
+ ```
655
+
656
+ NetworkPolicies (`networking.k8s.io/v1`), with the pods each selects and a plain
657
+ statement of what it allows in each direction it restricts. A policy's name
658
+ says nothing reliable about what it does: ITBench-Lite Scenario-31's
659
+ `frontend-block-all-ports` is `ingress: [{}]`, which allows every source on every
660
+ port. The statements follow the API's rules, including the ones most often
661
+ misread:
662
+
663
+ - **Default `policyTypes`.** Omitted, Ingress is always restricted, and Egress only when the policy has egress rules. A policy with neither field set denies all ingress.
664
+ - **A rule with no peers allows any peer, and one with no ports any port.** `ingress: [{}]` allows all ingress; `ingress: []` (or none) denies all.
665
+ - **`podSelector: {}` in a peer is every pod in the policy's namespace**, not everyone: other namespaces and anything outside the cluster are not allowed. `namespaceSelector: {}` is every pod in every namespace, still nothing outside the cluster.
666
+ - **One peer with both a pod and a namespace selector means pods matching both**; two peers (two list items) mean either.
667
+ - **Policies add up.** A pod selected by any policy for a direction gets only what some rule of some selecting policy allows; one policy allowing all outweighs any number denying.
668
+
669
+ What no statement here can show:
670
+
671
+ - **Enforcement.** A NetworkPolicy has no effect unless the cluster's network plugin implements it, and the API doesn't say whether it does.
672
+ - **Both ends.** A connection needs the client's egress and the server's ingress both allowed. Replies on an allowed connection always pass.
673
+ - **Other policy kinds.** Cilium's and Calico's policies, Antrea's, and AdminNetworkPolicy (`policy.networking.k8s.io`, which takes precedence over NetworkPolicy) are custom resources and aren't read; `get_workload_report` names the ones installed.
674
+ - **Traffic from the node** (e.g. kubelet probes) and **`ipBlock` matching pod IPs** are up to the network plugin.
675
+
676
+ #### Parameters
677
+
678
+ - **`namespace`** (`Optional[str]`): one namespace, or all if omitted.
679
+
680
+ #### Returns
681
+
682
+ list of NetworkPolicySummary, each with:
683
+
684
+ - **`name`**, **`namespace`**, **`age`**
685
+ - **`pod_selector`** (`str`): the pods it applies to, as a label selector in kubectl syntax ("app=web,tier in (a,b)", "!canary"); "" selects every pod.
686
+ - **`selected_pods`** (`list[str]`): the namespace's pods it selects now. Pods on the host network are left out: policies don't apply to them.
687
+ - **`policy_types`** (`list[str]`): the directions it restricts, with the default above applied.
688
+ - **`ingress`**, **`egress`** (`list[NetworkPolicyRule]`): its rules, each with:
689
+ - **`peers`** (`list[NetworkPolicyPeer]`): any of which may match; `[]` means any peer. A peer has `pod_selector` and `namespace_selector` (selectors as above, None when not set; both set means both must match), or `ip_block` ("10.0.0.0/8 except 10.1.0.0/16").
690
+ - **`ports`** (`list[NetworkPolicyPort]`): `protocol` (TCP by default), `port` (a number or a container port name; None for every port of the protocol) and `end_port`; `[]` means every port.
691
+ - **`ingress_effect`**, **`egress_effect`** (`Optional[str]`): what it allows, from its rules alone: "allows all ingress", "denies all egress", or "allows ingress only from pods with app=frontend-proxy in this namespace on TCP 8080; or from addresses in 10.0.0.0/8 on any port". None for a direction it doesn't restrict. A namespace selector on the name label every namespace has reads "namespace ingress-nginx". Worked out each time it's read, so a capture replays it as a live call would.
692
+ - **`notes`** (`list[str]`): see [Notes in results](#notes-in-results).
693
+
637
694
  ### `get_configmap_summaries`
638
695
 
639
696
  ```python