From 8f8cff4a75aacb3e6d7ca593a05aaeec237708ed Mon Sep 17 00:00:00 2001
From: Xiu Juan Xiang <xigxjn@cn.ibm.com>
Date: Mon, 9 Nov 2020 16:03:43 +0800
Subject: [PATCH] Add a document to show how to configure Thread, QPS and Burst

---
 .../configuring-qps-burst-thread.md           | 42 +++++++++++++++++++
 docs/install.md                               |  4 ++
 2 files changed, 46 insertions(+)
 create mode 100644 docs/developers/configuring-qps-burst-thread.md

diff --git a/docs/developers/configuring-qps-burst-thread.md b/docs/developers/configuring-qps-burst-thread.md
new file mode 100644
index 00000000000..183ec51856f
--- /dev/null
+++ b/docs/developers/configuring-qps-burst-thread.md
@@ -0,0 +1,42 @@
+# Configure ThreadsPerController, QPS and Burst
+
+- [Overview](#overview)
+- [Configuring Thread, QPS and Burst](#configuring-thread-qps-and-burst)
+
+## Overview
+
+---
+This document will show us how to configure the ThreadsPerController, QPS and Burst of [tekton-pipeline-controller](../../config/controller.yaml) when maintainers or developers wants to overwrite them.
+
+- `ThreadsPerController`: Threads (goroutines) to create per controller. It's the number of threads to use when processing the controller's work queue.
+
+- `QPS`: Queries per Second. Maximum QPS to the master from this client.
+
+- `Burst`: Maximum burst for throttle.
+
+## Configuring Thread, QPS and Burst
+
+---
+Default, the value of ThreadsPerController, QPS and Burst is [2](https://github.com/knative/pkg/blob/master/controller/controller.go#L58), [5.0](https://github.com/tektoncd/pipeline/blob/master/vendor/k8s.io/client-go/rest/config.go#L44) and [10](https://github.com/tektoncd/pipeline/blob/master/vendor/k8s.io/client-go/rest/config.go#L45) accordingly.
+
+Sometimes, above default values can't meet performance requirements, then you need to overwrite these values. You can modify them in the [tekton controller deployment](../../config/controller.yaml). You can specify these customized values in the `tekton-pipelines-controller` container via `threads-per-controller`, `kube-api-qps` and `kube-api-burst` flags accordingly. For example:
+
+```yaml
+spec:
+  serviceAccountName: tekton-pipelines-controller
+  containers:
+  - name: tekton-pipelines-controller
+    image: ko://github.com/tektoncd/pipeline/cmd/controller
+    args: [
+      "-kube-api-qps", "50",
+      "-kube-api-burst", "50",
+      "-threads-per-controller", "32",
+      # other flags defined here...
+    ]
+```
+
+Now, the ThreadsPerController, QPS and Burst have been changed to be `32`, `50` and `50`.
+
+**Note**:
+Although in above example, you set QPS and Burst to be `50` and `50`. However, the actual values of them are [multiplied by `2`](https://github.com/pierretasci/pipeline/blob/master/cmd/controller/main.go#L83-L84), so the actual QPS and Burst is `100` and `100`.
+
diff --git a/docs/install.md b/docs/install.md
index db75258a4a3..96af2cf1b1c 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -363,6 +363,10 @@ data:
 
 To customize the behavior of HA for the Tekton Pipelines controller, please refer to the related [documentation](developers/enabling-ha.md).
 
+## Overwriting the ThreadsPerController, QPS and Burst
+
+If you want to modify the default ThreadsPerController, QPS and Burst to meet your performance requirements, then please refer to this [guidance](developers/configuring-qps-burst-thread.md).
+
 ## Creating a custom release of Tekton Pipelines
 
 You can create a custom release of Tekton Pipelines by following and customizing the steps in [Creating an official release](https://github.com/tektoncd/pipeline/blob/master/tekton/README.md#create-an-official-release). For example, you might want to customize the container images built and used by Tekton Pipelines.