@@ -12,6 +12,7 @@ Prebuilt workspaces are:
1212- Created and maintained automatically by Coder to match your specified preset configurations.
1313- Claimed transparently when developers create workspaces.
1414- Monitored and replaced automatically to maintain your desired pool size.
15+ - Automatically scaled based on time-based schedules to optimize resource usage.
1516
1617##Relationship to workspace presets
1718
@@ -111,6 +112,105 @@ prebuilt workspace can remain before it is considered expired and eligible for c
111112Expired prebuilt workspaces are removed during the reconciliation loop to avoid stale environments and resource waste.
112113New prebuilt workspaces are only created to maintain the desired count if needed.
113114
115+ ###Scheduling and time-based scaling
116+
117+ Prebuilt workspaces support time-based scheduling to scale the number of instances based on usage patterns.
118+ This allows you to reduce resource costs during off-hours while maintaining availability during peak usage times.
119+
120+ Configure scheduling by adding a` scheduling ` block within your` prebuilds ` configuration:
121+
122+ ``` hcl
123+ data "coder_workspace_preset" "goland" {
124+ name = "GoLand: Large"
125+ parameters {
126+ jetbrains_ide = "GO"
127+ cpus = 8
128+ memory = 16
129+ }
130+
131+ prebuilds {
132+ instances = 0 # default to 0 instances
133+
134+ scheduling {
135+ timezone = "UTC" # only a single timezone may be used for simplicity
136+
137+ # scale to 3 instances during the work week
138+ schedule {
139+ cron = "* 8-18 * * 1-5" # from 8AM-6:59PM, Mon-Fri, UTC
140+ instances = 3 # scale to 3 instances
141+ }
142+
143+ # scale to 1 instance on Saturdays for urgent support queries
144+ schedule {
145+ cron = "* 8-14 * * 6" # from 8AM-2:59PM, Sat, UTC
146+ instances = 1 # scale to 1 instance
147+ }
148+ }
149+ }
150+ }
151+ ```
152+
153+ ** Scheduling configuration:**
154+
155+ - ** ` timezone ` ** : The timezone for all cron expressions (required). Only a single timezone is supported per scheduling configuration.
156+ - ** ` schedule ` ** : One or more schedule blocks defining when to scale to specific instance counts.
157+ - **`cron`**: Cron expression interpreted as continuous time ranges (required).
158+ - **`instances`**: Number of prebuilt workspaces to maintain during this schedule (required).
159+
160+ ** How scheduling works:**
161+
162+ 1 . Coder evaluates all active schedules at regular intervals.
163+ 2 . The schedule that matches the current time becomes active. Overlapping schedules are disallowed by validation rules.
164+ 3 . If no schedules match the current time, the base` instances ` count is used.
165+ 4 . The reconciliation loop automatically creates or destroys prebuilt workspaces to match the target count.
166+
167+ ** Cron expression format:**
168+
169+ Cron expressions follow the format:` * HOUR DOM MONTH DAY-OF-WEEK `
170+
171+ - ` * ` (minute): Must always be` * ` to ensure the schedule covers entire hours rather than specific minute intervals
172+ - ` HOUR ` : 0-23, range (e.g., 8-18 for 8AM-6:59PM), or` * `
173+ - ` DOM ` (day-of-month): 1-31, range, or` * `
174+ - ` MONTH ` : 1-12, range, or` * `
175+ - ` DAY-OF-WEEK ` : 0-6 (Sunday=0, Saturday=6), range (e.g., 1-5 for Monday to Friday), or` * `
176+
177+ ** Important notes about cron expressions:**
178+
179+ - ** Minutes must always be` * ` ** : To ensure the schedule covers entire hours
180+ - ** Time ranges are continuous** : A range like` 8-18 ` means from 8AM to 6:59PM (inclusive of both start and end hours)
181+ - ** Weekday ranges** :` 1-5 ` means Monday through Friday (Monday=1, Friday=5)
182+ - ** No overlapping schedules** : The validation system prevents overlapping schedules.
183+
184+ ** Example schedules:**
185+
186+ ``` hcl
187+ # Business hours only (8AM-6:59PM, Mon-Fri)
188+ schedule {
189+ cron = "* 8-18 * * 1-5"
190+ instances = 5
191+ }
192+
193+ # 24/7 coverage with reduced capacity overnight and on weekends
194+ schedule {
195+ cron = "* 8-18 * * 1-5" # Business hours (8AM-6:59PM, Mon-Fri)
196+ instances = 10
197+ }
198+ schedule {
199+ cron = "* 19-23,0-7 * * 1,5" # Evenings and nights (7PM-11:59PM, 12AM-7:59AM, Mon-Fri)
200+ instances = 2
201+ }
202+ schedule {
203+ cron = "* * * * 6,0" # Weekends
204+ instances = 2
205+ }
206+
207+ # Weekend support (10AM-4:59PM, Sat-Sun)
208+ schedule {
209+ cron = "* 10-16 * * 6,0"
210+ instances = 1
211+ }
212+ ```
213+
114214###Template updates and the prebuilt workspace lifecycle
115215
116216Prebuilt workspaces are not updated after they are provisioned.
@@ -195,12 +295,6 @@ The prebuilt workspaces feature has these current limitations:
195295
196296[ View issue] ( https://github.com/coder/internal/issues/364 )
197297
198- - ** Autoscaling**
199-
200- Prebuilt workspaces remain running until claimed. There's no automated mechanism to reduce instances during off-hours.
201-
202- [ View issue] ( https://github.com/coder/internal/issues/312 )
203-
204298###Monitoring and observability
205299
206300####Available metrics