Background

TLDR: When a parameter option value is changed, workspaces with the old value are unable to update.

I recommend watching my Loom video that describes the problem, why it matters, workarounds, and potential solutions.

The problem was initially described here #7442 but I figured I would create a new issue to describe the problem, share a couple of potential ways we can fix this in the product, and share workarounds!

Must have

• fix: prompt when parameter options are incompatible #9247 When parameter values change and there is a validation error, the user should see a pop-up to pick an appropriate value for the new version. Right now, workspaces get stuck and are unable to update
• docs: incompatibility in parameter options for workspace builds #9297 Documentation for the proper way to update image sources and tags via parameters

Should have

• Some way to update image source / tag without using locals as a dictionary.
  • Some ideas: we only save parameter name in the DB. the value is interpreted from the new version or add another value (e.g. slug) to save instead of the value in the DB.
  • I'm not really sure the best way to do this, but this is a common use case and the locals workaround feels a bit hacky to me.

To un-brick your workspace

A user can run coder update <workspace> --always-prompt from the CLI to get prompted to fill in the new parameters.

The locals workaround

If you are a template admin, you can do this to safely update your workspaces without causing workspaces to get un-updatable:

variable "go_image" {
}
variable "java_image" {
}

locals {
  images = {
    "go": var.go_image,
    "java": var.java_image
  }
}

data "coder_parameter" "image" {
  name = "Image"
  default = "go"
  type = "string"
  option {
    name = "Golang"
    value = "go"
  }
  option {
    name = "Java"
    value = "java"
  }
  mutable = "true"
}

resource "docker_container" "workspace" {
  count = data.coder_workspace.me.start_count
  image = local.images[data.coder_parameter.image.value]
  # 
}

Example commands:

# Create the template
coder templates push --var go_image="mcr.microsoft.com/devcontainers/go:1.20" --var java_image="mcr.microsoft.com/devcontainers/java:8" -y

# Push a new template version that uses Java 11, not Java 8
coder templates push --var go_image="mcr.microsoft.com/devcontainers/go:1.20" --var java_image="mcr.microsoft.com/devcontainers/java:11" -y