k8stools 2.0.2__tar.gz → 2.0.4__tar.gz

{k8stools-2.0.2 → k8stools-2.0.4}/CLAUDE.md

@@ -24,6 +24,7 @@ tests/
   test_capture.py            - Capture serialization round-trip and capture-time redaction
   test_k8s_tools_realk8s.py  - Integration tests (real cluster, auto-skipped if unreachable)
   test_mock_tools.py         - Tests for mock_tools module (incl. parity with k8s_tools.TOOLS)
+  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
 ```
@@ -60,10 +61,45 @@ Tools in `k8s_tools.py` follow three patterns:
 2. **API-typed** — Pydantic models that match K8s client types with lesser-used fields omitted (e.g. `get_pod_container_statuses`)
 3. **Raw dict** — `to_dict()` on the K8s client object; return type is `dict[str, Any]` with fields documented in the docstring (e.g. `get_pod_spec`)
 
-Use `datetime.timedelta` for age/duration fields. Use snake_case field names. Include `pod_name`/`namespace` in container-level models for context.
+Use the `Duration` type (`k8s_tools.Duration`) for age/duration fields, not a bare
+`datetime.timedelta`. It is a `timedelta` that normalizes to whole, non-negative
+seconds on validation. Pydantic describes a `timedelta` as
+`{"type": "string", "format": "duration"}` but serializes a microsecond-bearing one
+as `"P2DT5M27.978616S"`; JSON Schema's `duration` format points at RFC 3339
+Appendix A, whose grammar allows neither a decimal point nor a sign. An MCP client
+that validates structured output against the declared schema (ajv does; Python's
+`jsonschema` skips `duration` unless the optional `isoduration` extra is installed)
+therefore rejected the whole call, on every row of every list tool. Since every age
+is `now() - <k8s timestamp>` and Kubernetes timestamps are whole-second, the
+fractional part was never information — just the microseconds of that one `now()`.
+This is the same rule `MockState`'s replay clock already applies, for the same
+reason. `tests/test_duration_format.py` checks each model's serialized output
+against the format its own schema declares.
+
+Use snake_case field names. Include `pod_name`/`namespace` in container-level models for context.
 
 All tools are collected in the `TOOLS` list in `k8s_tools.py` for agent/MCP registration.
 
+The log readers decode the response themselves and pass `_preload_content=False`.
+The log endpoint is the only call whose body is a bare scalar rather than a model,
+and the generated client declares its response type as `str`, then produces it with
+`str(data)`. Since kubernetes 36 the body reaching that call is `bytes` (older
+clients decoded it in `rest.py`), so it returned `repr(bytes)` — one `b'...'` line
+with newlines as the two characters `\n`, useless as logs and silently breaking any
+caller that greps. Asking for the raw response and decoding in
+`_decode_log_response` bypasses that deserialization; non-2xx responses still raise
+`ApiException` either way, so error handling is unchanged. Decoding is
+`errors="replace"`, not strict: container logs are arbitrary bytes and `limit_bytes`
+truncates at a byte offset that can split a character. Don't set
+`_preload_content=True` here again — `tests/test_log_decoding.py` pins it off, and a
+test fake that returns `str` hides the whole failure, which is how it shipped.
+
+`previous=True` has three Kubernetes behaviors that read as bugs (identical output
+during CrashLoopBackOff, a restart shifting the window between two calls, and a
+reclaimed log file answering 200 with `unable to retrieve container logs`). They are
+documented in the tool's docstring — which is the MCP tool description — and in
+README's "Previous-instance log semantics". Don't "fix" them in code.
+
 `print_*` companion functions exist for each `get_*` summary/spec function — for human-readable debugging output only. The log readers (`get_logs_for_pod_and_container`, `get_logs_for_job`, `get_logs_for_cronjob`) have no `print_*` companion since they already return a printable string.
 
 ## Error handling
@@ -163,6 +199,35 @@ keys) and values under keys/env-var names matching
 separators and camelCase, so `apiKey` matches and `VALKEY_ADDR` does not),
 replacing them with a visible `[REDACTED]` marker.
 
+Redaction is **span-granular, with two deliberate exceptions.** A matched token
+(AWS key, JWT) is replaced where it sits, leaving the surrounding text readable.
+The exceptions:
+
+- **PEM blocks go whole.** The pattern matches only the `-----BEGIN ... PRIVATE
+  KEY-----` header, and the secret is the base64 body *after* it — substituting
+  just the matched span would black out the header and publish the key. Hence the
+  `_TOKEN_SHAPE_RES` / `_CONTAINMENT_SHAPE_RES` split: never move a pattern into
+  the former unless its match is the entire secret.
+- **A string that parses as a JSON object/array is recursed into** and
+  re-serialized, rather than treated as one opaque value. Config-as-JSON under a
+  single ConfigMap key is common, and opacity failed in both directions: one
+  incidental token match blacked out an entire non-secret config file, while a real
+  `{"password": ...}` inside a blob was invisible to the name rule and passed
+  through verbatim. Nothing is re-serialized when nothing matched, so clean values
+  keep their exact formatting.
+
+  The `key` exemption below applies *inside* these blobs too. Lifting it there
+  looked obviously right — those names are the author's, not Kubernetes schema —
+  and re-measuring said otherwise: on the 38-pod cluster it added 12 redactions,
+  every one `tags[].key: "instance"` in a Grafana dashboard ConfigMap, and no
+  secrets. Structural `key` fields dominate inside config documents just as they do
+  in the API. With the exemption kept, this whole change is redaction-neutral on
+  that cluster: same 6 redactions, same paths, same values as before it.
+
+`bytes` values are decoded, redacted, and re-encoded rather than falling through
+to the scalar branch — no tool returns bytes now that the log readers decode at the
+API boundary, but that branch is what let container logs nearly escape this pass.
+
 A field named *exactly* `key` is exempt — in the Kubernetes API that is always
 structural (taint, map entry, label selector, projected-volume item), never a
 credential. Before that exemption a real 38-pod capture produced 139 redactions of

{k8stools-2.0.2 → k8stools-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 2.0.2
+Version: 2.0.4
 Summary: Tools and an MCP server for building Kubernetes agents
 Project-URL: Homepage, https://github.com/BenedatLLC/k8stools
 Author: Jeff Fischer
@@ -283,7 +283,7 @@ These are the tools we define:
 * `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
-* `get_logs_for_pod_and_container` - retrieves logs from a pod and container (supports `tail`, `since_seconds`, and `previous`)
+* `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_service_summaries` - get a list of services, like `kubectl get services` (includes `selector`/labels/annotations)
@@ -567,6 +567,26 @@ summary reports how many could not be read (the previous instance may have been
 garbage-collected), because a crash-loop capture that lost them looks identical to
 one that never had any.
 
+### Previous-instance log semantics
+
+`previous=True` asks the kubelet for the container's last *terminated* instance.
+Three of its behaviors read as bugs and are not, and all three show up in captures
+as well as in live queries:
+
+- **In CrashLoopBackOff, both calls return the same text.** There is no running
+  instance during the backoff, so the kubelet serves the most recently terminated
+  one for `previous=False` too. Check `get_pod_container_statuses` before
+  concluding the flag was ignored.
+- **A restart between two calls shifts the window.** The instance that was current
+  becomes the previous one, so a container crash-looping every few seconds can
+  return byte-identical output for both. Compare the log timestamps, not the flag.
+- **A reclaimed log file returns 200, not an error**, with the body
+  `unable to retrieve container logs for <container-id>`. It is a successful call
+  whose content is an error message.
+
+Only the single most recent terminated instance is retained; there is no way to
+reach further back than one.
+
 ### Replay clock
 
 Every age in a capture is stored relative to the moment of capture, so the

{k8stools-2.0.2 → k8stools-2.0.4}/README.md

@@ -64,7 +64,7 @@ These are the tools we define:
 * `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
-* `get_logs_for_pod_and_container` - retrieves logs from a pod and container (supports `tail`, `since_seconds`, and `previous`)
+* `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_service_summaries` - get a list of services, like `kubectl get services` (includes `selector`/labels/annotations)
@@ -348,6 +348,26 @@ summary reports how many could not be read (the previous instance may have been
 garbage-collected), because a crash-loop capture that lost them looks identical to
 one that never had any.
 
+### Previous-instance log semantics
+
+`previous=True` asks the kubelet for the container's last *terminated* instance.
+Three of its behaviors read as bugs and are not, and all three show up in captures
+as well as in live queries:
+
+- **In CrashLoopBackOff, both calls return the same text.** There is no running
+  instance during the backoff, so the kubelet serves the most recently terminated
+  one for `previous=False` too. Check `get_pod_container_statuses` before
+  concluding the flag was ignored.
+- **A restart between two calls shifts the window.** The instance that was current
+  becomes the previous one, so a container crash-looping every few seconds can
+  return byte-identical output for both. Compare the log timestamps, not the flag.
+- **A reclaimed log file returns 200, not an error**, with the body
+  `unable to retrieve container logs for <container-id>`. It is a successful call
+  whose content is an error message.
+
+Only the single most recent terminated instance is retained; there is no way to
+reach further back than one.
+
 ### Replay clock
 
 Every age in a capture is stored relative to the moment of capture, so the

{k8stools-2.0.2 → k8stools-2.0.4}/pyproject.toml

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

k8stools-2.0.4/redaction-bug.md

@@ -0,0 +1,25 @@
+# get_configmap / ConfigMap.data redaction: a single value-shape match anywhere in a JSON-serialized ConfigMap value blacks out the entire value, not just the match
+## Repro:
+any ConfigMap whose data value is a JSON-encoded blob (common pattern: config-as-JSON-string under one key) where some substring incidentally matches the JWT/AKIA/PEM regexes.
+
+## Impact:
+legitimate, non-secret operational config (in our case: warm-runtime pool target count) becomes fully unreadable via the MCP tool, forcing a workaround (grep-ing cronjob logs instead).
+
+## Suggested fixes (in rough order of effort):
+* When a string value looks like JSON (json.loads succeeds), recurse redaction into the parsed structure and re-serialize, instead of treating it as one opaque string.
+* At minimum, redact only the matched span within the string (rx.sub(REDACTED, s)) rather than replacing the whole value when a partial match is found — this alone would have kept the rest of warm-runtimes.json visible.
+* Note in output when a value is a "detected JSON string with an internal match" vs. a flat credential-shaped value, so callers can tell which failure mode they hit.
+
+## What we saw
+Reading the warm-runtimes-config ConfigMap in openhands-cloud-c3:
+```
+{
+  "name": "warm-runtimes-config",
+  "namespace": "openhands-cloud-c3",
+  "data": {
+    "warm-runtimes.json": "[REDACTED]"
+  },
+  "binary_data_keys": []
+}
+```
+The whole value came back redacted, even though this ConfigMap is just warm-pool sizing config (count, runtime spec names) — nothing secret. We had to fall back to the reconciler's own log line (Missing N runtimes for v1, creating N warm runtimes...) to get the real number (5).

{k8stools-2.0.2 → k8stools-2.0.4}/src/k8stools/__init__.py

@@ -78,4 +78,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.0.2"
+__version__ = "2.0.4"

{k8stools-2.0.2 → k8stools-2.0.4}/src/k8stools/k8s_tools.py

@@ -16,9 +16,9 @@ import sys
 import os
 import logging
 import datetime
-from typing import Optional, Union, Literal, Any
+from typing import Optional, Union, Literal, Any, Annotated
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, AfterValidator
 import yaml
 
 from kubernetes import client, config
@@ -85,12 +85,47 @@ def _get_batch_v1_api_client() -> client.BatchV1Api:
             raise K8sConfigError(f"Unexpected error: {e}") from e
 
 
+def _to_whole_seconds(td: datetime.timedelta) -> datetime.timedelta:
+    """Truncate a duration to whole seconds, flooring at zero.
+
+    Both adjustments keep the value inside the grammar our own JSON Schema
+    declares for it (see :data:`Duration`).
+
+    Truncation: every age here is ``now() - <k8s timestamp>``, and Kubernetes
+    timestamps are whole-second, so the sub-second part of an age is nothing but
+    the microseconds of the ``now()`` that happened to compute it - noise, and
+    identical across every row of a single response. This matches the rule
+    ``MockState``'s replay clock already follows for the same reason.
+
+    Flooring: a cluster whose clock is ahead of ours yields a small negative age,
+    which pydantic renders as ``-PT5S``. A duration has no sign in this grammar,
+    so clamp it; at this granularity "just created" is the honest reading anyway.
+    """
+    return datetime.timedelta(seconds=max(int(td.total_seconds()), 0))
+
+
+#: A ``timedelta`` field on a response model.
+#:
+#: Pydantic's default JSON Schema for ``timedelta`` is
+#: ``{"type": "string", "format": "duration"}``, but its default *serialization*
+#: emits fractional seconds (``"P2DT5M27.978616S"``) whenever the value carries
+#: microseconds. JSON Schema's ``duration`` format references RFC 3339 Appendix A,
+#: whose grammar admits only integer components - so pydantic's own schema and its
+#: own serializer disagree, and an MCP client that validates structured output
+#: against the declared schema (ajv does; Python's ``jsonschema`` skips ``duration``
+#: unless the optional ``isoduration`` extra is installed) rejects the tool call
+#: outright, on every row, before the caller sees any data.
+#:
+#: Normalizing the value rather than the schema keeps ``format: "duration"``
+#: accurate and keeps direct Python callers' fields real ``timedelta`` objects.
+Duration = Annotated[datetime.timedelta, AfterValidator(_to_whole_seconds)]
+
 
 class NamespaceSummary(BaseModel):
     """Summary information about a namespace, like returned by `kubectl get namespace`"""
     name: str
     status: str
-    age: datetime.timedelta
+    age: Duration
 
 
 def get_namespaces() -> list[NamespaceSummary]:
@@ -142,7 +177,7 @@ class NodeSummary(BaseModel):
     name: str
     status: str
     roles: list[str]
-    age: datetime.timedelta
+    age: Duration
     version: str
     internal_ip: Optional[str] = None
     external_ip: Optional[str] = None
@@ -347,8 +382,8 @@ class PodSummary(BaseModel):
     total_containers: int
     ready_containers: int
     restarts: int
-    last_restart: Optional[datetime.timedelta]
-    age: datetime.timedelta
+    last_restart: Optional[Duration]
+    age: Duration
     ip: Optional[str] = None
     node: Optional[str] = None
 
@@ -501,7 +536,7 @@ def _format_timedelta(td: Optional[datetime.timedelta]) -> str:
 
 class EventSummary(BaseModel):
     """This is the representation of a Kubernetes Event"""
-    last_seen: Optional[datetime.timedelta]  # Time since event occurred
+    last_seen: Optional[Duration]  # Time since event occurred
     type: str
     reason: str
     object: str
@@ -864,6 +899,35 @@ def print_pod_spec(pod_name: str, namespace: str = "default") -> None:
         print(f"Error printing pod spec: {e}")
 
 
+def _decode_log_response(resp: Any) -> str:
+    """Decode what ``read_namespaced_pod_log`` hands back into usable text.
+
+    The log endpoint serves ``text/plain``, but the generated client declares the
+    response type as ``str`` and runs the body through
+    ``ApiClient.__deserialize_primitive``, which is ``str(data)``. Since
+    kubernetes 36 the body arriving there is ``bytes`` (older clients decoded it
+    in ``rest.py``), so that call yields ``repr(bytes)`` - one ``b'...'`` line
+    with every newline as the two characters ``\\n``. That is useless as logs and
+    silently breaks anything a caller greps for. Requesting the raw response and
+    decoding here bypasses that deserialization entirely; status handling is
+    unaffected, since the REST client raises ``ApiException`` for non-2xx
+    responses whether or not the content was preloaded.
+
+    ``errors="replace"`` rather than strict: container logs are arbitrary bytes,
+    and ``limit_bytes`` truncates at a byte offset that can land inside a
+    multi-byte character, so a ``UnicodeDecodeError`` here would fail a whole
+    investigation over one bad byte.
+    """
+    # The raw urllib3 response carries the body on `.data`; a preloaded response
+    # is already a str, and is passed through rather than decoded twice.
+    data = None if resp is None else getattr(resp, "data", resp)
+    if data is None:
+        return ''
+    if isinstance(data, bytes):
+        return data.decode("utf-8", errors="replace")
+    return data if isinstance(data, str) else str(data)
+
+
 def get_logs_for_pod_and_container(pod_name:str, namespace:str = "default",
                                     container_name:Optional[str]=None,
                                     tail:Optional[int]=None,
@@ -890,8 +954,36 @@ def get_logs_for_pod_and_container(pod_name:str, namespace:str = "default",
                               where the current instance's logs are empty or
                               post-restart. Fails if there is no previous instance.
 
+                              Three Kubernetes behaviors make `previous=True`
+                              look as though it were ignored or broken; none is a
+                              fault in this tool, and all are worth knowing before
+                              drawing a conclusion from the output:
+
+                              * While a container sits in CrashLoopBackOff there
+                                is no running instance, so the kubelet serves the
+                                most recently *terminated* one for `previous=False`
+                                as well - both calls then return the same text.
+                                Check the container's state with
+                                `get_pod_container_statuses` before concluding the
+                                flag had no effect.
+                              * A restart between two calls shifts the window: the
+                                instance that was current becomes the previous one,
+                                so a container crash-looping every few seconds can
+                                legitimately return identical bytes for both.
+                                Compare the log timestamps, not just the flag.
+                              * Once the previous instance's log file has been
+                                reclaimed, the API answers 200 with the text
+                                `unable to retrieve container logs for <id>` -
+                                a successful call whose body is an error message,
+                                not a raised error.
+
+                              Only the single most recent terminated instance is
+                              retained by the kubelet; there is no way to reach
+                              further back than one.
+
     Returns:
-        str, optional: Log content if any found for this pod/container, or None otherwise
+        str: The log content as text, with real newlines. An empty string if the
+             container has produced no log output (never None).
 
     Raises
     ------
@@ -912,7 +1004,7 @@ def get_logs_for_pod_and_container(pod_name:str, namespace:str = "default",
             namespace=namespace,
             container=container_name,  # Pass container_name if specified
             follow=False,              # Set to False to get all current logs
-            _preload_content=True,     # Important: This loads all content into memory
+            _preload_content=False,    # Raw response; see _decode_log_response()
             timestamps=True,           # Optional: Include timestamps
             tail_lines=tail if tail is not None else 1000,  # Default: last 1000 lines
             limit_bytes=1024*1024,     # Limit to 1MB to avoid memory issues
@@ -923,11 +1015,9 @@ def get_logs_for_pod_and_container(pod_name:str, namespace:str = "default",
             log_kwargs["previous"] = True
         resp = K8S.read_namespaced_pod_log(**log_kwargs)
 
-        # The response is a single string containing all logs
-        if resp:
-            return resp
-        else:
-            return ''
+        # A single string containing all logs, with real newlines. An empty log
+        # is '', never None - callers treat the two the same.
+        return _decode_log_response(resp)
     except client.ApiException as e:
         raise K8sApiError(f"Error fetching logs: {e}") from e
     except Exception as e:
@@ -942,7 +1032,7 @@ class DeploymentSummary(BaseModel):
     ready_replicas: int
     up_to_date_relicas: int
     available_replicas: int
-    age: datetime.timedelta
+    age: Duration
 
 def get_deployment_summaries(namespace: Optional[str] = None) -> list[DeploymentSummary]:
     """
@@ -1047,7 +1137,7 @@ class ReplicaSetSummary(BaseModel):
     current_replicas: int
     ready_replicas: int
     images: list[str]
-    age: datetime.timedelta
+    age: Duration
 
 
 def get_replicaset_summaries(namespace: Optional[str] = None,
@@ -1227,7 +1317,7 @@ class ServiceSummary(BaseModel):
     cluster_ip: Optional[str] = None
     external_ip: Optional[str] = None
     ports: list[PortInfo]
-    age: datetime.timedelta
+    age: Duration
     selector: dict[str, str] = Field(default_factory=dict)
     labels: dict[str, str] = Field(default_factory=dict)
     annotations: dict[str, str] = Field(default_factory=dict)
@@ -1378,7 +1468,7 @@ class ConfigMapSummary(BaseModel):
     namespace: str
     key_count: int
     data_size: int  # total bytes across all values (data + binary_data)
-    age: datetime.timedelta
+    age: Duration
 
 
 def _configmap_key_count_and_size(config_map) -> tuple[int, int]:
@@ -1548,7 +1638,7 @@ class StatefulSetSummary(BaseModel):
     current_replicas: int
     update_strategy: str
     service_name: Optional[str] = None
-    age: datetime.timedelta
+    age: Duration
 
 
 def get_statefulset_summaries(namespace: Optional[str] = None) -> list[StatefulSetSummary]:
@@ -1679,9 +1769,9 @@ class CronJobSummary(BaseModel):
     schedule: str
     suspend: bool
     active: int
-    last_schedule_time: Optional[datetime.timedelta] = None
-    last_successful_time: Optional[datetime.timedelta] = None
-    age: datetime.timedelta
+    last_schedule_time: Optional[Duration] = None
+    last_successful_time: Optional[Duration] = None
+    age: Duration
     containers: list[ContainerTemplateSummary] = Field(default_factory=list)
 
 
@@ -1791,10 +1881,10 @@ class JobSummary(BaseModel):
     active: int
     succeeded: int
     failed: int
-    start_time: Optional[datetime.timedelta] = None
-    completion_time: Optional[datetime.timedelta] = None
+    start_time: Optional[Duration] = None
+    completion_time: Optional[Duration] = None
     conditions: list[str] = Field(default_factory=list)
-    age: datetime.timedelta
+    age: Duration
     containers: list[ContainerTemplateSummary] = Field(default_factory=list)
 
 
@@ -1954,6 +2044,10 @@ def get_logs_for_job(job_name: str, namespace: str = "default",
         If set, only return logs newer than this many seconds.
     previous : bool, default False
         If True, return logs from the previous terminated container instance.
+        See `get_logs_for_pod_and_container` for the cases - CrashLoopBackOff, a
+        restart racing the call, a reclaimed log file - where that legitimately
+        returns the same text as `previous=False`, or a 200 whose body is an
+        error message.
 
     Returns
     -------
@@ -2001,6 +2095,10 @@ def get_logs_for_cronjob(cronjob_name: str, namespace: str = "default",
         If set, only return logs newer than this many seconds.
     previous : bool, default False
         If True, return logs from the previous terminated container instance.
+        See `get_logs_for_pod_and_container` for the cases - CrashLoopBackOff, a
+        restart racing the call, a reclaimed log file - where that legitimately
+        returns the same text as `previous=False`, or a 200 whose body is an
+        error message.
 
     Returns
     -------
@@ -2041,7 +2139,7 @@ class PVCSummary(BaseModel):
     access_modes: list[str] = Field(default_factory=list)
     storage_class: Optional[str] = None
     mounted_by: list[str] = Field(default_factory=list)
-    age: datetime.timedelta
+    age: Duration
 
 
 def get_pvc_summaries(namespace: Optional[str] = None) -> list[PVCSummary]:

{k8stools-2.0.2 → k8stools-2.0.4}/src/k8stools/mock_state.py

@@ -76,9 +76,18 @@ class CaptureFormatError(Exception):
 # ---------------------------------------------------------------------------
 
 def _annotation_contains(annotation: Any, target: type) -> bool:
-    """True if ``target`` appears anywhere in ``annotation`` (unwrapping Optional/Union)."""
+    """True if ``target`` appears anywhere in ``annotation``.
+
+    Unwraps ``Optional``/``Union`` and ``Annotated``. The latter matters because
+    ``k8s_tools.Duration`` is an annotated ``timedelta``: pydantic strips the
+    metadata from a bare field's ``annotation`` but keeps it inside an
+    ``Optional[...]``, so without this an optional duration would silently encode
+    under its plain name instead of ``<field>_seconds`` and fail to round-trip.
+    """
     if annotation is target:
         return True
+    if hasattr(annotation, "__metadata__"):  # Annotated[X, ...] -> X
+        return _annotation_contains(typing.get_args(annotation)[0], target)
     origin = typing.get_origin(annotation)
     if origin is Union or origin is types.UnionType:
         return any(_annotation_contains(arg, target) for arg in typing.get_args(annotation))