- Notifications
You must be signed in to change notification settings - Fork928
docs: describe single region and multi-region deployments#12779
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Merged
Uh oh!
There was an error while loading.Please reload this page.
Merged
Changes fromall commits
Commits
Show all changes
14 commits Select commitHold shift + click to select a range
37cfcf6 Refactor the page
mtojek42414a9 WIP
mtojek22e6aa9 Single region
mtojek6e521a2 Merge branch 'main' into 12429-deployments
mtojek9258f5f Description
mtojek2cdd2f5 WIP
mtojek9e7851c Describe
mtojekc3db4e9 Primary components
mtojekc038e5e Eric's proofreading
mtojeka582c77 WIP
mtojekd04da1f Use coderd
mtojekb385e34 Workspace proxies
mtojek64b9d98 Do not refer to replication
mtojekb7edf6d Improve multi-arch diagram
mtojekFile filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
128 changes: 109 additions & 19 deletionsdocs/about/architecture.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,39 +1,38 @@ | ||
| # Architecture | ||
| The Coder deployment model is flexible and offers various components that | ||
| platform administrators can deploy and scale depending on their use case. This | ||
| page describes possible deployments, challenges, and risks associated with them. | ||
| Learn more about our [Reference Architectures](../admin/architectures/index.md) | ||
| and platform scaling capabilities. | ||
| ## Primary components | ||
| ### coderd | ||
| _coderd_ is the service created by running `coder server`. It is a thin API that | ||
| connects workspaces, provisioners and users. _coderd_ stores its state in | ||
| Postgres and is the only service that communicates with Postgres. | ||
| It offers: | ||
| - Dashboard (UI) | ||
| - HTTP API | ||
| - Dev URLs (HTTP reverse proxy to workspaces) | ||
| - Workspace Web Applications (e.gfor easyaccessto `code-server`) | ||
| - Agent registration | ||
| ### provisionerd | ||
| _provisionerd_ is the execution context for infrastructure modifying providers. | ||
| Atthe moment, the only provider is Terraform (running `terraform`). | ||
| By default, the Coder server runs multiple provisioner daemons. | ||
| [External provisioners](../admin/provisioners.md) can be added for security or | ||
| scalability purposes. | ||
| ### Agents | ||
| An agent is the Coder service that runs within a user's remote workspace. It | ||
| provides a consistent interface for coderd and clients to communicate with | ||
| @@ -50,9 +49,9 @@ Templates are responsible for | ||
| [creating and running agents](../templates/index.md#coder-agent) within | ||
| workspaces. | ||
| ### Service Bundling | ||
| While_coderd_ and Postgres can be orchestrated independently, our default | ||
| installation paths bundle them all together into one system service. It's | ||
| perfectly fine to run a production deployment this way, but there are certain | ||
| situations that necessitate decomposition: | ||
| @@ -61,7 +60,7 @@ situations that necessitate decomposition: | ||
| - Achieving greater availability and efficiency (horizontally scale individual | ||
| services) | ||
| ### Workspaces | ||
| At the highest level, a workspace is a set of cloud resources. These resources | ||
| can be VMs, Kubernetes clusters, storage buckets, or whatever else Terraform | ||
| @@ -72,3 +71,94 @@ while those that don't are called _peripheral resources_. | ||
| Each resource may also be _persistent_ or _ephemeral_ depending on whether | ||
| they're destroyed on workspace stop. | ||
| ## Deployment models | ||
| ### Single region architecture | ||
|  | ||
| #### Components | ||
| This architecture consists of a single load balancer, several _coderd_ replicas, | ||
| and _Coder workspaces_ deployed in the same region. | ||
| ##### Workload resources | ||
| - Deploy at least one _coderd_ replica per availability zone with _coderd_ | ||
| instances and provisioners. High availability is recommended but not essential | ||
| for small deployments. | ||
| - Single replica deployment is a special case that can address a | ||
| tiny/small/proof-of-concept installation on a single virtual machine. If you | ||
| are serving more than 100 users/workspaces, you should add more replicas. | ||
| **Coder workspace** | ||
| - For small deployments consider a lightweight workspace runtime like the | ||
| [Sysbox](https://github.com/nestybox/sysbox) container runtime. Learn more how | ||
| to enable | ||
| [docker-in-docker using Sysbox](https://asciinema.org/a/kkTmOxl8DhEZiM2fLZNFlYzbo?speed=2). | ||
| **HA Database** | ||
| - Monitor node status and resource utilization metrics. | ||
| - Implement robust backup and disaster recovery strategies to protect against | ||
| data loss. | ||
| ##### Workload supporting resources | ||
| **Load balancer** | ||
| - Distributes and load balances traffic from agents and clients to _Coder | ||
| Server_ replicas across availability zones. | ||
| - Layer 7 load balancing. The load balancer can decrypt SSL traffic, and | ||
| re-encrypt using an internal certificate. | ||
| - Session persistence (sticky sessions) can be disabled as _coderd_ instances | ||
| are stateless. | ||
| - WebSocket and long-lived connections must be supported. | ||
| **Single sign-on** | ||
| - Integrate with existing Single Sign-On (SSO) solutions used within the | ||
| organization via the supported OAuth 2.0 or OpenID Connect standards. | ||
| - Learn more about [Authentication in Coder](../admin/auth.md). | ||
| ### Multi-region architecture | ||
|  | ||
| #### Components | ||
| This architecture is for globally distributed developer teams using Coder | ||
| workspaces on daily basis. It features a single load balancer with regionally | ||
| deployed _Workspace Proxies_, several _coderd_ replicas, and _Coder workspaces_ | ||
| provisioned in different regions. | ||
| Note: The _multi-region architecture_ assumes the same deployment principles as | ||
| the _single region architecture_, but it extends them to multi region deployment | ||
| with workspace proxies. Proxies are deployed in regions closest to developers to | ||
| offer the fastest developer experience. | ||
| ##### Workload resources | ||
| **Workspace proxy** | ||
| - Workspace proxy offers developers the option to establish a fast relay | ||
| connection when accessing their workspace via SSH, a workspace application, or | ||
| port forwarding. | ||
| - Dashboard connections, API calls (e.g. _list workspaces_) are not served over | ||
| proxies. | ||
| - Proxies do not establish connections to the database. | ||
| - Proxy instances do not share authentication tokens between one another. | ||
| ##### Workload supporting resources | ||
| **Proxy load balancer** | ||
| - Distributes and load balances workspace relay traffic in a single region | ||
| across availability zones. | ||
| - Layer 7 load balancing. The load balancer can decrypt SSL traffic, and | ||
| re-encrypt using internal certificate. | ||
mtojek marked this conversation as resolved. Show resolvedHide resolvedUh oh!There was an error while loading.Please reload this page. | ||
| - Session persistence (sticky sessions) can be disabled as _coderd_ instances | ||
| are stateless. | ||
| - WebSocket and long-lived connections must be supported. | ||
Binary file modifieddocs/images/architecture-multi-region.png
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.