k8stools 2.2.0__tar.gz → 2.3.0__tar.gz

{k8stools-2.2.0 → k8stools-2.3.0}/CHANGELOG.md

@@ -3,6 +3,82 @@
 All notable changes to k8stools. Versions follow [semantic versioning](https://semver.org/);
 dates are release-tag dates.
 
+## 2.3.0 — 2026-10-03
+
+### Added
+- **`conditions_since` on nodes** (issue #9). `get_node_summaries` now reports,
+  for each node condition, the time since its status last changed (the API's
+  `lastTransitionTime`, which was dropped), next to the unchanged `conditions`
+  map. A condition with no transition time is left out. `print_node_summaries`
+  gains a READY-SINCE column.
+- The tool description says what it does not show: a restart in which the node
+  comes back Ready without being marked NotReady or Unknown in between does not
+  reset it. On a minikube cluster stopped and started with its control plane,
+  `Ready` stayed "True since the node was created", 167 days, across a reboot.
+  It points to the node's `Starting`/`Rebooted` events and the start times of
+  kube-proxy and the control-plane containers for dating a node's last start.
+- Captures store it as `conditions_since_seconds` and replay advances it like
+  every other age; captures from before 2.3.0 replay it as an empty map. (The
+  capture format had no handling for a map of durations: without it the values
+  would have been replayed as fixed spans that never advanced.)
+- **`get_daemonset_summaries` tool** (issue #10), like `kubectl get daemonsets -o wide`:
+  desired, current, ready, up-to-date, available and misscheduled counts, the pod
+  template's node selector and images, update strategy, and age. Until now a
+  DaemonSet was visible only through its pods, whose `<name>-<5 chars>` names
+  can't be told apart from other names. Captures store DaemonSets; captures from
+  before 2.3.0 replay none. `print_daemonset_summaries` is its companion.
+- **`owner` on pods.** `get_pod_summaries` reports each pod's controlling owner
+  as `"Kind/name"` (e.g. `"DaemonSet/otel-collector-agent"`), so pods can be
+  grouped into workloads without guessing from name suffixes. It is the direct
+  owner: a Deployment's pods name a replica set, whose `owner_deployment` names
+  the Deployment. `None` for a pod nobody manages; captures from before 2.3.0
+  replay `None`. `print_pod_summaries` gains an OWNER column.
+- **The built-in `--mock` fixture shows the 2.3.0 fields** and now describes a
+  cluster that could exist. It gains an `otel-collector-agent` DaemonSet and its
+  pod, pod owners, node condition times, and event counts. Every workload now has
+  its pods (`test-deployment`'s three, and `postgres-0`, which a PVC already
+  named as mounting it), services select the pods they front, and the
+  `postgres` StatefulSet's headless service exists. It also fixes
+  contradictions in the old data that an agent would reason from:
+  - the `ad` pod ran its previous revision's image;
+  - its last instance's status said it ran 2 seconds while its log covered 2
+    minutes;
+  - its 93 restarts were more than its age allows at the 5-minute backoff cap
+    (now 67);
+  - several logs were dated 14 months before the capture;
+  - the namespaces were older than anything else in the cluster;
+  - `test-pod-123`'s spec declared one container while its status had two.
+
+  The `ad` container now shows the case `previous=True` is for: it restarted 58
+  seconds ago, so its current log is JVM startup and the OOM is only in the
+  previous one. A new test file keeps the fixture consistent.
+
+### Changed
+- **A capture needs `list` on `daemonsets`** (apps). `k8s-capture-state` now
+  captures DaemonSets, so it fails where the cluster role does not grant them,
+  rather than writing a capture that replays as if there were none. Add
+  `daemonsets` to the role's apps resources (see README, "Permissions").
+
+### Documentation
+- README lists the read-only RBAC rules that cover every tool.
+
+## 2.2.1 — 2026-09-29
+
+### Documentation
+- **Event records can lag behind what they count** (follow-up to issue #8). The
+  kubelet counts every occurrence but, by default, writes at most one update per
+  object and event type every 5 minutes once a burst of 25 is used up (client-go's
+  event spam filter). A crash-looping pod's `Created` record read `last_seen`
+  29 minutes while the container had restarted 46 seconds earlier, then its count
+  jumped by six in one update. The `get_pod_events` and `get_events` descriptions
+  now say so: `count / (first_seen - last_seen)` still gives the rate, since both
+  lag together, but `last_seen` is not the time of the last restart (use the
+  container status or `PodSummary.last_restart`), and counts for different reasons
+  can differ by a few for the same restarts.
+- `PodSummary.last_restart` is described as what it is: time since a container
+  last *terminated*. For a container waiting in CrashLoopBackOff, that is its last
+  crash, not a restart.
+
 ## 2.2.0 — 2026-09-28
 
 ### Added

{k8stools-2.2.0 → k8stools-2.3.0}/CLAUDE.md

@@ -14,7 +14,7 @@ src/k8stools/
   mcp_server.py  - MCP server (stdio or streamable-http transport)
   mcp_client.py  - MCP client used for manual testing
   fixtures/
-    otel-demo.json - Built-in capture served by `--mock` (real Minikube + OTel Demo)
+    otel-demo.json - Built-in capture served by `--mock` (hand-maintained, modeled on Minikube + OTel Demo)
 tests/
   test_k8s_tools.py          - Unit tests for the original tools (mocked K8s API)
   test_new_tools.py          - Unit tests for the 1.1.0 tools (ConfigMaps, CronJobs/Jobs, PVCs, StatefulSets, events, log enhancements)
@@ -26,6 +26,9 @@ tests/
   test_mock_tools.py         - Tests for mock_tools module (incl. parity with k8s_tools.TOOLS)
   test_events.py             - Event aggregation (count/first_seen), incl. the events.k8s.io fallback
   test_cluster_binding.py    - Cluster selection: configure(), the shared binding, get_cluster_info, server flags
+  test_node_conditions.py    - NodeSummary.conditions_since (condition transition times), incl. capture replay
+  test_workloads.py          - get_daemonset_summaries and PodSummary.owner, incl. capture replay
+  test_builtin_fixture.py    - The built-in fixture describes a cluster that could exist (owners, images, ages, log windows)
   test_log_decoding.py       - Log decoding at the API boundary (bytes vs str), `previous` plumbing, log redaction
   test_mcp_client.py         - MCP client tests
   test_version.py            - Asserts pyproject and package __version__ agree
@@ -224,6 +227,9 @@ Invariants worth preserving when touching this code:
   but read back unchanged. Replay tests that freeze the clock can't tell the two
   apart (frozen elapsed time is zero), so test a new duration field on an
   advancing clock with a `server_start_time` in the past.
+  A `dict[str, Duration]` (`NodeSummary.conditions_since`) is stored as a map
+  under `<field>_seconds` and each value advances (the codec looks through a
+  dict to its value type).
 - **`MockState` must match the real tool's documented behavior**, not just its
   types — filter semantics, result ordering (`get_replicaset_summaries` re-sorts
   at query time), and which failures raise vs. return empty.
@@ -235,7 +241,13 @@ Invariants worth preserving when touching this code:
   synthesizes answers for unknown pod names.
 
 The built-in fixture lives under `src/k8stools/` (not `tests/`) because
-`--mock` serves it, so it has to ship in the wheel.
+`--mock` serves it, so it has to ship in the wheel. It is **hand-maintained**, not
+a raw capture (it began as the pre-2.0 mock data, re-encoded): a real capture is
+megabytes, and a test cluster has no CronJobs, Jobs or PVCs to show. When a tool
+gains a field, add it to the fixture by hand, with values that agree with the
+rest of it. `tests/test_builtin_fixture.py` checks that it does (owners exist and
+run the pod's images, nothing predates its namespace, logs fall inside the
+instance that wrote them, restarts fit the pod's age at the backoff cap).
 
 Captures are written **indented, and uncompressed by default**, on purpose: these
 files get re-captured and re-committed, and git deltas successive versions of
@@ -310,4 +322,4 @@ Example `mcp.json`:
 
 - Read-only tools first; state-modifying tools will be kept in a separate module when added
 - Quality over quantity: well-documented, strongly typed, useful for real monitoring/RCA agents
-- Mock data captured from a real Minikube instance running the OpenTelemetry Demo app
+- Mock data modeled on a Minikube instance running the OpenTelemetry Demo app, kept internally consistent by tests

{k8stools-2.2.0 → k8stools-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 2.2.0
+Version: 2.3.0
 Summary: Tools and an MCP server for building Kubernetes agents
 Project-URL: Homepage, https://github.com/BenedatLLC/k8stools
 Project-URL: Changelog, https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md
@@ -277,6 +277,32 @@ replayable file).
 What changed in each release is in the
 [changelog](https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md).
 
+### Permissions
+
+The tools only read, with the `get` and `list` verbs. A read-only ClusterRole
+that covers every tool:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: k8stools-reader
+rules:
+- apiGroups: [""]
+  resources: [namespaces, nodes, pods, pods/log, events, services, configmaps,
+              persistentvolumeclaims]
+  verbs: [get, list]
+- apiGroups: [apps]
+  resources: [deployments, replicasets, statefulsets, daemonsets]
+  verbs: [get, list]
+- apiGroups: [batch]
+  resources: [jobs, cronjobs]
+  verbs: [get, list]
+```
+
+`get_cluster_info` also reads the server version (`/version`), which every
+authenticated user can read by default. No tool reads Secrets.
+
 ## Current tools
 
 These are the tools we define:
@@ -284,7 +310,7 @@ These are the tools we define:
 * `get_cluster_info` - which cluster the tools are answering from: kubeconfig context, API server URL and version, or the capture being replayed
 * `get_namespaces` - get a list of namespaces, like `kubectl get namespace`
 * `get_node_summaries` - get a list of nodes, like `kubectl get nodes -o wide` (includes capacity/allocatable/conditions/taints/labels)
-* `get_pod_summaries` - get a list of pods, like `kubectl get pods -o wide`
+* `get_pod_summaries` - get a list of pods, like `kubectl get pods -o wide`, with each pod's controlling owner (e.g. `DaemonSet/otel-collector-agent`)
 * `get_pod_container_statuses` - return the status for each of the container in a pod
 * `get_pod_events` - return the events for a pod
 * `get_pod_spec` - retrieves the spec for a given pod
@@ -295,6 +321,7 @@ These are the tools we define:
 * `get_configmap_summaries` - get a list of ConfigMaps, like `kubectl get configmaps`
 * `get_configmap` - retrieve the full contents of a single ConfigMap
 * `get_statefulset_summaries` - get a list of StatefulSets, like `kubectl get statefulsets`
+* `get_daemonset_summaries` - get a list of DaemonSets, like `kubectl get daemonsets -o wide` (includes node selector and images)
 * `get_cronjob_summaries` - get a list of CronJobs, like `kubectl get cronjobs`
 * `get_job_summaries` - get a list of Jobs, like `kubectl get jobs`
 * `get_logs_for_job` - retrieve logs from a Job's most-recent pod
@@ -315,6 +342,7 @@ We also define a set of associated "print_" functions that are helpful in debugg
 * `print_configmap_summaries`
 * `print_configmap`
 * `print_statefulset_summaries`
+* `print_daemonset_summaries`
 * `print_cronjob_summaries`
 * `print_job_summaries`
 * `print_pvc_summaries`
@@ -501,11 +529,12 @@ data: {"jsonrpc":"2.0","id":1,"result":{"tools":[.... long text elided ...]}}
 ## Mock tools
 When building agents, it can be helpful to test them against *mock* versions that do
 not go against a real cluster, but return realistic values. The module
-`k8stools.mock_tools` does just that. The data values were captured when running
-against a real Minikube instance running the
+`k8stools.mock_tools` does just that. The data is a small, hand-maintained
+cluster modeled on a Minikube instance running the
 [Open Telemetry Demo](https://github.com/open-telemetry/opentelemetry-demo)
-application. When running the MCP server, this may be enabled by using the
-`--mock` command line option.
+application: a crash-looping `ad` service mid-upgrade, a DaemonSet, a CronJob and
+its Job, a StatefulSet with PVCs, and a few events. When running the MCP server,
+this may be enabled by using the `--mock` command line option.
 
 The mock serves a *capture* — a JSON snapshot of one cluster — rather than a set of
 per-tool canned answers, so the tools agree with each other: a pod that is not in the
@@ -580,7 +609,7 @@ Everything the tools can read, so that every tool answers on replay:
 |---|---|
 | Cluster | context name, API server URL and version, so `get_cluster_info` answers on replay (not the kubeconfig path, which names a file on the capturing machine) |
 | Cluster-wide | namespaces, nodes |
-| Per namespace | deployments, replica sets, services, statefulsets, cronjobs, jobs, PVCs, events |
+| Per namespace | deployments, replica sets, services, statefulsets, daemonsets, cronjobs, jobs, PVCs, events |
 | ConfigMaps | summary **and** full contents, so `get_configmap` works too |
 | Per pod | summary, labels, container statuses, spec, and per-container logs |
 

{k8stools-2.2.0 → k8stools-2.3.0}/README.md

@@ -57,6 +57,32 @@ replayable file).
 What changed in each release is in the
 [changelog](https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md).
 
+### Permissions
+
+The tools only read, with the `get` and `list` verbs. A read-only ClusterRole
+that covers every tool:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: k8stools-reader
+rules:
+- apiGroups: [""]
+  resources: [namespaces, nodes, pods, pods/log, events, services, configmaps,
+              persistentvolumeclaims]
+  verbs: [get, list]
+- apiGroups: [apps]
+  resources: [deployments, replicasets, statefulsets, daemonsets]
+  verbs: [get, list]
+- apiGroups: [batch]
+  resources: [jobs, cronjobs]
+  verbs: [get, list]
+```
+
+`get_cluster_info` also reads the server version (`/version`), which every
+authenticated user can read by default. No tool reads Secrets.
+
 ## Current tools
 
 These are the tools we define:
@@ -64,7 +90,7 @@ These are the tools we define:
 * `get_cluster_info` - which cluster the tools are answering from: kubeconfig context, API server URL and version, or the capture being replayed
 * `get_namespaces` - get a list of namespaces, like `kubectl get namespace`
 * `get_node_summaries` - get a list of nodes, like `kubectl get nodes -o wide` (includes capacity/allocatable/conditions/taints/labels)
-* `get_pod_summaries` - get a list of pods, like `kubectl get pods -o wide`
+* `get_pod_summaries` - get a list of pods, like `kubectl get pods -o wide`, with each pod's controlling owner (e.g. `DaemonSet/otel-collector-agent`)
 * `get_pod_container_statuses` - return the status for each of the container in a pod
 * `get_pod_events` - return the events for a pod
 * `get_pod_spec` - retrieves the spec for a given pod
@@ -75,6 +101,7 @@ These are the tools we define:
 * `get_configmap_summaries` - get a list of ConfigMaps, like `kubectl get configmaps`
 * `get_configmap` - retrieve the full contents of a single ConfigMap
 * `get_statefulset_summaries` - get a list of StatefulSets, like `kubectl get statefulsets`
+* `get_daemonset_summaries` - get a list of DaemonSets, like `kubectl get daemonsets -o wide` (includes node selector and images)
 * `get_cronjob_summaries` - get a list of CronJobs, like `kubectl get cronjobs`
 * `get_job_summaries` - get a list of Jobs, like `kubectl get jobs`
 * `get_logs_for_job` - retrieve logs from a Job's most-recent pod
@@ -95,6 +122,7 @@ We also define a set of associated "print_" functions that are helpful in debugg
 * `print_configmap_summaries`
 * `print_configmap`
 * `print_statefulset_summaries`
+* `print_daemonset_summaries`
 * `print_cronjob_summaries`
 * `print_job_summaries`
 * `print_pvc_summaries`
@@ -281,11 +309,12 @@ data: {"jsonrpc":"2.0","id":1,"result":{"tools":[.... long text elided ...]}}
 ## Mock tools
 When building agents, it can be helpful to test them against *mock* versions that do
 not go against a real cluster, but return realistic values. The module
-`k8stools.mock_tools` does just that. The data values were captured when running
-against a real Minikube instance running the
+`k8stools.mock_tools` does just that. The data is a small, hand-maintained
+cluster modeled on a Minikube instance running the
 [Open Telemetry Demo](https://github.com/open-telemetry/opentelemetry-demo)
-application. When running the MCP server, this may be enabled by using the
-`--mock` command line option.
+application: a crash-looping `ad` service mid-upgrade, a DaemonSet, a CronJob and
+its Job, a StatefulSet with PVCs, and a few events. When running the MCP server,
+this may be enabled by using the `--mock` command line option.
 
 The mock serves a *capture* — a JSON snapshot of one cluster — rather than a set of
 per-tool canned answers, so the tools agree with each other: a pod that is not in the
@@ -360,7 +389,7 @@ Everything the tools can read, so that every tool answers on replay:
 |---|---|
 | Cluster | context name, API server URL and version, so `get_cluster_info` answers on replay (not the kubeconfig path, which names a file on the capturing machine) |
 | Cluster-wide | namespaces, nodes |
-| Per namespace | deployments, replica sets, services, statefulsets, cronjobs, jobs, PVCs, events |
+| Per namespace | deployments, replica sets, services, statefulsets, daemonsets, cronjobs, jobs, PVCs, events |
 | ConfigMaps | summary **and** full contents, so `get_configmap` works too |
 | Per pod | summary, labels, container statuses, spec, and per-container logs |
 

{k8stools-2.2.0 → k8stools-2.3.0}/designs/mock-state-capture.md

@@ -151,6 +151,7 @@ A single JSON file per capture. Top-level keys:
   "services": [ ... ],
   "configmaps": [ ... ],
   "statefulsets": [ ... ],
+  "daemonsets": [ ... ],
   "cronjobs": [ ... ],
   "jobs": [ ... ],
   "pvcs": [ ... ],
@@ -162,7 +163,9 @@ The `configmaps`..`events` keys were added alongside the 1.1.0 tool batch
 (ConfigMaps, StatefulSets, CronJobs/Jobs, PVCs, and cluster-wide events). See
 [Resource records added in 1.1.0](#resource-records-added-in-110) below for their
 shapes. `replicasets` was added alongside the 1.2.0 tool batch — see
-[Resource records added in 1.2.0](#resource-records-added-in-120).
+[Resource records added in 1.2.0](#resource-records-added-in-120). `daemonsets` was added
+in 2.3.0: `DaemonSetSummary` fields with `age` → `age_seconds`; captures without it
+replay no DaemonSets.
 
 `redacted` records which mode the capture was taken in — see
 [Redaction](#redaction). It exists so a consumer can tell without guessing;
@@ -448,6 +451,7 @@ class MockState:
     def get_configmap_summaries(self, namespace: str | None = None) -> list[ConfigMapSummary]: ...
     def get_configmap(self, name: str, namespace: str) -> dict[str, Any]: ...
     def get_statefulset_summaries(self, namespace: str | None = None) -> list[StatefulSetSummary]: ...
+    def get_daemonset_summaries(self, namespace: str | None = None) -> list[DaemonSetSummary]: ...  # 2.3.0
     def get_cronjob_summaries(self, namespace: str | None = None) -> list[CronJobSummary]: ...
     def get_job_summaries(self, namespace: str | None = None) -> list[JobSummary]: ...
     def get_logs_for_job(self, job_name: str, namespace: str, container_name: str | None = None,
@@ -538,7 +542,7 @@ Behavior:
    (`configmaps`, `statefulsets`, `cronjobs`, `jobs`, `pvcs`), the 1.2.0 addition
    (`replicasets`), and a namespace/cluster-wide `get_events` sweep. If
    `--namespace` is given, only captures namespaced resources (pods/deployments/
-   replicasets/services/configmaps/statefulsets/cronjobs/jobs/pvcs/events) in those
+   replicasets/services/configmaps/statefulsets/daemonsets/cronjobs/jobs/pvcs/events) in those
    namespaces; namespaces and nodes are always captured in full.
 3. For each pod and each container, calls `get_logs_for_pod_and_container` unless `--no-logs`. Default log cap: 1000 lines (override with `--max-log-lines`).
 4. For each container whose `restart_count > 0`, calls the same tool with

{k8stools-2.2.0 → k8stools-2.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 
 [project]
 name = "k8stools"
-version = "2.2.0"
+version = "2.3.0"
 description = "Tools and an MCP server for building Kubernetes agents"
 readme = "README.md"
 requires-python = ">=3.12"

{k8stools-2.2.0 → k8stools-2.3.0}/src/k8stools/__init__.py

@@ -38,6 +38,7 @@ These are the tools we define:
 * get_configmap_summaries - get a list of ConfigMaps, like `kubectl get configmaps`
 * get_configmap - retrieve the full contents of a single ConfigMap
 * get_statefulset_summaries - get a list of StatefulSets, like `kubectl get statefulsets`
+* get_daemonset_summaries - get a list of DaemonSets, like `kubectl get daemonsets`
 * get_cronjob_summaries - get a list of CronJobs, like `kubectl get cronjobs`
 * get_job_summaries - get a list of Jobs, like `kubectl get jobs`
 * get_logs_for_job - retrieve logs from a Job's most-recent pod
@@ -59,6 +60,7 @@ We also define a set of associated "print_" functions that are helpful in debugg
 * print_configmap_summaries
 * print_configmap
 * print_statefulset_summaries
+* print_daemonset_summaries
 * print_cronjob_summaries
 * print_job_summaries
 * print_pvc_summaries
@@ -78,4 +80,4 @@ the built-in OTel Demo snapshot by default, or your own via load_mock_state() or
 the server's --state-file option.
 """
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"

{k8stools-2.2.0 → k8stools-2.3.0}/src/k8stools/capture.py

@@ -185,6 +185,7 @@ def capture_state(namespaces: Optional[list[str]] = None,
         "services": [],
         "configmaps": [],
         "statefulsets": [],
+        "daemonsets": [],
         "cronjobs": [],
         "jobs": [],
         "pvcs": [],
@@ -196,6 +197,7 @@ def capture_state(namespaces: Optional[list[str]] = None,
         state["replicasets"] += _encode_all(redactor(k8s_tools.get_replicaset_summaries(ns)), captured_at)
         state["services"] += _encode_all(redactor(k8s_tools.get_service_summaries(ns)), captured_at)
         state["statefulsets"] += _encode_all(redactor(k8s_tools.get_statefulset_summaries(ns)), captured_at)
+        state["daemonsets"] += _encode_all(redactor(k8s_tools.get_daemonset_summaries(ns)), captured_at)
         state["cronjobs"] += _encode_all(redactor(k8s_tools.get_cronjob_summaries(ns)), captured_at)
         state["jobs"] += _encode_all(redactor(k8s_tools.get_job_summaries(ns)), captured_at)
         state["pvcs"] += _encode_all(redactor(k8s_tools.get_pvc_summaries(ns)), captured_at)