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