2k

mtojek · mtojek · commit 233866f0631b · 2024-03-13T11:55:37.000+01:00
diff --git a/docs/admin/architectures/2k-users.md b/docs/admin/architectures/2k-users.md
@@ -23,33 +23,26 @@ enabling it for deployment reliability.
 
 ### Provisioner nodes
 
-TODO
+| Users       | Node capacity        | Replicas                 | GCP              | AWS          | Azure             |
+| ----------- | -------------------- | ------------------------ | ---------------- | ------------ | ----------------- |
+| Up to 2,000 | 8 vCPU, 32 GB memory | 4 / 30 provisioners each | `t2d-standard-8` | `t3.2xlarge` | `Standard_D8s_v3` |
 
-In practice, this doesn’t change much besides the diagram and workspaces node
-pool autoscaling config as it still uses the central provisioner. Recommend
-multiple provisioner groups for zero-trust and multi-cloud use cases.
-
-For example, to support 120 concurrent workspace builds:
+**Footnotes**:
 
-- Create a cluster/nodepool with 4 nodes, 8-core each (AWS: `t3.2xlarge` GCP:
-  `e2-highcpu-8`)
-- Run coderd with 4 replicas, 30 provisioner daemons each.
-  (`CODER_PROVISIONER_DAEMONS=30`)
-- Ensure Coder's [PostgreSQL server](./configure.md#postgresql-database) can use
-  up to 2 cores and 4 GB RAM
+- An external provisioner is deployed as Kubernetes pod.
+- It is not recommended to run provisioner daemons on `coderd` nodes.
+- Consider separating provisioners into different namespaces in favor of
+  zero-trust or multi-cloud deployments.
 
 ### Workspace nodes
 
 | Users       | Node capacity        | Replicas | GCP              | AWS          | Azure             |
 | ----------- | -------------------- | -------- | ---------------- | ------------ | ----------------- |
 | Up to 2,000 | 8 vCPU, 32 GB memory | 128      | `t2d-standard-8` | `t3.2xlarge` | `Standard_D8s_v3` |
 
-**Assumptions**:
-
-- Workspace user needs 2 GB memory to perform
-
 **Footnotes**:
 
+- Assumed that a workspace user needs 2 GB memory to perform
 - Maximum number of Kubernetes pods per node: 256
 - Nodes can be distributed in 2 regions, not necessarily evenly split, depending
   on developer team sizes
diff --git a/docs/admin/architectures/index.md b/docs/admin/architectures/index.md
@@ -236,15 +236,31 @@ for more details.
 
 ### Control plane: provisionerd
 
-TODO
+Each provisioner can run a single concurrent workspace build. For example,
+running 10 provisioner containers will allow 10 users to start workspaces at the
+same time.
+
+By default, the Coder server runs built-in provisioner daemons, but the
+_Enterprise_ Coder release allows for running external provisioners to separate
+the load caused by workspace provisioning on the `coderd` nodes.
 
 #### Scaling formula
 
-TODO
+When determining scaling requirements, consider the following factors:
+
+- `0.5 vCPU x 512 MB memory x concurrent workspace build`: A formula to
+  determine resource allocation based on the number of concurrent workspace
+  builds, and standard complexity of a Terraform template. _The rule of thumb_:
+  the more provisioners are free/available, the more concurrent workspace builds
+  can be performed.
 
 **Node Autoscaling**
 
-TODO
+Autoscaling provisioners is not an easy problem to solve unless it can be
+predicted when a number of concurrent workspace builds increases.
+
+We recommend disabling autoscaling and adjusting the number of provisioners to
+developer needs based on the workspace build queuing time.
 
 ### Data plane: Workspaces
 
@@ -279,6 +295,8 @@ ongoing workspaces
 
 ### Database
 
+TODO
+
 PostgreSQL database
 
 measure and document the impact of dbcrypt
