mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: restructure docs (#14421)
Closes #13434 Supersedes #14182 --------- Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com> Co-authored-by: Ethan Dickson <ethan@coder.com> Co-authored-by: Ben Potter <ben@coder.com> Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com> Co-authored-by: Stephen Kirby <me@skirby.dev> Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
co-authored by
Ethan
Ethan Dickson
Ben Potter
Stephen Kirby
Stephen Kirby
EdwardAngert
Edward Angert
Ethan
Ethan Dickson
Ben Potter
Stephen Kirby
Stephen Kirby
EdwardAngert
Edward Angert
parent
288df75686
commit
419eba5fb6
@@ -0,0 +1,95 @@
|
||||
# Template Change Management
|
||||
|
||||
We recommend source-controlling your templates as you would other any code, and
|
||||
automating the creation of new versions in CI/CD pipelines.
|
||||
|
||||
These pipelines will require tokens for your deployment. To cap token lifetime
|
||||
on creation,
|
||||
[configure Coder server to set a shorter max token lifetime](../../../reference/cli/server.md#--max-token-lifetime).
|
||||
|
||||
## coderd Terraform Provider
|
||||
|
||||
The
|
||||
[coderd Terraform provider](https://registry.terraform.io/providers/coder/coderd/latest)
|
||||
can be used to push new template versions, either manually, or in CI/CD
|
||||
pipelines. To run the provider in a CI/CD pipeline, and to prevent drift, you'll
|
||||
need to store the Terraform state
|
||||
[remotely](https://developer.hashicorp.com/terraform/language/backend).
|
||||
|
||||
```tf
|
||||
terraform {
|
||||
required_providers {
|
||||
coderd = {
|
||||
source = "coder/coderd"
|
||||
}
|
||||
}
|
||||
backend "gcs" {
|
||||
bucket = "example-bucket"
|
||||
prefix = "terraform/state"
|
||||
}
|
||||
}
|
||||
|
||||
provider "coderd" {
|
||||
// Can be populated from environment variables
|
||||
url = "https://coder.example.com"
|
||||
token = "****"
|
||||
}
|
||||
|
||||
// Get the commit SHA of the configuration's git repository
|
||||
variable "TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA" {
|
||||
type = string
|
||||
}
|
||||
|
||||
resource "coderd_template" "kubernetes" {
|
||||
name = "kubernetes"
|
||||
description = "Develop in Kubernetes!"
|
||||
versions = [{
|
||||
directory = ".coder/templates/kubernetes"
|
||||
active = true
|
||||
# Version name is optional
|
||||
name = var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA
|
||||
tf_vars = [{
|
||||
name = "namespace"
|
||||
value = "default4"
|
||||
}]
|
||||
}]
|
||||
/* ... Additional template configuration */
|
||||
}
|
||||
```
|
||||
|
||||
For an example, see how we push our development image and template
|
||||
[with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml).
|
||||
|
||||
## Coder CLI
|
||||
|
||||
You can also [install Coder](../../../install/cli.md) to automate pushing new
|
||||
template versions in CI/CD pipelines.
|
||||
|
||||
```console
|
||||
# Install the Coder CLI
|
||||
curl -L https://coder.com/install.sh | sh
|
||||
# curl -L https://coder.com/install.sh | sh -s -- --version=0.x
|
||||
|
||||
# To create API tokens, use `coder tokens create`.
|
||||
# If no `--lifetime` flag is passed during creation, the default token lifetime
|
||||
# will be 30 days.
|
||||
# These variables are consumed by Coder
|
||||
export CODER_URL=https://coder.example.com
|
||||
export CODER_SESSION_TOKEN=*****
|
||||
|
||||
# Template details
|
||||
export CODER_TEMPLATE_NAME=kubernetes
|
||||
export CODER_TEMPLATE_DIR=.coder/templates/kubernetes
|
||||
export CODER_TEMPLATE_VERSION=$(git rev-parse --short HEAD)
|
||||
|
||||
# Push the new template version to Coder
|
||||
coder templates push --yes $CODER_TEMPLATE_NAME \
|
||||
--directory $CODER_TEMPLATE_DIR \
|
||||
--name=$CODER_TEMPLATE_VERSION # Version name is optional
|
||||
```
|
||||
|
||||
### Next steps
|
||||
|
||||
- [Coder CLI Reference](../../../reference/cli/templates.md)
|
||||
- [Coderd Terraform Provider Reference](https://registry.terraform.io/providers/coder/coderd/latest/docs)
|
||||
- [Coderd API Reference](../../../reference/index.md)
|
||||
@@ -0,0 +1,114 @@
|
||||
# Template Dependencies
|
||||
|
||||
When creating Coder templates, it is unlikely that you will just be using
|
||||
built-in providers. Part of Terraform's flexibility stems from its rich plugin
|
||||
ecosystem, and it makes sense to take advantage of this.
|
||||
|
||||
That having been said, here are some recommendations to follow, based on the
|
||||
[Terraform documentation](https://developer.hashicorp.com/terraform/tutorials/configuration-language/provider-versioning).
|
||||
|
||||
Following these recommendations will:
|
||||
|
||||
- **Prevent unexpected changes:** Your templates will use the same versions of
|
||||
Terraform providers each build. This will prevent issues related to changes in
|
||||
providers.
|
||||
- **Improve build performance:** Coder caches provider versions on each build.
|
||||
If the same provider version can be re-used on subsequent builds, Coder will
|
||||
simply re-use the cached version if it is available.
|
||||
- **Improve build reliability:** As some providers are hundreds of megabytes in
|
||||
size, interruptions in connectivity to the Terraform registry during a
|
||||
workspace build can result in a failed build. If Coder is able to re-use a
|
||||
cached provider version, the likelihood of this is greatly reduced.
|
||||
|
||||
## Lock your provider and module versions
|
||||
|
||||
If you add a Terraform provider to `required_providers` without specifying a
|
||||
version requirement, Terraform will always fetch the latest version on each
|
||||
invocation:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
coder = {
|
||||
source = "coder/coder"
|
||||
}
|
||||
frobnicate = {
|
||||
source = "acme/frobnicate"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Any new releases of the `coder` or `frobnicate` providers will be picked up upon
|
||||
the next time a workspace is built using this template. This may include
|
||||
breaking changes.
|
||||
|
||||
To prevent this, add a
|
||||
[version constraint](https://developer.hashicorp.com/terraform/language/expressions/version-constraints)
|
||||
to each provider in the `required_providers` block:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
coder = {
|
||||
source = "coder/coder"
|
||||
version = ">= 0.2, < 0.3"
|
||||
}
|
||||
frobnicate = {
|
||||
source = "acme/frobnicate"
|
||||
version = "~> 1.0.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, the `coder/coder` provider will be limited to all versions
|
||||
above or equal to `0.2.0` and below `0.3.0`, while the `acme/frobnicate`
|
||||
provider will be limited to all versions matching `1.0.x`.
|
||||
|
||||
The above also applies to Terraform modules. In the below example, the module
|
||||
`razzledazzle` is locked to version `1.2.3`.
|
||||
|
||||
```terraform
|
||||
module "razzledazzle" {
|
||||
source = "registry.example.com/modules/razzle/dazzle"
|
||||
version = "1.2.3"
|
||||
foo = "bar"
|
||||
}
|
||||
```
|
||||
|
||||
## Use a Dependency Lock File
|
||||
|
||||
Terraform allows creating a
|
||||
[dependency lock file](https://developer.hashicorp.com/terraform/language/files/dependency-lock)
|
||||
to track which provider versions were selected previously. This allows you to
|
||||
ensure that the next workspace build uses the same provider versions as with the
|
||||
last build.
|
||||
|
||||
To create a new Terraform lock file, run the
|
||||
[`terraform init` command](https://developer.hashicorp.com/terraform/cli/commands/init)
|
||||
inside a folder containing the Terraform source code for a given template.
|
||||
|
||||
This will create a new file named `.terraform.lock.hcl` in the current
|
||||
directory. When you next run
|
||||
[`coder templates push`](../../../reference/cli/templates_push.md), the lock
|
||||
file will be stored alongside with the other template source code.
|
||||
|
||||
> Note: Terraform best practices also recommend checking in your
|
||||
> `.terraform.lock.hcl` into Git or other VCS.
|
||||
|
||||
The next time a workspace is built from that template, Coder will make sure to
|
||||
use the same versions of those providers as specified in the lock file.
|
||||
|
||||
If, at some point in future, you need to update the providers and versions you
|
||||
specified within the version constraints of the template, run
|
||||
|
||||
```console
|
||||
terraform init -upgrade
|
||||
```
|
||||
|
||||
This will check each provider, check the newest satisfiable version based on the
|
||||
version constraints you specified, and update the `.terraform.lock.hcl` with
|
||||
those new versions. When you next run `coder templates push`, again, the updated
|
||||
lock file will be stored and used to determine the provider versions to use for
|
||||
subsequent workspace builds.
|
||||
@@ -0,0 +1,112 @@
|
||||
# Dev Containers
|
||||
|
||||
[Development containers](https://containers.dev) are an open source
|
||||
specification for defining development environments.
|
||||
|
||||
[Envbuilder](https://github.com/coder/envbuilder) is an open source project by
|
||||
Coder that runs dev containers via Coder templates and your underlying
|
||||
infrastructure. It can run on Docker or Kubernetes.
|
||||
|
||||
There are several benefits to adding a devcontainer-compatible template to
|
||||
Coder:
|
||||
|
||||
- Drop-in migration from Codespaces (or any existing repositories that use dev
|
||||
containers)
|
||||
- Easier to start projects from Coder. Just create a new workspace then pick a
|
||||
starter devcontainer.
|
||||
- Developer teams can "bring their own image." No need for platform teams to
|
||||
manage complex images, registries, and CI pipelines.
|
||||
|
||||
## How it works
|
||||
|
||||
A Coder admin adds a devcontainer-compatible template to Coder (envbuilder).
|
||||
Then developers enter their repository URL as a
|
||||
[parameter](../extending-templates/parameters.md) when they create their
|
||||
workspace. [Envbuilder](https://github.com/coder/envbuilder) clones the repo and
|
||||
builds a container from the `devcontainer.json` specified in the repo.
|
||||
|
||||
When using the [Envbuilder Terraform provider](#provider), a previously built
|
||||
and cached image can be re-used directly, allowing instantaneous dev container
|
||||
starts.
|
||||
|
||||
Developers can edit the `devcontainer.json` in their workspace to rebuild to
|
||||
iterate on their development environments.
|
||||
|
||||
## Example templates
|
||||
|
||||
- [Devcontainers (Docker)](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
|
||||
provisions a development container using Docker.
|
||||
- [Devcontainers (Kubernetes)](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
|
||||
provisioners a development container on the Kubernetes.
|
||||
- [Google Compute Engine (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
|
||||
runs a development container inside a single GCP instance. It also mounts the
|
||||
Docker socket from the VM inside the container to enable Docker inside the
|
||||
workspace.
|
||||
- [AWS EC2 (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
|
||||
runs a development container inside a single EC2 instance. It also mounts the
|
||||
Docker socket from the VM inside the container to enable Docker inside the
|
||||
workspace.
|
||||
|
||||
|
||||
|
||||
Your template can prompt the user for a repo URL with
|
||||
[Parameters](../extending-templates/parameters.md).
|
||||
|
||||
## Authentication
|
||||
|
||||
You may need to authenticate to your container registry, such as Artifactory, or
|
||||
git provider such as GitLab, to use Envbuilder. See the
|
||||
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/container-registry-auth.md)
|
||||
for more information.
|
||||
|
||||
## Caching
|
||||
|
||||
To improve build times, dev containers can be cached. There are two main forms
|
||||
of caching:
|
||||
|
||||
1. **Layer Caching** caches individual layers and pushes them to a remote
|
||||
registry. When building the image, Envbuilder will check the remote registry
|
||||
for pre-existing layers. These will be fetched and extracted to disk instead
|
||||
of building the layers from scratch.
|
||||
2. **Image Caching** caches the _entire image_, skipping the build process
|
||||
completely (except for post-build lifecycle scripts).
|
||||
|
||||
Refer to the
|
||||
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
|
||||
for more information.
|
||||
|
||||
## Envbuilder Terraform Provider
|
||||
|
||||
To support resuming from a cached image, use the
|
||||
[Envbuilder Terraform Provider](https://github.com/coder/terraform-provider-envbuilder)
|
||||
in your template. The provider will:
|
||||
|
||||
1. Clone the remote Git repository,
|
||||
2. Perform a 'dry-run' build of the dev container in the same manner as
|
||||
Envbuilder would,
|
||||
3. Check for the presence of a previously built image in the provided cache
|
||||
repository,
|
||||
4. Output the image remote reference in SHA256 form, if found.
|
||||
|
||||
The above example templates will use the provider if a remote cache repository
|
||||
is provided.
|
||||
|
||||
If you are building your own Devcontainer template, you can consult the
|
||||
[provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image).
|
||||
You may also wish to consult a
|
||||
[documented example usage of the `envbuilder_cached_image` resource](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf).
|
||||
|
||||
## Other features & known issues
|
||||
|
||||
Envbuilder provides two release channels:
|
||||
|
||||
- **Stable:** available at
|
||||
[`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder).
|
||||
Tags `>=1.0.0` are considered stable.
|
||||
- **Preview:** available at
|
||||
[`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview).
|
||||
This is built from the tip of `main`, and should be considered
|
||||
**experimental** and prone to **breaking changes**.
|
||||
|
||||
Refer to the [Envbuilder GitHub repo](https://github.com/coder/envbuilder/) for
|
||||
more information and to submit feature requests or bug reports.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Image Management
|
||||
|
||||
While Coder provides example
|
||||
[base container images](https://github.com/coder/enterprise-images) for
|
||||
workspaces, it's often best to create custom images that matches the needs of
|
||||
your users. This document serves a guide to operational maturity with some best
|
||||
practices around managing workspaces images for Coder.
|
||||
|
||||
1. Create a minimal base image
|
||||
2. Create golden image(s) with standard tooling
|
||||
3. Allow developers to bring their own images and customizations with Dev
|
||||
Containers
|
||||
|
||||
> Note: An image is just one of the many properties defined within the template.
|
||||
> Templates can pull images from a public image registry (e.g. Docker Hub) or an
|
||||
> internal one., thanks to Terraform.
|
||||
|
||||
## Create a minimal base image
|
||||
|
||||
While you may not use this directly in Coder templates, it's useful to have a
|
||||
minimal base image is a small image that contains only the necessary
|
||||
dependencies to work in your network and work with Coder. Here are some things
|
||||
to consider:
|
||||
|
||||
- `curl`, `wget`, or `busybox` is required to download and run
|
||||
[the agent](https://github.com/coder/coder/blob/main/provisionersdk/scripts/bootstrap_linux.sh)
|
||||
- `git` is recommended so developers can clone repositories
|
||||
- If the Coder server is using a certificate from an internal certificate
|
||||
authority (CA), you'll need to add or mount these into your image
|
||||
- Other generic utilities that will be required by all users, such as `ssh`,
|
||||
`docker`, `bash`, `jq`, and/or internal tooling
|
||||
- Consider creating (and starting the container with) a non-root user
|
||||
|
||||
> See Coder's
|
||||
> [example base image](https://github.com/coder/enterprise-images/tree/main/images/minimal)
|
||||
> for reference.
|
||||
|
||||
## Create general-purpose golden image(s) with standard tooling
|
||||
|
||||
It's often practical to have a few golden images that contain standard tooling
|
||||
for developers. These images should contain a number of languages (e.g. Python,
|
||||
Java, TypeScript), IDEs (VS Code, JetBrains, PyCharm), and other tools (e.g.
|
||||
`docker`). Unlike project-specific images (which are also important), general
|
||||
purpose images are great for:
|
||||
|
||||
- **Scripting:** Developers may just want to hop in a Coder workspace to run
|
||||
basic scripts or queries.
|
||||
- **Day 1 Onboarding:** New developers can quickly get started with a familiar
|
||||
environment without having to browse through (or create) an image
|
||||
- **Basic Projects:** Developers can use these images for simple projects that
|
||||
don't require any specific tooling outside of the standard libraries. As the
|
||||
project gets more complex, its best to move to a project-specific image.
|
||||
- **"Golden Path" Projects:** If your developer platform offers specific tech
|
||||
stacks and types of projects, the golden image can be a good starting point
|
||||
for those projects.
|
||||
|
||||
> This is often referred to as a "sandbox" or "kitchen sink" image. Since large
|
||||
> multi-purpose container images can quickly become difficult to maintain, it's
|
||||
> important to keep the number of general-purpose images to a minimum (2-3 in
|
||||
> most cases) with a well-defined scope.
|
||||
|
||||
Examples:
|
||||
|
||||
- [Universal Dev Containers Image](https://github.com/devcontainers/images/tree/main/src/universal)
|
||||
|
||||
## Allow developers to bring their own images and customizations with Dev Containers
|
||||
|
||||
While golden images are great for general use cases, developers will often need
|
||||
specific tooling for their projects. The [Dev Container](https://containers.dev)
|
||||
specification allows developers to define their projects dependencies within a
|
||||
`devcontainer.json` in their Git repository.
|
||||
|
||||
- [Learn how to integrate Dev Containers with Coder](./devcontainers.md)
|
||||
@@ -0,0 +1,95 @@
|
||||
# Working with templates
|
||||
|
||||
You create and edit Coder templates as [Terraform](../../../start/coder-tour.md)
|
||||
configuration files (`.tf`) and any supporting files, like a README or
|
||||
configuration files for other services.
|
||||
|
||||
## Who creates templates?
|
||||
|
||||
The [Template Admin](../../../admin/users/groups-roles.md#roles) role (and
|
||||
above) can create templates. End users, like developers, create workspaces from
|
||||
them. Templates can also be [managed with git](./change-management.md), allowing
|
||||
any developer to propose changes to a template.
|
||||
|
||||
You can give different users and groups access to templates with
|
||||
[role-based access control](../template-permissions.md).
|
||||
|
||||
## Starter templates
|
||||
|
||||
We provide starter templates for common cloud providers, like AWS, and
|
||||
orchestrators, like Kubernetes. From there, you can modify them to use your own
|
||||
images, VPC, cloud credentials, and so on. Coder supports all Terraform
|
||||
resources and properties, so fear not if your favorite cloud provider isn't
|
||||
here!
|
||||
|
||||
|
||||
|
||||
If you prefer to use Coder on the
|
||||
[command line](../../../reference/cli/index.md), `coder templates init`.
|
||||
|
||||
> Coder starter templates are also available on our
|
||||
> [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates).
|
||||
|
||||
## Community Templates
|
||||
|
||||
As well as Coder's starter templates, you can see a list of community templates
|
||||
by our users
|
||||
[here](https://github.com/coder/coder/blob/main/examples/templates/community-templates.md).
|
||||
|
||||
## Editing templates
|
||||
|
||||
Our starter templates are meant to be modified for your use cases. You can edit
|
||||
any template's files directly in the Coder dashboard.
|
||||
|
||||
|
||||
|
||||
If you'd prefer to use the CLI, use `coder templates pull`, edit the template
|
||||
files, then `coder templates push`.
|
||||
|
||||
> Even if you are a Terraform expert, we suggest reading our
|
||||
> [guided tour of a template](../../../tutorials/template-from-scratch.md).
|
||||
|
||||
## Updating templates
|
||||
|
||||
Coder tracks a template's versions, keeping all developer workspaces up-to-date.
|
||||
When you publish a new version, developers are notified to get the latest
|
||||
infrastructure, software, or security patches. Learn more about
|
||||
[change management](./change-management.md).
|
||||
|
||||
|
||||
|
||||
### Template update policies (enterprise) (premium)
|
||||
|
||||
Enterprise template admins may want workspaces to always remain on the latest
|
||||
version of their parent template. To do so, enable **Template Update Policies**
|
||||
in the template's general settings. All non-admin users of the template will be
|
||||
forced to update their workspaces before starting them once the setting is
|
||||
applied. Workspaces which leverage autostart or start-on-connect will be
|
||||
automatically updated on the next startup.
|
||||
|
||||
|
||||
|
||||
## Delete templates
|
||||
|
||||
You can delete a template using both the coder CLI and UI. Only
|
||||
[template admins and owners](../../users/groups-roles.md#roles) can delete a
|
||||
template, and the template must not have any running workspaces associated to
|
||||
it.
|
||||
|
||||
In the UI, navigate to the template you want to delete, and select the dropdown
|
||||
in the right-hand corner of the page to delete the template.
|
||||
|
||||
|
||||
|
||||
Using the CLI, login to Coder and run the following command to delete a
|
||||
template:
|
||||
|
||||
```shell
|
||||
coder templates delete <template-name>
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Image management](./image-management.md)
|
||||
- [Devcontainer templates](./devcontainers.md)
|
||||
- [Change management](./change-management.md)
|
||||
@@ -0,0 +1,103 @@
|
||||
# Workspace Scheduling
|
||||
|
||||
You can configure a template to control how workspaces are started and stopped.
|
||||
You can also manage the lifecycle of failed or inactive workspaces.
|
||||
|
||||
|
||||
|
||||
## Schedule
|
||||
|
||||
Template [admins](../../users/index.md) may define these default values:
|
||||
|
||||
- [**Default autostop**](../../../user-guides/workspace-scheduling.md#autostop):
|
||||
How long a workspace runs without user activity before Coder automatically
|
||||
stops it.
|
||||
- [**Autostop requirement**](#autostop-requirement-enterprise-premium): Enforce
|
||||
mandatory workspace restarts to apply template updates regardless of user
|
||||
activity.
|
||||
- **Activity bump**: The duration of inactivity that must pass before a
|
||||
workspace is automatically stopped.
|
||||
- **Dormancy**: This allows automatic deletion of unused workspaces to reduce
|
||||
spend on idle resources.
|
||||
|
||||
## Allow users scheduling
|
||||
|
||||
For templates where a uniform autostop duration is not appropriate, admins may
|
||||
allow users to define their own autostart and autostop schedules. Admins can
|
||||
restrict the days of the week a workspace should automatically start to help
|
||||
manage infrastructure costs.
|
||||
|
||||
## Failure cleanup (enterprise) (premium)
|
||||
|
||||
Failure cleanup defines how long a workspace is permitted to remain in the
|
||||
failed state prior to being automatically stopped. Failure cleanup is an
|
||||
enterprise-only feature.
|
||||
|
||||
## Dormancy threshold (enterprise) (premium)
|
||||
|
||||
Dormancy Threshold defines how long Coder allows a workspace to remain inactive
|
||||
before being moved into a dormant state. A workspace's inactivity is determined
|
||||
by the time elapsed since a user last accessed the workspace. A workspace in the
|
||||
dormant state is not eligible for autostart and must be manually activated by
|
||||
the user before being accessible. Coder stops workspaces during their transition
|
||||
to the dormant state if they are detected to be running. Dormancy Threshold is
|
||||
an enterprise-only feature.
|
||||
|
||||
## Dormancy auto-deletion (enterprise) (premium)
|
||||
|
||||
Dormancy Auto-Deletion allows a template admin to dictate how long a workspace
|
||||
is permitted to remain dormant before it is automatically deleted. Dormancy
|
||||
Auto-Deletion is an enterprise-only feature.
|
||||
|
||||
## Autostop requirement (enterprise) (premium)
|
||||
|
||||
Autostop requirement is a template setting that determines how often workspaces
|
||||
using the template must automatically stop. Autostop requirement ignores any
|
||||
active connections, and ensures that workspaces do not run in perpetuity when
|
||||
connections are left open inadvertently.
|
||||
|
||||
Workspaces will apply the template autostop requirement on the given day in the
|
||||
user's timezone and specified quiet hours (see below). This ensures that
|
||||
workspaces will not be stopped during work hours.
|
||||
|
||||
The available options are "Days", which can be set to "Daily", "Saturday" or
|
||||
"Sunday", and "Weeks", which can be set to any number from 1 to 16.
|
||||
|
||||
"Days" governs which days of the week workspaces must stop. If you select
|
||||
"daily", workspaces must be automatically stopped every day at the start of the
|
||||
user's defined quiet hours. When using "Saturday" or "Sunday", workspaces will
|
||||
be automatically stopped on Saturday or Sunday in the user's timezone and quiet
|
||||
hours.
|
||||
|
||||
"Weeks" determines how many weeks between required stops. It cannot be changed
|
||||
from the default of 1 if you have selected "Daily" for "Days". When using a
|
||||
value greater than 1, workspaces will be automatically stopped every N weeks on
|
||||
the day specified by "Days" and the user's quiet hours. The autostop week is
|
||||
synchronized for all workspaces on the same template.
|
||||
|
||||
Autostop requirement is disabled when the template is using the deprecated max
|
||||
lifetime feature. Templates can choose to use a max lifetime or an autostop
|
||||
requirement during the deprecation period, but only one can be used at a time.
|
||||
|
||||
## User quiet hours (enterprise) (premium)
|
||||
|
||||
User quiet hours can be configured in the user's schedule settings page.
|
||||
Workspaces on templates with an autostop requirement will only be forcibly
|
||||
stopped due to the policy at the start of the user's quiet hours.
|
||||
|
||||
|
||||
|
||||
Admins can define the default quiet hours for all users with the
|
||||
`--default-quiet-hours-schedule` flag or `CODER_DEFAULT_QUIET_HOURS_SCHEDULE`
|
||||
environment variable. The value should be a cron expression such as
|
||||
`CRON_TZ=America/Chicago 30 2 * * *` which would set the default quiet hours to
|
||||
2:30 AM in the America/Chicago timezone. The cron schedule can only have a
|
||||
minute and hour component. The default schedule is UTC 00:00. It is recommended
|
||||
to set the default quiet hours to a time when most users are not expected to be
|
||||
using Coder.
|
||||
|
||||
Admins can force users to use the default quiet hours with the
|
||||
[CODER_ALLOW_CUSTOM_QUIET_HOURS](../../../reference/cli/server.md#allow-custom-quiet-hours)
|
||||
environment variable. Users will still be able to see the page, but will be
|
||||
unable to set a custom time or timezone. If users have already set a custom
|
||||
quiet hours schedule, it will be ignored and the default will be used instead.
|
||||
Reference in New Issue
Block a user