Skip to content

docs: upcoming auto-stop behavior #8117

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.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

docs: upcoming auto-stop behavior #8117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8fc6a76
docs: upcoming scheduling behavior
bpmct Jun 20, 2023
2275251
typo
bpmct Jun 20, 2023
e87fb94
changes from call
bpmct Jun 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/images/workspaces/approaching-stop.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/workspaces/quiet-hours.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/workspaces/stops-after-3-hours.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
35 changes: 29 additions & 6 deletions docs/templates/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,14 +69,37 @@ coder templates create <template-name>
> [examples/](https://github.com/coder/coder/tree/main/examples/templates)
> directory in the repo.

## Configure Max Workspace Autostop
## Template policies (enterprise)

To control cost, specify a maximum time to live flag for a template in hours or
minutes.
By default, developers have unlimited workspace usage and can use any template version. Template policies allows you to:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should add something about how developers have full control of their workspace schedules without policy. The policy is just the enforcement layer. It reads to me like the community edition doesn't have scheduling at all.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I agree. I will rephrase

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can't a developer use only the active version of a template? Only admins can create workspaces from any version.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We plan on making the behavior configurable per-template.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But restricting users to only use the active template is a good double-check if we do something like this


```sh
coder templates create my-template --default-ttl 4h
```
- Auto-stop workspaces after 3 hours of inactivity.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: these clauses shouldn't end with periods since they're not complete sentences

- Require workspaces to be restarted frequently to ensure they use the most recent template version.
- Disable workspace auto-start.

### Stop policy

Stop policies require workspaces be stopped (or restarted), regardless of activity:

- Daily (Restart on next quiet hours)
- Weekly (Restart on weekends)
- Custom (Every 2 weeks)

```text
Every [2] [Weeks] on [Friday]
or
Every [2] [Days]
or
Every [4] [Weeks] on [Saturday]
```

- Never

Stops occur during a user's [quiet hours](../workspaces.md#quiet-hours), which prevent interruptions. If a user is still using their workspace, they can postpone a restart up to 3 hours.

Learn more about [workspace auto-stop](../workspaces.md#workspace-auto-stop)

<!-- TODO: Add the dashboard screenshots. We can remove the "most recent version" bullet point once we finish template version policies -->

## Customize templates

Expand Down
49 changes: 36 additions & 13 deletions docs/workspaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,27 +37,50 @@ information, see [Resource Persistence](./templates/resource-persistence.md).

When a workspace is deleted, all of the workspace's resources are deleted.

## Workspace scheduling
## Workspace auto-stop

By default, workspaces are manually turned on/off by the user. However, a schedule
can be defined on a per-workspace basis to automate the workspace start/stop.
In Coder, workspaces can auto-stop when the user is not actively using the workspace. By default, Coder recognizes the following actions as activity and will keep the workspace online:

![Scheduling UI](./images/schedule.png)
- Open SSH connections (VS Code Extension, JetBrains Gateway, `coder ssh`)
- Open tunnels (`coder port-forward`)
- Open WebSockets (web terminal, [web IDEs](./ides/web-ides.md) such as code-server and JupyterLab)

### Autostart
> [Custom activity](#TODO) can be registered via Coder's REST API, such as an ongoing data science pipeline.

The autostart feature automates the workspace build at a user-specified time
and day(s) of the week. In addition, users can select their preferred timezone.
<!-- TODO. Document this. We may want to move to a custom activity section. See coder/coder[#8064](https://github.com/coder/coder/issues/8064) and coder/coder#5629 -->

![Autostart UI](./images/autostart.png)
Your workspace's auto-stop behavior can be seen in the dashboard. Template settings in Coder determine if users can alter their workspace schedules.

### Autostop
![TODO: use real screenshot](./images/workspaces/stops-after-3-hours.png)

The autostop feature shuts off workspaces after given number of hours in the "on"
state. If Coder detects workspace connection activity, the autostop timer is bumped up
one hour. IDE, SSH, Port Forwarding, and coder_app activity trigger this bump.
### Max workspace lifetime (enterprise)

![autostop UI](./images/autostop.png)
Workspaces may also have a max lifetime, which enforces a stop or restart even if you are actively using your workspace.

![TODO: use real screenshot](./images/workspaces/approaching-stop.png)

#### Quiet hours

To avoid interruptions, users can establish their "quiet hours", which are by default set from midnight to 4 AM, during which these actions occur. Users can also extend the deadline by up to 3 hours if they are in the middle of important work.

Example:

```text
Quiet hours: 12- 4:00 AM
11:30AM: User is notified their workspace is about to stop

user bumps
user bumps
user bumps

4 AM: workspace stops
```

![TODO: use real screenshot](./images/workspaces/quiet-hours.png)

<!-- NOTE: This will be in the "Account settings" page -->

Admin controls around workspace auto-stop are an enterprise feature. [Learn more here](./admin/template)

## Updating workspaces

Expand Down