k8stools 2.3.0__tar.gz → 2.4.0__tar.gz

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

@@ -3,6 +3,40 @@
 All notable changes to k8stools. Versions follow [semantic versioning](https://semver.org/);
 dates are release-tag dates.
 
+## 2.4.0 — 2026-10-05
+
+### Added
+- **`get_workload_history` tool** (issue #11): what changed in a Deployment,
+  StatefulSet or DaemonSet, and when. It lists the retained pod-template revisions
+  newest first (a Deployment's ReplicaSets; a StatefulSet's or DaemonSet's
+  ControllerRevisions), each compared with the one before it:
+  - per container, matched by name: image, resource requests and limits,
+    command, args, probes, env vars, `envFrom` and volume mounts;
+  - for the pod: volumes, node selector and tolerations;
+  - any other changed field is named;
+  - template label and annotation changes are listed separately, so a Helm
+    version-label bump doesn't bury a memory-limit change;
+  - a `kubectl rollout restart` is flagged.
+
+  Env vars are compared by name and shown by name only, never by value. The
+  result also lists the ConfigMaps and Secrets the current template uses, and
+  how. ConfigMaps get their age and `last_written`. Secrets are named but never
+  read. Each result carries the limits of what history can show. `print_workload_history`
+  is its companion.
+- Captures store each workload's history (the tool's result, so no env values are
+  written); captures from before 2.4.0 replay an images-only history rebuilt from
+  their ReplicaSet records, marked `complete: false`. The `--mock` fixture has a
+  history for each of its four workloads.
+
+### Changed
+- **A capture needs `list` on `controllerrevisions`** (apps), for StatefulSet and
+  DaemonSet histories, and fails without it. The README's role includes it.
+
+### Documentation
+- `get_replicaset_summaries` no longer says the newest replica set's age is always
+  when the deployment last changed: a rollback re-activates an older replica set
+  under a new revision number.
+
 ## 2.3.0 — 2026-10-03
 
 ### Added

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

@@ -28,7 +28,8 @@ tests/
   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_builtin_fixture.py    - The built-in fixture describes a cluster that could exist (owners, images, ages, log windows, histories)
+  test_workload_history.py   - get_workload_history: template diffs, revisions, config refs, no env values or Secret reads, replay
   test_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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 2.3.0
+Version: 2.4.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
@@ -293,7 +293,7 @@ rules:
               persistentvolumeclaims]
   verbs: [get, list]
 - apiGroups: [apps]
-  resources: [deployments, replicasets, statefulsets, daemonsets]
+  resources: [deployments, replicasets, statefulsets, daemonsets, controllerrevisions]
   verbs: [get, list]
 - apiGroups: [batch]
   resources: [jobs, cronjobs]
@@ -301,7 +301,8 @@ rules:
 ```
 
 `get_cluster_info` also reads the server version (`/version`), which every
-authenticated user can read by default. No tool reads Secrets.
+authenticated user can read by default. No tool reads Secrets: `get_workload_history`
+names the Secrets a workload uses, from its pod template, without reading them.
 
 ## Current tools
 
@@ -317,6 +318,7 @@ These are the tools we define:
 * `get_logs_for_pod_and_container` - retrieves logs from a pod and container (supports `tail`, `since_seconds`, and `previous`). See [Previous-instance log semantics](#previous-instance-log-semantics) for when `previous=True` returns the same text as `previous=False` — it is Kubernetes behavior, not a bug.
 * `get_deployment_summaries` - get a list of deployments, like `kubectl get deployments`
 * `get_replicaset_summaries` - get a deployment's replica sets with their revision numbers and images. A deployment's replica sets are its change history: use this to see when a workload last changed and what the change was.
+* `get_workload_history` - what changed in a Deployment, StatefulSet or DaemonSet, and when: each retained revision of its pod template compared with the one before (images, resources, probes, command/args, env var *names*, volumes, scheduling), plus the ConfigMaps and Secrets it references. It states what history cannot show.
 * `get_service_summaries` - get a list of services, like `kubectl get services` (includes `selector`/labels/annotations)
 * `get_configmap_summaries` - get a list of ConfigMaps, like `kubectl get configmaps`
 * `get_configmap` - retrieve the full contents of a single ConfigMap
@@ -338,6 +340,7 @@ We also define a set of associated "print_" functions that are helpful in debugg
 * `print_pod_events`
 * `print_pod_spec`
 * `print_deployment_summaries`
+* `print_workload_history`
 * `print_service_summaries`
 * `print_configmap_summaries`
 * `print_configmap`
@@ -609,7 +612,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, daemonsets, cronjobs, jobs, PVCs, events |
+| Per namespace | deployments, replica sets, services, statefulsets, daemonsets, cronjobs, jobs, PVCs, events, and each workload's change history (`get_workload_history`'s result, so no env values are written) |
 | ConfigMaps | summary **and** full contents, so `get_configmap` works too |
 | Per pod | summary, labels, container statuses, spec, and per-container logs |
 

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

@@ -73,7 +73,7 @@ rules:
               persistentvolumeclaims]
   verbs: [get, list]
 - apiGroups: [apps]
-  resources: [deployments, replicasets, statefulsets, daemonsets]
+  resources: [deployments, replicasets, statefulsets, daemonsets, controllerrevisions]
   verbs: [get, list]
 - apiGroups: [batch]
   resources: [jobs, cronjobs]
@@ -81,7 +81,8 @@ rules:
 ```
 
 `get_cluster_info` also reads the server version (`/version`), which every
-authenticated user can read by default. No tool reads Secrets.
+authenticated user can read by default. No tool reads Secrets: `get_workload_history`
+names the Secrets a workload uses, from its pod template, without reading them.
 
 ## Current tools
 
@@ -97,6 +98,7 @@ These are the tools we define:
 * `get_logs_for_pod_and_container` - retrieves logs from a pod and container (supports `tail`, `since_seconds`, and `previous`). See [Previous-instance log semantics](#previous-instance-log-semantics) for when `previous=True` returns the same text as `previous=False` — it is Kubernetes behavior, not a bug.
 * `get_deployment_summaries` - get a list of deployments, like `kubectl get deployments`
 * `get_replicaset_summaries` - get a deployment's replica sets with their revision numbers and images. A deployment's replica sets are its change history: use this to see when a workload last changed and what the change was.
+* `get_workload_history` - what changed in a Deployment, StatefulSet or DaemonSet, and when: each retained revision of its pod template compared with the one before (images, resources, probes, command/args, env var *names*, volumes, scheduling), plus the ConfigMaps and Secrets it references. It states what history cannot show.
 * `get_service_summaries` - get a list of services, like `kubectl get services` (includes `selector`/labels/annotations)
 * `get_configmap_summaries` - get a list of ConfigMaps, like `kubectl get configmaps`
 * `get_configmap` - retrieve the full contents of a single ConfigMap
@@ -118,6 +120,7 @@ We also define a set of associated "print_" functions that are helpful in debugg
 * `print_pod_events`
 * `print_pod_spec`
 * `print_deployment_summaries`
+* `print_workload_history`
 * `print_service_summaries`
 * `print_configmap_summaries`
 * `print_configmap`
@@ -389,7 +392,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, daemonsets, cronjobs, jobs, PVCs, events |
+| Per namespace | deployments, replica sets, services, statefulsets, daemonsets, cronjobs, jobs, PVCs, events, and each workload's change history (`get_workload_history`'s result, so no env values are written) |
 | ConfigMaps | summary **and** full contents, so `get_configmap` works too |
 | Per pod | summary, labels, container statuses, spec, and per-container logs |
 

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

@@ -152,6 +152,7 @@ A single JSON file per capture. Top-level keys:
   "configmaps": [ ... ],
   "statefulsets": [ ... ],
   "daemonsets": [ ... ],
+  "workload_histories": [ ... ],
   "cronjobs": [ ... ],
   "jobs": [ ... ],
   "pvcs": [ ... ],
@@ -165,7 +166,10 @@ The `configmaps`..`events` keys were added alongside the 1.1.0 tool batch
 shapes. `replicasets` was added alongside the 1.2.0 tool batch — see
 [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.
+replay no DaemonSets. `workload_histories` was added in 2.4.0: one encoded
+`WorkloadHistory` (the tool's result, not raw pod templates, so env values never
+reach the file) per Deployment, StatefulSet and DaemonSet. Captures without it
+replay an images-only history rebuilt from `replicasets`, with `complete: false`.
 
 `redacted` records which mode the capture was taken in — see
 [Redaction](#redaction). It exists so a consumer can tell without guessing;

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

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

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

@@ -34,6 +34,7 @@ These are the tools we define:
 * get_logs_for_pod_and_container - retrieves logs from a pod and container (supports tail/since/previous)
 * get_deployment_summaries - get a list of deployments, like `kubectl get deployments`
 * get_replicaset_summaries - get a deployment's revision history, like `kubectl get replicasets`
+* get_workload_history - a workload's pod-template revisions, compared, and the config it references
 * get_service_summaries - get a list of services, like `kubectl get services`
 * get_configmap_summaries - get a list of ConfigMaps, like `kubectl get configmaps`
 * get_configmap - retrieve the full contents of a single ConfigMap
@@ -56,6 +57,7 @@ We also define a set of associated "print_" functions that are helpful in debugg
 * print_pod_spec
 * print_deployment_summaries
 * print_replicaset_summaries
+* print_workload_history
 * print_service_summaries
 * print_configmap_summaries
 * print_configmap
@@ -80,4 +82,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.3.0"
+__version__ = "2.4.0"

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

@@ -186,6 +186,7 @@ def capture_state(namespaces: Optional[list[str]] = None,
         "configmaps": [],
         "statefulsets": [],
         "daemonsets": [],
+        "workload_histories": [],
         "cronjobs": [],
         "jobs": [],
         "pvcs": [],
@@ -193,11 +194,21 @@ def capture_state(namespaces: Optional[list[str]] = None,
     }
 
     for ns in target_namespaces:
-        state["deployments"] += _encode_all(redactor(k8s_tools.get_deployment_summaries(ns)), captured_at)
+        deployments = k8s_tools.get_deployment_summaries(ns)
+        state["deployments"] += _encode_all(redactor(deployments), captured_at)
         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)
+        statefulsets = k8s_tools.get_statefulset_summaries(ns)
+        state["statefulsets"] += _encode_all(redactor(statefulsets), captured_at)
+        daemonsets = k8s_tools.get_daemonset_summaries(ns)
+        state["daemonsets"] += _encode_all(redactor(daemonsets), captured_at)
+        # The tool's own result, not raw templates: replay serves it as is, and
+        # env values never reach the file.
+        for kind, workloads in (("Deployment", deployments), ("StatefulSet", statefulsets),
+                                ("DaemonSet", daemonsets)):
+            for w in workloads:
+                state["workload_histories"].append(encode_model(
+                    redactor(k8s_tools.get_workload_history(w.name, ns, kind)), 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)

{k8stools-2.3.0 → k8stools-2.4.0}/src/k8stools/fixtures/otel-demo.json

@@ -476,6 +476,26 @@
             "key": "node.kubernetes.io/unreachable",
             "operator": "Exists"
           }
+        ],
+        "volumes": [
+          {
+            "name": "opentelemetry-collector-configmap",
+            "config_map": {
+              "name": "otel-collector-agent",
+              "items": [
+                {
+                  "key": "relay",
+                  "path": "relay.yaml"
+                }
+              ]
+            }
+          },
+          {
+            "name": "hostfs",
+            "host_path": {
+              "path": "/"
+            }
+          }
         ]
       },
       "logs": {
@@ -939,6 +959,13 @@
       "age_seconds": 777605.0,
       "data": {},
       "binary_data_keys": []
+    },
+    {
+      "name": "otel-collector-agent",
+      "namespace": "default",
+      "key_count": 1,
+      "data_size": 234,
+      "age_seconds": 691200.0
     }
   ],
   "statefulsets": [
@@ -971,6 +998,173 @@
       "age_seconds": 691200.0
     }
   ],
+  "workload_histories": [
+    {
+      "kind": "Deployment",
+      "name": "ad",
+      "namespace": "default",
+      "revisions": [
+        {
+          "revision": 2,
+          "source": "ReplicaSet/ad-647b4947cc",
+          "age_seconds": 27240.0,
+          "current": true,
+          "reused": false,
+          "images": [
+            "ghcr.io/open-telemetry/demo:2.2.0-ad"
+          ],
+          "compared_with": 1,
+          "changes": [
+            {
+              "field": "containers[ad].image",
+              "change": "changed",
+              "before": "ghcr.io/open-telemetry/demo:2.0.2-ad",
+              "after": "ghcr.io/open-telemetry/demo:2.2.0-ad"
+            },
+            {
+              "field": "containers[ad].env[OTEL_RESOURCE_ATTRIBUTES]",
+              "change": "removed",
+              "before": null,
+              "after": null
+            }
+          ],
+          "metadata_changes": [
+            {
+              "field": "metadata.labels[app.kubernetes.io/version]",
+              "change": "changed",
+              "before": "2.0.2",
+              "after": "2.2.0"
+            }
+          ],
+          "rollout_restart": false
+        },
+        {
+          "revision": 1,
+          "source": "ReplicaSet/ad-d5c94c49b",
+          "age_seconds": 691199.0,
+          "current": false,
+          "reused": false,
+          "images": [
+            "ghcr.io/open-telemetry/demo:2.0.2-ad"
+          ],
+          "compared_with": null,
+          "changes": [],
+          "metadata_changes": [],
+          "rollout_restart": false
+        }
+      ],
+      "config": [],
+      "complete": true,
+      "limits": [
+        "Only pod-template changes are recorded. Replica counts, autoscaling and the update strategy are not, and neither are changes outside the cluster (feature flags, traffic, dependencies).",
+        "Kubernetes keeps 10 old revisions (revisionHistoryLimit); older ones are deleted, so the oldest listed revision is not necessarily the first.",
+        "A revision's age is when its ReplicaSet was created. A rollback reuses an older one (reused=true), which then went live later than its age says.",
+        "Env var values are never shown, only names. Secret contents and change times are not read.",
+        "A ConfigMap's last_written is its latest write of any kind, including label-only changes such as a Helm upgrade: it does not show that the data changed."
+      ]
+    },
+    {
+      "kind": "Deployment",
+      "name": "test-deployment",
+      "namespace": "default",
+      "revisions": [
+        {
+          "revision": 1,
+          "source": "ReplicaSet/test-deployment-7d4b9c85f",
+          "age_seconds": 7199.0,
+          "current": true,
+          "reused": false,
+          "images": [
+            "ghcr.io/open-telemetry/demo:2.2.0-cart"
+          ],
+          "compared_with": null,
+          "changes": [],
+          "metadata_changes": [],
+          "rollout_restart": false
+        }
+      ],
+      "config": [],
+      "complete": true,
+      "limits": [
+        "Only pod-template changes are recorded. Replica counts, autoscaling and the update strategy are not, and neither are changes outside the cluster (feature flags, traffic, dependencies).",
+        "Kubernetes keeps 10 old revisions (revisionHistoryLimit); older ones are deleted, so the oldest listed revision is not necessarily the first.",
+        "A revision's age is when its ReplicaSet was created. A rollback reuses an older one (reused=true), which then went live later than its age says.",
+        "Env var values are never shown, only names. Secret contents and change times are not read.",
+        "A ConfigMap's last_written is its latest write of any kind, including label-only changes such as a Helm upgrade: it does not show that the data changed."
+      ]
+    },
+    {
+      "kind": "StatefulSet",
+      "name": "postgres",
+      "namespace": "default",
+      "revisions": [
+        {
+          "revision": 1,
+          "source": "ControllerRevision/postgres-5d8f6c7b9",
+          "age_seconds": 259200.0,
+          "current": true,
+          "reused": false,
+          "images": [
+            "postgres:16.4"
+          ],
+          "compared_with": null,
+          "changes": [],
+          "metadata_changes": [],
+          "rollout_restart": false
+        }
+      ],
+      "config": [],
+      "complete": true,
+      "limits": [
+        "Only pod-template changes are recorded. Replica counts, autoscaling and the update strategy are not, and neither are changes outside the cluster (feature flags, traffic, dependencies).",
+        "Kubernetes keeps 10 old revisions (revisionHistoryLimit); older ones are deleted, so the oldest listed revision is not necessarily the first.",
+        "A revision's age is when its ControllerRevision was created. A rollback reuses an older one (reused=true), which then went live later than its age says.",
+        "Env var values are never shown, only names. Secret contents and change times are not read.",
+        "A ConfigMap's last_written is its latest write of any kind, including label-only changes such as a Helm upgrade: it does not show that the data changed."
+      ]
+    },
+    {
+      "kind": "DaemonSet",
+      "name": "otel-collector-agent",
+      "namespace": "default",
+      "revisions": [
+        {
+          "revision": 1,
+          "source": "ControllerRevision/otel-collector-agent-7bfc667c67",
+          "age_seconds": 691200.0,
+          "current": true,
+          "reused": false,
+          "images": [
+            "otel/opentelemetry-collector-contrib:0.142.0"
+          ],
+          "compared_with": null,
+          "changes": [],
+          "metadata_changes": [],
+          "rollout_restart": false
+        }
+      ],
+      "config": [
+        {
+          "kind": "ConfigMap",
+          "name": "otel-collector-agent",
+          "used_as": [
+            "volume"
+          ],
+          "exists": true,
+          "age_seconds": 691200.0,
+          "last_written_seconds": 691200.0
+        }
+      ],
+      "complete": true,
+      "limits": [
+        "Only pod-template changes are recorded. Replica counts, autoscaling and the update strategy are not, and neither are changes outside the cluster (feature flags, traffic, dependencies).",
+        "Kubernetes keeps 10 old revisions (revisionHistoryLimit); older ones are deleted, so the oldest listed revision is not necessarily the first.",
+        "A revision's age is when its ControllerRevision was created. A rollback reuses an older one (reused=true), which then went live later than its age says.",
+        "Env var values are never shown, only names. Secret contents and change times are not read.",
+        "A ConfigMap's last_written is its latest write of any kind, including label-only changes such as a Helm upgrade: it does not show that the data changed."
+      ]
+    }
+  ],
   "cronjobs": [
     {
       "name": "cleanup",