k8stools 2.0.3__tar.gz → 2.0.4__tar.gz

{k8stools-2.0.3 → 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
 ```
@@ -79,6 +80,26 @@ Use snake_case field names. Include `pod_name`/`namespace` in container-level mo
 
 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
@@ -203,6 +224,10 @@ The exceptions:
   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.3 → k8stools-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 2.0.3
+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.3 → 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.3 → k8stools-2.0.4}/pyproject.toml

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

{k8stools-2.0.3 → 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.3"
+__version__ = "2.0.4"

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

@@ -899,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,
@@ -925,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
     ------
@@ -947,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
@@ -958,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:
@@ -1989,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
     -------
@@ -2036,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
     -------

{k8stools-2.0.3 → k8stools-2.0.4}/src/k8stools/redaction.py

@@ -234,6 +234,19 @@ def _redact(value: Any, key_is_sensitive: bool = False) -> tuple[Any, int]:
     if isinstance(value, str):
         return _redact_string(value, key_is_sensitive)
 
+    if isinstance(value, bytes):
+        # No tool returns bytes today - `get_logs_for_pod_and_container` decodes at
+        # the API boundary - but letting them fall through to the scalar branch at
+        # the end would publish the single largest payload we handle unredacted,
+        # which is how container logs nearly escaped this pass (issue #6). Redact
+        # the decoded text and hand back bytes, so the caller's type is unchanged
+        # and a future bytes-returning tool cannot silently repeat it.
+        text, count = _redact_string(value.decode("utf-8", errors="replace"),
+                                     key_is_sensitive)
+        # Nothing is re-encoded when nothing matched, for the same reason nothing is
+        # re-serialized in `_redact_json_string`: clean values keep their exact bytes.
+        return (text.encode("utf-8"), count) if count else (value, 0)
+
     if isinstance(value, BaseModel):
         count = 0
         for name in type(value).model_fields:
@@ -275,6 +288,7 @@ def _redact(value: Any, key_is_sensitive: bool = False) -> tuple[Any, int]:
         return value, count
 
     # int / float / bool / None / datetime / timedelta / etc. — never secret-shaped.
+    # Anything that can carry text is handled above, not here.
     return value, 0
 
 

{k8stools-2.0.3 → k8stools-2.0.4}/tests/test_k8s_tools.py

@@ -135,8 +135,10 @@ class MockK8S:
         )
         return SimpleNamespace(items=[event1, event2])
 
-    def read_namespaced_pod_log(self, name, namespace, container=None, follow=False, _preload_content=True, timestamps=True, tail_lines=None, limit_bytes=None):
-        # Return a sample log string for testing
+    def read_namespaced_pod_log(self, name, namespace, container=None, follow=False, _preload_content=False, timestamps=True, tail_lines=None, limit_bytes=None):
+        # Returns an already-decoded str, unlike the bytes-bearing response the real
+        # client hands back; this is the deliberate counterpart to MockCoreV1 in
+        # test_new_tools.py, and covers the pass-through (no double-decode) branch.
         if name == "pod-1" and namespace == "default" and container == "container-1":
             return "2025-07-12T00:00:00Z container-1 log line 1\n2025-07-12T00:01:00Z container-1 log line 2"
         return ""

{k8stools-2.0.3 → k8stools-2.0.4}/tests/test_k8s_tools_realk8s.py

@@ -155,8 +155,20 @@ def test_retrieve_logs_for_pod_and_container():
     
     pod_name = running_pod.metadata.name
     try:
-        logs = k8s_tools.get_logs_for_pod_and_container(pod_name, "default")
+        logs = k8s_tools.get_logs_for_pod_and_container(pod_name, "default", tail=5)
         assert isinstance(logs, str)
+        if logs:
+            # Real text, not `repr(bytes)` - the failure mode of issue #6, which only
+            # a real client reproduces (a fake returning str hides it entirely).
+            assert not logs.startswith("b'")
+            assert "\\n" not in logs
+            assert logs.count("\n") <= 5
+            # Every line is timestamped, so a decoded log always has a real newline.
+            assert logs.endswith("\n")
+        # `previous` is not asserted to differ from the above: while a container is in
+        # CrashLoopBackOff the kubelet serves the same terminated instance for both,
+        # and a reclaimed log file comes back 200 with "unable to retrieve container
+        # logs". Both are correct, so the only stable assertion is on the format.
     except k8s_tools.K8sApiError as e:
         # If we still get an error (e.g., no logs available yet), that's acceptable for this test
         # We just want to make sure the function doesn't crash unexpectedly

k8stools-2.0.4/tests/test_log_decoding.py

@@ -0,0 +1,147 @@
+"""Tests for log decoding at the Kubernetes API boundary (issue #6).
+
+`read_namespaced_pod_log` is the only tool call whose response is a bare scalar
+rather than a model, and the generated client stringifies its body with
+`str(data)`. Since kubernetes 36 that body is `bytes`, so the client returns
+`repr(bytes)`: one `b'...'` line with newlines as the two characters `\\n`.
+`get_logs_for_pod_and_container` therefore asks for the raw response and decodes
+it itself; these tests pin that down from both directions, plus the redaction and
+`previous`-plumbing behavior that depends on it.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from k8stools import k8s_tools
+from k8stools.redaction import REDACTED, redact_object, wrap_with_redaction
+
+
+class FakeLogApi:
+    """Stands in for CoreV1Api, returning whatever body the test hands it."""
+
+    def __init__(self, body):
+        self.body = body
+        self.last_log_kwargs = None
+
+    def read_namespaced_pod_log(self, **kwargs):
+        self.last_log_kwargs = kwargs
+        if isinstance(self.body, (bytes, str)) or self.body is None:
+            # The raw urllib3 response carries the body on `.data`.
+            return SimpleNamespace(data=self.body)
+        return self.body
+
+
+@pytest.fixture
+def fake_api(monkeypatch):
+    def install(body):
+        api = FakeLogApi(body)
+        monkeypatch.setattr(k8s_tools, "K8S", api)
+        return api
+    return install
+
+
+# --- decoding ---------------------------------------------------------------
+
+LOG_BYTES = (b"2026-09-19T00:00:00Z line one\n"
+             b"2026-09-19T00:00:01Z line two\n"
+             b"2026-09-19T00:00:02Z line three\n")
+
+
+def test_bytes_body_decoded_to_text(fake_api):
+    fake_api(LOG_BYTES)
+    logs = k8s_tools.get_logs_for_pod_and_container("pod-1", "default", "c")
+    assert isinstance(logs, str)
+    assert not logs.startswith("b'")
+    assert logs.count("\n") == 3          # real newlines...
+    assert "\\n" not in logs              # ...not the two characters of an escape
+    assert logs.splitlines()[0].endswith("line one")
+
+
+def test_str_body_passed_through_not_double_decoded(fake_api):
+    """A client that decodes for us (or a preloaded response) must not be re-decoded."""
+    fake_api("2026-09-19T00:00:00Z already text\n")
+    logs = k8s_tools.get_logs_for_pod_and_container("pod-1", "default", "c")
+    assert logs == "2026-09-19T00:00:00Z already text\n"
+
+
+def test_bare_str_response_without_data_attribute(monkeypatch):
+    """A preloaded response is a bare str with no `.data` at all; still fine."""
+    class PreloadedApi:
+        def read_namespaced_pod_log(self, **kwargs):
+            return "plain string response"
+
+    monkeypatch.setattr(k8s_tools, "K8S", PreloadedApi())
+    assert k8s_tools.get_logs_for_pod_and_container("pod-1") == "plain string response"
+
+
+def test_invalid_utf8_does_not_raise(fake_api):
+    """`limit_bytes` truncates at a byte offset, which can split a character."""
+    fake_api(b"2026-09-19T00:00:00Z caf\xe9 \xf0\x9f\x92 truncated\n")
+    logs = k8s_tools.get_logs_for_pod_and_container("pod-1", "default", "c")
+    assert "�" in logs
+    assert "truncated" in logs
+
+
+@pytest.mark.parametrize("body", [b"", None])
+def test_empty_log_is_empty_string(fake_api, body):
+    fake_api(body)
+    assert k8s_tools.get_logs_for_pod_and_container("pod-1", "default", "c") == ''
+
+
+def test_raw_response_requested(fake_api):
+    """Flipping `_preload_content` back on reintroduces `repr(bytes)`; pin it off."""
+    api = fake_api(LOG_BYTES)
+    k8s_tools.get_logs_for_pod_and_container("pod-1", "default", "c")
+    assert api.last_log_kwargs["_preload_content"] is False
+
+
+# --- redaction --------------------------------------------------------------
+
+SECRET_LOG = (b"2026-09-19T00:00:00Z starting up\n"
+              b"2026-09-19T00:00:01Z using key AKIAIOSFODNN7EXAMPLE\n")
+
+
+@pytest.mark.parametrize("body", [SECRET_LOG, SECRET_LOG.decode()])
+def test_secret_in_logs_is_redacted(fake_api, body):
+    """Logs are the largest and most secret-prone payload the server returns;
+    they must not escape the redaction boundary in either response shape."""
+    fake_api(body)
+    tool = wrap_with_redaction(k8s_tools.get_logs_for_pod_and_container)
+    logs = tool("pod-1", "default", "c")
+    assert "AKIAIOSFODNN7EXAMPLE" not in logs
+    assert REDACTED in logs
+    assert "starting up" in logs          # span-granular: the rest stays readable
+
+
+def test_bytes_are_redacted_not_passed_through():
+    """Defence in depth: bytes reaching `_redact` directly are handled, not
+    dropped into the never-secret-shaped scalar branch."""
+    out, count = redact_object({"blob": b"token AKIAIOSFODNN7EXAMPLE here"})
+    assert count == 1
+    assert isinstance(out["blob"], bytes)
+    assert b"AKIAIOSFODNN7EXAMPLE" not in out["blob"]
+    assert REDACTED.encode() in out["blob"]
+
+
+def test_clean_bytes_keep_their_exact_value():
+    original = b"nothing secret here\n\xff\xfe"
+    out, count = redact_object({"blob": original})
+    assert count == 0
+    assert out["blob"] == original        # not re-encoded, so no lossy round-trip
+
+
+# --- `previous` plumbing ----------------------------------------------------
+
+def test_previous_forwarded_once(fake_api):
+    api = fake_api(LOG_BYTES)
+    k8s_tools.get_logs_for_pod_and_container("pod-1", "default", "c", previous=True)
+    assert api.last_log_kwargs["previous"] is True
+
+
+def test_previous_false_omits_the_key(fake_api):
+    """The API rejects `previous` for a container with no terminated instance, so
+    the key is left out entirely rather than sent as False."""
+    api = fake_api(LOG_BYTES)
+    k8s_tools.get_logs_for_pod_and_container("pod-1", "default", "c")
+    assert "previous" not in api.last_log_kwargs

{k8stools-2.0.3 → k8stools-2.0.4}/tests/test_new_tools.py

@@ -113,7 +113,10 @@ class MockCoreV1:
 
     def read_namespaced_pod_log(self, name, namespace, container=None, **kwargs):
         self.last_log_kwargs = dict(name=name, namespace=namespace, container=container, **kwargs)
-        return f"logs for {name}"
+        # Faithful to the real client under `_preload_content=False`: the raw
+        # response object, with the body as bytes on `.data`. A fake returning a
+        # plain str is what let the repr-of-bytes bug (issue #6) reach a release.
+        return SimpleNamespace(data=f"logs for {name}".encode())
 
     # --- events ---
     def list_event_for_all_namespaces(self, field_selector=None):