Merge pull request #44390 from sftim/20231216_revise_statefulset_tutorial

Add comments to shell snippets in StatefulSet tutorial

Author: k8s-ci-robot

content/en/docs/tutorials/stateful-application/basic-stateful-set.md

@@ -81,7 +81,9 @@ You will need to use at least two terminal windows. In the first terminal, use
 of the StatefulSet's Pods.
 
 ```shell
-kubectl get pods -w -l app=nginx
+# use this terminal to run commands that specify --watch
+# end this watch when you are asked to start a new watch
+kubectl get pods --watch -l app=nginx
 ```
 
 In the second terminal, use
@@ -122,7 +124,9 @@ created sequentially, ordered from _{0..n-1}_. Examine the output of the
 look like the example below.
 
 ```shell
-kubectl get pods -w -l app=nginx
+# Do not start a new watch;
+# this should already be running
+kubectl get pods --watch -l app=nginx
 ```
 ```
 NAME      READY     STATUS    RESTARTS   AGE
@@ -221,7 +225,9 @@ contain the Pods' IP addresses.
 In one terminal, watch the StatefulSet's Pods:
 
 ```shell
-kubectl get pod -w -l app=nginx
+# Start a new watch
+# End this watch when you've seen that the delete is finished
+kubectl get pod --watch -l app=nginx
 ```
 In a second terminal, use
 [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands/#delete) to delete all
@@ -239,7 +245,8 @@ Wait for the StatefulSet to restart them, and for both Pods to transition to
 Running and Ready:
 
 ```shell
-kubectl get pod -w -l app=nginx
+# This should already be running
+kubectl get pod --watch -l app=nginx
 ```
 ```
 NAME      READY     STATUS              RESTARTS   AGE
@@ -364,7 +371,9 @@ before retrying the `curl` command above.
 In one terminal, watch the StatefulSet's Pods:
 
 ```shell
-kubectl get pod -w -l app=nginx
+# End this watch when you've reached the end of the section.
+# At the start of "Scaling a StatefulSet" you'll start a new watch.
+kubectl get pod --watch -l app=nginx
 ```
 
 In a second terminal, delete all of the StatefulSet's Pods:
@@ -380,7 +389,8 @@ Examine the output of the `kubectl get` command in the first terminal, and wait
 for all of the Pods to transition to Running and Ready.
 
 ```shell
-kubectl get pod -w -l app=nginx
+# This should already be running
+kubectl get pod --watch -l app=nginx
 ```
 ```
 NAME      READY     STATUS              RESTARTS   AGE
@@ -421,7 +431,10 @@ This is accomplished by updating the `replicas` field. You can use either
 In one terminal window, watch the Pods in the StatefulSet:
 
 ```shell
-kubectl get pods -w -l app=nginx
+# If you already have a watch running, you can continue using that.
+# Otherwise, start one.
+# End this watch when there are 5 healthy Pods for the StatefulSet
+kubectl get pods --watch -l app=nginx
 ```
 
 In another terminal window, use `kubectl scale` to scale the number of replicas
@@ -438,7 +451,8 @@ Examine the output of the `kubectl get` command in the first terminal, and wait
 for the three additional Pods to transition to Running and Ready.
 
 ```shell
-kubectl get pods -w -l app=nginx
+# This should already be running
+kubectl get pod --watch -l app=nginx
 ```
 ```
 NAME      READY     STATUS    RESTARTS   AGE
@@ -470,7 +484,8 @@ subsequent Pod.
 In one terminal, watch the StatefulSet's Pods:
 
 ```shell
-kubectl get pods -w -l app=nginx
+# End this watch when there are only 3 Pods for the StatefulSet
+kubectl get pod --watch -l app=nginx
 ```
 
 In another terminal, use `kubectl patch` to scale the StatefulSet back down to
@@ -486,7 +501,8 @@ statefulset.apps/web patched
 Wait for `web-4` and `web-3` to transition to Terminating.
 
 ```shell
-kubectl get pods -w -l app=nginx
+# This should already be running
+kubectl get pods --watch -l app=nginx
 ```
 ```
 NAME      READY     STATUS              RESTARTS   AGE
@@ -565,7 +581,10 @@ statefulset.apps/web patched
 In another terminal, watch the Pods in the StatefulSet:
 
 ```shell
-kubectl get pod -l app=nginx -w
+# End this watch when the rollout is complete
+#
+# If you're not sure, leave it running one more minute
+kubectl get pod -l app=nginx --watch
 ```
 The output is similar to:
 ```
@@ -671,7 +690,8 @@ pod "web-2" deleted
 Wait for the Pod to be Running and Ready.
 
 ```shell
-kubectl get pod -l app=nginx -w
+# End the watch when you see that web-2 is healthy
+kubectl get pod -l app=nginx --watch
 ```
 ```
 NAME      READY     STATUS              RESTARTS   AGE
@@ -703,6 +723,8 @@ you specified [above](#staging-an-update).
 Patch the StatefulSet to decrement the partition:
 
 ```shell
+# The value of "partition" should match the highest existing ordinal for
+# the StatefulSet
 kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":2}}}}'
 ```
 ```
@@ -712,7 +734,8 @@ statefulset.apps/web patched
 Wait for `web-2` to be Running and Ready.
 
 ```shell
-kubectl get pod -l app=nginx -w
+# This should already be running
+kubectl get pod -l app=nginx --watch
 ```
 ```
 NAME      READY     STATUS              RESTARTS   AGE
@@ -748,7 +771,8 @@ pod "web-1" deleted
 Wait for the `web-1` Pod to be Running and Ready.
 
 ```shell
-kubectl get pod -l app=nginx -w
+# This should already be running
+kubectl get pod -l app=nginx --watch
 ```
 The output is similar to:
 ```
@@ -801,7 +825,8 @@ statefulset.apps/web patched
 Wait for all of the Pods in the StatefulSet to become Running and Ready.
 
 ```shell
-kubectl get pod -l app=nginx -w
+# This should already be running
+kubectl get pod -l app=nginx --watch
 ```
 The output is similar to:
 ```
@@ -856,7 +881,8 @@ deleted.
 In one terminal window, watch the Pods in the StatefulSet.
 
 ```
-kubectl get pods -w -l app=nginx
+# End this watch when there are no Pods for the StatefulSet
+kubectl get pods --watch -l app=nginx
 ```
 
 Use [`kubectl delete`](/docs/reference/generated/kubectl/kubectl-commands/#delete) to delete the
@@ -909,7 +935,8 @@ As the `web` StatefulSet has been deleted, `web-0` has not been relaunched.
 In one terminal, watch the StatefulSet's Pods.
 
 ```shell
-kubectl get pods -w -l app=nginx
+# Leave this watch running until the next time you start a watch
+kubectl get pods --watch -l app=nginx
 ```
 
 In a second terminal, recreate the StatefulSet. Note that, unless
@@ -930,7 +957,8 @@ headless Service even though that Service already exists.
 Examine the output of the `kubectl get` command running in the first terminal.
 
 ```shell
-kubectl get pods -w -l app=nginx
+# This should already be running
+kubectl get pods --watch -l app=nginx
 ```
 ```
 NAME      READY     STATUS    RESTARTS   AGE
@@ -977,7 +1005,8 @@ PersistentVolume was remounted.
 In one terminal window, watch the Pods in the StatefulSet.
 
 ```shell
-kubectl get pods -w -l app=nginx
+# Leave this running until the next page section
+kubectl get pods --watch -l app=nginx
 ```
 
 In another terminal, delete the StatefulSet again. This time, omit the
@@ -995,7 +1024,8 @@ Examine the output of the `kubectl get` command running in the first terminal,
 and wait for all of the Pods to transition to Terminating.
 
 ```shell
-kubectl get pods -w -l app=nginx
+# This should already be running
+kubectl get pods --watch -l app=nginx
 ```
 
 ```
@@ -1108,7 +1138,8 @@ of the `web` StatefulSet is set to `Parallel`.
 In one terminal, watch the Pods in the StatefulSet.
 
 ```shell
-kubectl get pod -l app=nginx -w
+# Leave this watch running until the end of the section
+kubectl get pod -l app=nginx --watch
 ```
 
 In another terminal, create the StatefulSet and Service in the manifest:
@@ -1124,7 +1155,8 @@ statefulset.apps/web created
 Examine the output of the `kubectl get` command that you executed in the first terminal.
 
 ```shell
-kubectl get pod -l app=nginx -w
+# This should already be running
+kubectl get pod -l app=nginx --watch
 ```
 ```
 NAME      READY     STATUS    RESTARTS   AGE
@@ -1177,7 +1209,8 @@ kubectl delete sts web
 
 You can watch `kubectl get` to see those Pods being deleted.
 ```shell
-kubectl get pod -l app=nginx -w
+# end the watch when you've seen what you need to
+kubectl get pod -l app=nginx --watch
 ```
 ```
 web-3     1/1       Terminating   0         9m