Skip to content

feat: allow execution ordering for coder_script #10352

Description

@stirby

Overview

Currently, when building a workspace with multiple instances of coder_script, all are run concurrently, preventing any sequencing logic. To remedy this, some serialization should be implemented allowing users to either define the sequence manually or through a dependency graph.

Activity

  1. spikecurtis commented on Oct 30, 2023

    @spikecurtis
    Collaborator

    I'd actually call this a bug. We don't know a priori that scripts are safe to run concurrently. In particular, I use dotfiles to install software on startup, and this fails if other scripts are also doing dpkg stuff

    Running install.sh...
    E: Could not get lock /var/lib/dpkg/lock-frontend. It is held by process 176 (apt-get)
    E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), is another process using it?
    sudo: add-apt-repository: command not found
    
  2. added
    s2Broken use cases or features (with a workaround). Only humans may set this.
    and removed on Oct 30, 2023
  3. matifali commented on Oct 30, 2023

    @matifali
    Contributor

    It could be done in multiple ways,

    1. Use a syntax like run_after = coder_script.dotfiles. If no run_after exists, we can default to running alphabetically.
    resource "coder_script" "dotfiles" {
      agent_id = coder_agent.main.id
      ...
    }
    
    resource "coder_script" "personalize" {
      agent_id = coder_agent.main.id
      ...
      run_after = coder_script.dotfiles
    }
    1. We use order the same as with coder_parameter, It may look something like the below,
    resource "coder_script" "dotfiles" {
      agent_id = coder_agent.main.id
      ...
      order    = "1"
    }
    
    resource "coder_script" "personalize" {
      agent_id = coder_agent.main.id
      ...
      order    = "2"
    }
    1. I am not sure if we can also use the built-in terraform depends_on as the scripts are run after the terraform apply has finished (in a running workspace by the coder_agent)
    resource "coder_script" "dotfiles" {
      agent_id = coder_agent.main.id
      ...
    }
    
    resource "coder_script" "personalize" {
      agent_id   = coder_agent.main.id
      ...
      depends_on = ["coder_script.dotfiles"]
    }

    I am not very sure how we can expose this on module level and how the coder_agent will use this.

  4. kconley-sq commented on Oct 30, 2023

    @kconley-sq
    Contributor

    I think it'd be neat if depends_on could be used for this because otherwise I think the run_after or order approaches would require Coder (Terraform) modules providing coder_script's to expose those fields as module input variables for consumers of the module to set them, and I imagine that exposing may not be done consistently (at least for 3rd party modules).

  5. ammario commented on Nov 13, 2023

    @ammario
    Member

    I strongly prefer a depends_on or similar DAG-based approach as its consistent with Terraform's philosophy.

  6. matifali commented on Nov 14, 2023

    @matifali
    Contributor

    This is a prerequisite for coder/registry#82

  7. bpmct commented on Nov 16, 2023

    @bpmct
    Member

    We had a chat with @kylecarbs on this yesterday. Here are some conclusions.

    • depends_on is very idiomatic but may be difficult for module 1 to wait on a script for module 2. We're not entirely sure so this should require a bit of investigation
    • Another idea is for a startup script to do something inline to wait on another script
      coder script wait code-server
      code-server --install-extension myextension
      • This was @bpmct and @kylecarbs preference because it also allows us to do stuff like coder script follow to see logs or even coder script restart if something fails. A pretty good new abstraction :)
    • We definitely want to avoid an order property
  8. spikecurtis commented on Nov 16, 2023

    @spikecurtis
    Collaborator

    This is getting complex enough that we should have an RFC, IMO. But, since I'm thinking about it right now, I'll add some comments directly to the issue.


    depends_on sort of makes sense if you squint, but usually it's for telling Terraform about dependencies such that terraform apply does things in the right order. Here, it's not terraform apply that needs to get stuff in the right order, it's the script execution in the agent.


    One big downside of coder script wait is that the script itself needs to be aware of the exact thing it is waiting for. But, when scripts are encapsulated in modules, the module author might not know about a problem. For example, my dotfiles consistently fail to run install.sh because another script is holding the dpkg lock. In order to use coder script wait, firstly, it would mean my dotfiles only work on Coder, and secondly, they would probably only work on a specific Coder template where I can figure out what script is conflicting.

    Another related issue is that a module author might know what it is dependent on, but not which module provides it. Some dependencies might not be provided by any modules and instead are baked in. For example, my module might require curl. Maybe curl is just available in my image, or maybe some other script or module installs it, as a module author I shouldn't have to know as this creates inflexible dependencies.

    Therefore, I think we need to be able to define module dependencies in the template, so that the template author has flexibility to control dependencies, rather than forcing the module author to.


    One last comment is that modules generally don't expose their scripts as outputs, so we need to handle all combinations of module and script dependencies. Then, in the terraform provisioner, we can resolve the DAG of scripts & modules into a DAG of just scripts.

    • script -> script
    • script -> module
      • the script gets an edge to every script in the target module
    • module -> script
      • every script in the module gets an edge to the target script
    • module -> module
      • every script in the module gets an edge to every script in the target module
  9. matifali commented on Nov 16, 2023

    @matifali
    Contributor

    I agree with @spikecurtis reservation and on having an RFC on this.

    My thoughts:

    1. Modules can or cannot contain coder_script resources depending on the nature of what the module does. We have modules that only add some coder_parameter data items to the workspace form.
    2. For Modules that use coder_script, they can have multiple coder_script resources, and in that case, we do need an order property that the module builder will use or if someone is directly using coder_script resources in a template.
    3. For all modules that use any coder_script resource, we must pass an agent_id in the form of coder_agent.NAME.id as input. So, for one module to depend on another, we need a way to let the agent running the module's coder_script resources wait for any dependency modules' ' coder_script` resources to finish executing. I am unsure how it can be done while staying close to what we have now.
  10. bpmct commented on Nov 18, 2023

    @bpmct
    Member

    Workaround

    For those looking for this behavior today, you can use a bash while loop in your coder script to wait for a specific command (e.g. code-server to become available or conditionals to wait for a process to complete, start, or be unlocked)

  11. michaelbrewer commented on Apr 5, 2024

    @michaelbrewer
    Contributor

    Workaround

    For those looking for this behavior today, you can use a bash while loop in your coder script to wait for a specific command (e.g. code-server to become available or conditionals to wait for a process to complete, start, or be unlocked)

    This kind of works, but there are many other cases, like git-clone script needs to complete before executing the next script from another module.

  12. MrPeacockNLB commented on Apr 5, 2024

    @MrPeacockNLB
    Contributor

    We are using more than 16 scripts at startup. Some of them has to wait until git cloned has finished. Other has to wait for other scripts or at least part of it. We are providing 2 simple bash scripts to realize the sendSignal and waitFor. This creates a file under /tmp and the other waits in a while loop until it is created. This way we can build our own DAG.

    NOTE: Sending signals should be possible at any time or any place. Not just at the edges of entry and exit points!

    This works pretty stable. But it would be nice if there was something similar as build in function without needing to store files in a temporary filesystem. For me I could think of storing signals at workspace level.

    coder signal git-cloned # This sends the signal to coder server
    coder waitfor git-cloned # wait until signal "git-clond" has been send to coder server

    @michaelbrewer I can say this works as expected

  13. 41 remaining items

  14. SasSwart commented on Oct 20, 2025

    @SasSwart
    Collaborator

    Update:

    The first of a few components required for this feature is nearing completion here:
    #20208

  15. SasSwart commented on Dec 1, 2025

    @SasSwart
    Collaborator

    Hey all,

    Update:

    We've implemented an experimental feature to address this issue. We're trying to get it in by the next release (cc @david-fraley).

    I will provide documentation on how to use the feature soon, but basic examples can already be seen in the description of #20976.

  16. Ashok-Varma commented on Feb 19, 2026

    @Ashok-Varma

    Hi @SasSwart 👋

    This is great progress — thanks for pushing this forward!

    I had a couple of clarifications regarding usage:

    1. Can we use this with existing Terraform-based templates?
      The examples in feat: implement agent socket api, client and cli (#20758) #20976 show usage via CLI commands inside scripts, but I don’t see documentation yet on how this integrates from a Terraform perspective. feat: allow execution ordering for coder_script #10352 (comment) which would be last phase of this. But just curious

    2. Terraform usage pattern
      My understanding is that we would invoke this inside a coder_script, for example at the beginning of the script:

      coder exp sync want --script="<dependency-script>"

      Is that the intended approach for testing right now ?
      Or is there (or will there be) a first-class Terraform attribute for declaring dependencies directly in coder_script?

    3. Feature flags / version requirements

      • Do we need to enable any experimental flags to use this?
      • Is there a minimum Coder server / agent version required?
      • Does the Terraform provider need to be on a specific version?

    It would be helpful to understand:

    • Whether this is purely runtime orchestration (CLI-only inside scripts), or
    • If we should expect upcoming Terraform-level support for defining dependencies declaratively.

    Thanks again — excited to try this out 🚀

  17. SasSwart commented on Feb 19, 2026

    @SasSwart
    Collaborator

    Hey there @Ashok-Varma!

    I'm delighted to see your interest in the feature.
    We do have plans to integrate this with Terraform for a better user experience and to allow a-priori dependency expression. The coder exp sync want was the minimal shippable increment.

    The implementation isn't planned for the immediate term, but I do have some conceptual designs ready for this.

    I hope to implement this as soon as I can, but I can't provide a more specific timeline than that right now. If anything changes, I'll post an update here.

  18. Ashok-Varma commented on Feb 20, 2026

    @Ashok-Varma

    Thank you for the clarification @SasSwart 🙌

    Just confirming these 2 points

    1. In the meantime, My understanding is that for now we could invoke these cli commands inside a coder_script, for example at the beginning of the script: coder exp sync want --script="<dependency-script>", Is this expectation correct, for testing and early adoption right now.
    2. There is currently no first-class Terraform attribute for declaring dependencies directly in coder_script, but that is something you’re conceptually planning for later — correct?

    Appreciate the guidance — we’re keen to start experimenting with this.

  19. SasSwart commented on Feb 20, 2026

    @SasSwart
    Collaborator
    1. Correct, you can find more information on how to do so here.
    2. Correct.

    I'm excited that you're experimenting with this!
    If you'd like to have a more high-bandwidth conversation, please feel free to reach out in our community Discord as well. I'd be happy to take note of your experience onboarding the feature. It will help me build it out to be maximally valuable!

  20. ewengillies commented on Feb 27, 2026

    @ewengillies

    thanks for shipping an exciting new feature!

    just to add a request/use-case. It goes like this:

    1. Sometimes I want my coder_script to depend on a TF module.
    2. The implementation details of the TF module are outside my scope/control.
      a. The TF module might call coder_script or something else entirely.
      b. A common issue would be something like apt-get or some other blocking installation calls inside the module.
      c. I don't control how the module behaviour changes over time either - its internals are opaque.
    3. The script is in my control - i.e. I can add coder cli calls at my whim.
    4. I want to run my script after one or more modules-I-install-but-cannot-change have finished.

    Is this something that is on the table if/when the first-class TF attribute is ready (a la depends_on)? Are there any workarounds here that do not involve sleep?

    Also - is there a better issue to raise this use-case on? this current one is closed, which makes sense since the original scope only mentioned coder_script dependencies.

  21. matifali commented on Feb 27, 2026

    @matifali
    Contributor

    @ewengillies, I created #22365 to cover the Terraform side of this.
    @SasSwart please update/edit the issue as needed.

  22. SasSwart commented on Mar 3, 2026

    @SasSwart
    Collaborator

    Update:

    I've built a prototype to add Terraform support for the ordering solution we've built so far and I'd love some feedback from any interested stakeholders. The solutions proposed so far all rely on a decentralised dependency definition mechanism. See here for examples. This is similar to how Systemd declares dependencies within its unit files. Unfortunately, these do not stand up to implementation in our particular environment because of Terraform SDK related minutiae.

    Instead, I've implemented this interface:

    data "coder_unit_graph" "startup" {
      dependencies {
        unit            = "setup"
        depends_on_unit = "clone"
        to_be           = "completed"
      }
      dependencies {
        unit            = "app"
        depends_on_unit = "setup"
        to_be           = "completed"
      }
    }
    resource "coder_script" "clone" {
      unit_name    = "clone"
      ...
    }
    
    resource "coder_script" "setup" {
      unit_name    = "setup"
      ...
    }
    
    resource "coder_script" "app" {
      unit_name    = "app"
      ...
    }

    It produces the following timing chart:
    Image

    It uses a centrally declared dependency graph. Given this solution, any template author would be able to centrally manage the ordering and dependencies of any coder script in their template, regardless of the module of origin. Directed Acyclic Dependency graphs of practically arbitrary complexity should be possible, although more complex graphs will be difficult to troubleshoot unless we build additional tooling to assist.

    If using this interface, users would not need to use the coder exp sync commands.

  23. Ashok-Varma commented on Mar 7, 2026

    @Ashok-Varma

    Thank you @SasSwart for this, I'll try out in couple of weeks. this will be very handy, compared to coder exp sync commands

    I was just curious on the API, can we not use depends_on parameter to build the DAG, given it's terraform native way to declare dependencies, API might be more intuative, if that's feasible.
    I'm not sure of any complications to use that, or if it wouldn't fit certain usecases. But I'm just curious on API

    Ignore this : I've read the above thread, which is very detailed, Thankyou

  24. Ashok-Varma commented on Apr 3, 2026

    @Ashok-Varma

    Looks like we don't have this in Terra-form yet

  25. matifali commented on Apr 3, 2026

    @matifali
    Contributor

    Looks like we don't have this in Terra-form yet

    Yes for tracking that you can follow #22365

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions