From 0f6fbe773625dabbebeeeaae2ba07eeddf1b5d8d Mon Sep 17 00:00:00 2001 From: "blinkagent[bot]" <237617714+blinkagent[bot]@users.noreply.github.com> Date: Thu, 19 Feb 2026 10:53:05 -0600 Subject: [PATCH] chore(examples): clarify azure-linux resource lifecycle on stop vs delete (#22150) The existing README for the Azure Linux starter template only mentioned that the VM is ephemeral and the managed disk is persistent, but did not explain that the resource group, virtual network, subnet, and network interface also persist when a workspace is stopped. This led to confusion where users expected all Azure resources to be cleaned up on stop, when in reality only the VM is destroyed. ## Changes - Added the persistent networking/infrastructure resources to the resource list - Added "What happens on stop" section explaining which resources persist and why - Added "What happens on delete" section confirming all resources are cleaned up - Moved the existing note about ephemeral tools/files into a "Workspace restarts" subsection for clarity These changes exactly mirror https://github.com/coder/registry/pull/713 since the registry is not yet linked to the starter templates in `coder/coder`. Once the registry is linked, the starter templates will pull from the registry and this duplication will no longer be necessary. --------- Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com> --- examples/examples.gen.json | 2 +- examples/templates/azure-linux/README.md | 16 ++++++++++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/examples/examples.gen.json b/examples/examples.gen.json index 432e6d3f51..5226d64cf6 100644 --- a/examples/examples.gen.json +++ b/examples/examples.gen.json @@ -53,7 +53,7 @@ "linux", "azure" ], - "markdown": "\n# Remote Development on Azure VMs (Linux)\n\nProvision Azure Linux VMs as [Coder workspaces](https://coder.com/docs/workspaces) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Azure. For example, run `az login` then `az account set --subscription=\u003cid\u003e`\nto import credentials on the system and user running coderd. For other ways to\nauthenticate, [consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).\n\n## Architecture\n\nThis template provisions the following resources:\n\n- Azure VM (ephemeral, deleted on stop)\n- Managed disk (persistent, mounted to `/home/coder`)\n\nThis means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script). Alternatively, individual developers can [personalize](https://coder.com/docs/dotfiles) their workspaces with dotfiles.\n\n\u003e [!NOTE]\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n\n### Persistent VM\n\n\u003e [!IMPORTANT] \n\u003e This approach requires the [`az` CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli#install) to be present in the PATH of your Coder Provisioner.\n\u003e You will have to do this installation manually as it is not included in our official images.\n\nIt is possible to make the VM persistent (instead of ephemeral) by removing the `count` attribute in the `azurerm_linux_virtual_machine` resource block as well as adding the following snippet:\n\n```hcl\n# Stop the VM\nresource \"null_resource\" \"stop_vm\" {\n count = data.coder_workspace.me.transition == \"stop\" ? 1 : 0\n depends_on = [azurerm_linux_virtual_machine.main]\n provisioner \"local-exec\" {\n # Use deallocate so the VM is not charged\n command = \"az vm deallocate --ids ${azurerm_linux_virtual_machine.main.id}\"\n }\n}\n\n# Start the VM\nresource \"null_resource\" \"start\" {\n count = data.coder_workspace.me.transition == \"start\" ? 1 : 0\n depends_on = [azurerm_linux_virtual_machine.main]\n provisioner \"local-exec\" {\n command = \"az vm start --ids ${azurerm_linux_virtual_machine.main.id}\"\n }\n}\n```\n" + "markdown": "\n# Remote Development on Azure VMs (Linux)\n\nProvision Azure Linux VMs as [Coder workspaces](https://coder.com/docs/workspaces) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Authentication\n\nThis template assumes that coderd is run in an environment that is authenticated\nwith Azure. For example, run `az login` then `az account set --subscription=\u003cid\u003e`\nto import credentials on the system and user running coderd. For other ways to\nauthenticate, [consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure).\n\n## Architecture\n\nThis template provisions the following resources:\n\n- Azure VM (ephemeral, deleted on stop)\n- Managed disk (persistent, mounted to `/home/coder`)\n- Resource group, virtual network, subnet, and network interface (persistent, required by the managed disk and VM)\n\n### What happens on stop\n\nWhen a workspace is **stopped**, only the VM is destroyed. The managed disk, resource group, virtual network, subnet, and network interface all persist. This is by design — the managed disk retains your `/home/coder` data across workspace restarts, and the other resources remain because the disk depends on them.\n\nThis means you will see these Azure resources in your subscription even when a workspace is stopped. This is expected behavior.\n\n### What happens on delete\n\nWhen a workspace is **deleted**, all resources are destroyed, including the resource group, networking resources, and managed disk.\n\n### Workspace restarts\n\nSince the VM is ephemeral, any tools or files outside of the home directory are not persisted across restarts. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script). Alternatively, individual developers can [personalize](https://coder.com/docs/dotfiles) their workspaces with dotfiles.\n\n\u003e [!NOTE]\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n### Persistent VM\n\n\u003e [!IMPORTANT] \n\u003e This approach requires the [`az` CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli#install) to be present in the PATH of your Coder Provisioner.\n\u003e You will have to do this installation manually as it is not included in our official images.\n\nIt is possible to make the VM persistent (instead of ephemeral) by removing the `count` attribute in the `azurerm_linux_virtual_machine` resource block as well as adding the following snippet:\n\n```hcl\n# Stop the VM\nresource \"null_resource\" \"stop_vm\" {\n count = data.coder_workspace.me.transition == \"stop\" ? 1 : 0\n depends_on = [azurerm_linux_virtual_machine.main]\n provisioner \"local-exec\" {\n # Use deallocate so the VM is not charged\n command = \"az vm deallocate --ids ${azurerm_linux_virtual_machine.main.id}\"\n }\n}\n\n# Start the VM\nresource \"null_resource\" \"start\" {\n count = data.coder_workspace.me.transition == \"start\" ? 1 : 0\n depends_on = [azurerm_linux_virtual_machine.main]\n provisioner \"local-exec\" {\n command = \"az vm start --ids ${azurerm_linux_virtual_machine.main.id}\"\n }\n}\n```\n" }, { "id": "digitalocean-linux", diff --git a/examples/templates/azure-linux/README.md b/examples/templates/azure-linux/README.md index a16526c187..335be55bb1 100644 --- a/examples/templates/azure-linux/README.md +++ b/examples/templates/azure-linux/README.md @@ -28,13 +28,25 @@ This template provisions the following resources: - Azure VM (ephemeral, deleted on stop) - Managed disk (persistent, mounted to `/home/coder`) +- Resource group, virtual network, subnet, and network interface (persistent, required by the managed disk and VM) -This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script). Alternatively, individual developers can [personalize](https://coder.com/docs/dotfiles) their workspaces with dotfiles. +### What happens on stop + +When a workspace is **stopped**, only the VM is destroyed. The managed disk, resource group, virtual network, subnet, and network interface all persist. This is by design — the managed disk retains your `/home/coder` data across workspace restarts, and the other resources remain because the disk depends on them. + +This means you will see these Azure resources in your subscription even when a workspace is stopped. This is expected behavior. + +### What happens on delete + +When a workspace is **deleted**, all resources are destroyed, including the resource group, networking resources, and managed disk. + +### Workspace restarts + +Since the VM is ephemeral, any tools or files outside of the home directory are not persisted across restarts. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script). Alternatively, individual developers can [personalize](https://coder.com/docs/dotfiles) their workspaces with dotfiles. > [!NOTE] > This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case. - ### Persistent VM > [!IMPORTANT]