|
| 1 | +# Quotas |
| 2 | + |
| 3 | +Quotas are a mechanism for controlling spend by associating costs with workspace |
| 4 | +templates and assigning budgets to users. Users that exceed their budget will be |
| 5 | +blocked from launching more workspaces until they either delete their other |
| 6 | +workspaces or get their budget extended. |
| 7 | + |
| 8 | +For example: A template is configured with a cost of 5 credits per day, and the |
| 9 | +user is granted 15 credits, which can be consumed by both started and stopped |
| 10 | +workspaces. This budget limits the user to 3 concurrent workspaces. |
| 11 | + |
| 12 | +Quotas are scoped to [Groups](./groups.md) in Enterprise and |
| 13 | +[organizations](./organizations.md) in Premium. |
| 14 | + |
| 15 | +## Definitions |
| 16 | + |
| 17 | +- **Credits** is the fundamental unit representing cost in the quota system. |
| 18 | + This integer can be arbitrary, or it can map to your preferred currency. |
| 19 | +- **Budget** is the per-user, enforced, upper limit to credit spend. |
| 20 | +- **Allowance** is a grant of credits to the budget. |
| 21 | + |
| 22 | +## Establishing Costs |
| 23 | + |
| 24 | +Templates describe their cost through the `daily_cost` attribute in |
| 25 | +[`resource_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata). |
| 26 | +Since costs are associated with resources, an offline workspace may consume less |
| 27 | +quota than an online workspace. |
| 28 | + |
| 29 | +A common use case is separating costs for a persistent volume and ephemeral |
| 30 | +compute: |
| 31 | + |
| 32 | +```hcl |
| 33 | +resource "docker_volume" "home_volume" { |
| 34 | + name = "coder-${data.coder_workspace_owner.me.name}-${data.coder_workspace.me.name}-root" |
| 35 | +} |
| 36 | +
|
| 37 | +resource "coder_metadata" "home_volume" { |
| 38 | + resource_id = docker_volume.home_volume.id |
| 39 | + daily_cost = 10 |
| 40 | +} |
| 41 | +
|
| 42 | +resource "docker_container" "workspace" { |
| 43 | + count = data.coder_workspace.me.start_count |
| 44 | + image = "codercom/code-server:latest" |
| 45 | + ... |
| 46 | + volumes { |
| 47 | + container_path = "/home/coder/" |
| 48 | + volume_name = docker_volume.home_volume.name |
| 49 | + read_only = false |
| 50 | + } |
| 51 | +} |
| 52 | +
|
| 53 | +resource "coder_metadata" "workspace" { |
| 54 | + count = data.coder_workspace.me.start_count |
| 55 | + resource_id = docker_container.workspace.id |
| 56 | + daily_cost = 20 |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +When the workspace above is shut down, the `docker_container` and |
| 61 | +`coder_metadata` both get deleted. This reduces the cost from 30 credits to 10 |
| 62 | +credits. |
| 63 | + |
| 64 | +Resources without a `daily_cost` value are considered to cost 0. If the cost was |
| 65 | +removed on the `docker_volume` above, the template would consume 0 credits when |
| 66 | +it's offline. This technique is good for incentivizing users to shut down their |
| 67 | +unused workspaces and freeing up compute in the cluster. |
| 68 | + |
| 69 | +## Establishing Budgets |
| 70 | + |
| 71 | +Each group has a configurable Quota Allowance. A user's budget is calculated as |
| 72 | +the sum of their allowances. |
| 73 | + |
| 74 | + |
| 75 | + |
| 76 | +For example: |
| 77 | + |
| 78 | +| Group Name | Quota Allowance | |
| 79 | +| ---------- | --------------- | |
| 80 | +| Frontend | 10 | |
| 81 | +| Backend | 20 | |
| 82 | +| Data | 30 | |
| 83 | + |
| 84 | +<br/> |
| 85 | + |
| 86 | +| Username | Groups | Effective Budget | |
| 87 | +| -------- | ----------------- | ---------------- | |
| 88 | +| jill | Frontend, Backend | 30 | |
| 89 | +| jack | Backend, Data | 50 | |
| 90 | +| sam | Data | 30 | |
| 91 | +| alex | Frontend | 10 | |
| 92 | + |
| 93 | +By default, groups are assumed to have a default allowance of 0. |
| 94 | + |
| 95 | +## Quota Enforcement |
| 96 | + |
| 97 | +Coder enforces Quota on workspace start and stop operations. The workspace build |
| 98 | +process dynamically calculates costs, so quota violation fails builds as opposed |
| 99 | +to failing the build-triggering operation. For example, the Workspace Create |
| 100 | +Form will never get held up by quota enforcement. |
| 101 | + |
| 102 | + |
| 103 | + |
| 104 | +## Up next |
| 105 | + |
| 106 | +- [Group Sync](./group-sync.md) |
| 107 | +- [Control plane configuration](../setup.md) |
0 commit comments