feat: add design docs for including additional objects in bundles

Author: exdx

doc/design/adding-pod-disruption-budgets.md

@@ -0,0 +1,25 @@
+# Adding Pod Disruption Budgets
+
+## Description
+
+OLM supports users including `PodDisruptionBudget` (PDB) objects in their bundle alongside their operator manifests. `PodDisruptionBudgets`
+are used to provide detailed information to the kube-scheduler about how many pods in a collection can be available or unavailable at given time. 
+For more info, see the docs at https://kubernetes.io/docs/tasks/run-application/configure-pdb/#protecting-an-application-with-a-poddisruptionbudget. 
+
+## Caveats
+
+PDBs are namespaced resources that only affect certain pods selected by the pod selector. However, 
+setting `maxUnavailable` to 0 or 0% (or `minAvailable` to 100%) on the PDB means zero voluntary evictions. 
+This can make a node impossible to drain and block important lifecycle actions like operator upgrades or even cluster upgrades. 
+
+Multiple PDBs can exist in one namespace- this can cause conflicts. Be sure to know of existing PDBs in the namespace in which
+your operator and operands will exist in the cluster. 
+
+PDBs for pods controlled by operators have additional restrictions around them. See https://kubernetes.io/docs/tasks/run-application/configure-pdb/#arbitrary-controllers-and-selectors
+for additional details - PDBs for operands managed by OLM-installed operators will fall into these restrictions. 
+
+## Conclusions
+
+PDBs are useful for configuring how many operator replicas or operands should run at any given time. However, it's important
+to set reasonable values for any PDBs included in the bundle and carefully consider how the PDB can affect the lifecycle of other resources
+in the cluster, such as nodes, to ensure cluster autoscaling and cluster upgrades are able to proceed if they are enabled. 

doc/design/adding-priority-classes.md

@@ -0,0 +1,31 @@
+# Adding Priority Classes
+
+## Description
+
+OLM supports users including `PriorityClass` objects in their bundle alongside their operator manifests. `PriorityClass`
+is used to establish a priority, or weight, to a collection of pods in order to aid the kube-scheduler when assigning pods
+to nodes. For more info, see the docs at https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass. 
+
+## Caveats
+
+`PriorityClass` objects are clusterwide in scope, meaning they can affect the scheduling of pods in all namespaces. All pods
+have a default priority of zero, and only those pods explicitly selected by the `PriorityClass` object will be given a priority when created.
+Existing pods running on the cluster are not affected by a new `PriorityClass`, but since clusters are dynamic and pods can be 
+rescheduled as nodes cycle in and out, a `PriorityClass` can have an impact on the long term behavior of the cluster. 
+
+Exactly one `PriorityClass` object is allowed to have the `globalDefault` setting set to true - this means that all pods on the cluster
+without an explicit priority class will use this default `PriorityClass`. Make sure you understand the effects of setting a global
+priority for pods running in the cluster before setting a `PriorityClass` as the `globalDefault`.
+
+Pods with higher priorities can preempt pods with lower priorities when they are being scheduled onto nodes: preemption can result in lower-priority pods being evicted to make room for the higher priority pod. 
+If the `PriorityClass` of the pod is extremely high (higher than the priority of core components) scheduling the pod can potentially disrupt core components running in the cluster. 
+
+Once a `PriorityClass` is removed, no further pods can be created that reference the deleted `PriorityClass`. 
+
+## Conclusion
+
+`PriorityClasses` are useful but also potentially far-reaching in nature. Be sure to understand the state of your cluster and
+your scheduling requirements before including one in your bundle alongside your operator. Best practice would be to 
+include a `PriorityClass` that only affects pods like your operator deployment and the respective operands. Setting the `globalDefault`
+on a `PriorityClass` to true is not advised in the general sense that it affects all pods scheduled in the cluster, whether or not
+they are in the scope of your operator bundle. 

doc/design/adding-vertical-pod-autoscaler.md

@@ -0,0 +1,26 @@
+# Adding Vertical Pod Autoscaler 
+
+## Description
+
+OLM supports users including `VerticalPodAutoscaler` (VPA) objects in their bundle alongside their operator manifests. `VerticalPodAutoscalers`
+objects are used to configure the VerticalPodAutoscaler controller to dynamically allocate resources to pods based on their usage of CPU, memory, 
+and other custom metrics. VPAs allow for more efficient use of cluster resources as pod resource needs are continually evaluated and adjusted by the VPA controller.
+For more info, see the docs at https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler. 
+
+## Caveats
+
+`VerticalPodAutoscaler` objects watch a controller reference, such as deployment, to find a collection of pods to resize. Be sure to pass
+the appropriate reference to your operator or operands depending on which you would like the VPA to watch. 
+
+The VerticalPodAutoscaler controller must be enabled and active in the cluster for the VPA objects included in the bundle to have an effect. 
+
+The VPA will continually terminate pods and adjust the resource limits as needed - be sure your application is tolerant of restarts
+before including a VPA alongside it. 
+
+Note: at this time it is not recommended for the VPA to run alongside the HorizontalPodAutoscaler. 
+
+## Conclusion
+
+Adding a VPA object in your bundle can lead to more efficient use of resource in your cluster. Best practices include limiting
+the VPA to only the objects associated with your bundle. Consider your existing autoscaling setup in the cluster before adding
+VPA objects to a bundle and installing the bundle on the cluster.