From a777397dbc845b5c6fb6d9627915896e6e7996dd Mon Sep 17 00:00:00 2001 From: Eric Date: Thu, 13 Jun 2024 18:41:18 +0000 Subject: [PATCH 1/6] refactor scaling docs --- docs/admin/architectures/validated-arch.md | 2 +- .../scale-testing.md | 13 ++--- .../{scale.md => scaling/scale-utility.md} | 8 +-- docs/manifest.json | 54 ++++++++++--------- 4 files changed, 43 insertions(+), 34 deletions(-) rename docs/admin/{architectures => scaling}/scale-testing.md (96%) rename docs/admin/{scale.md => scaling/scale-utility.md} (98%) diff --git a/docs/admin/architectures/validated-arch.md b/docs/admin/architectures/validated-arch.md index 0595b29cf3019..b535347a140a0 100644 --- a/docs/admin/architectures/validated-arch.md +++ b/docs/admin/architectures/validated-arch.md @@ -2,7 +2,7 @@ Many customers operate Coder in complex organizational environments, consisting of multiple business units, agencies, and/or subsidiaries. This can lead to -numerous Coder deployments, caused by discrepancies in regulatory compliance, +numerous Coder deployments, due to discrepancies in regulatory compliance, data sovereignty, and level of funding across groups. The Coder Validated Architecture (CVA) prescribes a Kubernetes-based deployment approach, enabling your organization to deploy a stable Coder instance that is easier to maintain diff --git a/docs/admin/architectures/scale-testing.md b/docs/admin/scaling/scale-testing.md similarity index 96% rename from docs/admin/architectures/scale-testing.md rename to docs/admin/scaling/scale-testing.md index 38e27b63be1ca..d3dba2d0736dc 100644 --- a/docs/admin/architectures/scale-testing.md +++ b/docs/admin/scaling/scale-testing.md @@ -1,18 +1,19 @@ -## Scale Testing +# Scale Testing Scaling Coder involves planning and testing to ensure it can handle more load without compromising service. This process encompasses infrastructure setup, traffic projections, and aggressive testing to identify and mitigate potential bottlenecks. -A dedicated Kubernetes cluster for Coder is Kubernetes cluster specifically -configured to host and manage Coder workloads. Kubernetes provides container -orchestration capabilities, allowing Coder to efficiently deploy, scale, and +A dedicated Kubernetes cluster for Coder is recommended to configure, host and +manage Coder workloads. Kubernetes provides container orchestration capabilities, allowing Coder to efficiently deploy, scale, and manage workspaces across a distributed infrastructure. This ensures high availability, fault tolerance, and scalability for Coder deployments. Coder is deployed on this cluster using the [Helm chart](../../install/kubernetes.md#install-coder-with-helm). +## Methodology + Our scale tests include the following stages: 1. Prepare environment: create expected users and provision workspaces. @@ -33,7 +34,7 @@ Our scale tests include the following stages: 6. Cleanup: delete workspaces and users created in step 1. -### Infrastructure and setup requirements +## Infrastructure and setup requirements The scale tests runner can distribute the workload to overlap single scenarios based on the workflow configuration: @@ -60,7 +61,7 @@ The test is deemed successful if users did not experience interruptions in their workflows, `coderd` did not crash or require restarts, and no other internal errors were observed. -### Traffic Projections +## Traffic Projections In our scale tests, we simulate activity from 2000 users, 2000 workspaces, and 2000 agents, with two items of workspace agent metadata being sent every 10 diff --git a/docs/admin/scale.md b/docs/admin/scaling/scale-utility.md similarity index 98% rename from docs/admin/scale.md rename to docs/admin/scaling/scale-utility.md index d8569fb8dffef..ee36a50ed6fb9 100644 --- a/docs/admin/scale.md +++ b/docs/admin/scaling/scale-utility.md @@ -1,17 +1,19 @@ +# Scale Tests and Utilities + We scale-test Coder with [a built-in utility](#scale-testing-utility) that can be used in your environment for insights into how Coder scales with your infrastructure. For scale-testing Kubernetes clusters we recommend to install and use the dedicated Coder template, [scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner). -Learn more about [Coder’s architecture](architectures/architecture.md) and our -[scale-testing methodology](architectures/scale-testing.md). +Learn more about [Coder’s architecture](../architectures/architecture.md) and our +[scale-testing methodology](scale-testing.md). ## Recent scale tests > Note: the below information is for reference purposes only, and are not > intended to be used as guidelines for infrastructure sizing. Review the -> [Reference Architectures](architectures/validated-arch.md#node-sizing) for +> [Reference Architectures](../architectures/validated-arch.md#node-sizing) for > hardware sizing recommendations. | Environment | Coder CPU | Coder RAM | Coder Replicas | Database | Users | Concurrent builds | Concurrent connections (Terminal/SSH) | Coder Version | Last tested | diff --git a/docs/manifest.json b/docs/manifest.json index 8acd4ad517313..c4d6a877ffcbc 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -336,6 +336,34 @@ "path": "./admin/README.md", "icon_path": "./images/icons/wrench.svg", "children": [ + { + "title": "Architecture", + "description": "Learn about validated and reference architectures for Coder", + "path": "./admin/architectures/architecture.md", + "icon_path": "./images/icons/container.svg", + "children": [ + { + "title": "Validated Architecture", + "path": "./admin/architectures/validated-arch.md" + }, + { + "title": "Scale Testing", + "path": "./admin/architectures/scale-testing.md" + }, + { + "title": "Up to 1,000 users", + "path": "./admin/architectures/1k-users.md" + }, + { + "title": "Up to 2,000 users", + "path": "./admin/architectures/2k-users.md" + }, + { + "title": "Up to 3,000 users", + "path": "./admin/architectures/3k-users.md" + } + ] + }, { "title": "Authentication", "description": "Learn how to set up authentication using GitHub or OpenID Connect", @@ -389,34 +417,12 @@ { "title": "Scaling Coder", "description": "Learn how to use load testing tools", - "path": "./admin/scale.md", - "icon_path": "./images/icons/scale.svg" - }, - { - "title": "Architecture", - "description": "Learn about validated and reference architectures for Coder", - "path": "./admin/architectures/architecture.md", + "path": "./admin/scaling/scale-testing.md", "icon_path": "./images/icons/scale.svg", "children": [ { - "title": "Validated Architecture", + "title": "Scaling ", "path": "./admin/architectures/validated-arch.md" - }, - { - "title": "Scale Testing", - "path": "./admin/architectures/scale-testing.md" - }, - { - "title": "Up to 1,000 users", - "path": "./admin/architectures/1k-users.md" - }, - { - "title": "Up to 2,000 users", - "path": "./admin/architectures/2k-users.md" - }, - { - "title": "Up to 3,000 users", - "path": "./admin/architectures/3k-users.md" } ] }, From 545fc3100291f4d780b22b7591ac14668fa0d463 Mon Sep 17 00:00:00 2001 From: Eric Date: Thu, 13 Jun 2024 18:41:32 +0000 Subject: [PATCH 2/6] manifest --- docs/manifest.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index c4d6a877ffcbc..236ae159fa927 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -421,8 +421,8 @@ "icon_path": "./images/icons/scale.svg", "children": [ { - "title": "Scaling ", - "path": "./admin/architectures/validated-arch.md" + "title": "Scaling Utility", + "path": "./admin/architectures/scale-utility.md" } ] }, From b0f8b8965863afc927a860cddb590d41c713fb83 Mon Sep 17 00:00:00 2001 From: Eric Date: Thu, 13 Jun 2024 18:42:30 +0000 Subject: [PATCH 3/6] make fmt --- docs/admin/architectures/validated-arch.md | 4 ++-- docs/admin/scaling/scale-testing.md | 9 +++++---- docs/admin/scaling/scale-utility.md | 4 ++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/admin/architectures/validated-arch.md b/docs/admin/architectures/validated-arch.md index b535347a140a0..ffb5a1e919ad7 100644 --- a/docs/admin/architectures/validated-arch.md +++ b/docs/admin/architectures/validated-arch.md @@ -2,8 +2,8 @@ Many customers operate Coder in complex organizational environments, consisting of multiple business units, agencies, and/or subsidiaries. This can lead to -numerous Coder deployments, due to discrepancies in regulatory compliance, -data sovereignty, and level of funding across groups. The Coder Validated +numerous Coder deployments, due to discrepancies in regulatory compliance, data +sovereignty, and level of funding across groups. The Coder Validated Architecture (CVA) prescribes a Kubernetes-based deployment approach, enabling your organization to deploy a stable Coder instance that is easier to maintain and troubleshoot. diff --git a/docs/admin/scaling/scale-testing.md b/docs/admin/scaling/scale-testing.md index d3dba2d0736dc..85e9be96f8599 100644 --- a/docs/admin/scaling/scale-testing.md +++ b/docs/admin/scaling/scale-testing.md @@ -6,10 +6,11 @@ traffic projections, and aggressive testing to identify and mitigate potential bottlenecks. A dedicated Kubernetes cluster for Coder is recommended to configure, host and -manage Coder workloads. Kubernetes provides container orchestration capabilities, allowing Coder to efficiently deploy, scale, and -manage workspaces across a distributed infrastructure. This ensures high -availability, fault tolerance, and scalability for Coder deployments. Coder is -deployed on this cluster using the +manage Coder workloads. Kubernetes provides container orchestration +capabilities, allowing Coder to efficiently deploy, scale, and manage workspaces +across a distributed infrastructure. This ensures high availability, fault +tolerance, and scalability for Coder deployments. Coder is deployed on this +cluster using the [Helm chart](../../install/kubernetes.md#install-coder-with-helm). ## Methodology diff --git a/docs/admin/scaling/scale-utility.md b/docs/admin/scaling/scale-utility.md index ee36a50ed6fb9..fb0e4150e935a 100644 --- a/docs/admin/scaling/scale-utility.md +++ b/docs/admin/scaling/scale-utility.md @@ -6,8 +6,8 @@ infrastructure. For scale-testing Kubernetes clusters we recommend to install and use the dedicated Coder template, [scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner). -Learn more about [Coder’s architecture](../architectures/architecture.md) and our -[scale-testing methodology](scale-testing.md). +Learn more about [Coder’s architecture](../architectures/architecture.md) and +our [scale-testing methodology](scale-testing.md). ## Recent scale tests From 241373bfe3cc7f7dbffea12c02edcb674a4fcfce Mon Sep 17 00:00:00 2001 From: Eric Date: Thu, 13 Jun 2024 21:33:21 +0000 Subject: [PATCH 4/6] fix 404s --- docs/admin/provisioners.md | 4 ++-- docs/admin/scaling/scale-testing.md | 10 +++++----- docs/admin/scaling/scale-utility.md | 2 +- docs/platforms/aws.md | 2 +- docs/platforms/gcp.md | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/admin/provisioners.md b/docs/admin/provisioners.md index 22f1eccdf1a88..e96e1ec98cfb2 100644 --- a/docs/admin/provisioners.md +++ b/docs/admin/provisioners.md @@ -21,8 +21,8 @@ sometimes benefits to running external provisioner daemons: [Scaling Coder](./scale.md#concurrent-workspace-builds) for more details. Each provisioner can run a single -[concurrent workspace build](./scale.md#concurrent-workspace-builds). For -example, running 30 provisioner containers will allow 30 users to start +[concurrent workspace build](scaling/scale-testing.md#control-plane-provisionerd). +For example, running 30 provisioner containers will allow 30 users to start workspaces at the same time. Provisioners are started with the diff --git a/docs/admin/scaling/scale-testing.md b/docs/admin/scaling/scale-testing.md index 85e9be96f8599..761f22bfcd0e6 100644 --- a/docs/admin/scaling/scale-testing.md +++ b/docs/admin/scaling/scale-testing.md @@ -90,11 +90,11 @@ Database: ## Available reference architectures -[Up to 1,000 users](1k-users.md) +[Up to 1,000 users](../architectures/1k-users.md) -[Up to 2,000 users](2k-users.md) +[Up to 2,000 users](../architectures/2k-users.md) -[Up to 3,000 users](3k-users.md) +[Up to 3,000 users](../architectures/3k-users.md) ## Hardware recommendation @@ -153,8 +153,8 @@ with a deployment of Coder [workspace proxies](../workspace-proxies.md). **Node Autoscaling** We recommend disabling the autoscaling for `coderd` nodes. Autoscaling can cause -interruptions for user connections, see [Autoscaling](../scale.md#autoscaling) -for more details. +interruptions for user connections, see +[Autoscaling](scale-utility.md#autoscaling) for more details. ### Control plane: Workspace Proxies diff --git a/docs/admin/scaling/scale-utility.md b/docs/admin/scaling/scale-utility.md index fb0e4150e935a..b841c52f6ee48 100644 --- a/docs/admin/scaling/scale-utility.md +++ b/docs/admin/scaling/scale-utility.md @@ -249,6 +249,6 @@ an annotation on the coderd deployment. ## Troubleshooting If a load test fails or if you are experiencing performance issues during -day-to-day use, you can leverage Coder's [Prometheus metrics](./prometheus.md) +day-to-day use, you can leverage Coder's [Prometheus metrics](../prometheus.md) to identify bottlenecks during scale tests. Additionally, you can use your existing cloud monitoring stack to measure load, view server logs, etc. diff --git a/docs/platforms/aws.md b/docs/platforms/aws.md index b5114d720feac..83e0c6c2aa642 100644 --- a/docs/platforms/aws.md +++ b/docs/platforms/aws.md @@ -27,7 +27,7 @@ We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB memory) if you plan on provisioning Docker containers as workspaces on this EC2 instance. Keep in mind this platforms is intended for proof-of-concept deployments and you should adjust your infrastructure when preparing for -production use. See: [Scaling Coder](../admin/scale.md) +production use. See: [Scaling Coder](../admin/scaling/scale-testing.md) Be sure to add a keypair so that you can connect over SSH to further [configure Coder](../admin/configure.md). diff --git a/docs/platforms/gcp.md b/docs/platforms/gcp.md index 630897fc79d6e..c8c4203314c77 100644 --- a/docs/platforms/gcp.md +++ b/docs/platforms/gcp.md @@ -23,7 +23,7 @@ We recommend keeping the default instance type (`e2-standard-4`, 4 cores and 16 GB memory) if you plan on provisioning Docker containers as workspaces on this VM instance. Keep in mind this platforms is intended for proof-of-concept deployments and you should adjust your infrastructure when preparing for -production use. See: [Scaling Coder](../admin/scale.md) +production use. See: [Scaling Coder](../admin/scaling/scale-testing.md)