### Run a script on agent startup

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/script.md

This example shows how to run a script when the agent starts. The script is templated with variables and will execute on startup.

```terraform
data "coder_workspace" "me" {}

resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
  dir  = "/workspace"
}

resource "coder_script" "dotfiles" {
  agent_id     = coder_agent.dev.id
  display_name = "Dotfiles"
  icon         = "/icon/dotfiles.svg"
  run_on_start = true
  script = templatefile("~/get_dotfiles.sh", {
    DOTFILES_URI : var.dotfiles_uri,
    DOTFILES_USER : var.dotfiles_user
  })
}
```

--------------------------------

### Example Usage of coder_provisioner Data Source

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/provisioner.md

This example demonstrates how to use the coder_provisioner data source to retrieve provisioner details and then use those details to configure a coder_agent resource.

```terraform
provider "coder" {}

data "coder_provisioner" "dev" {}

data "coder_workspace" "dev" {}

resource "coder_agent" "main" {
  arch = data.coder_provisioner.dev.arch
  os   = data.coder_provisioner.dev.os
  dir  = "/workspace"
  display_apps {
    vscode          = true
    vscode_insiders = false
    web_terminal    = true
    ssh_helper      = false
  }
}
```

--------------------------------

### Attach a blocking startup script to an agent

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

The `coder_script` resource can attach shell scripts to an agent. Set `start_blocks_login = true` to ensure the workspace remains in the 'Starting' state until the script completes execution. This is useful for critical setup tasks like installing software.

```hcl
resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
}

# Blocking startup script: workspace is "ready" only after this exits
resource "coder_script" "install_tools" {
  agent_id           = coder_agent.dev.id
  display_name       = "Install Tools"
  icon               = "/icon/code.svg"
  run_on_start       = true
  start_blocks_login = true
  timeout            = 300
  script = <<-EOF
    #!/bin/bash
    set -euo pipefail
    curl -fsSL https://code-server.dev/install.sh | sh
    echo "code-server installed"
  EOF
}
```

--------------------------------

### Example Usage of coder_workspace_tags

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/workspace_tags.md

This example demonstrates how to define parameters and then use their values to configure workspace tags for a coder_workspace_tags data source. It shows dynamic assignment of tag values based on parameter selections and conditional logic.

```terraform
provider "coder" {}

data "coder_parameter" "os_selector" {
  name         = "os_selector"
  display_name = "Operating System"
  mutable      = false

  default = "osx"

  option {
    icon  = "/icons/linux.png"
    name  = "Linux"
    value = "linux"
  }
  option {
    icon  = "/icons/osx.png"
    name  = "OSX"
    value = "osx"
  }
  option {
    icon  = "/icons/windows.png"
    name  = "Windows"
    value = "windows"
  }
}

data "coder_parameter" "feature_cache_enabled" {
  name         = "feature_cache_enabled"
  display_name = "Enable cache?"
  type         = "bool"

  default = false
}

data "coder_parameter" "feature_debug_enabled" {
  name         = "feature_debug_enabled"
  display_name = "Enable debug?"
  type         = "bool"

  default = true
}

data "coder_workspace_tags" "custom_workspace_tags" {
  tags = {
    "cluster" = "developers"
    "os"      = data.coder_parameter.os_selector.value
    "debug"   = "${data.coder_parameter.feature_debug_enabled.value}+12345"
    "cache"   = data.coder_parameter.feature_cache_enabled.value == "true" ? "nix-with-cache" : "no-cache"
  }
}
```

--------------------------------

### coder_parameter Data Source Example

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/parameter.md

This example demonstrates how to define a string parameter named 'Region' with a default value and a list of selectable options.

```APIDOC
## coder_parameter (Data Source)

### Description
Use this data source to configure editable options for workspaces.

### Example Usage

```terraform
provider "coder" {}

data "coder_parameter" "example" {
  name        = "Region"
  description = "Specify a region to place your workspace."
  mutable     = false
  type        = "string"
  default     = "us-central1-a"
  option {
    value = "us-central1-a"
    name  = "US Central"
    icon  = "/icons/1f1fa-1f1f8.png"
  }
  option {
    value = "asia-southeast1-a"
    name  = "Singapore"
    icon  = "/icons/1f1f8-1f1ec.png"
  }
}
```

## Schema

### Required

- `name` (String) The name of the parameter. If this is changed, developers will be re-prompted for a new value.

### Optional

- `default` (String) A default value for the parameter.
- `description` (String) Describe what this parameter does.
- `display_name` (String) The displayed name of the parameter as it will appear in the interface.
- `ephemeral` (Boolean) The value of an ephemeral parameter will not be preserved between consecutive workspace builds.
- `form_type` (String) The type of this parameter. Must be one of: `"radio"`, `"slider"`, `"input"`, `"dropdown"`, `"checkbox"`, `"switch"`, `"multi-select"`, `"tag-select"`, `"textarea"`, `"error"`.
- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/<path>"`.
- `mutable` (Boolean) Whether this value can be changed after workspace creation. This can be destructive for values like region, so use with caution!
- `option` (Block List) Each `option` block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option))
- `order` (Number) The order determines the position of a template parameter in the UI/CLI presentation. The lowest order is shown first and parameters with equal order are sorted by name (ascending order).
- `styling` (String) JSON encoded string containing the metadata for controlling the appearance of this parameter in the UI. This option is purely cosmetic and does not affect the function of the parameter in terraform. See [styling options documentation](https://coder.com/docs/admin/templates/extending-templates/dynamic-parameters#available-styling-options) for available styling attributes.
- `type` (String) The type of this parameter. Must be one of: `"string"`, `"number"`, `"bool"`, `"list(string)"`.
- `validation` (Block List, Max: 1) Validate the input of a parameter. (see [below for nested schema](#nestedblock--validation))

### Read-Only

- `id` (String) The ID of this resource.
- `optional` (Boolean) Whether this value is optional.
- `value` (String) The output value of the parameter.

<a id="nestedblock--option"></a>

```

--------------------------------

### Example Usage of coder_workspace Data Source

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/workspace.md

This example demonstrates how to use the coder_workspace data source to retrieve workspace information and then use that information to configure a Docker container for the workspace. It also shows the usage of coder_workspace_owner and coder_agent data sources and resources.

```terraform
provider "coder" {}

provider "docker" {}

data "coder_workspace" "me" {}

data "coder_workspace_owner" "me" {}

resource "coder_agent" "dev" {
  arch = "amd64"
  os   = "linux"
  dir  = "/workspace"
}

resource "docker_container" "workspace" {
  count = data.coder_workspace.me.start_count
  image = docker_image.main.name
  # Uses lower() to avoid Docker restriction on container names.
  name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
  # Hostname makes the shell more user friendly: coder@my-workspace:~$ 
  hostname = data.coder_workspace.me.name
  # Use the docker gateway if the access URL is 127.0.0.1
  entrypoint = ["sh", "-c", replace(coder_agent.main.init_script, "/localhost|127\.0\.0\.1/", "host.docker.internal")]
  env        = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"]
  host {
    host = "host.docker.internal"
    ip   = "host-gateway"
  }
  # Add labels in Docker to keep track of orphan resources.
  labels {
    label = "coder.owner"
    value = data.coder_workspace_owner.me.name
  }
  labels {
    label = "coder.owner_id"
    value = data.coder_workspace_owner.me.id
  }
  labels {
    label = "coder.workspace_id"
    value = data.coder_workspace.me.id
  }
  labels {
    label = "coder.workspace_name"
    value = data.coder_workspace.me.name
  }
}
```

--------------------------------

### Run a script every 5 minutes

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/script.md

This example sets up a script to run every 5 minutes using a cron schedule. It logs the current date and time.

```terraform
resource "coder_script" "every_5_minutes" {
  agent_id     = coder_agent.dev.id
  display_name = "Health check"
  icon         = "/icon/heart.svg"
  cron         = "0 */5 * * * *" # Run every 5 minutes
  script       = <<EOF
    #!/bin/sh
    echo "Health check at $(date)"
  EOF
}
```

--------------------------------

### Configure a non-blocking dotfiles setup script

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Use `coder_script` for non-blocking startup tasks like setting up dotfiles. The `log_path` attribute specifies where the script's output will be logged. This script uses `templatefile` to inject variables.

```hcl
resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
}

# Non-blocking dotfiles setup
resource "coder_script" "dotfiles" {
  agent_id     = coder_agent.dev.id
  display_name = "Dotfiles"
  icon         = "/icon/dotfiles.svg"
  run_on_start = true
  log_path     = "/tmp/dotfiles.log"
  script = templatefile("${path.module}/scripts/dotfiles.sh", {
    DOTFILES_REPO = var.dotfiles_repo
  })
}
```

--------------------------------

### Get Workspace Runtime Context

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Returns runtime context for the current workspace build, including name, owner, and transition state. The `start_count` attribute is used to conditionally create infrastructure resources only when the workspace is starting.

```hcl
data "coder_workspace" "me" {}
data "coder_workspace_owner" "me" {}

resource "docker_container" "workspace" {
  count    = data.coder_workspace.me.start_count  # 1 on start, 0 on stop
  image    = "codercom/enterprise-base:ubuntu"
  name     = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
  hostname = data.coder_workspace.me.name

  entrypoint = ["sh", "-c", coder_agent.dev.init_script]
  env        = ["CODER_AGENT_TOKEN=${coder_agent.dev.token}"]

  labels {
    label = "coder.workspace_id"
    value = data.coder_workspace.me.id
  }
  labels {
    label = "coder.template_version"
    value = data.coder_workspace.me.template_version
  }
}

# Conditionally act on prebuild vs. assigned workspace
locals {
  is_prebuild = data.coder_workspace.me.prebuild_count == 1
}
```

--------------------------------

### Define a Workspace Preset

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/workspace_preset.md

This example demonstrates how to define a workspace preset with specific parameters. Presets are useful for standardizing common workspace configurations. Ensure that the referenced data sources for parameters are defined elsewhere.

```terraform
data "coder_workspace_preset" "example" {
  name        = "example"
  description = "Example description of what this preset does."
  icon        = "/icon/example.svg"
  parameters = {
    (data.coder_parameter.example.name) = "us-central1-a"
    (data.coder_parameter.ami.name)     = "ami-xxxxxxxx"
  }
}
```

--------------------------------

### Run a script on agent startup and block login

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/script.md

This example demonstrates running a script on agent startup that also blocks user login until it completes. This is useful for ensuring a fully configured environment before a user logs in.

```terraform
resource "coder_script" "code-server" {
  agent_id           = coder_agent.dev.id
  display_name       = "code-server"
  icon               = "/icon/code.svg"
  run_on_start       = true
  start_blocks_login = true
  script = templatefile("./install-code-server.sh", {
    LOG_PATH : "/tmp/code-server.log"
  })
}
```

--------------------------------

### Create a coder_app Resource

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/app.md

This example demonstrates how to create a `coder_app` resource to provide access to a code-server application within a workspace. It includes configuration for the agent, display name, icon, URL, sharing, and health checks.

```terraform
data "coder_workspace" "me" {}

resource "coder_agent" "dev" {
  os             = "linux"
  arch           = "amd64"
  dir            = "/workspace"
  startup_script = <<EOF
curl -fsSL https://code-server.dev/install.sh | sh
code-server --auth none --port 13337
EOF
}

resource "coder_app" "code-server" {
  agent_id     = coder_agent.dev.id
  slug         = "code-server"
  display_name = "VS Code"
  icon         = "${data.coder_workspace.me.access_url}/icon/code.svg"
  url          = "http://localhost:13337"
  tooltip      = "You need to [Install Coder Desktop](https://coder.com/docs/user-guides/desktop#install-coder-desktop) to use this button."
  share        = "owner"
  subdomain    = false
  open_in      = "slim-window"
  healthcheck {
    url       = "http://localhost:13337/healthz"
    interval  = 5
    threshold = 6
  }
}
```

--------------------------------

### Create a coder_app Resource for a command-line application

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/app.md

This example shows how to define a `coder_app` resource for a command-line application like Vim. It specifies the agent, slug, display name, icon, and the command to execute when the app is launched.

```terraform
resource "coder_app" "vim" {
  agent_id     = coder_agent.dev.id
  slug         = "vim"
  display_name = "Vim"
  icon         = "${data.coder_workspace.me.access_url}/icon/vim.svg"
  command      = "vim"
}
```

--------------------------------

### Configure Provider Version (Previous)

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/guides/version-2-upgrade.md

Example of previous provider configuration using version constraints.

```terraform
terraform {
  required_providers {
    coder = {
      source  = "coder/coder"
      version = ">~ 1.0.0"
    }
  }
}

provider "coder" {
  feature_use_managed_variables = true
}
```

--------------------------------

### Define a Default Workspace Preset

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/workspace_preset.md

This example shows how to define a workspace preset that will be pre-selected by default for users. Only one preset per template can be marked as default. This is useful for establishing a standard or recommended configuration.

```terraform
data "coder_workspace_preset" "standard" {
  name        = "Standard"
  description = "A workspace preset with medium compute in the US West region."
  icon        = "/icon/standard.svg"
  default     = true
  parameters = {
    (data.coder_parameter.instance_type.name) = "t3.medium"
    (data.coder_parameter.region.name)        = "us-west-2"
  }
}
```

--------------------------------

### Example Usage of coder_external_auth Data Source

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/external_auth.md

This example demonstrates how to use the coder_external_auth data source to reference configured external authentication providers. The first references a mandatory GitHub provider, while the second references an optional Azure Identity provider.

```terraform
provider "coder" {}

data "coder_external_auth" "github" {
  id = "github"
}

data "coder_external_auth" "azure-identity" {
  id       = "azure-identity"
  optional = true
}
```

--------------------------------

### Basic Terraform Configuration with Coder Provider

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/index.md

This example shows a basic Terraform configuration that includes the Coder provider and demonstrates how to provision a Google Compute Engine instance managed by Coder. It utilizes data sources for workspace information and Coder agent configuration, and resources for the agent and the compute instance.

```terraform
terraform {
  required_providers {
    coder = {
      source = "coder/coder"
    }
  }
}

provider "google" {
  region = "us-central1"
}

data "coder_workspace" "me" {}

resource "coder_agent" "dev" {
  arch = "amd64"
  os   = "linux"
  auth = "google-instance-identity"
}

data "google_compute_default_service_account" "default" {}

resource "google_compute_instance" "dev" {
  zone         = "us-central1-a"
  count        = data.coder_workspace.me.start_count
  name         = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}"
  machine_type = "e2-medium"
  network_interface {
    network = "default"
    access_config {
      // Ephemeral public IP
    }
  }
  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-9"
    }
  }
  service_account {
    email  = data.google_compute_default_service_account.default.email
    scopes = ["cloud-platform"]
  }
  metadata_startup_script = coder_agent.dev.init_script
}
```

--------------------------------

### Run a script on a daily cron schedule

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/script.md

This example configures a script to run daily at 10 PM using a 6-field cron expression. The script updates apt packages.

```terraform
resource "coder_script" "nightly_update" {
  agent_id     = coder_agent.dev.id
  display_name = "Nightly update"
  icon         = "/icon/database.svg"
  cron         = "0 0 22 * * *" # Run at 22:00 (10 PM) every day
  script       = <<EOF
    #!/bin/sh
    echo "Running nightly update"
    sudo apt-get update
  EOF
}
```

--------------------------------

### Get Coder Provisioner Info

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Use the `coder_provisioner` data source to dynamically set the OS and architecture for a `coder_agent`. This avoids hard-coding values and is useful when the provisioner runs on different host types.

```hcl
data "coder_provisioner" "me" {}

resource "coder_agent" "dev" {
  os   = data.coder_provisioner.me.os    # e.g., "linux"
  arch = data.coder_provisioner.me.arch  # e.g., "amd64"
  dir  = "/workspace"
  display_apps {
    vscode       = true
    web_terminal = true
  }
}
```

--------------------------------

### Example Usage of coder_task Data Source

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/task.md

This example demonstrates how to use the `coder_task` data source to conditionally enable or disable resources based on whether the execution context is a Coder Task. It retrieves workspace and task information to control the count of `coder_ai_task` and `example-agent` resources.

```terraform
provider "coder" {}

data "coder_workspace" "me" {}
data "coder_task" "me" {}

resource "coder_ai_task" "task" {
  count  = data.coder_task.me.enabled ? data.coder_workspace.me.start_count : 0
  app_id = module.example-agent.task_app_id
}

module "example-agent" {
  count  = data.coder_task.me.enabled ? data.coder_workspace.me.start_count : 0
  prompt = data.coder_ai_task.me.prompt
}
```

--------------------------------

### Run a script on agent stop

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/script.md

This example configures a script to run when the agent is stopped. It finds and kills a process listening on port 3002.

```terraform
resource "coder_script" "shutdown" {
  agent_id     = coder_agent.dev.id
  display_name = "Stop daemon server"
  run_on_stop  = true
  icon         = "/icons/memory.svg"
  script       = <<EOF
    #!/bin/sh 
    kill $(lsof -i :3002 -t) >/tmp/pid.log 2>&1 &
  EOF
}
```

--------------------------------

### Configure a graceful shutdown script

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Use `run_on_stop = true` in the `coder_script` resource to define actions that should occur when the workspace is shut down. This example stops processes listening on port 3000.

```hcl
resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
}

# Graceful shutdown script
resource "coder_script" "shutdown" {
  agent_id     = coder_agent.dev.id
  display_name = "Stop Services"
  icon         = "/icon/memory.svg"
  run_on_stop  = true
  script       = "kill $(lsof -t -i:3000) 2>/dev/null || true"
}
```

--------------------------------

### Schedule a daily update script using cron

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

The `coder_script` resource can be scheduled using the `cron` attribute. This example sets up a daily dependency update at 22:00. Ensure the script has the necessary permissions to run commands like `apt-get`.

```hcl
resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
}

# Cron script: daily dependency update at 22:00
resource "coder_script" "nightly_update" {
  agent_id     = coder_agent.dev.id
  display_name = "Nightly Update"
  icon         = "/icon/database.svg"
  cron         = "0 0 22 * * *"
  script       = "sudo apt-get update -y && sudo apt-get upgrade -y"
}
```

--------------------------------

### Fetch Workspace Owner and Configure Agent

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/workspace_owner.md

This example demonstrates how to use the coder_workspace_owner data source to retrieve the owner's OIDC access token and set it as an environment variable for a coder_agent. This is useful for agents that need to authenticate with external services using the owner's credentials.

```terraform
provider "coder" {}

data "coder_workspace_owner" "me" {}

resource "coder_agent" "dev" {
  arch = "amd64"
  os   = "linux"
  dir  = "/workspace"
  env = {
    OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token,
  }
}
```

--------------------------------

### Set Environment Variables in a Workspace

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/env.md

This example demonstrates how to set environment variables for a Coder workspace using the `coder_env` resource. It first retrieves workspace information using `coder_workspace` and defines a `coder_agent`. Then, it creates two `coder_env` resources to set `WELCOME_MESSAGE` and `INTERNAL_API_URL` for the agent.

```terraform
data "coder_workspace" "me" {}

resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
  dir  = "/workspace"
}

resource "coder_env" "welcome_message" {
  agent_id = coder_agent.dev.id
  name     = "WELCOME_MESSAGE"
  value    = "Welcome to your Coder workspace!"
}

resource "coder_env" "internal_api_url" {
  agent_id = coder_agent.dev.id
  name     = "INTERNAL_API_URL"
  value    = "https://api.internal.company.com/v1"
}
```

--------------------------------

### Use a secret value in an agent startup script

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/secret.md

This example shows how to reference the value of a previously declared secret within a coder_script resource. The secret's value is accessed via data.coder_secret.<name>.value.

```terraform
# Use the secret value in an agent startup script.
resource "coder_script" "setup" {
  agent_id = coder_agent.main.id
  script   = "echo ${data.coder_secret.my_token.value}"
}
```

--------------------------------

### Attach Metadata to a Kubernetes Pod

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/metadata.md

This example demonstrates how to attach metadata to a Kubernetes pod resource using the `coder_metadata` resource. It includes a description, the pod's UID, and a sensitive public key, linking them to the pod's ID.

```terraform
data "coder_workspace" "me" {
}

resource "kubernetes_pod" "dev" {
  count = data.coder_workspace.me.start_count
  metadata {
    name      = "k8s_example"
    namespace = "example"
  }
  spec {
    # Draw the rest of the pod!
  }
}

resource "tls_private_key" "example_key_pair" {
  algorithm   = "ECDSA"
  ecdsa_curve = "P256"
}

resource "coder_metadata" "pod_info" {
  count       = data.coder_workspace.me.start_count
  resource_id = kubernetes_pod.dev[0].id
  # (Enterprise-only) this resource consumes 200 quota units
  daily_cost = 200
  item {
    key   = "description"
    value = "This description will show up in the Coder dashboard."
  }
  item {
    key   = "pod_uid"
    value = kubernetes_pod.dev[0].uid
  }
  item {
    key   = "public_key"
    value = tls_private_key.example_key_pair.public_key_openssh
    # The value of this item will be hidden from view by default
    sensitive = true
  }
}
```

--------------------------------

### Inject a simple string environment variable

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

The `coder_env` resource injects environment variables into the workspace agent process. This example sets a simple string value for `INTERNAL_API_URL`. Variables already set on the `coder_agent` cannot be overwritten.

```hcl
resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
}

# Simple string variable
resource "coder_env" "api_url" {
  agent_id = coder_agent.dev.id
  name     = "INTERNAL_API_URL"
  value    = "https://api.internal.example.com/v1"
}
```

--------------------------------

### Define Workspace Preset with Prebuilds and Scheduling

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Configure a workspace preset with default parameters, prebuilt instances, and time-based scheduling for those prebuilds. This allows users to select a predefined environment with instant availability.

```hcl
data "coder_parameter" "instance_type" {
  name = "instance_type"
  type = "string"
}
data "coder_parameter" "region" {
  name = "region"
  type = "string"
}

# Default preset with prebuilds
data "coder_workspace_preset" "standard" {
  name        = "Standard"
  description = "Medium compute in US West — recommended for most users."
  icon        = "/icon/aws.svg"
  default     = true
  parameters = {
    (data.coder_parameter.instance_type.name) = "t3.medium"
    (data.coder_parameter.region.name)        = "us-west-2"
  }
  prebuilds {
    instances = 3
    expiration_policy {
      ttl = 86400  # 24 hours
    }
    scheduling {
      timezone = "America/New_York"
      schedule {
        cron      = "* 8-18 * * 1-5"  # business hours weekdays
        instances = 5
      }
      schedule {
        cron      = "* 0-7,19-23 * * 1-5"  # off-hours weekdays
        instances = 1
      }
    }
  }
}
```

--------------------------------

### Declare a secret requirement using a file path

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/secret.md

Use this to declare a secret that will be injected as a file. Provide a helpful message for users if the secret is not satisfied. The file path must start with `~/` or `/`.

```terraform
data "coder_secret" "my_cert" {
  file         = "~/my-cert.pem"
  help_message = "Certificate chain injected as the file ~/my-cert.pem"
}
```

--------------------------------

### Configure Devcontainer for Auto-start

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Use this to auto-start a devcontainer located at the repository root. Ensure the agent_id and workspace_folder are correctly set.

```hcl
resource "coder_devcontainer" "app" {
  agent_id         = coder_agent.dev.id
  workspace_folder = "/home/coder/project"
  config_path      = "/home/coder/project/.devcontainer/devcontainer.json"
}

output "subagent_id" {
  value = coder_devcontainer.app.subagent_id
}
```

--------------------------------

### Define Workspace Preset without Prebuilds

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Create a workspace preset that defines specific parameter values for instance type and region, without configuring prebuilt instances. This is suitable for users who prefer to build their workspace on demand.

```hcl
# Power-user preset (no prebuilds)
data "coder_workspace_preset" "large" {
  name        = "Large"
  description = "High-memory instance for data science workloads."
  parameters = {
    (data.coder_parameter.instance_type.name) = "r6i.2xlarge"
    (data.coder_parameter.region.name)        = "us-east-1"
  }
}
```

--------------------------------

### Vendor Provider for Local Coder Testing

Source: https://github.com/coder/terraform-provider-coder/blob/main/README.md

When testing with a local clone of the Coder repository, use these `go mod` commands to replace the provider module path with your local development path. Ensure the version in the module path matches your `go.mod` file.

```console
go mod edit -replace github.com/coder/terraform-provider-coder/v2=/path/to/terraform-provider-coder
go mod tidy
```

--------------------------------

### Use Parameters in Resource Configuration

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Demonstrates how to reference `coder_parameter` values within resource configurations, such as setting an EC2 instance type based on a region parameter and configuring EBS volume size.

```hcl
resource "aws_instance" "workspace" {
  instance_type     = data.coder_parameter.region.value == "us-central1" ? "t3.medium" : "t3.large"
  availability_zone = data.coder_parameter.region.value
  ebs_block_device {
    volume_size = tonumber(data.coder_parameter.disk_size.value)
  }
}
```

--------------------------------

### Create and Push Git Tag for Release

Source: https://github.com/coder/terraform-provider-coder/blob/main/README.md

Tag a new release using semantic versioning and push the tag to the remote repository to trigger the automated release workflow. Ensure you have pulled the latest changes and are not retagging a commit.

```console
git tag -a v2.1.2 -m "v2.1.2"
git push origin tag v2.1.2
```

--------------------------------

### Set Git identity environment variables from workspace owner

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

This example demonstrates setting `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` using data from the `coder_workspace_owner`. The `coalesce` function provides a fallback for the name, and `count` conditionally creates the email variable if an email is available.

```hcl
# Git identity from workspace owner
data "coder_workspace_owner" "me" {}

resource "coder_env" "git_author_name" {
  agent_id = coder_agent.dev.id
  name     = "GIT_AUTHOR_NAME"
  value    = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
}

resource "coder_env" "git_author_email" {
  agent_id = coder_agent.dev.id
  name     = "GIT_AUTHOR_EMAIL"
  value    = data.coder_workspace_owner.me.email
  count    = data.coder_workspace_owner.me.email != "" ? 1 : 0
}
```

--------------------------------

### Set Git Author Email using Workspace Owner

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/workspace_owner.md

This example configures the GIT_AUTHOR_EMAIL environment variable for a coder_agent, using the workspace owner's email address. It includes a conditional `count` to only create the resource if the owner's email is not empty.

```terraform
resource "coder_env" "git_author_email" {
  agent_id = coder_agent.dev.id
  name     = "GIT_AUTHOR_EMAIL"
  value    = data.coder_workspace_owner.me.email
  count    = data.coder_workspace_owner.me.email != "" ? 1 : 0
}
```

--------------------------------

### Configure Optional External Authentication

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Set up an optional external authentication source, allowing users to skip the authentication step if they choose. This provides flexibility for users who may not need to connect to the external provider.

```hcl
# Optional Azure auth — users can skip it
data "coder_external_auth" "azure" {
  id       = "azure-identity"
  optional = true
}
```

--------------------------------

### Configure an external application link

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Use the `coder_app` resource to create an external link that opens in the client browser without being proxied. The `external` attribute must be set to `true`.

```hcl
resource "coder_app" "docs" {
  agent_id  = coder_agent.dev.id
  slug      = "docs"
  url       = "https://docs.example.com"
  external  = true
  icon      = "${data.coder_workspace.me.access_url}/icon/docs.svg"
}
```

--------------------------------

### coder_workspace

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Provides runtime context for the current workspace build.

```APIDOC
## Data Source: `coder_workspace`

Returns runtime context for the current workspace build: name, owner, transition state (`start`/`stop`), access URL, template info, and prebuild status. The `start_count` attribute (0 or 1) is the idiomatic way to conditionally create infrastructure resources only when the workspace is starting.

### Attributes

* `name` - The name of the workspace.
* `owner` - The owner of the workspace.
* `start_count` - 1 on start, 0 on stop. Used to conditionally create resources.
* `access_url` - The access URL for the workspace.
* `template_info` - Information about the workspace template.
* `prebuild_status` - The status of the workspace prebuild.
* `id` - The ID of the workspace.
* `template_version` - The version of the workspace template.

### Example

```hcl
data "coder_workspace" "me" {}
data "coder_workspace_owner" "me" {}

resource "docker_container" "workspace" {
  count    = data.coder_workspace.me.start_count  # 1 on start, 0 on stop
  image    = "codercom/enterprise-base:ubuntu"
  name     = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
  hostname = data.coder_workspace.me.name

  entrypoint = ["sh", "-c", coder_agent.dev.init_script]
  env        = ["CODER_AGENT_TOKEN=${coder_agent.dev.token}"]

  labels {
    label = "coder.workspace_id"
    value = data.coder_workspace.me.id
  }
  labels {
    label = "coder.template_version"
    value = data.coder_workspace.me.template_version
  }
}

# Conditionally act on prebuild vs. assigned workspace
locals {
  is_prebuild = data.coder_workspace.me.prebuild_count == 1
}
```
```

--------------------------------

### Attach metadata to a Kubernetes pod resource

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

The `coder_metadata` resource attaches key/value pairs to any Terraform resource, which are then displayed in the Coder dashboard. This example attaches information like namespace, pod UID, node name, and SSH keys to a `kubernetes_pod` resource. Sensitive values can be masked.

```hcl
data "coder_workspace" "me" {}

resource "kubernetes_pod" "dev" {
  count = data.coder_workspace.me.start_count
  metadata {
    name      = "coder-dev"
    namespace = "workspaces"
  }
  spec { /* ... */ }
}

resource "tls_private_key" "workspace_key" {
  algorithm   = "ECDSA"
  ecdsa_curve = "P256"
}

resource "coder_metadata" "pod_info" {
  count       = data.coder_workspace.me.start_count
  resource_id = kubernetes_pod.dev[0].id
  daily_cost  = 50  # Enterprise: 50 quota units per day

  item {
    key   = "namespace"
    value = "workspaces"
  }
  item {
    key   = "pod_uid"
    value = kubernetes_pod.dev[0].uid
  }
  item {
    key   = "node"
    value = kubernetes_pod.dev[0].spec[0].node_name
  }
  item {
    key       = "ssh_public_key"
    value     = tls_private_key.workspace_key.public_key_openssh
    sensitive = false
  }
  item {
    key       = "ssh_private_key"
    value     = tls_private_key.workspace_key.private_key_pem
    sensitive = true  # Hidden in the dashboard by default
  }
}
```

--------------------------------

### Basic coder_agent Resource Configuration

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/agent.md

Configures a Linux amd64 agent named 'dev' with specific display apps and metadata. It also shows how to use the agent's init script and token in a Kubernetes pod definition.

```terraform
data "coder_workspace" "me" {
}

resource "coder_agent" "dev" {
  os            = "linux"
  arch          = "amd64"
  dir           = "/workspace"
  api_key_scope = "all"
  display_apps {
    vscode          = true
    vscode_insiders = false
    web_terminal    = true
    ssh_helper      = false
  }

  metadata {
    display_name = "CPU Usage"
    key          = "cpu_usage"
    script       = "coder stat cpu"
    interval     = 10
    timeout      = 1
    order        = 2
  }
  metadata {
    display_name = "RAM Usage"
    key          = "ram_usage"
    script       = "coder stat mem"
    interval     = 10
    timeout      = 1
    order        = 1
  }

  order = 1
}

resource "kubernetes_pod" "dev" {
  count = data.coder_workspace.me.start_count
  spec {
    container {
      command = ["sh", "-c", coder_agent.dev.init_script]
      env {
        name  = "CODER_AGENT_TOKEN"
        value = coder_agent.dev.token
      }
    }
  }
}
```

--------------------------------

### Access Coder AI Task Context

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

The `coder_task` data source reads runtime context when a workspace is invoked as a Coder AI Task. `enabled` distinguishes a task invocation from a regular workspace start, and `prompt` holds the text prompt submitted to the task. Requires Coder v2.28+.

```hcl
data "coder_workspace" "me" {}
data "coder_task" "me" {}

resource "coder_agent" "dev" {
  os  = "linux"
  arch = "amd64"
  env = {
    TASK_PROMPT = data.coder_task.me.prompt
  }
}

resource "coder_app" "ai_interface" {
  agent_id = coder_agent.dev.id
  slug     = "ai-chat"
  url      = "http://localhost:8080"
  share    = "owner"
}

resource "coder_ai_task" "task" {
  count  = data.coder_task.me.enabled ? data.coder_workspace.me.start_count : 0
  app_id = coder_app.ai_interface.id
}
```

--------------------------------

### Set Git Author Name using Workspace Owner

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/workspace_owner.md

This example shows how to set the GIT_AUTHOR_NAME environment variable for a coder_agent using the workspace owner's full name or username. It uses the `coalesce` function to prioritize the full name if available, otherwise falling back to the username.

```terraform
resource "coder_env" "git_author_name" {
  agent_id = coder_agent.agent_id
  name     = "GIT_AUTHOR_NAME"
  value    = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
}
```

--------------------------------

### Define Drop-down Parameter with Icons

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Use the `coder_parameter` data source to create a string parameter with selectable options, each associated with an icon. This is useful for user-friendly selection of cloud regions or similar choices.

```hcl
data "coder_parameter" "region" {
  name        = "region"
  display_name = "Cloud Region"
  description = "Select the region for your workspace."
  type        = "string"
  mutable     = false
  default     = "us-central1"
  order       = 1
  option {
    name  = "US Central"
    value = "us-central1"
    icon  = "/icons/1f1fa-1f1f8.png"
  }
  option {
    name  = "Europe West"
    value = "europe-west1"
    icon  = "/icons/1f1ea-1f1fa.png"
  }
}
```

--------------------------------

### coder_provisioner Data Source

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/provisioner.md

Use the `coder_provisioner` data source to retrieve information about the Coder provisioner. This is useful for configuring agents or other resources that depend on the provisioner's environment details.

```APIDOC
## coder_provisioner (Data Source)

### Description

Use this data source to get information about the Coder provisioner.

### Schema

#### Read-Only Attributes

- **arch** (String) The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).
- **id** (String) The ID of this resource.
- **os** (String) The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).

### Example Usage

```terraform
provider "coder" {}

data "coder_provisioner" "dev" {}

data "coder_workspace" "dev" {}

resource "coder_agent" "main" {
  arch = data.coder_provisioner.dev.arch
  os   = data.coder_provisioner.dev.os
  dir  = "/workspace"
  display_apps {
    vscode          = true
    vscode_insiders = false
    web_terminal    = true
    ssh_helper      = false
  }
}
```
```

--------------------------------

### Basic String Parameter

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/parameter.md

Defines a string parameter with a default value and selectable options. Use this to provide users with a predefined list of choices for a workspace setting.

```terraform
provider "coder" {}

data "coder_parameter" "example" {
  name        = "Region"
  description = "Specify a region to place your workspace."
  mutable     = false
  type        = "string"
  default     = "us-central1-a"
  option {
    value = "us-central1-a"
    name  = "US Central"
    icon  = "/icons/1f1fa-1f1f8.png"
  }
  option {
    value = "asia-southeast1-a"
    name  = "Singapore"
    icon  = "/icons/1f1f8-1f1ec.png"
  }
}
```

--------------------------------

### Terraform Configuration for Local Development

Source: https://github.com/coder/terraform-provider-coder/blob/main/README.md

Include this block in your `main.tf` to specify the coder provider and trigger the local development override warning upon `terraform init`.

```hcl
terraform {
    required_providers {
        coder = {
            source = "coder/coder"
        }
    }
}
```

--------------------------------

### Register a Dev Container configuration with an agent

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

The `coder_devcontainer` resource registers a Dev Container configuration with an agent, enabling auto-start using the Dev Containers specification. This requires Coder v2.21+.

```hcl
resource "coder_agent" "dev" {
  os   = "linux"
  arch = "amd64"
}

```

--------------------------------

### coder_agent_instance Resource

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/resources/agent_instance.md

The `coder_agent_instance` resource is used to associate a `coder_agent` with a specific cloud instance. This is crucial for enabling zero-trust authentication by linking the agent's identity to the instance's identity. While this association can be done manually, it is often handled automatically for common cloud provider instance resources.

```APIDOC
## coder_agent_instance Resource

### Description
Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources.

### Schema

#### Required

- `agent_id` (String) - The `id` property of a `coder_agent` resource to associate with.
- `instance_id` (String) - The instance identifier of a provisioned resource.

#### Read-Only

- `id` (String) - The ID of this resource.
```

--------------------------------

### Prepend to the PATH environment variable

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Use the `merge_strategy` attribute with `prepend` to add a directory to the existing `PATH` environment variable. This ensures that executables in the prepended directory are found first.

```hcl
# PATH extension using append strategy
resource "coder_env" "extra_path" {
  agent_id       = coder_agent.dev.id
  name           = "PATH"
  value          = "/home/coder/.local/bin"
  merge_strategy = "prepend"
}
```

--------------------------------

### Define Workspace Tags with Dynamic Values

Source: https://context7.com/coder/terraform-provider-coder/llms.txt

Configure workspace tags using the `coder_workspace_tags` data source. Tag values can be static strings or dynamic expressions referencing `coder_parameter` values, enabling dynamic routing of builds.

```hcl
data "coder_parameter" "os" {
  name    = "os"
  type    = "string"
  default = "linux"
  option { name = "Linux";   value = "linux" }
  option { name = "Windows"; value = "windows" }
}

data "coder_parameter" "use_cache" {
  name    = "use_cache"
  type    = "bool"
  default = true
}

data "coder_workspace_tags" "tags" {
  tags = {
    "cluster"  = "production"
    "os"       = data.coder_parameter.os.value
    "cache"    = data.coder_parameter.use_cache.value == "true" ? "nix-cache" : "no-cache"
  }
}
```

--------------------------------

### String Parameter with Markdown Description

Source: https://github.com/coder/terraform-provider-coder/blob/main/docs/data-sources/parameter.md

Configures a string parameter where the description includes markdown for richer formatting. This is useful for providing detailed instructions or links within the parameter's help text.

```terraform
data "coder_parameter" "ami" {
  name        = "Machine Image"
  description = <<-EOT
    # Provide the machine image
    See the [registry](https://container.registry.blah/namespace) for options.
    EOT
  option {
    value = "ami-xxxxxxxx"
    name  = "Ubuntu"
    icon  = "/icon/ubuntu.svg"
  }
}
```