Document HiveConfig.Spec.DeploymentConfig

HIVE-2091

Author: 2uasimojo

docs/scaling-hive.md

@@ -10,7 +10,13 @@ Most importantly, be aware that Hive uses CRDs to store its state. The amount of
 
 # Horizontal vs. Vertical Scale
 
-With the exception of install pods (used only when clusters are installing), Hive 1.x is not horizontally scalable at the worker level. Most of the work Hive does happens in the hive-controllers pod, which is one single pod on one single worker. This means that when no installs are running, if you have a cluster with 10 workers, 9 of the workers are very bored. Hive clusters are prime candidates for using worker autoscaling. Keep the worker count as low as you can, but allow bursts of concurrent installs to call for temporary workers to spin up.
+With the exception of install pods (used only when clusters are installing), Hive 1.x is not horizontally scalable at the worker level with the exception of the [clustersync controller](using-hive.md#scaling-clustersync).
+Most of the work Hive does happens in the hive-controllers pod, which is one single pod on one single worker.
+This means that when no installs are running, if you have a cluster with 10 workers, 9 of the workers are very bored.
+Hive clusters are prime candidates for using worker autoscaling.
+Keep the worker count as low as you can, but allow bursts of concurrent installs to call for temporary workers to spin up.
+
+See [using hive](using-hive.md#vertical-scaling) for information about vertically scaling the hive-controllers, hive-clustersync, and hiveadmission pods themselves.
 
 In AWS, Hive performs best on C (CPU Optimized) instance types. Hive performs fine on M (General purpose) instances, but C instances are better.
 

docs/using-hive.md

@@ -2,47 +2,47 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
-- [Using Hive](#using-hive)
-  - [Cluster Provisioning](#cluster-provisioning)
-    - [DNS](#dns)
-      - [Native](#native)
-        - [Managed DNS](#managed-dns)
-      - [Non-native](#non-native)
-        - [oVirt](#ovirt)
-    - [Pull Secret](#pull-secret)
-    - [OpenShift Version](#openshift-version)
-    - [Cloud credentials](#cloud-credentials)
-      - [Alibaba Cloud](#alibaba-cloud)
-        - [Alibaba Cloud Credential Manifests](#alibaba-cloud-credential-manifests)
-      - [AWS](#aws)
-      - [Azure](#azure)
-      - [GCP](#gcp)
-      - [IBM Cloud](#ibm-cloud)
-        - [IBM Cloud Credential Manifests](#ibm-cloud-credential-manifests)
-      - [oVirt](#ovirt-1)
-      - [vSphere](#vsphere)
-      - [OpenStack](#openstack)
-    - [SSH Key Pair](#ssh-key-pair)
-    - [InstallConfig](#installconfig)
-    - [ClusterDeployment](#clusterdeployment)
-    - [Machine Pools](#machine-pools)
-      - [Configuring Availability Zones](#configuring-availability-zones)
-      - [Auto-scaling](#auto-scaling)
-        - [Integration with Horizontal Pod Autoscalers](#integration-with-horizontal-pod-autoscalers)
-    - [Create Cluster on Bare Metal](#create-cluster-on-bare-metal)
-  - [Monitor the Install Job](#monitor-the-install-job)
-    - [Saving Logs for Failed Provisions](#saving-logs-for-failed-provisions)
-    - [Cluster Admin Kubeconfig](#cluster-admin-kubeconfig)
-    - [Access the Web Console](#access-the-web-console)
-  - [Managed DNS](#managed-dns-1)
-  - [Cluster Adoption](#cluster-adoption)
-    - [Example Adoption ClusterDeployment](#example-adoption-clusterdeployment)
-    - [Adopting with hiveutil](#adopting-with-hiveutil)
-  - [Configuration Management](#configuration-management)
-    - [SyncSet](#syncset)
-    - [Scaling ClusterSync](#scaling-clustersync)
-    - [Identity Provider Management](#identity-provider-management)
-  - [Cluster Deprovisioning](#cluster-deprovisioning)
+- [Cluster Provisioning](#cluster-provisioning)
+  - [DNS](#dns)
+    - [Native](#native)
+      - [Managed DNS](#managed-dns)
+    - [Non-native](#non-native)
+      - [oVirt](#ovirt)
+  - [Pull Secret](#pull-secret)
+  - [OpenShift Version](#openshift-version)
+  - [Cloud credentials](#cloud-credentials)
+    - [Alibaba Cloud](#alibaba-cloud)
+      - [Alibaba Cloud Credential Manifests](#alibaba-cloud-credential-manifests)
+    - [AWS](#aws)
+    - [Azure](#azure)
+    - [GCP](#gcp)
+    - [IBM Cloud](#ibm-cloud)
+      - [IBM Cloud Credential Manifests](#ibm-cloud-credential-manifests)
+    - [oVirt](#ovirt-1)
+    - [vSphere](#vsphere)
+    - [OpenStack](#openstack)
+  - [SSH Key Pair](#ssh-key-pair)
+  - [InstallConfig](#installconfig)
+  - [ClusterDeployment](#clusterdeployment)
+  - [Machine Pools](#machine-pools)
+    - [Configuring Availability Zones](#configuring-availability-zones)
+    - [Auto-scaling](#auto-scaling)
+      - [Integration with Horizontal Pod Autoscalers](#integration-with-horizontal-pod-autoscalers)
+  - [Create Cluster on Bare Metal](#create-cluster-on-bare-metal)
+- [Monitor the Install Job](#monitor-the-install-job)
+  - [Saving Logs for Failed Provisions](#saving-logs-for-failed-provisions)
+  - [Cluster Admin Kubeconfig](#cluster-admin-kubeconfig)
+  - [Access the Web Console](#access-the-web-console)
+- [Managed DNS](#managed-dns-1)
+- [Cluster Adoption](#cluster-adoption)
+  - [Example Adoption ClusterDeployment](#example-adoption-clusterdeployment)
+  - [Adopting with hiveutil](#adopting-with-hiveutil)
+- [Configuration Management](#configuration-management)
+  - [Vertical Scaling](#vertical-scaling)
+  - [SyncSet](#syncset)
+  - [Scaling ClusterSync](#scaling-clustersync)
+  - [Identity Provider Management](#identity-provider-management)
+- [Cluster Deprovisioning](#cluster-deprovisioning)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -1213,6 +1213,36 @@ bin/hiveutil create-cluster --namespace=namespace-to-adopt-into --base-domain=ex
 
 ## Configuration Management
 
+### Vertical Scaling
+hive-operator deploys each component (the [hive-controllers](../config/controllers/deployment.yaml) and [hiveadmission](../config/hiveadmission/deployment.yaml) Deployments; and the [hive-clustersync](../config/clustersync/statefulset.yaml) StatefulSet) with default resource requests.
+If you need to scale any of these components vertically, you may add one or more `deploymentConfig` sections to HiveConfig's `spec`. For example:
+
+```yaml
+  deploymentConfig:
+  - deploymentName: hive-controllers
+    resources:
+      requests:
+        memory: 256Mi
+  - deploymentName: hive-clustersync
+    resources:
+      requests:
+        cpu: 30m
+        memory: 257Mi
+      limits:
+        cpu: 50m
+  - deploymentName: hiveadmission
+    resources:
+      requests:
+        cpu: 20m
+```
+
+For each entry, the `deploymentName` must match the `metadata.name` of the Deployment/StatefulSet.
+The `resources` is a standard corev1.ResourceRequirements.
+
+See [below](#scaling-clustersync) for information on _horizontally_ scaling the clustersync controller.
+
+Note: The hive-operator itself must be scaled by directly editing its Deployment.
+
 ### SyncSet
 
 Hive offers two CRDs for applying configuration in a cluster once it is installed: `SyncSet` for config destined for specific clusters in a specific namespace, and `SelectorSyncSet` for config destined for any cluster matching a label selector.