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.
- {k8stools-4.2.0 → k8stools-4.4.0}/CHANGELOG.md +134 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/CLAUDE.md +50 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/PKG-INFO +72 -5
- {k8stools-4.2.0 → k8stools-4.4.0}/README.md +71 -4
- {k8stools-4.2.0 → k8stools-4.4.0}/docs/TOOL_REFERENCE.md +62 -5
- {k8stools-4.2.0 → k8stools-4.4.0}/pyproject.toml +1 -1
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/__init__.py +1 -1
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/capture.py +61 -1
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/composites.py +277 -33
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/fixtures/otel-demo.json +1 -0
- k8stools-4.4.0/src/k8stools/itbench.py +560 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/k8s_tools.py +366 -30
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/mock_state.py +73 -18
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/mock_tools.py +7 -0
- k8stools-4.4.0/tests/fixtures/itbench-33-excerpt/k8s_events_raw.tsv +73 -0
- k8stools-4.4.0/tests/fixtures/itbench-33-excerpt/k8s_objects_raw.tsv +79 -0
- k8stools-4.4.0/tests/fixtures/itbench-33-excerpt/otel_logs_raw.tsv +61 -0
- k8stools-4.4.0/tests/fixtures/make_itbench_excerpt.py +97 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_capture.py +1 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_composites.py +2 -1
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_custom_resources.py +3 -2
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_endpoints.py +3 -2
- k8stools-4.4.0/tests/test_hooks.py +135 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_hpa.py +3 -2
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_ingress.py +2 -1
- k8stools-4.4.0/tests/test_itbench.py +350 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_live_writes.py +6 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_metrics.py +1 -1
- k8stools-4.4.0/tests/test_networkpolicy.py +285 -0
- k8stools-4.4.0/tests/test_not_recorded.py +172 -0
- k8stools-4.4.0/tests/test_placement.py +195 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_workloads.py +3 -2
- {k8stools-4.2.0 → k8stools-4.4.0}/uv.lock +1 -1
- {k8stools-4.2.0 → k8stools-4.4.0}/.claude/settings.local.json +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/.github/workflows/unit-tests.yml +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/.gitignore +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/.python-version +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/.vscode/mcp.json +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/.vscode/settings.json +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/LICENSE +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/chat-with-cluster.png +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/designs/mock-state-capture.md +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/docs/ROADMAP.md +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/envrc.template +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/mcp_client.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/mcp_server.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/src/k8stools/redaction.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/conftest.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_builtin_fixture.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_cluster_binding.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_duration_format.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_events.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_init_containers.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_k8s_tools.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_k8s_tools_realk8s.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_log_decoding.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_mcp_client.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_mcp_errors.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_mock_state.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_mock_tools.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_new_tools.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_node_conditions.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_notes.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_redaction.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_replicaset_tool.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_stuck_rollouts.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_toolsets.py +0 -0
- {k8stools-4.2.0 → k8stools-4.4.0}/tests/test_version.py +0 -0
- {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.
|
|
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.
|
|
885
|
-
replays as
|
|
886
|
-
|
|
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.
|
|
664
|
-
replays as
|
|
665
|
-
|
|
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),
|
|
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
|
|
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
|