feat: add filtering by initiator to provisioner job listing in the CLI #20137

SasSwart · 2025-10-02T07:35:17Z

This PR provides a mechanism to filter provisioner jobs according to who initiated the job.
This will be used to find pending prebuild jobs when prebuilds have overwhelmed the provisioner job queue. They can then be canceled.

If prebuilds are overwhelming provisioners, the following steps will be taken:

# pause prebuild reconciliation to limit provisioner queue pollution:
coder prebuilds pause 
# cancel pending provisioner jobs to clear the queue
coder provisioner jobs list --initiator="prebuilds" --status="pending" | jq ... | xargs -n1 -I{} coder provisioner jobs cancel {}
# push a fixed template and wait for the import to complete
coder templates push ... # push a fixed template
# resume prebuild reconciliation
coder prebuilds resume

This interface differs somewhat from what was specified in the issue, but still provides a mechanism that addresses the issue. The original proposal was made by myself and this simpler implementation makes sense. I might add a --search parameter in a follow-up if there is appetite for it.

Potential follow ups:

Support for this usage: coder provisioner jobs list --search "initiator:prebuilds status:pending"
Adding the same parameters to coder provisioner jobs cancel as a convenience feature so that operators don't have to pipe through jq and xargs

SasSwart · 2025-10-02T07:39:20Z

cli/provisionerjobs_test.go

 	t.Run("Cancel", func(t *testing.T) {
 		t.Parallel()

+		db, ps := dbtestutil.NewDB(t)


Moving this inside the subtest to properly isolate these tests from the list subcommand tests

SasSwart · 2025-10-02T07:40:11Z

cli/provisionerjobs_test.go

 		}
 	})
+
+	t.Run("List", func(t *testing.T) {


There were no tests for the list subcommand. I've added some basic test cases as a scouting effort, but I focus on the tests to prove my own work right now.

mafredri

Looks good, and thanks for expanding test coverage.

I don't see anything blocking, so approving, but had a few comments inline.

mafredri · 2025-10-02T09:43:11Z

cli/provisionerjobs.go


+			var initiatorID *uuid.UUID
+
+			if initiatorIDStr != "" {


This can be ID or name, right? Suggest renaming it to be more generic.

mafredri · 2025-10-02T09:48:02Z

coderd/provisionerjobs.go

 // @Param ids query []string false "Filter results by job IDs" format(uuid)
 // @Param status query codersdk.ProvisionerJobStatus false "Filter results by status" enums(pending,running,succeeded,canceling,canceled,failed)
 // @Param tags query object false "Provisioner tags to filter by (JSON of the form {'tag1':'value1','tag2':'value2'})"
+// @Param initiator_id query string false "Filter results by initiator ID" format(uuid)


I'm not opposed to enforcing uuid here, but typically we allow for both name and UUID for users (which this kind of is), and usually even me. Food for thought before we introduce this as part of stable API.

SasSwart · 2025-10-02T09:54:39Z

@mafredri do you have opinions for or against the coder provisioner jobs list --search "initiator:prebuilds status:pending" syntax? I'd like to know whether I should work on a follow up for it or whether that can wait.

Same question applies to whether or not I should add bulk deletion using the --initiator flag to coder provisioner jobs cancel. Do you see value in this?

mafredri · 2025-10-02T10:06:09Z

@mafredri do you have opinions for or against the coder provisioner jobs list --search "initiator:prebuilds status:pending" syntax? I'd like to know whether I should work on a follow up for it or whether that can wait.

I don't mind adding --search, I like to have feature parity with UI and also a unified interface across commands (e.g. coder list).

If we want to keep --initiator and --status, though, we need to either deprecate them or change the documentation to say alias for "--search status:[value]", etc. The --search query is less discoverable so I somewhat prefer the alias route.

Same question applies to whether or not I should add bulk deletion using the --initiator flag to coder provisioner jobs cancel. Do you see value in this?

I'm not sold it's needed on cancel as canceling everything on such a granularity seems potentially dangerous. By listing you are encouraged to vet the list before proceeding.

I think a step 1 could be to just allow passing multiple IDs to cancel.

# via args
coder provisioner jobs cancel $(coder provisioner jobs list --initiator prebuild --quiet)

# via stdin
coder provisioner jobs list --initiator prebuild --quiet | coder provisioner jobs cancel --stdin

See coder exp task list --quiet for motivation for the quiet flag (prints only IDs, same behavior as docker commands).

ssncferreira

Overall this looks good! I just left a few questions in the inline comments. A couple of additional thoughts:

~~In the PR description, you mention a --status="pending" flag, but I see the CLI already has a status option:~~
```
 -s, --status [offline|idle|busy], $CODER_PROVISIONER_LIST_STATUS
        Filter by provisioner status.
```
~~Could you update the description?~~ (edit: was looking at the coder provisioner list CLI command by mistake)
In the description you also note:
```
Adding the same parameters to coder provisioner jobs cancel as a convenience feature so that operators don't have to pipe through jq and xargs
```
I wonder if it might be more reliable to pass an explicit list of job IDs to the cancel command. That way, you know exactly what’s being canceled and avoid the risk of unintentionally including other jobs.
Not necessarly for this PR, but down the line it could be really useful to support search queries for template (and possibly version, defaulting to active). The main use case I see for this command would be when a faulty template is published, and users want to quickly delete all the related prebuild jobs. That could be a nice follow-up.

ssncferreira · 2025-10-02T11:11:05Z

cli/provisionerjobs.go


+			var initiatorID *uuid.UUID
+
+			if initiatorIDStr != "" {


I’m curious, what made you go with initiator instead of owner here? If I’m remembering correctly, prebuild claims also use the prebuild system user as the initiator (link), which makes me wonder if this might unintentionally filter prebuild claim related jobs.

Also, for consistency with other parts of Coder (e.g., coder list --search and the UI both use owner), I wonder if using a search flag and owner might be a clearer fit. What do you think?

Owner doesn't fit the data model, because jobs can either be workspace builds or template imports. Workspace builds have an owner, but template versions (for import jobs) do not.

Therefore the owner label is only applicable to some jobs and that confuses the interface.

I initially wanted to include the owner label but it was the clearer, simpler solution to go with initiator. Furthermore, the searchquery package shows that each searchable resource defines its own list of searchable attributes. Therefore I don't think using initiator is a problem.

We can add owner in a separate PR if you'd like. But it would come with the implicit filter that only workspace build jobs are returned. Unless we want to assume that created_by is the same thing as owner, but that makes me uncomfortable.

Ok, that is a good point about the import job. Let's keep it as initiator in that case. Maybe it would make sense to add this reasoning in the PR description?

ssncferreira · 2025-10-02T11:22:53Z

coderd/provisionerjobs.go

 	job := codersdk.ProvisionerJob{
 		ID:             provisionerJob.ID,
 		OrganizationID: provisionerJob.OrganizationID,
+		InitiatorID:    provisionerJob.InitiatorID,


It might be worth adding a test around claiming prebuilds to ensure that InitiatorID isn’t the prebuilds user. Otherwise, there’s a risk we could inadvertently cancel prebuild-claiming jobs.

We should just fix that bug (which I'm happy to do in a separate PR) and rather have claims be initiated by the user that claimed it.

I’m not 100% sure this is a bug, I think it’s more a matter of perspective. It’s true that the user action initiates the claim process, but internally it’s the prebuilds user who actually performs the claim.
I’m okay with changing the initiator to be the user who claims the prebuild, since I still think that makes the most sense, I’m just not 100% sure if there might be any problems that come with making that change.

In either case, I still think we should have a test for this scenario to cover that specific case.

SasSwart · 2025-10-02T13:29:53Z

@ssncferreira where did you see -s, --status [offline|idle|busy], $CODER_PROVISIONER_LIST_STATUS?

I just ran the command using --status="pending" and it works fine.

See attached:

ssncferreira · 2025-10-02T14:41:48Z

@ssncferreira where did you see -s, --status [offline|idle|busy], $CODER_PROVISIONER_LIST_STATUS?

I just ran the command using --status="pending" and it works fine.

See attached:

You’re totally right, I was looking at the coder provisioner list CLI command instead 🤦‍♀️ That’s what I get for multitasking 😅, sorry about the confusion!

github-actions bot assigned SasSwart Oct 2, 2025

SasSwart changed the title ~~Jjs/internal 934~~ feat: add filtering by initiator to provisioner job listing in the CLI Oct 2, 2025

SasSwart added 2 commits October 2, 2025 07:38

feat: allow the provisioner jobs list command to filter by initiator

c0d3650

add a shorthand flag for the initiator

89febea

SasSwart force-pushed the jjs/internal-934 branch from e254d6e to 89febea Compare October 2, 2025 07:38

SasSwart commented Oct 2, 2025

View reviewed changes

add API level tests for provisioner job listing with initiator filter

14d2906

SasSwart marked this pull request as ready for review October 2, 2025 09:30

SasSwart requested a review from mafredri October 2, 2025 09:30

SasSwart added 2 commits October 2, 2025 09:38

make -B gen

8cc77d0

add missing property in testHelpers

1a797ac

SasSwart requested a review from ssncferreira October 2, 2025 09:46

mafredri approved these changes Oct 2, 2025

View reviewed changes

ssncferreira reviewed Oct 2, 2025

View reviewed changes

SasSwart added 3 commits October 6, 2025 08:29

rename parameter to allow more flexible use in a follow-up

d5c16c4

make -B gen

39bcac2

Merge branch 'main' into jjs/internal-934

c4a89d0

SasSwart enabled auto-merge (squash) October 6, 2025 08:46

SasSwart merged commit d17dd5d into main Oct 6, 2025
28 of 30 checks passed

SasSwart deleted the jjs/internal-934 branch October 6, 2025 08:56

github-actions bot locked and limited conversation to collaborators Oct 6, 2025

feat: add filtering by initiator to provisioner job listing in the CLI #20137

feat: add filtering by initiator to provisioner job listing in the CLI #20137

Uh oh!

Conversation

SasSwart commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SasSwart Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

SasSwart Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

mafredri left a comment

Choose a reason for hiding this comment

Uh oh!

mafredri Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

mafredri Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

SasSwart commented Oct 2, 2025

Uh oh!

mafredri commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ssncferreira left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ssncferreira Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SasSwart Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ssncferreira Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

ssncferreira Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

SasSwart Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ssncferreira Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

SasSwart commented Oct 2, 2025

Uh oh!

ssncferreira commented Oct 2, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SasSwart commented Oct 2, 2025 •

edited

Loading

mafredri commented Oct 2, 2025 •

edited

Loading

ssncferreira left a comment •

edited

Loading

ssncferreira Oct 2, 2025 •

edited

Loading

SasSwart Oct 2, 2025 •

edited

Loading

SasSwart Oct 2, 2025 •

edited

Loading