From b0a86ffa8a55cc77dcc489221b6eb23c01c9a56c Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Thu, 15 May 2025 13:31:05 +0200 Subject: [PATCH 1/7] chore: documenting workspace update issue Signed-off-by: Danny Kopping --- .../templates/extending-templates/prebuilt-workspaces.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index 894a2a219a9cf..4c59209a8c4ac 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -169,6 +169,13 @@ For example, the [`ami`](https://registry.terraform.io/providers/hashicorp/aws/l has [`ForceNew`](https://github.com/hashicorp/terraform-provider-aws/blob/main/internal/service/ec2/ec2_instance.go#L75-L81) set, since the AMI cannot be changed in-place._ +#### Updating claimed prebuilt workspaces' templates + +Once a prebuilt workspace has been claimed, and if its template uses `ignore_changes`, users may run into an issue where the agent +does not reconnect after a template update. This shortcoming is described in [this issue](https://github.com/coder/coder/issues/17840) +and will be addressed before the next release (v2.23). In the interim, a simple workaround is to restart the workspace +when it is in this problematic state. + ### Current limitations The prebuilt workspaces feature has these current limitations: From e88569ff19b67b211f021d4d51dcd01d5759bc5b Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Thu, 15 May 2025 13:36:18 +0200 Subject: [PATCH 2/7] chore: document stopped behaviour Signed-off-by: Danny Kopping --- .../templates/extending-templates/prebuilt-workspaces.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index 4c59209a8c4ac..5fcc29a9d2474 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -91,6 +91,10 @@ You can view available prebuilt workspaces in the **Workspaces** view in the Cod ![A prebuilt workspace in the dashboard](../../../images/admin/templates/extend-templates/prebuilt/prebuilt-workspaces.png) _Note the search term `owner:prebuilds`._ +Prebuilt workspaces may be operated on like any other workspace. However, if a prebuilt workspace is stopped, the +reconciliation loop will not destroy it. The intention behind this design is to give operators the ability to park +problematic prebuilt workspaces in a stopped state for further investigation. + ### Template updates and the prebuilt workspace lifecycle Prebuilt workspaces are not updated after they are provisioned. From 2dc3af8fd5d56954bd9c51a3fcfab7f3b22de53b Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Thu, 15 May 2025 13:37:07 +0200 Subject: [PATCH 3/7] chore: move back to "transparent" phrasing Signed-off-by: Danny Kopping --- .../templates/extending-templates/prebuilt-workspaces.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index 5fcc29a9d2474..96e7d202d7dd6 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -75,7 +75,7 @@ Prebuilt workspaces follow a specific lifecycle from creation through eligibilit Prebuilt workspaces that fail during provisioning are retried with a backoff to prevent transient failures. -1. When a developer requests a new workspace, the claiming process occurs: +1. When a developer creates a new workspace, the claiming process occurs: 1. Developer selects a template and preset that has prebuilt workspaces configured. 1. If an eligible prebuilt workspace exists, ownership transfers from the `prebuilds` user to the requesting user. @@ -84,7 +84,7 @@ Prebuilt workspaces follow a specific lifecycle from creation through eligibilit [`coder_workspace_owner`](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace_owner) datasources (see [Preventing resource replacement](#preventing-resource-replacement) for further considerations). - The developer doesn't see the claiming process — the workspace will just be ready faster than usual. + The claiming process is transparent to the developer — the workspace will just be ready faster than usual. You can view available prebuilt workspaces in the **Workspaces** view in the Coder dashboard: From f1cffaac0f563baedc7623b20452b858bb0889d2 Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Thu, 15 May 2025 13:38:52 +0200 Subject: [PATCH 4/7] chore: removing coder/internal reference Signed-off-by: Danny Kopping --- .../templates/extending-templates/prebuilt-workspaces.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index 96e7d202d7dd6..d6a0d462e5101 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -188,13 +188,13 @@ The prebuilt workspaces feature has these current limitations: Prebuilt workspaces can only be used with the default organization. - [coder/internal#364](https://github.com/coder/internal/issues/364) + [View issue](https://github.com/coder/internal/issues/364) - **Autoscaling** Prebuilt workspaces remain running until claimed. There's no automated mechanism to reduce instances during off-hours. - [coder/internal#312](https://github.com/coder/internal/issues/312) + [View issue](https://github.com/coder/internal/issues/312) ### Monitoring and observability From e8634fab65eb8ddf2a9d700dd2b7bac962e10ecd Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Thu, 15 May 2025 13:39:04 +0200 Subject: [PATCH 5/7] chore: update provider version Signed-off-by: Danny Kopping --- docs/admin/templates/extending-templates/prebuilt-workspaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index d6a0d462e5101..5930b96a5afb1 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -25,7 +25,7 @@ Prebuilt workspaces are tightly integrated with [workspace presets](./parameters ## Prerequisites - [**Premium license**](../../licensing/index.md) -- **Compatible Terraform provider**: Use `coder/coder` Terraform provider `>= 2.4.0`. +- **Compatible Terraform provider**: Use `coder/coder` Terraform provider `>= 2.4.1`. - **Feature flag**: Enable the `workspace-prebuilds` [experiment](../../../reference/cli/server.md#--experiments). ## Enable prebuilt workspaces for template presets From 253ce2308735ec26c25dfd15c466c5b490903c62 Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Fri, 16 May 2025 07:57:55 +0200 Subject: [PATCH 6/7] chore: apply suggestions from code review Co-authored-by: Edward Angert --- .../templates/extending-templates/prebuilt-workspaces.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index 5930b96a5afb1..d6be5e0e61b52 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -91,9 +91,9 @@ You can view available prebuilt workspaces in the **Workspaces** view in the Cod ![A prebuilt workspace in the dashboard](../../../images/admin/templates/extend-templates/prebuilt/prebuilt-workspaces.png) _Note the search term `owner:prebuilds`._ -Prebuilt workspaces may be operated on like any other workspace. However, if a prebuilt workspace is stopped, the -reconciliation loop will not destroy it. The intention behind this design is to give operators the ability to park -problematic prebuilt workspaces in a stopped state for further investigation. +Prebuilt workspaces can be maintained and updated in the same way as any other workspace. +However, if a Prebuilt workspace is stopped, the reconciliation loop will not destroy it. +This gives template admins the ability to park problematic prebuilt workspaces in a stopped state for further investigation. ### Template updates and the prebuilt workspace lifecycle @@ -173,7 +173,7 @@ For example, the [`ami`](https://registry.terraform.io/providers/hashicorp/aws/l has [`ForceNew`](https://github.com/hashicorp/terraform-provider-aws/blob/main/internal/service/ec2/ec2_instance.go#L75-L81) set, since the AMI cannot be changed in-place._ -#### Updating claimed prebuilt workspaces' templates +#### Updating claimed prebuilt workspace templates Once a prebuilt workspace has been claimed, and if its template uses `ignore_changes`, users may run into an issue where the agent does not reconnect after a template update. This shortcoming is described in [this issue](https://github.com/coder/coder/issues/17840) From c38e356b58eff3de2285dbadfec68f909e5c44be Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Fri, 16 May 2025 07:59:49 +0200 Subject: [PATCH 7/7] chore: clarify also, there is no "maintenance" of prebuilt workspaces, so dropped that Signed-off-by: Danny Kopping --- docs/admin/templates/extending-templates/prebuilt-workspaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md index d6be5e0e61b52..3fd82d62d1943 100644 --- a/docs/admin/templates/extending-templates/prebuilt-workspaces.md +++ b/docs/admin/templates/extending-templates/prebuilt-workspaces.md @@ -91,7 +91,7 @@ You can view available prebuilt workspaces in the **Workspaces** view in the Cod ![A prebuilt workspace in the dashboard](../../../images/admin/templates/extend-templates/prebuilt/prebuilt-workspaces.png) _Note the search term `owner:prebuilds`._ -Prebuilt workspaces can be maintained and updated in the same way as any other workspace. +Unclaimed prebuilt workspaces can be interacted with in the same way as any other workspace. However, if a Prebuilt workspace is stopped, the reconciliation loop will not destroy it. This gives template admins the ability to park problematic prebuilt workspaces in a stopped state for further investigation.