fix docs and add max-result-size optional feature flag

Fixing some formatting issues in docs. Added a reference to the additional-configs
to the tasks.md to learn the complete list of instructions on how to enable
larger results using sidecar logs.

Signed-off-by: Priti Desai <[email protected]>

config/config-feature-flags.yaml

@@ -110,6 +110,10 @@ data:
   # "sidecar-logs" is an experimental feature and thus should still be considered
   # an alpha feature.
   results-from: "termination-message"
+  # Setting this flag will determine the upper limit of each task result
+  # This flag is optional and only associated with the previous flag, results-from
+  # When results-from is set to "sidecar-logs", this flag can be used to configure the upper limit of a task result
+  # max-result-size: "4096"
   # Setting this flag to "true" will limit privileges for containers injected by Tekton into TaskRuns.
   # This allows TaskRuns to run in namespaces with "restricted" pod security standards.
   # Not all Kubernetes implementations support this option.

docs/additional-configs.md

@@ -341,25 +341,33 @@ Features currently in "beta" are:
 
 ## Enabling larger results using sidecar logs
 
-**Note**: The maximum size of a Task's results is limited by the container termination message feature of Kubernetes, as results are passed back to the controller via this mechanism. At present, the limit is per task is “4096 bytes”. All results produced by the task share this upper limit.
+**Note**: The maximum size of a Task's results is limited by the container termination message feature of Kubernetes,
+as results are passed back to the controller via this mechanism. At present, the limit is per task is “4096 bytes”. All
+results produced by the task share this upper limit.
 
-To exceed this limit of 4096 bytes, you can enable larger results using sidecar logs. By enabling this feature, you will have a configurable limit (with a default of 4096 bytes) per result with no restriction on the number of results. The results are still stored in the taskrun crd so they should not exceed the 1.5MB CRD size limit.
+To exceed this limit of 4096 bytes, you can enable larger results using sidecar logs. By enabling this feature, you will
+have a configurable limit (with a default of 4096 bytes) per result with no restriction on the number of results. The
+results are still stored in the taskRun CRD, so they should not exceed the 1.5MB CRD size limit.
 
-**Note**: to enable this feature, you need to grant `get` access to all `pods/log` to the `Tekton pipeline controller`. This means that the tekton pipeline controller has the ability to access the pod logs.
+**Note**: to enable this feature, you need to grant `get` access to all `pods/log` to the `tekton-pipelines-controller`.
+This means that the tekton pipeline controller has the ability to access the pod logs.
 
 1. Create a cluster role and rolebinding by applying the following spec to provide log access to `tekton-pipelines-controller`.
 
 ```
 kubectl apply -f optional_config/enable-log-access-to-controller/
 ```
 
-2. Set the `results-from` feature flag to use sidecar logs by setting `results-from: sidecar-logs` in the [configMap](#customizing-the-pipelines-controller-behavior).
+2. Set the `results-from` feature flag to use sidecar logs by setting `results-from: sidecar-logs` in the
+[configMap](#customizing-the-pipelines-controller-behavior).
 
 ```
 kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"results-from":"sidecar-logs"}}'
 ```
 
-3. If you want the size per result to be something other than 4096 bytes, you can set the `max-result-size` feature flag in bytes by setting `max-result-size: 8192(whatever you need here)`. **Note:** The value you can set here cannot exceed the size of the CRD limit of 1.5 MB.
+3. If you want the size per result to be something other than 4096 bytes, you can set the `max-result-size` feature flag
+in bytes by setting `max-result-size: 8192(whatever you need here)`. **Note:** The value you can set here cannot exceed
+the size of the CRD limit of 1.5 MB.
 
 ```
 kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"max-result-size":"<VALUE-IN-BYTES>"}}'

docs/tasks.md

@@ -944,13 +944,26 @@ As a general rule-of-thumb, if a result needs to be larger than a kilobyte, you
 
 #### Larger `Results` using sidecar logs
 
-This is an experimental feature. The `results-from` feature flag must be set to `"sidecar-logs"`](./install.md#enabling-larger-results-using-sidecar-logs).
-
-Instead of using termination messages to store results, the taskrun controller injects a sidecar container which monitors the results of all the steps. The sidecar mounts the volume where results of all the steps are stored. As soon as it finds a new result, it logs it to std out. The controller has access to the logs of the sidecar container (Caution: we need you to enable access to [kubernetes pod/logs](./install.md#enabling-larger-results-using-sidecar-logs).
-
-This feature allows users to store up to 4 KB per result by default. Because we are not limited by the size of the termination messages, users can have as many results as they require (or until the CRD reaches its limit). If the size of a result exceeds this limit, then the TaskRun will be placed into a failed state with the following message: `Result exceeded the maximum allowed limit.`
-
-**Note**: If you require even larger results, you can specify a different upper limit per result by setting `max-result-size` feature flag to your desired size in bytes ([see instructions](./install.md#enabling-larger-results-using-sidecar-logs)). **CAUTION**: the larger you make the size, more likely will the CRD reach its max limit enforced by the `etcd` server leading to bad user experience.
+This is an alpha feature which is guarded behind its own feature flag.  The `results-from` feature flag must be set to
+[`"sidecar-logs"`](./install.md#enabling-larger-results-using-sidecar-logs) to enable larger results using sidecar logs.
+
+Instead of using termination messages to store results, the taskrun controller injects a sidecar container which monitors
+the results of all the steps. The sidecar mounts the volume where results of all the steps are stored. As soon as it
+finds a new result, it logs it to std out. The controller has access to the logs of the sidecar container.
+**CAUTION**: we need you to enable access to [kubernetes pod/logs](./install.md#enabling-larger-results-using-sidecar-logs).
+
+This feature allows users to store up to 4 KB per result by default. Because we are not limited by the size of the
+termination messages, users can have as many results as they require (or until the CRD reaches its limit). If the size
+of a result exceeds this limit, then the TaskRun will be placed into a failed state with the following message: `Result
+exceeded the maximum allowed limit.`
+
+**Note**: If you require even larger results, you can specify a different upper limit per result by setting
+`max-result-size` feature flag to your desired size in bytes ([see instructions](./install.md#enabling-larger-results-using-sidecar-logs)).
+**CAUTION**: the larger you make the size, more likely will the CRD reach its max limit enforced by the `etcd` server
+leading to bad user experience.
+
+Refer to the detailed instructions listed in [additional config](additional-configs.md#enabling-larger-results-using-sidecar-logs)
+to learn how to enable this feature.
 
 ### Specifying `Volumes`