From ea5d003ebcb24cefc07dbd1a35b8dfc506d97c8f Mon Sep 17 00:00:00 2001
From: Alex Dellapenta <adellape@redhat.com>
Date: Fri, 17 Feb 2023 14:36:42 -0700
Subject: [PATCH] Add catsrc grpcPodConfig for nodeselector, priorityclass,
 tolerations

---
 _topic_maps/_topic_map.yml                    |  3 ++
 modules/olm-catalogsource.adoc                | 27 +++++++---
 modules/olm-node-selector.adoc                | 24 +++++++++
 modules/olm-priority-class-name.adoc          | 54 +++++++++++++++++++
 modules/olm-tolerations.adoc                  | 25 +++++++++
 operators/admin/olm-cs-podsched.adoc          | 39 ++++++++++++++
 .../olm/olm-understanding-olm.adoc            |  1 +
 7 files changed, 165 insertions(+), 8 deletions(-)
 create mode 100644 modules/olm-node-selector.adoc
 create mode 100644 modules/olm-priority-class-name.adoc
 create mode 100644 modules/olm-tolerations.adoc
 create mode 100644 operators/admin/olm-cs-podsched.adoc

diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
index 608806af17..941b32ccdf 100644
--- a/_topic_maps/_topic_map.yml
+++ b/_topic_maps/_topic_map.yml
@@ -1660,6 +1660,9 @@ Topics:
   - Name: Using OLM on restricted networks
     File: olm-restricted-networks
     Distros: openshift-origin,openshift-enterprise
+  - Name: Catalog source pod scheduling
+    File: olm-cs-podsched
+    Distros: openshift-origin,openshift-enterprise
   - Name: Managing platform Operators
     File: olm-managing-po
     Distros: openshift-enterprise,openshift-origin
diff --git a/modules/olm-catalogsource.adoc b/modules/olm-catalogsource.adoc
index f63d8e59b4..173cfdef94 100644
--- a/modules/olm-catalogsource.adoc
+++ b/modules/olm-catalogsource.adoc
@@ -43,16 +43,24 @@ spec:
   sourceType: grpc <7>
   grpcPodConfig:
     securityContextConfig: <security_mode> <8>
+    nodeSelector: <9>
+      custom_label: <label>
+    priorityClassName: system-cluster-critical <10>
+    tolerations: <11>
+      - key: "key1"
+        operator: "Equal"
+        value: "value1"
+        effect: "NoSchedule"
   updateStrategy:
-    registryPoll: <9>
+    registryPoll: <12>
       interval: 30m0s
 status:
   connectionState:
     address: example-catalog.{global_ns}.svc:50051
     lastConnect: 2021-08-26T18:14:31Z
-    lastObservedState: READY <10>
-  latestImageRegistryPoll: 2021-08-26T18:46:25Z <11>
-  registryService: <12>
+    lastObservedState: READY <13>
+  latestImageRegistryPoll: 2021-08-26T18:46:25Z <14>
+  registryService: <15>
     createdAt: 2021-08-26T16:16:37Z
     port: 50051
     protocol: grpc
@@ -75,8 +83,11 @@ Set the `olm.catalogImageTemplate` annotation to your index image name and use o
 * `configmap`: OLM parses config map data and runs a pod that can serve the gRPC API over it.
 --
 <8> Specify the value of `legacy` or `restricted`. If the field is not set, the default value is `legacy`. In a future {product-title} release, it is planned that the default value will be `restricted`. If your catalog cannot run with `restricted` permissions, it is recommended that you manually set this field to `legacy`.
-<9> Automatically check for new versions at a given interval to stay up-to-date.
-<10> Last observed state of the catalog connection. For example:
+<9> Optional: For `grpc` type catalog sources, overrides the default node selector for the pod serving the content in `spec.image`, if defined.
+<10> Optional: For `grpc` type catalog sources, overrides the default priority class name for the pod serving the content in `spec.image`, if defined. Kubernetes provides `system-cluster-critical` and `system-node-critical` priority classes by default. Setting the field to empty (`""`) assigns the pod the default priority. Other priority classes can be defined manually.
+<11> Optional: For `grpc` type catalog sources, overrides the default tolerations for the pod serving the content in `spec.image`, if defined.
+<12> Automatically check for new versions at a given interval to stay up-to-date.
+<13> Last observed state of the catalog connection. For example:
 +
 --
 * `READY`: A connection is successfully established.
@@ -85,8 +96,8 @@ Set the `olm.catalogImageTemplate` annotation to your index image name and use o
 --
 +
 See link:https://grpc.github.io/grpc/core/md_doc_connectivity-semantics-and-api.html[States of Connectivity] in the gRPC documentation for more details.
-<11> Latest time the container registry storing the catalog image was polled to ensure the image is up-to-date.
-<12> Status information for the catalog's Operator Registry service.
+<14> Latest time the container registry storing the catalog image was polled to ensure the image is up-to-date.
+<15> Status information for the catalog's Operator Registry service.
 ====
 
 Referencing the `name` of a `CatalogSource` object in a subscription instructs OLM where to search to find a requested Operator:
diff --git a/modules/olm-node-selector.adoc b/modules/olm-node-selector.adoc
new file mode 100644
index 0000000000..eb33de1a0f
--- /dev/null
+++ b/modules/olm-node-selector.adoc
@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-cs-podsched.adoc
+
+:_content-type: PROCEDURE
+[id="olm-node-selector_{context}"]
+= Overriding the node selector for catalog source pods
+
+.Prequisites
+
+* `CatalogSource` object of source type `grpc` with `spec.image` defined
+
+.Procedure
+
+* Edit the `CatalogSource` object and add or modify the `spec.grpcPodConfig` section to include the following:
++
+[source,yaml]
+----
+  grpcPodConfig:
+    nodeSelector:
+      custom_label: <label>
+----
++
+where `<label>` is the label for the node selector that you want catalog source pods to use for scheduling.
diff --git a/modules/olm-priority-class-name.adoc b/modules/olm-priority-class-name.adoc
new file mode 100644
index 0000000000..d027f599ab
--- /dev/null
+++ b/modules/olm-priority-class-name.adoc
@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-cs-podsched.adoc
+
+ifdef::openshift-origin[]
+:global_ns: olm
+endif::[]
+ifndef::openshift-origin[]
+:global_ns: openshift-marketplace
+endif::[]
+
+:_content-type: PROCEDURE
+[id="olm-priority-class-name_{context}"]
+= Overriding the priority class name for catalog source pods
+
+.Prequisites
+
+* `CatalogSource` object of source type `grpc` with `spec.image` defined
+
+.Procedure
+
+* Edit the `CatalogSource` object and add or modify the `spec.grpcPodConfig` section to include the following:
++
+[source,yaml]
+----
+  grpcPodConfig:
+    priorityClassName: <priority_class>
+----
++
+where `<priority_class>` is one of the following:
++
+--
+* One of the default priority classes provided by Kubernetes: `system-cluster-critical` or `system-node-critical`
+* An empty set (`""`) to assign the default priority
+* A pre-existing and custom defined priority class
+--
+
+[NOTE]
+====
+Previously, the only pod scheduling parameter that could be overriden was `priorityClassName`. This was done by adding the `operatorframework.io/priorityclass` annotation to the `CatalogSource` object. For example:
+
+[source,yaml,subs="attributes+"]
+----
+apiVersion: operators.coreos.com/v1alpha1
+kind: CatalogSource
+metadata:
+  name: example-catalog
+  namespace: namespace: {global_ns}
+  annotations:
+    operatorframework.io/priorityclass: system-cluster-critical
+----
+
+If a `CatalogSource` object defines both the annotation and `spec.grpcPodConfig.priorityClassName`, the annotation takes precedence over the configuration parameter.
+====
\ No newline at end of file
diff --git a/modules/olm-tolerations.adoc b/modules/olm-tolerations.adoc
new file mode 100644
index 0000000000..9656d556f2
--- /dev/null
+++ b/modules/olm-tolerations.adoc
@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-cs-podsched.adoc
+
+:_content-type: PROCEDURE
+[id="olm-tolerations_{context}"]
+= Overriding tolerations for catalog source pods
+
+.Prequisites
+
+* `CatalogSource` object of source type `grpc` with `spec.image` defined
+
+.Procedure
+
+* Edit the `CatalogSource` object and add or modify the `spec.grpcPodConfig` section to include the following:
++
+[source,yaml]
+----
+  grpcPodConfig:
+    tolerations:
+      - key: "<key_name>"
+        operator: "<operator_type>"
+        value: "<value>"
+        effect: "<effect>"
+----
\ No newline at end of file
diff --git a/operators/admin/olm-cs-podsched.adoc b/operators/admin/olm-cs-podsched.adoc
new file mode 100644
index 0000000000..1fb9f240c3
--- /dev/null
+++ b/operators/admin/olm-cs-podsched.adoc
@@ -0,0 +1,39 @@
+:_content-type: ASSEMBLY
+[id="olm-cs-podsched"]
+= Catalog source pod scheduling
+include::_attributes/common-attributes.adoc[]
+:context: olm-cs-podsched
+
+toc::[]
+
+When an Operator Lifecycle Manager (OLM) catalog source of source type `grpc` defines a `spec.image`, the Catalog Operator creates a pod that serves the defined image content. By default, this pod defines the following in its spec:
+
+* Only the `kubernetes.io/os=linux` node selector
+* No priority class name
+* No tolerations
+
+As an administrator, you can override these values by modifying fields in the `CatalogSource` object's optional `spec.grpcPodConfig` section.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource_olm-understanding-olm[OLM concepts and resources -> Catalog source]
+
+include::modules/olm-node-selector.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../nodes/scheduling/nodes-scheduler-node-selectors.adoc#nodes-scheduler-node-selectors[Placing pods on specific nodes using node selectors]
+
+include::modules/olm-priority-class-name.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../nodes/pods/nodes-pods-priority.adoc#admin-guide-priority-preemption-priority-class_nodes-pods-priority[Pod priority classes]
+
+include::modules/olm-tolerations.adoc[leveloffset=+1]
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations-about_nodes-scheduler-taints-tolerations[Understanding taints and tolerations]
+
diff --git a/operators/understanding/olm/olm-understanding-olm.adoc b/operators/understanding/olm/olm-understanding-olm.adoc
index fcbedeada1..9ebd7338d7 100644
--- a/operators/understanding/olm/olm-understanding-olm.adoc
+++ b/operators/understanding/olm/olm-understanding-olm.adoc
@@ -22,6 +22,7 @@ include::modules/olm-catalogsource.adoc[leveloffset=+2]
 * xref:../../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-dependency-catalog-priority_olm-understanding-dependency-resolution[Catalog priority]
 * xref:../../../operators/admin/olm-status.adoc#olm-cs-status-cli_olm-status[Viewing Operator catalog source status by using the CLI]
 * xref:../../../authentication/understanding-and-managing-pod-security-admission.adoc#understanding-and-managing-pod-security-admission[Understanding and managing pod security admission]
+* xref:../../../operators/admin/olm-cs-podsched.adoc#olm-cs-podsched[Catalog source pod scheduling]
 
 include::modules/olm-catalogsource-image-template.adoc[leveloffset=+3]
 include::modules/olm-subscription.adoc[leveloffset=+2]