diff --git a/docs/admin/scaling/scale-testing.md b/docs/admin/scaling/scale-testing.md index 761f22bfcd0e6..f107dc7f7f071 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](../architectures/1k-users.md) +[Up to 1,000 users](../../architecture/1k-users.md) -[Up to 2,000 users](../architectures/2k-users.md) +[Up to 2,000 users](../../architecture/2k-users.md) -[Up to 3,000 users](../architectures/3k-users.md) +[Up to 3,000 users](../../architecture/3k-users.md) ## Hardware recommendation diff --git a/docs/admin/scaling/scale-utility.md b/docs/admin/scaling/scale-utility.md index b841c52f6ee48..0cc0316193724 100644 --- a/docs/admin/scaling/scale-utility.md +++ b/docs/admin/scaling/scale-utility.md @@ -6,15 +6,15 @@ 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 +Learn more about [Coder’s architecture](../../architecture/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 -> hardware sizing recommendations. +> [Reference Architectures](../../architecture/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/admin/architectures/1k-users.md b/docs/architecture/1k-users.md similarity index 100% rename from docs/admin/architectures/1k-users.md rename to docs/architecture/1k-users.md diff --git a/docs/admin/architectures/2k-users.md b/docs/architecture/2k-users.md similarity index 100% rename from docs/admin/architectures/2k-users.md rename to docs/architecture/2k-users.md diff --git a/docs/admin/architectures/3k-users.md b/docs/architecture/3k-users.md similarity index 100% rename from docs/admin/architectures/3k-users.md rename to docs/architecture/3k-users.md diff --git a/docs/admin/architectures/architecture.md b/docs/architecture/architecture.md similarity index 93% rename from docs/admin/architectures/architecture.md rename to docs/architecture/architecture.md index 318e8e7d5356a..9813197e6ffbe 100644 --- a/docs/admin/architectures/architecture.md +++ b/docs/architecture/architecture.md @@ -26,7 +26,7 @@ _provisionerd_ is the execution context for infrastructure modifying providers. At the moment, the only provider is Terraform (running `terraform`). By default, the Coder server runs multiple provisioner daemons. -[External provisioners](../provisioners.md) can be added for security or +[External provisioners](../admin/provisioners.md) can be added for security or scalability purposes. ### Agents @@ -43,7 +43,7 @@ It offers the following services along with much more: - `startup_script` automation Templates are responsible for -[creating and running agents](../../templates/index.md#coder-agent) within +[creating and running agents](../templates/index.md#coder-agent) within workspaces. ### Service Bundling @@ -73,7 +73,7 @@ they're destroyed on workspace stop. ### Single region architecture -![Architecture Diagram](../../images/architecture-single-region.png) +![Architecture Diagram](../images/architecture-single-region.png) #### Components @@ -118,11 +118,11 @@ and _Coder workspaces_ deployed in the same region. - 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](../auth.md). +- Learn more about [Authentication in Coder](../admin/auth.md). ### Multi-region architecture -![Architecture Diagram](../../images/architecture-multi-region.png) +![Architecture Diagram](../images/architecture-multi-region.png) #### Components @@ -168,7 +168,7 @@ disruptions. Additionally, multi-cloud deployment enables organizations to leverage the unique features and capabilities offered by each cloud provider, such as region availability and pricing models. -![Architecture Diagram](../../images/architecture-multi-cloud.png) +![Architecture Diagram](../images/architecture-multi-cloud.png) #### Components @@ -202,7 +202,7 @@ nearest region and technical specifications provided by the cloud providers. **Workspace proxy** - _Security recommendation_: Use `coder` CLI to create - [authentication tokens for every workspace proxy](../workspace-proxies.md#requirements), + [authentication tokens for every workspace proxy](../admin/workspace-proxies.md#requirements), and keep them in regional secret stores. Remember to distribute them using safe, encrypted communication channel. @@ -220,11 +220,11 @@ nearest region and technical specifications provided by the cloud providers. - For Azure: _Azure Kubernetes Service_ - For GCP: _Google Kubernetes Engine_ -See how to deploy +See here for an example deployment of [Coder on Azure Kubernetes Service](https://github.com/ericpaulsen/coder-aks). -Learn more about [security requirements](../../install/kubernetes.md) for -deploying Coder on Kubernetes. +Learn more about [security requirements](../install/kubernetes.md) for deploying +Coder on Kubernetes. **Load balancer** @@ -283,9 +283,9 @@ The key features of the air-gapped architecture include: - _Secure data transfer_: Enable encrypted communication channels and robust access controls to safeguard sensitive information. -Learn more about [offline deployments](../../install/offline.md) of Coder. +Learn more about [offline deployments](../install/offline.md) of Coder. -![Architecture Diagram](../../images/architecture-air-gapped.png) +![Architecture Diagram](../images/architecture-air-gapped.png) #### Components @@ -327,8 +327,8 @@ across multiple regions and diverse cloud platforms. - Since the _Registry_ is isolated from the internet, platform engineers are responsible for maintaining Workspace container images and conducting periodic updates of base Docker images. -- It is recommended to keep [Dev Containers](../../templates/dev-containers.md) - up to date with the latest released +- It is recommended to keep [Dev Containers](../templates/dev-containers.md) up + to date with the latest released [Envbuilder](https://github.com/coder/envbuilder) runtime. **Mirror of Terraform Registry** @@ -360,7 +360,7 @@ Learn more about [Dev containers support](https://coder.com/docs/v2/latest/templates/dev-containers) in Coder. -![Architecture Diagram](../../images/architecture-devcontainers.png) +![Architecture Diagram](../images/architecture-devcontainers.png) #### Components diff --git a/docs/admin/architectures/validated-arch.md b/docs/architecture/validated-arch.md similarity index 88% rename from docs/admin/architectures/validated-arch.md rename to docs/architecture/validated-arch.md index ffb5a1e919ad7..6379c3563915a 100644 --- a/docs/admin/architectures/validated-arch.md +++ b/docs/architecture/validated-arch.md @@ -61,14 +61,14 @@ by default. ### User -A [user](../users.md) is an individual who utilizes the Coder platform to +A [user](../admin/users.md) is an individual who utilizes the Coder platform to develop, test, and deploy applications using workspaces. Users can select available templates to provision workspaces. They interact with Coder using the web interface, the CLI tool, or directly calling API methods. ### Workspace -A [workspace](../../workspaces.md) refers to an isolated development environment +A [workspace](../workspaces.md) refers to an isolated development environment where users can write, build, and run code. Workspaces are fully configurable and can be tailored to specific project requirements, providing developers with a consistent and efficient development environment. Workspaces can be @@ -82,20 +82,20 @@ Coder templates and deployed on resources created by provisioners. ### Template -A [template](../../templates/index.md) in Coder is a predefined configuration -for creating workspaces. Templates streamline the process of workspace creation -by providing pre-configured settings, tooling, and dependencies. They are built -by template administrators on top of Terraform, allowing for efficient -management of infrastructure resources. Additionally, templates can utilize -Coder modules to leverage existing features shared with other templates, -enhancing flexibility and consistency across deployments. Templates describe -provisioning rules for infrastructure resources offered by Terraform providers. +A [template](../templates/index.md) in Coder is a predefined configuration for +creating workspaces. Templates streamline the process of workspace creation by +providing pre-configured settings, tooling, and dependencies. They are built by +template administrators on top of Terraform, allowing for efficient management +of infrastructure resources. Additionally, templates can utilize Coder modules +to leverage existing features shared with other templates, enhancing flexibility +and consistency across deployments. Templates describe provisioning rules for +infrastructure resources offered by Terraform providers. ### Workspace Proxy -A [workspace proxy](../workspace-proxies.md) serves as a relay connection option -for developers connecting to their workspace over SSH, a workspace app, or -through port forwarding. It helps reduce network latency for geo-distributed +A [workspace proxy](../admin/workspace-proxies.md) serves as a relay connection +option for developers connecting to their workspace over SSH, a workspace app, +or through port forwarding. It helps reduce network latency for geo-distributed teams by minimizing the distance network traffic needs to travel. Notably, workspace proxies do not handle dashboard connections or API calls. @@ -212,11 +212,11 @@ resource "kubernetes_deployment" "coder" { For sizing recommendations, see the below reference architectures: -- [Up to 1,000 users](1k-users.md) +- [Up to 1,000 users](./1k-users.md) -- [Up to 2,000 users](2k-users.md) +- [Up to 2,000 users](./2k-users.md) -- [Up to 3,000 users](3k-users.md) +- [Up to 3,000 users](./3k-users.md) ### Networking @@ -297,7 +297,7 @@ considerations: active users. - Enable High Availability mode for database engine for large scale deployments. -If you enable [database encryption](../encryption.md) in Coder, consider +If you enable [database encryption](../admin/encryption.md) in Coder, consider allocating an additional CPU core to every `coderd` replica. #### Resource utilization guidelines @@ -320,26 +320,26 @@ could affect workspace users experience once the platform is live. ### Helm Chart Configuration -1. Reference our [Helm chart values file](../../../helm/coder/values.yaml) and +1. Reference our [Helm chart values file](../../helm/coder/values.yaml) and identify the required values for deployment. 1. Create a `values.yaml` and add it to your version control system. 1. Determine the necessary environment variables. Here is the - [full list of supported server environment variables](../../cli/server.md). + [full list of supported server environment variables](../cli/server.md). 1. Follow our documented - [steps for installing Coder via Helm](../../install/kubernetes.md). + [steps for installing Coder via Helm](../install/kubernetes.md). ### Template configuration 1. Establish dedicated accounts for users with the _Template Administrator_ role. 1. Maintain Coder templates using - [version control](../../templates/change-management.md). + [version control](../templates/change-management.md). 1. Consider implementing a GitOps workflow to automatically push new template versions into Coder from git. For example, on Github, you can use the [Update Coder Template](https://github.com/marketplace/actions/update-coder-template) action. 1. Evaluate enabling - [automatic template updates](../../templates/general-settings.md#require-automatic-updates-enterprise) + [automatic template updates](../templates/general-settings.md#require-automatic-updates-enterprise) upon workspace startup. ### Observability @@ -351,13 +351,13 @@ could affect workspace users experience once the platform is live. leverage pre-configured dashboards, alerts, and runbooks for monitoring Coder. This includes integrations between Prometheus, Grafana, Loki, and Alertmanager. -1. Review the [Prometheus response](../prometheus.md) and set up alarms on +1. Review the [Prometheus response](../admin/prometheus.md) and set up alarms on selected metrics. ### User support -1. Incorporate [support links](../appearance.md#support-links) into internal - documentation accessible from the user context menu. Ensure that hyperlinks - are valid and lead to up-to-date materials. +1. Incorporate [support links](../admin/appearance.md#support-links) into + internal documentation accessible from the user context menu. Ensure that + hyperlinks are valid and lead to up-to-date materials. 1. Encourage the use of `coder support bundle` to allow workspace users to generate and provide network-related diagnostic data. diff --git a/docs/images/icons/container.svg b/docs/images/icons/container.svg new file mode 100644 index 0000000000000..0739fdc84d840 --- /dev/null +++ b/docs/images/icons/container.svg @@ -0,0 +1,2 @@ + + diff --git a/docs/manifest.json b/docs/manifest.json index bdfb26c4831ae..ec09e1b8669c9 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -14,6 +14,30 @@ } ] }, + { + "title": "Architecture", + "description": "Learn about validated and reference architectures for Coder", + "path": "./architecture/architecture.md", + "icon_path": "./images/icons/container.svg", + "children": [ + { + "title": "Validated Architecture", + "path": "./architecture/validated-arch.md" + }, + { + "title": "Up to 1,000 users", + "path": "./architecture/1k-users.md" + }, + { + "title": "Up to 2,000 users", + "path": "./architecture/2k-users.md" + }, + { + "title": "Up to 3,000 users", + "path": "./architecture/3k-users.md" + } + ] + }, { "title": "Installation", "description": "How to install and deploy Coder", @@ -343,30 +367,6 @@ "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": "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", diff --git a/docs/platforms/other.md b/docs/platforms/other.md index 474efe56a46e2..097f45e813bd7 100644 --- a/docs/platforms/other.md +++ b/docs/platforms/other.md @@ -3,8 +3,7 @@ Coder is highly extensible and is not limited to the platforms outlined in these docs. The control plane can be provisioned on any VM or container compute, and workspaces can include any Terraform resource. See our -[architecture documentation](../admin/architectures/architecture.md) for more -details. +[architecture documentation](../architecture/architecture.md) for more details. The following resources may help as you're deploying Coder.