docs: describe dynamic options and locals (#9429)

examples/parameters-dynamic-options/README.md

@@ -0,0 +1,40 @@
+---
+name: Sample Template with Dynamic Parameter Options
+description: Review the sample template and introduce dynamic parameter options to your template
+tags: [local, docker, parameters]
+icon: /icon/docker.png
+---
+
+# Overview
+
+This Coder template presents use of [dynamic](https://developer.hashicorp.com/terraform/language/expressions/dynamic-blocks) [parameter options](https://coder.com/docs/v2/latest/templates/parameters#options) and Terraform [locals](https://developer.hashicorp.com/terraform/language/values/locals).
+
+## Use case
+
+The Coder template makes use of Docker containers to provide workspace users with programming language SDKs like Go, Java, and more.
+The template administrator wants to make sure that only certain versions of these programming environments are available,
+without allowing users to manually change them.
+
+Workspace users should simply choose the programming environment they prefer. When the template admin upgrades SDK versions,
+during the next workspace update the chosen environment will automatically be upgraded to the latest version without causing any disruption or prompts.
+
+The references to Docker images are represented by Terraform variables, and they're passed via the configuration file like this:
+
+```yaml
+go_image: "bitnami/golang:1.20-debian-11"
+java_image: "bitnami/java:1.8-debian-11
+```
+
+The template admin needs to update image references, publish a new version of the template, and then either handle workspace updates on their own or let workspace users take care of it.
+
+## Development
+
+Update the template and push it using the following command:
+
+```bash
+./scripts/coder-dev.sh templates push examples-parameters-dynamic-options \
+  -d examples/parameters-dynamic-options \
+  --variables-file examples/parameters-dynamic-options/variables.yml \
+  --create \
+  -y
+```

examples/parameters-dynamic-options/main.tf

@@ -0,0 +1,157 @@
+terraform {
+  required_providers {
+    coder = {
+      source  = "coder/coder"
+      version = "0.11.1"
+    }
+    docker = {
+      source  = "kreuzwerker/docker"
+      version = "~> 2.22"
+    }
+  }
+}
+
+variable "go_image" {
+  description = "Go SDK image reference"
+  type        = string
+}
+
+variable "java_image" {
+  description = "Java image reference."
+  type        = string
+}
+
+locals {
+  username = data.coder_workspace.me.owner
+
+  images = {
+    "go"   = var.go_image,
+    "java" = var.java_image,
+  }
+}
+
+data "coder_provisioner" "me" {
+}
+
+data "coder_workspace" "me" {
+}
+
+data "coder_parameter" "container_image" {
+  name         = "container_image"
+  display_name = "Workspace container image"
+  description  = "Select the container image for your development environment."
+  default      = "java"
+  mutable      = true
+
+  dynamic "option" {
+    for_each = [for k in keys(local.images) : { name = k, value = lower(k) }]
+    content {
+      name  = option.value.name
+      value = option.value.value
+    }
+  }
+}
+
+resource "coder_agent" "main" {
+  arch           = data.coder_provisioner.me.arch
+  os             = "linux"
+  startup_script = <<EOF
+    #!/bin/sh
+    # install and start code-server
+    curl -fsSL https://code-server.dev/install.sh | sh -s -- --version 4.8.3
+    code-server --auth none --port 13337
+    EOF
+
+  env = {
+    GIT_AUTHOR_NAME     = "${data.coder_workspace.me.owner}"
+    GIT_COMMITTER_NAME  = "${data.coder_workspace.me.owner}"
+    GIT_AUTHOR_EMAIL    = "${data.coder_workspace.me.owner_email}"
+    GIT_COMMITTER_EMAIL = "${data.coder_workspace.me.owner_email}"
+  }
+}
+
+resource "coder_app" "code-server" {
+  agent_id     = coder_agent.main.id
+  slug         = "code-server"
+  display_name = "code-server"
+  url          = "http://localhost:13337/?folder=/home/${local.username}"
+  icon         = "/icon/code.svg"
+  subdomain    = false
+  share        = "owner"
+
+  healthcheck {
+    url       = "http://localhost:13337/healthz"
+    interval  = 5
+    threshold = 6
+  }
+}
+
+resource "docker_volume" "home_volume" {
+  name = "coder-${data.coder_workspace.me.id}-home"
+  lifecycle {
+    ignore_changes = all
+  }
+  labels {
+    label = "coder.owner"
+    value = data.coder_workspace.me.owner
+  }
+  labels {
+    label = "coder.owner_id"
+    value = data.coder_workspace.me.owner_id
+  }
+  labels {
+    label = "coder.workspace_id"
+    value = data.coder_workspace.me.id
+  }
+  labels {
+    label = "coder.workspace_name_at_creation"
+    value = data.coder_workspace.me.name
+  }
+}
+
+resource "coder_metadata" "home_info" {
+  resource_id = docker_volume.home_volume.id
+
+  item {
+    key   = "size"
+    value = "5 GiB"
+  }
+}
+
+resource "docker_container" "workspace" {
+  count      = data.coder_workspace.me.start_count
+  image      = local.images[data.coder_parameter.container_image.value]
+  name       = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
+  hostname   = data.coder_workspace.me.name
+  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}",
+    "CODER_PARAMETER_CONTAINER_IMAGE=${local.images[data.coder_parameter.container_image.value]}"
+  ]
+  host {
+    host = "host.docker.internal"
+    ip   = "host-gateway"
+  }
+  volumes {
+    container_path = "/home/${local.username}"
+    volume_name    = docker_volume.home_volume.name
+    read_only      = false
+  }
+
+  labels {
+    label = "coder.owner"
+    value = data.coder_workspace.me.owner
+  }
+  labels {
+    label = "coder.owner_id"
+    value = data.coder_workspace.me.owner_id
+  }
+  labels {
+    label = "coder.workspace_id"
+    value = data.coder_workspace.me.id
+  }
+  labels {
+    label = "coder.workspace_name"
+    value = data.coder_workspace.me.name
+  }
+}

examples/parameters-dynamic-options/variables.yml

@@ -0,0 +1,2 @@
+go_image: "bitnami/golang:1.20-debian-11"
+java_image: "bitnami/java:1.8-debian-11"