openshift · rolfedh · Nov 30, 2021
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -1463,6 +1463,8 @@ Topics:
     File: working-with-pipelines-using-the-developer-perspective
   - Name: Reducing resource consumption of OpenShift Pipelines
     File: reducing-pipelines-resource-consumption
+  - Name: Setting compute resource quota for OpenShift Pipelines
+    File: setting-compute-resource-quota-for-openshift-pipelines
   - Name: Using pods in a privileged security context
     File: using-pods-in-a-privileged-security-context
   - Name: Securing webhooks with event listeners

diff --git a/cicd/pipelines/reducing-pipelines-resource-consumption.adoc b/cicd/pipelines/reducing-pipelines-resource-consumption.adoc
@@ -1,5 +1,5 @@
 [id="reducing-pipelines-resource-consumption"]
-= Reducing resource consumption of pipelines
+= Reducing resource consumption of OpenShift Pipelines
 include::modules/common-attributes.adoc[]
 include::modules/pipelines-document-attributes.adoc[]
 :context: reducing-pipelines-resource-consumption
@@ -20,8 +20,10 @@ include::modules/op-understanding-pipelines-resource-consumption.adoc[leveloffse
 
 include::modules/op-mitigating-extra-pipeline-resource-consumption.adoc[leveloffset=+1]
 
-== Additional Resources
+[id="additional-resources_reducing-pipelines-resource-consumption"]
+== Additional resources
 
-* xref:../../applications/quotas/quotas-setting-per-project.html[Resource Quotas]
+* xref:../../cicd/pipelines/setting-compute-resource-quota-for-openshift-pipelines.adoc[Setting compute resource quota for OpenShift Pipelines]
+* xref:../../applications/quotas/quotas-setting-per-project.html[Resource quotas per project]
 * xref:../../nodes/clusters/nodes-cluster-limit-ranges.html[Restricting resource consumption using limit ranges]
 * link:https://kubernetes.io/docs/concepts/workloads/pods/init-containers/#resources[Resource requests and limits in Kubernetes]
diff --git a/cicd/pipelines/setting-compute-resource-quota-for-openshift-pipelines.adoc b/cicd/pipelines/setting-compute-resource-quota-for-openshift-pipelines.adoc
@@ -0,0 +1,37 @@
+[id="setting-compute-resource-quota-for-openshift-pipelines"]
+= Setting compute resource quota for OpenShift Pipelines
+include::modules/common-attributes.adoc[]
+include::modules/pipelines-document-attributes.adoc[]
+:context: setting-compute-resource-quota-for-pipelines
+
+toc::[]
+
+
+A `ResourceQuota` object in {pipelines-title} controls the total resource consumption per namespace. You can use it to limit the quantity of objects created in a namespace, based on the type of the object. In addition, you can specify a compute resource quota to restrict the total amount of compute resources consumed in a namespace. 
+
+However, you might want to limit the amount of compute resources consumed by pods resulting from a pipeline run, rather than setting quotas for the entire namespace. Currently, {pipelines-title} does not enable you to directly specify the compute resource quota for a pipeline.  
+
+include::modules/op-alternative-approaches-compute-resource-quota-pipelines.adoc[leveloffset=+1]
+
+[NOTE]
+====
+When using {pipelines-title} in a namespace configured with a `ResourceQuota` object, the pods resulting from task runs and pipeline runs might fail with an error, such as: `failed quota: <quota name> must specify cpu, memory`. 
+
+To avoid this error, do any one of the following:
+
+* (Recommended) Specify a limit range for the namespace.
+* Explicitly define requests and limits for all containers.
+
+For more information, refer to the link:https://issues.redhat.com/browse/SRVKP-1801[issue] and the link:https://access.redhat.com/solutions/2841971[resolution].
+====
+
+If your use case is not addressed by these approaches, you can implement a workaround by using a resource quota for a priority class.
+
+include::modules/op-specifying-pipelines-resource-quota-using-priority-class.adoc[leveloffset=+1]
+
+[id="additional-references_setting-compute-resource-quota-for-pipelines"]
+== Additional resources
+
+* link:https://kubernetes.io/docs/concepts/policy/resource-quotas/[Resource quotas in Kubernetes]
+* link:https://kubernetes.io/docs/concepts/policy/limit-range/[Limit ranges in Kubernetes]
+* link:https://kubernetes.io/docs/concepts/workloads/pods/init-containers/#resources[Resource requests and limits in Kubernetes]
diff --git a/modules/op-alternative-approaches-compute-resource-quota-pipelines.adoc b/modules/op-alternative-approaches-compute-resource-quota-pipelines.adoc
@@ -0,0 +1,37 @@
+// This module is included in the following assembly:
+//
+// */cicd/pipelines/setting-compute-resource-quota-for-openshift-pipelines.adoc
+
+
+[id="alternative-approaches-compute-resource-quota-pipelines_{context}"]
+= Alternative approaches for limiting compute resource consumption in OpenShift Pipelines
+
+To attain some degree of control over the usage of compute resources by a pipeline, consider the following alternative approaches:
+
+* Set resource requests and limits for each step in a task.
++
+.Example: Set resource requests and limits for each step in a task.
++ 
+[source,yaml]
+----
+...
+spec:
+  steps:
+    - name: step-with-limts
+      resources:
+        requests:
+          memory: 1Gi
+          cpu: 500m
+        limits:
+          memory: 2Gi
+          cpu: 800m
+...
+----
+
+* Set resource limits by specifying values for the `LimitRange` object. For more information on `LimitRange`, refer to xref:../../nodes/clusters/nodes-cluster-limit-ranges.adoc[Restrict resource consumption with limit ranges].
+
+* xref:../../cicd/pipelines/reducing-pipelines-resource-consumption.adoc[Reduce pipeline resource consumption].
+
+* Set and manage xref:../../applications/quotas/quotas-setting-per-project.adoc[resource quotas per project].
+
+* Ideally, the compute resource quota for a pipeline should be same as the total amount of compute resources consumed by the concurrently running pods in a pipeline run. However, the pods running the tasks consume compute resources based on the use case. For example, a Maven build task might require different compute resources for different applications that it builds. As a result, you cannot predetermine the compute resource quotas for tasks in a generic pipeline. For greater predictability and control over usage of compute resources, use customized pipelines for different applications.
diff --git a/modules/op-specifying-pipelines-resource-quota-using-priority-class.adoc b/modules/op-specifying-pipelines-resource-quota-using-priority-class.adoc
@@ -0,0 +1,198 @@
+// This module is included in the following assembly:
+//
+// */cicd/pipelines/setting-compute-resource-quota-for-openshift-pipelines.adoc
+
+
+[id="specifying-pipelines-resource-quota-using-priority-class_{context}"]
+= Specifying pipelines resource quota using priority class
+
+A `PriorityClass` object maps priority class names to the integer values that indicates their relative priorities. Higher values increase the priority of a class. After you create a priority class, you can create pods that specify the priority class name in their specifications. In addition, you can control a pod's consumption of system resources based on the pod's priority.
+
+Specifying resource quota for a pipeline is similar to setting a resource quota for the subset of pods created by a pipeline run. The following steps provide an example of the workaround by specifying resource quota based on priority class.
+
+.Procedure
+
+. Create a priority class for a pipeline.
++
+.Example: Priority class for a pipeline
+[source,yaml]
+----
+apiVersion: scheduling.k8s.io/v1
+kind: PriorityClass
+metadata:
+  name: pipeline1-pc
+value: 1000000
+description: "Priority class for pipeline1"
+----
+
+. Create a resource quota for a pipeline.
++
+.Example: Resource quota for a pipeline
+[source,yaml]
+----
+apiVersion: v1
+kind: ResourceQuota
+metadata:
+  name: pipeline1-rq
+spec:
+  hard:
+    cpu: "1000"
+    memory: 200Gi
+    pods: "10"
+  scopeSelector:
+    matchExpressions:
+    - operator : In
+      scopeName: PriorityClass
+      values: ["pipeline1-pc"]
+----
+
+. Verify the resource quota usage for the pipeline.
++
+.Example: Verify resource quota usage for the pipeline
+[source,terminal]
+----
+$ kubectl describe quota
+
+Name:       pipeline1-rq
+Namespace:  default
+Resource    Used  Hard
+--------    ----  ----
+cpu         0     1k
+memory      0     200Gi
+pods        0     10
+----
++
+Because pods are not running, the quota is unused.
+
+. Create the pipelines and tasks.
++
+.Example: YAML for the pipeline
+[source,yaml]
+----
+apiVersion: tekton.dev/v1alpha1
+kind: Pipeline
+metadata:
+  name: maven-build
+spec:
+  workspaces:
+  - name: local-maven-repo
+  resources:
+  - name: app-git
+    type: git
+  tasks:
+  - name: build
+    taskRef:
+      name: mvn
+    resources:
+      inputs:
+      - name: source
+        resource: app-git
+    params:
+    - name: GOALS
+      value: ["package"]
+    workspaces:
+    - name: maven-repo
+      workspace: local-maven-repo
+  - name: int-test
+    taskRef:
+      name: mvn
+    runAfter: ["build"]
+    resources:
+      inputs:
+      - name: source
+        resource: app-git
+    params:
+    - name: GOALS
+      value: ["verify"]
+    workspaces:
+    - name: maven-repo
+      workspace: local-maven-repo
+  - name: gen-report
+    taskRef:
+      name: mvn
+    runAfter: ["build"]
+    resources:
+      inputs:
+      - name: source
+        resource: app-git
+    params:
+    - name: GOALS
+      value: ["site"]
+    workspaces:
+    - name: maven-repo
+      workspace: local-maven-repo
+----
++
+.Example: YAML for a task in the pipeline
+[source,yaml]
+----
+apiVersion: tekton.dev/v1alpha1
+kind: Task
+metadata:
+  name: mvn
+spec:
+  workspaces:
+  - name: maven-repo
+  inputs:
+    params:
+    - name: GOALS
+      description: The Maven goals to run
+      type: array
+      default: ["package"]
+    resources:
+    - name: source
+      type: git
+  steps:
+    - name: mvn
+      image: gcr.io/cloud-builders/mvn
+      workingDir: /workspace/source
+      command: ["/usr/bin/mvn"]
+      args:
+        - -Dmaven.repo.local=$(workspaces.maven-repo.path)
+        - "$(inputs.params.GOALS)"
+      priorityClassName: pipeline1-pc
+----
++
+[NOTE]
+====
+Ensure that all tasks in the pipeline belongs to the same priority class.
+====
+
+. Create and start the pipeline run.
++
+.Example: YAML for a pipeline run
+[source,yaml]
+----
+apiVersion: tekton.dev/v1alpha1
+kind: PipelineRun
+metadata:
+  generateName: petclinic-run-
+spec:
+  pipelineRef:
+    name: maven-build
+  resources:
+  - name: app-git
+    resourceSpec:
+      type: git
+      params:
+        - name: url
+          value: https://github.com/spring-projects/spring-petclinic
+----
+
+. After the pods are created, verify the resource quota usage for the pipeline run.
++
+.Example: Verify resource quota usage for the pipeline
+[source,terminal]
+----
+$ kubectl describe quota
+
+Name:       pipeline1-rq
+Namespace:  default
+Resource    Used  Hard
+--------    ----  ----
+cpu         500m  1k
+memory      10Gi  200Gi
+pods        1     10
+----
++
+The output indicates that you can manage the combined resource quota for all concurrent running pods belonging to a priority class, by specifying the resource quota per priority class.