Review remarks

Co-authored-by: Qiming Teng <tengqm@outlook.com>
Co-authored-by: Tim Bannister <22591623+sftim@users.noreply.github.com>

Author: 3 people

content/en/docs/concepts/workloads/controllers/job.md

@@ -383,6 +383,8 @@ from failed Jobs is not lost inadvertently.
 
 ### Backoff limit per index {#backoff-limit-per-index}
 
+{{< feature-state feature_gate_name="JobBackoffLimitPerIndex" >}}
+
 When you run an [indexed](#completion-mode) Job, you can choose to handle retries
 for pod failures independently for each index. To do so, set the
 `.spec.backoffLimitPerIndex` to specify the maximal number of pod failures

content/en/docs/tasks/job/pod-failure-policy.md

@@ -244,49 +244,53 @@ The cluster automatically cleans up the Pods.
 
 ## Using Pod Failure Policy to avoid unnecessary Pod retries per index
 
-With the following example, you can learn how to use Pod failure policy and
-Backoff limit per index features to avoid unnecessary Pod restarts per index.
+To avoid unnecessary Pod restarts per index, you can use the _Pod failure policy_ and
+_backoff limit per index_ features. This section of the page shows how to use these features
+together.
 
-1. First, create a Job based on the config:
+1. Save the following manifest as `job-backoff-limit-per-index-failindex.yaml`:
+
+   {{% code_sample file="/controllers/job-backoff-limit-per-index-failindex.yaml" %}}
+
+1. Apply the manifest:
 
-  {{% code_sample file="/controllers/job-backoff-limit-per-index-failindex.yaml" %}}
+   ```sh
+   kubectl create -f job-backoff-limit-per-index-failindex.yaml
+   ```
 
-  by running:
+1. After around 15 seconds, inspect the status of the Pods for the Job. You can do that by running:
 
-  ```sh
-  kubectl create -f job-backoff-limit-per-index-failindex.yaml
-  ```
+   ```shell
+   kubectl get pods -l job-name=job-backoff-limit-per-index-failindex -o yaml
+   ```
 
-2. After a while inspect the status of the job's Pods by running:
+   You will see output similar to this:
 
-  ```sh
-  kubectl get pods -l job-name=job-backoff-limit-per-index-failindex -o yaml
-  ```
+   ```none
+   NAME                                            READY   STATUS      RESTARTS   AGE
+   job-backoff-limit-per-index-failindex-0-4g4cm   0/1     Error       0          4s
+   job-backoff-limit-per-index-failindex-0-fkdzq   0/1     Error       0          15s
+   job-backoff-limit-per-index-failindex-1-2bgdj   0/1     Error       0          15s
+   job-backoff-limit-per-index-failindex-2-vs6lt   0/1     Completed   0          11s
+   job-backoff-limit-per-index-failindex-3-s7s47   0/1     Completed   0          6s
+   ```
 
-  You will see output similar to this:
-  ```yaml
-NAME                                            READY   STATUS      RESTARTS   AGE
-job-backoff-limit-per-index-failindex-0-4g4cm   0/1     Error       0          4s
-job-backoff-limit-per-index-failindex-0-fkdzq   0/1     Error       0          15s
-job-backoff-limit-per-index-failindex-1-2bgdj   0/1     Error       0          15s
-job-backoff-limit-per-index-failindex-2-vs6lt   0/1     Completed   0          11s
-job-backoff-limit-per-index-failindex-3-s7s47   0/1     Completed   0          6s
-  ```
+   Note that the output shows the following:
 
-  Note that there are two Pods with index 0, because the backoff limit allowed
-  for one retry of the index. At the same time, there is only one Pod with index
-  1, because the exit code of the failed Pod matched the Pod failure policy with
-  the FailIndex action.
+   * Two Pods have index 0, because of the backoff limit allowed for one retry
+   of the index.
+   * Only one Pod has index 1, because the exit code of the failed Pod matched
+   the Pod failure policy with the `FailIndex` action.
 
-3. Inspect the status of the Job by running:
+1. Inspect the status of the Job by running:
 
-  ```sh
-  kubectl get jobs -l job-name=job-backoff-limit-per-index-failindex -o yaml
-  ```
+   ```sh
+   kubectl get jobs -l job-name=job-backoff-limit-per-index-failindex -o yaml
+   ```
 
-  In the Job status, see the `failedIndexes` field shows "0,1", because both
-  indexes failed. Since the index 1 was not retried the number of failed Pods,
-  indicated by the status field "failed" equals 3.
+   In the Job status, see that the `failedIndexes` field shows "0,1", because
+   both indexes failed. Because the index 1 was not retried the number of failed
+   Pods, indicated by the status field "failed" equals 3.
 
 ### Cleaning up
 

content/en/examples/controllers/job-backoff-limit-per-index-failindex.yaml

@@ -12,10 +12,10 @@ spec:
       restartPolicy: Never
       containers:
       - name: main
-        image: python
+        image: docker.io/library/python:3
         command:
           # The script:
-          # - fails the Pod with index 0 with exit code 1 which result in retry,
+          # - fails the Pod with index 0 with exit code 1, which results in one retry;
           # - fails the Pod with index 1 with exit code 42 which results
           #   in failing the index without retry.
           # - succeeds Pods with any other index.