[JENKINS-75954] OnceRetentionStrategy - Enable for General Use via API

[jenkins-infra-bot]

It's possible for external automation systems to use the REST API to create new agent configurations.  Unfortunately, they cannot choose the OnceRetentionStrategy because it has no DataBoundConstructor:

org.kohsuke.stapler.NoStaplerConstructorException: There's no @​DataBoundConstructor on any constructor of class org.jenkinsci.plugins.durabletask.executors.OnceRetentionStrategy 	at org.kohsuke.stapler.ClassDescriptor.loadConstructorParamNames(ClassDescriptor.java:291) 	at org.kohsuke.stapler.RequestImpl.instantiate(RequestImpl.java:983) 	at org.kohsuke.stapler.RequestImpl$TypePair.convertJSON(RequestImpl.java:874) Caused: java.lang.IllegalArgumentException: Failed to instantiate class hudson.slaves.RetentionStrategy from {"stapler-class":"org.jenkinsci.plugins.durabletask.executors.OnceRetentionStrategy"} 

Here's the code:

https://github.com/jenkinsci/durable-task-plugin/blob/master/src/main/java/org/jenkinsci/plugins/durabletask/executors/OnceRetentionStrategy.java

Can anyone familiar with this code indicate if there are any barriers or complications to adding a DataBoundConstructor to it? It seems likely there's a reason it wasn't included by default.

Assuming adding it is not an option, would it be reasonable within DurableTask to expose a new OnceRetentionStrategy class which is bindable for such use cases?

---

Originally reported by solvingj, imported from: OnceRetentionStrategy - Enable for General Use via API

• status: Open
• priority: Minor
• component(s): durable-task-plugin
• resolution: Unresolved
• votes: 0
• watchers: 2
• imported: 2025-12-09

Raw content of original issue

It's possible for external automation systems to use the REST API to create new agent configurations.  Unfortunately, they cannot choose the OnceRetentionStrategy because it has no DataBoundConstructor:

org.kohsuke.stapler.NoStaplerConstructorException: There's no @DataBoundConstructor on any constructor of class org.jenkinsci.plugins.durabletask.executors.OnceRetentionStrategy 	at org.kohsuke.stapler.ClassDescriptor.loadConstructorParamNames(ClassDescriptor.java:291) 	at org.kohsuke.stapler.RequestImpl.instantiate(RequestImpl.java:983) 	at org.kohsuke.stapler.RequestImpl$TypePair.convertJSON(RequestImpl.java:874) Caused: java.lang.IllegalArgumentException: Failed to instantiate class hudson.slaves.RetentionStrategy from {"stapler-class":"org.jenkinsci.plugins.durabletask.executors.OnceRetentionStrategy"} 

Here's the code:
https://github.com/jenkinsci/durable-task-plugin/blob/master/src/main/java/org/jenkinsci/plugins/durabletask/executors/OnceRetentionStrategy.java
Can anyone familiar with this code indicate if there are any barriers or complications to adding a DataBoundConstructor to it? It seems likely there's a reason it wasn't included by default.
Assuming adding it is not an option, would it be reasonable within DurableTask to expose a new OnceRetentionStrategy class which is bindable for such use cases?

[jenkins-infra-bot]

mawinter69:

• Original comment link
• Raw content of original comment:

  "OnceRetentionStrategy" extends "CloudRetentionStrategy". This means it is specifically for agents that are created by plugins implementing clouds. There it is the cloud plugin that creates the agent programmatically and the OnceRetentionStrategy calls the method "terminate" on the agent implemented by the cloud plugin that knows what to do to terminate the agent properly and free any kind of resources (e.g. terminate pods, vms, ...). As you can't create cloud agents via the UI it also doesn't make sense to be able to create "OnceRetentionStrategy" via the UI
  

"OnceRetentionStrategy" extends "CloudRetentionStrategy". This means it is specifically for agents that are created by plugins implementing clouds. There it is the cloud plugin that creates the agent programmatically and the OnceRetentionStrategy calls the method "terminate" on the agent implemented by the cloud plugin that knows what to do to terminate the agent properly and free any kind of resources (e.g. terminate pods, vms, ...). As you can't create cloud agents via the UI it also doesn't make sense to be able to create "OnceRetentionStrategy" via the UI

[jenkins-infra-bot]

solvingj:

• Original comment link
• Raw content of original comment:

  I see. From that perspective, I can see why it was omitted. 
  
  I’ll share my complete use-case for posterity. 
  
  We have a in-house generic node management service. It provides a unified API for allocating and de-allocating workers for CI/CD,  with a drivers interface which enables it to support clouds like AWS/EC2, Vsphere, k8, and bare-metal workers via an agent, etc. Our company supports many CI/CD platforms including Jenkins, TeamCity, CircleCI, GithubActions, and more.  We’re building out support for each of those platforms via custom plugins. 
  
  With this Any-to-Any requirement/design, the easiest CI/CD platform for us to support is GitHub Actions.  Its solution for auto-scaling self-hosted runners is just to send webhooks, and assume all the lifecycle management intelligence exists in an external service. it’s basically designed exactly for a system like ours. 
  
  So we’ve created a custom Jenkins cloud plugin which essentially works in a very similar way.  It sends out webhooks for the queue events, and our service makes rest API calls to create agent configurations, and then start ephemeral agents which connect to those configurations, and de-allocate/delete as needed. The only tricky part about this model, is ensuring that Jenkins only uses a note once.. With this in mind, you can see why it would be beneficial for us to be able to create a node with the OnceRetentionStrategy outside the context/code of a cloud Plugin. Indeed it’s not really a use case about the gooey, or the forms involved with using the gooey.. Our use case is really REST API, but the conversation and question is awkward because many tasks like this in Jenkins  don’t have a separate and proper REST API, the status quo is to basically automate these web forms which is a bit ugly, but gets the job done. 
  
  In closing, I can understand if the decision here is that such use cases are outside the scope of the intended use of this part of the model. The unfortunate part on my side will just be that I have to implement my own OnceRetentionStrategy which I can reference when I call the API. Not the worst, but the existing class seemed extremely close to what I needed, just based on the name, and not knowing the history, so it was worth asking.
  
  Thanks again for the response, and all your contributions.
  

I see. From that perspective, I can see why it was omitted.

I’ll share my complete use-case for posterity.

We have a in-house generic node management service. It provides a unified API for allocating and de-allocating workers for CI/CD, with a drivers interface which enables it to support clouds like AWS/EC2, Vsphere, k8, and bare-metal workers via an agent, etc. Our company supports many CI/CD platforms including Jenkins, TeamCity, CircleCI, GithubActions, and more. We’re building out support for each of those platforms via custom plugins.

With this Any-to-Any requirement/design, the easiest CI/CD platform for us to support is GitHub Actions. Its solution for auto-scaling self-hosted runners is just to send webhooks, and assume all the lifecycle management intelligence exists in an external service. it’s basically designed exactly for a system like ours.

So we’ve created a custom Jenkins cloud plugin which essentially works in a very similar way. It sends out webhooks for the queue events, and our service makes rest API calls to create agent configurations, and then start ephemeral agents which connect to those configurations, and de-allocate/delete as needed. The only tricky part about this model, is ensuring that Jenkins only uses a note once.. With this in mind, you can see why it would be beneficial for us to be able to create a node with the OnceRetentionStrategy outside the context/code of a cloud Plugin. Indeed it’s not really a use case about the gooey, or the forms involved with using the gooey.. Our use case is really REST API, but the conversation and question is awkward because many tasks like this in Jenkins don’t have a separate and proper REST API, the status quo is to basically automate these web forms which is a bit ugly, but gets the job done.

In closing, I can understand if the decision here is that such use cases are outside the scope of the intended use of this part of the model. The unfortunate part on my side will just be that I have to implement my own OnceRetentionStrategy which I can reference when I call the API. Not the worst, but the existing class seemed extremely close to what I needed, just based on the name, and not knowing the history, so it was worth asking.

Thanks again for the response, and all your contributions.

[jenkins-infra-bot]

solvingj:

• Original comment link
• Raw content of original comment:

  mawinter69 , I can understand that due to existing implementation details of "OnceRetentionStrategy", it's not suitable for this use case.  No problem. 
  
  In principle, can we then shift focus back to the spirit of the request and use case. 
  
  	
  Creating agents via API is common use case
  	
  The "new request" is ability to ensure such agents are used only once.
  
  
  
  Would there be any objection to us submitting a new and simple retention strategy class which makes this possible, fully independent from the CloudPlugin lineage?
  

mawinter69 , I can understand that due to existing implementation details of "OnceRetentionStrategy", it's not suitable for this use case.  No problem. 

In principle, can we then shift focus back to the spirit of the request and use case. 

• Creating agents via API is common use case
• The "new request" is ability to ensure such agents are used only once.

Would there be any objection to us submitting a new and simple retention strategy class which makes this possible, fully independent from the CloudPlugin lineage?

[jenkins-infra-bot]

mawinter69:

• Original comment link
• Raw content of original comment:

  I see several possible ways to solve your problem.
  
  	
  You implement your own OnceRetentionStrategy in your plugin (though that means duplicating code)
  	
  Implement a new OnceRetentionStrategy somewhere (not sure if core is the right place or that should go in a separate plugin but there are probably no other plugins that need this), 
  	
  Add the DataBoundConstructor to the OnceRetentionStrategy in durable-task plugin (don't know if that would be accepted by the plugin)
  	
  Instead of your service creating the agent via rest api (I assume you make a POST call to /computer/doCreateItem with the json, that is basically what the UI is doing), you could implement yourself a rest api in your custom Jenkins plugin that you call from your service and that takes care to create the agent programmatically. You would then be able to use the OnceRetentionStrategy from durable task plugin. 
  	
  Adapt the rest api in Jenkins core so that you can create an agent by posting the config xml to /computer/createItem, your service would need to create that xml (it is already possible to create agents from xml via the cli) and do the post request. I've opened Add rest api to create agent from xml jenkins#11229 for that
  
  
  

I see several possible ways to solve your problem.

1. You implement your own OnceRetentionStrategy in your plugin (though that means duplicating code)
2. Implement a new OnceRetentionStrategy somewhere (not sure if core is the right place or that should go in a separate plugin but there are probably no other plugins that need this), 
3. Add the DataBoundConstructor to the OnceRetentionStrategy in durable-task plugin (don't know if that would be accepted by the plugin)
4. Instead of your service creating the agent via rest api (I assume you make a POST call to /computer/doCreateItem with the json, that is basically what the UI is doing), you could implement yourself a rest api in your custom Jenkins plugin that you call from your service and that takes care to create the agent programmatically. You would then be able to use the OnceRetentionStrategy from durable task plugin. 
5. Adapt the rest api in Jenkins core so that you can create an agent by posting the config xml to /computer/createItem, your service would need to create that xml (it is already possible to create agents from xml via the cli) and do the post request. I've opened Add rest api to create agent from xml jenkins#11229 for that

[jenkins-infra-bot]

solvingj:

• Original comment link
• Raw content of original comment:

  mawinter69 
  
  RE: #5, I REALLY appreciate your work on the PR.  This seems like a big win generally speaking, as I remember awkwardness in the past to toggle between json/xml for agent configs and posting to the json API.  Would the XML post allow us to post the parameter needed to satisfy and use the existing OnceRetentionStrategy? 
  
  RE: #1, #2, #4,  We did copy/paste/modify OnceRetentionStrategy to "CustomOnceRetentionStrategy" in our existing plugin. However, we're now at a point where this is the only reason we need to have a custom plugin at all.  Being able to operate on Jenkins servers without need for any new plugin is a game changer for us and for consumers. So, we'll keep pursuing the other options.
  
  RE: #3, I guess one hope in opening this ticket was that someone from DurableTask plugin would say "we can just add the databoundconstructor" or a new class that has it.  Of course, by "all good" i mean that in 3-5 years, when all the jenkins servers in our company catch up to the latest durable task plugin version...
  

mawinter69

RE: #5, I REALLY appreciate your work on the PR.  This seems like a big win generally speaking, as I remember awkwardness in the past to toggle between json/xml for agent configs and posting to the json API.  Would the XML post allow us to post the parameter needed to satisfy and use the existing OnceRetentionStrategy? 

RE: #1, #2, #4,  We did copy/paste/modify OnceRetentionStrategy to "CustomOnceRetentionStrategy" in our existing plugin. However, we're now at a point where this is the only reason we need to have a custom plugin at all.  Being able to operate on Jenkins servers without need for any new plugin is a game changer for us and for consumers. So, we'll keep pursuing the other options.

RE: #3, I guess one hope in opening this ticket was that someone from DurableTask plugin would say "we can just add the databoundconstructor" or a new class that has it.  Of course, by "all good" i mean that in 3-5 years, when all the jenkins servers in our company catch up to the latest durable task plugin version...

[jenkins-infra-bot]

mawinter69:

• Original comment link
• Raw content of original comment:

  yes when you post the xml, all that is required is that the class exists basically. I tested that with the mock-agent plugin that also has a mock cloud. It uses the OnceRetentionStrategy from durable task. So taking the xml of such an agent and posting it to the new api the agent is properly created.
  

yes when you post the xml, all that is required is that the class exists basically. I tested that with the mock-agent plugin that also has a mock cloud. It uses the OnceRetentionStrategy from durable task. So taking the xml of such an agent and posting it to the new api the agent is properly created.