concepts: Document caveats with HPAs and PDBs (#461)

* concepts: Document the use of HPAs

* concepts: Document caveats with HPAs and PDBs

* Add PDB guidelines

* typo

* Update modules/concepts/pages/operations/pod_disruptions.adoc

Co-authored-by: Malte Sander <malte.sander.it@gmail.com>

* Update modules/concepts/pages/operations/pod_disruptions.adoc

Co-authored-by: Malte Sander <malte.sander.it@gmail.com>

* Update modules/concepts/pages/operations/pod_disruptions.adoc

Co-authored-by: Malte Sander <malte.sander.it@gmail.com>

* Address review feedback

* Apply suggestions from code review

Co-authored-by: Malte Sander <malte.sander.it@gmail.com>

* fix links

* newlines

* trigger ci

---------

Co-authored-by: Malte Sander <malte.sander.it@gmail.com>

modules/concepts/pages/opa.adoc

@@ -81,7 +81,7 @@ The automatic connection is facilitated by the xref:service_discovery.adoc[servi
 
 Read more about the xref:opa:index.adoc[]. Read more about product integration with OPA for these products:
 
-* xref:trino:usage_guide/security.adoc#_authorization[Trino]
+* xref:trino:usage-guide/security.adoc#_authorization[Trino]
 * xref:kafka:usage.adoc[Kafka]
 * xref:druid:usage-guide/security.adoc#authorization[Druid]
 

modules/concepts/pages/operations/index.adoc

@@ -7,18 +7,19 @@ It provides you with the necessary details to operate it in a production environ
 
 Make sure to go through the following checklist to achieve the maximum level of availability for your services.
 
-1. Make setup highly available (HA): In case the product supports running in an HA fashion, our operators will automatically
-   configure it for you. You only need to make sure that you deploy a sufficient number of replicas. Please note that
-   some products don't support HA.
-2. Reduce the number of simultaneous pod disruptions (unavailable replicas). The Stackable operators write defaults
-   based upon knowledge about the fault tolerance of the product, which should cover most of the use-cases. For details
-   have a look at xref:operations/pod_disruptions.adoc[].
-3. Reduce impact of pod disruption: Many HA capable products offer a way to gracefully shut down the service running
-   within the Pod. The flow is as follows: Kubernetes wants to shut down the Pod and calls a hook into the Pod, which in turn
-   interacts with the product, telling it to gracefully shut down. The final deletion of the Pod is then blocked until
-   the product has successfully migrated running workloads away from the Pod that is to be shut down. Details covering the graceful shutdown mechanism are described in the actual operator documentation.
+1. Make setup highly available (HA): In case the product supports running in an HA fashion, our operators will automatically configure it for you.
+   You only need to make sure that you deploy a sufficient number of replicas.
+   Please note that some products don't support HA.
+2. Reduce the number of simultaneous pod disruptions (unavailable replicas).
+   The Stackable operators write defaults based upon knowledge about the fault tolerance of the product, which should cover most of the use-cases.
+   For details have a look at xref:operations/pod_disruptions.adoc[].
+3. Reduce impact of pod disruptions:
+   Many HA capable products offer a way to gracefully shut down the service running within the Pod.
+   The flow is as follows: Kubernetes wants to shut down the Pod and calls a hook into the Pod, which in turn interacts with the product, signaling it to gracefully shut down.
+   The final deletion of the Pod is then blocked until the product has successfully migrated running workloads away from the Pod that is to be shut down.
+   Details covering the graceful shutdown mechanism are described in the actual operator documentation.
 +
-WARNING: Graceful shutdown is not implemented for all products yet. Please check the documentation specific to the product operator to see if it is supported (such as e.g. xref:trino:usage_guide/operations/graceful-shutdown.adoc[the documentation for Trino].
+WARNING: Graceful shutdown is not implemented for all products yet. Please check the documentation specific to the product operator to see if it is supported (such as e.g. xref:trino:usage-guide/operations/graceful-shutdown.adoc[the documentation for Trino].
 
 4. Spread workload across multiple Kubernetes nodes, racks, datacenter rooms or datacenters to guarantee availability
    in the case of e.g. power outages or fire in parts of the datacenter. All of this is supported by
@@ -27,23 +28,26 @@ WARNING: Graceful shutdown is not implemented for all products yet. Please check
 
 == Maintenance actions
 
-Sometimes you want to quickly shut down a product or update the Stackable operators without all the managed products
-restarting at the same time. You can achieve this using the following methods:
+Sometimes you want to quickly shut down a product or update the Stackable operators without all the managed products restarting at the same time.
+You can achieve this using the following methods:
 
 1. Quickly stop and start a whole product using `stopped` as described in xref:operations/cluster_operations.adoc[].
-2. Prevent any changes to your deployed product using `reconcilePaused` as described in xref:operations/cluster_operations.adoc[].
+2. Prevent any changes to your deployed product using `reconciliationPaused` as described in xref:operations/cluster_operations.adoc[].
 
 == Performance
 
-1. You can configure the available resource every product has using xref:concepts:resources.adoc[]. The defaults are
-   very restrained, as you should be able to spin up multiple products running on your Laptop.
-2. You can not only use xref:operations/pod_placement.adoc[] to achieve more resilience, but also to co-locate products
-   that communicate frequently with each other. One example is placing HBase regionservers on the same Kubernetes node
-   as the HDFS datanodes. Our operators already take this into account and co-locate connected services. However, if
-   you are not satisfied with the automatically created affinities you can use ref:operations/pod_placement.adoc[] to
-   configure your own.
-3. If you want to have certain services running on dedicated nodes you can also use xref:operations/pod_placement.adoc[]
-   to force the Pods to be scheduled on certain nodes. This is especially helpful if you e.g. have Kubernetes nodes with
-   16 cores and 64 GB, as you could allocate nearly 100% of these node resources to your Spark executors or Trino workers.
-   In this case it is important that you https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/[taint]
-   your Kubernetes nodes and use xref:overrides.adoc#pod-overrides[podOverrides] to add a `toleration` for the taint.
+1. *Compute resources*: You can configure the available resource every product has using xref:concepts:resources.adoc[].
+   The defaults are very restrained, as you should be able to spin up multiple products running on your Laptop.
+2. *Autoscaling*: Although not supported by the platform natively yet, you can use
+   https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale[HorizontalPodAutoscaler] to autoscale the number of Pods running for a given rolegroup dynamically based upon resource usage.
+   To achieve this you need to omit the number of replicas on the rolegroup to be scaled, which in turn results in the created StatefulSet not having any replicas set as well.
+   Afterwards you can deploy a HorizontalPodAutoscaler as usual.
+   Please note that not all product-operators have implemented graceful shutdown, so the product might be disturbed during scale down.
+   Later platform versions will support autoscaling natively with sensible defaults and will deploy HorizontalPodAutoscaler objects for you.
+3. *Co-location*: You can not only use xref:operations/pod_placement.adoc[] to achieve more resilience, but also to co-locate products that communicate frequently with each other.
+   One example is placing HBase regionservers on the same Kubernetes node as the HDFS datanodes.
+   Our operators take this into account and co-locate connected services by default.
+   If you are not satisfied with the automatically created affinities you can use xref:operations/pod_placement.adoc[] to configure your own.
+4. *Dedicated nodes*: If you want to have certain services running on dedicated nodes you can also use xref:operations/pod_placement.adoc[] to force the Pods to be scheduled on certain nodes.
+   This is especially helpful if you e.g. have Kubernetes nodes with 16 cores and 64 GB, as you could allocate nearly 100% of these node resources to your Spark executors or Trino workers.
+   In this case it is important that you https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/[taint] your Kubernetes nodes and use xref:overrides.adoc#pod-overrides[podOverrides] to add a `toleration` for the taint.

modules/concepts/pages/operations/pod_disruptions.adoc

@@ -15,6 +15,28 @@ The defaults depend on the individual product and can be found below the "Operat
 They are based on our knowledge of each product's fault tolerance.
 In some cases they may be a little pessimistic, but they can be adjusted as documented in the following sections.
 
+In general, product roles are split into the following two categories, which serve as guidelines for the default values we apply:
+
+=== Multiple replicas to increase availability
+
+For these roles (e.g. ZooKeeper servers, HDFS journal + namenodes or HBase masters), only a single Pod is allowed to be unavailable.
+For example, imagine a cluster with 7 ZooKeeper servers, where 4 servers are required to form a quorum and healthy ensemble.
+By allowing 2 servers to be unavailable, there is no single point of failure (as there are at least 5 servers available).
+But there is only a single spare server left. The reason to choose 7 instead of e.g. 5 ZooKeeper servers might be, that there are always at least 2 spare servers.
+Increasing the number of allowed disruptions and increasing the number of replicas is not improving the general availability.
+
+=== Multiple replicas to increase performance
+
+For these roles (e.g. HDFS datanodes, HBase regionservers or Trino workers), more than a single Pod is allowed to be unavailable. Otherwise, rolling re-deployments may take very long.
+
+IMPORTANT: The operators calculate the number of Pods for a given role by adding the number of replicas of every rolegroup that is part of that role.
+
+In case there are no replicas defined on a rolegroup, one Pod will be assumed for this rolegroup, as the created Kubernetes objects (StatefulSets or Deployments) will default to a single replica as well.
+However, in case there are https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/[HorizontalPodAutoscaler] in place, the number of replicas of a rolegroup can change dynamically.
+In this case the operators might falsely assume that rolegroups have fewer Pods than they actually have.
+This is a pessimistic approach, as the number of allowed disruptions normally stays the same or even increases when the number of Pods increases.
+This should be safe, but in some cases more Pods *could* have been allowed to be unavailable which may increase the duration of rolling re-deployments.
+
 == Influencing and disabling PDBs
 
 You can configure