From 387153787a103b6cb9e002be33598b3e50464f61 Mon Sep 17 00:00:00 2001
From: Jian Zeng <anonymousknight96@gmail.com>
Date: Thu, 17 Oct 2024 23:21:18 +0800
Subject: [PATCH] doc: document the usage of the PodLogsQuerySplitStreams
 feature

Signed-off-by: Jian Zeng <anonymousknight96@gmail.com>
---
 .../cluster-administration/logging.md         | 31 +++++++++++++++++++
 .../pod-logs-query-split-streams.md           | 13 ++++++++
 .../en/examples/debug/counter-pod-err.yaml    | 10 ++++++
 3 files changed, 54 insertions(+)
 create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/pod-logs-query-split-streams.md
 create mode 100644 content/en/examples/debug/counter-pod-err.yaml

diff --git a/content/en/docs/concepts/cluster-administration/logging.md b/content/en/docs/concepts/cluster-administration/logging.md
index 5cc9429578..e7a3724bb1 100644
--- a/content/en/docs/concepts/cluster-administration/logging.md
+++ b/content/en/docs/concepts/cluster-administration/logging.md
@@ -75,6 +75,37 @@ appending a container name to the command, with a `-c` flag, like so:
 kubectl logs counter -c count
 ```
 
+
+### Container log streams
+
+{{< feature-state feature_gate_name="PodLogsQuerySplitStreams" >}}
+
+As an alpha feature, the kubelet can split out the logs from the two standard streams produced
+by a container: [standard output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout))
+and [standard error](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
+To use this behavior, you must enable the `PodLogsQuerySplitStreams`
+[feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
+With that feature gate enabled, Kubernetes {{< skew currentVersion >}} allows access to these
+log streams directly via the Pod API. You can fetch a specific stream by specifying the stream name (either `Stdout` or `Stderr`),
+using the `stream` query string. You must have access to read the `log` subresource of that Pod.
+
+To demonstrate this feature, you can create a Pod that periodically writes text to both the standard output and error stream.
+
+{{% code_sample file="debug/counter-pod-err.yaml" %}}
+
+To run this pod, use the following command:
+
+```shell
+kubectl apply -f https://k8s.io/examples/debug/counter-pod-err.yaml
+```
+
+To fetch only the stderr log stream, you can run:
+
+```shell
+kubectl get --raw "/api/v1/namespaces/default/pods/counter-err/log?stream=Stderr"
+```
+
+
 See the [`kubectl logs` documentation](/docs/reference/generated/kubectl/kubectl-commands#logs)
 for more details.
 
diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/pod-logs-query-split-streams.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/pod-logs-query-split-streams.md
new file mode 100644
index 0000000000..ba7a066d0a
--- /dev/null
+++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/pod-logs-query-split-streams.md
@@ -0,0 +1,13 @@
+---
+title: PodLogsQuerySplitStreams
+content_type: feature_gate
+_build:
+  list: never
+  render: false
+
+stages:
+  - stage: alpha
+    defaultValue: false
+    fromVersion: "1.32"
+---
+Enable fetching specific log streams (either stdout or stderr) from a container's log streams, using the Pod API.
diff --git a/content/en/examples/debug/counter-pod-err.yaml b/content/en/examples/debug/counter-pod-err.yaml
new file mode 100644
index 0000000000..d9d2327528
--- /dev/null
+++ b/content/en/examples/debug/counter-pod-err.yaml
@@ -0,0 +1,10 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: counter-err
+spec:
+  containers:
+  - name: count
+    image: busybox:1.28
+    args: [/bin/sh, -c,
+            'i=0; while true; do echo "$i: $(date)"; echo "$i: err" >&2 ; i=$((i+1)); sleep 1; done']