docs: document new terraform-managed devcontainers (#21978)

docs/admin/integrations/devcontainers/integration.md

@@ -144,22 +144,70 @@ during workspace initialization. This only applies to Dev Containers found via
 project discovery. Dev Containers defined with the `coder_devcontainer` resource
 always auto-start regardless of this setting.
 
-## Per-Container Customizations
+## Attach Resources to Dev Containers
 
-> [!NOTE]
->
-> Dev container sub-agents are created dynamically after workspace provisioning,
-> so Terraform resources like
-> [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script)
-> and [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
-> cannot currently be attached to them. Modules from the
-> [Coder registry](https://registry.coder.com) that depend on these resources
-> are also not currently supported for sub-agents.
->
-> To add tools to dev containers, use
-> [dev container features](../../../user-guides/devcontainers/working-with-dev-containers.md#dev-container-features).
-> For Coder-specific apps, use the
-> [`apps` customization](../../../user-guides/devcontainers/customizing-dev-containers.md#custom-apps).
+You can attach
+[`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app),
+[`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script),
+and [`coder_env`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/env)
+resources to a `coder_devcontainer` by referencing its `subagent_id` attribute
+as the `agent_id`:
+
+```terraform
+resource "coder_devcontainer" "my-repository" {
+  count            = data.coder_workspace.me.start_count
+  agent_id         = coder_agent.dev.id
+  workspace_folder = "/home/coder/my-repository"
+}
+
+resource "coder_app" "code-server" {
+  count        = data.coder_workspace.me.start_count
+  agent_id     = coder_devcontainer.my-repository[0].subagent_id
+  # ...
+}
+
+resource "coder_script" "dev-setup" {
+  count        = data.coder_workspace.me.start_count
+  agent_id     = coder_devcontainer.my-repository[0].subagent_id
+  # ...
+}
+
+resource "coder_env" "my-var" {
+  count    = data.coder_workspace.me.start_count
+  agent_id = coder_devcontainer.my-repository[0].subagent_id
+  # ...
+}
+```
+
+This also enables using [Coder registry](https://registry.coder.com) modules
+that depend on these resources inside dev containers, by passing the
+`subagent_id` as the module's `agent_id`.
+
+### Terraform-managed dev containers
+
+When a `coder_devcontainer` has any `coder_app`, `coder_script`, or `coder_env`
+resource attached, it becomes a **terraform-managed** dev container. This
+changes how Coder handles the sub-agent:
+
+- The sub-agent is pre-defined during Terraform provisioning rather than created
+  dynamically.
+- On dev container configuration changes, Coder updates the sub-agent in-place
+  instead of deleting and recreating it.
+
+### Interaction with devcontainer.json customizations
+
+Terraform-defined resources and
+[`devcontainer.json` customizations](../../../user-guides/devcontainers/customizing-dev-containers.md)
+work together with some limitations. The `displayApps` settings from
+`devcontainer.json` are applied to terraform-managed dev containers, so you can
+control built-in app visibility (e.g., hide VS Code Insiders) via
+`devcontainer.json` even when using Terraform resources.
+
+However, custom `apps` defined in `devcontainer.json` are **not applied** to
+terraform-managed dev containers. If you need custom apps, define them as
+`coder_app` resources in Terraform instead.
+
+## Per-Container Customizations
 
 Developers can customize individual dev containers using the `customizations.coder`
 block in their `devcontainer.json` file. Available options include:
@@ -211,6 +259,17 @@ resource "coder_devcontainer" "my-repository" {
   agent_id         = coder_agent.dev.id
   workspace_folder = "/home/coder/my-repository"
 }
+
+# Attaching resources to dev containers is optional. By attaching
+# this resource to the dev container, we are changing how the dev
+# container will be treated by Coder. This limits the ability to
+# customize the injected agent via the devcontainer.json file.
+resource "coder_env" "env" {
+  count    = data.coder_workspace.me.start_count
+  agent_id = coder_devcontainer.my-repository[0].subagent_id
+  name     = "MY_VAR"
+  value    = "my-value"
+}
 ```
 
 ### Alternative: Project Discovery with Autostart

docs/user-guides/devcontainers/customizing-dev-containers.md

@@ -4,6 +4,13 @@ Coder supports custom configuration in your `devcontainer.json` file through the
 `customizations.coder` block. These options let you control how Coder interacts
 with your dev container without requiring template changes.
 
+> [!TIP]
+>
+> Alternatively, template administrators can also define apps, scripts, and
+> environment variables for dev containers directly in Terraform. See
+> [Attach resources to dev containers](../../admin/integrations/devcontainers/integration.md#attach-resources-to-dev-containers)
+> for details.
+
 ## Ignore a dev container
 
 Use the `ignore` option to hide a dev container from Coder completely:

docs/user-guides/devcontainers/index.md

@@ -31,6 +31,7 @@ for setup details.
 - Seamless container startup during workspace initialization
 - Change detection with outdated status indicator
 - On-demand container rebuild via dashboard button
+- Template-defined apps, scripts, and environment variables via Terraform (see [limitations](../../admin/integrations/devcontainers/integration.md#interaction-with-devcontainerjson-customizations))
 - Integrated IDE experience with VS Code
 - Direct SSH access to containers
 - Automatic port detection
@@ -95,12 +96,15 @@ containers within your Coder workspace.
 
 When a workspace with Dev Containers integration starts:
 
+1. If the template defines `coder_app`, `coder_script`, or `coder_env` resources
+   attached to the dev container, a sub-agent is pre-created with these resources.
 1. The workspace initializes the Docker environment.
 1. The integration detects repositories with dev container configurations.
 1. Detected dev containers appear in the Coder dashboard.
 1. If auto-start is configured (via `coder_devcontainer` or autostart settings),
    the integration builds and starts the dev container automatically.
-1. Coder creates a sub-agent for the running container, enabling direct access.
+1. Coder creates a sub-agent (or updates the pre-created one) for the running
+   container, enabling direct access.
 
 Without auto-start, users can manually start discovered dev containers from the
 dashboard.