[JENKINS-30376] More equals methods on Jenkins runtime objects

[timja]

It would be great if there were more equals() methods on Jenkins runtime objects. For example, I've implemented equals() methods via GitHub OAuth plugin pull request #43.

More objects need this kind of method available in order to ease managing Jenkins masters with configuration management.

---

Originally reported by sag47, imported from: More equals methods on Jenkins runtime objects

• status: Open
• priority: Minor
• resolution: Unresolved
• imported: 2022/01/10

[timja]

markewaite:

Can you explain further how a configuration management system might use the equals methods to ease managing Jenkins masters? I don't understand the use case you're trying to achieve.

Once the use case is understood, there may be simpler ways to obtain the same result, without requiring that we add equals methods solely for the benefit of this request.

As an example, I version control my job definitions by extracting them from Jenkins using the REST API and then I commit then in a git repository. That uses an existing API, requires no changes to plugins, and works quite well for my needs.

[timja]

sag47:

Version controlling the job configs means that you must modify the XML (not recommended) and reload the Jenkins master configuration.

In the pull request I linked, I've given an example where it is a use case (currently being used in production). Here's the example, with more explanation.

import hudson.security.SecurityRealm
import org.jenkinsci.plugins.GithubSecurityRealm
String githubWebUri = 'https://github.com'
String githubApiUri = 'https://api.github.com'
String clientID = 'someid'
String clientSecret = 'somesecret'
String oauthScopes = 'read:org'
SecurityRealm github_realm = new GithubSecurityRealm(githubWebUri, githubApiUri, clientID, clientSecret, oauthScopes)
//check for equality, no need to modify the runtime if no settings changed
if(!github_realm.equals(Jenkins.instance.getSecurityRealm())) {
    Jenkins.instance.setSecurityRealm(github_realm)
    Jenkins.instance.save()
}

That would be executed on the script console. Notice that the GithubSecurityRealm class has an equals method implemented. It is being used by github_realm.equals(Jenkins.instance.getSecurityRealm())

Or you could save it as a groovy script (e.g. security-realm.groovy). Once you have the script, config management would essentially execute the following command.

curl --user "userName:apiToken" --data-urlencode "script=$(<./security-realm.groovy)" http://localhost:8080/scriptText

Basically, I've decided if I need to log into the web UI and click a check box to configure in production then I've failed. Configuration management needs to maintain the entire state of the system. By having configuration management manipulate the Jenkins runtime via the Script Console this is easily accomplished (with a token that has administer permissions).

This is the better way to do it rather than maintain the XML on the filesystem. By modifying the runtime via the script console you're modifying the configuration itself. By executing Jenkins.instance.save() you're serializing the runtime to XML and saving the configuration to disk.

I believe this is the simpler method rather than checking XML into source control. It is more reliable and idempotent because the configuration can be checked for its current state before being changed.

[timja]

sag47:

Hi markewaite, was my explanation sufficient? Would you like me to elaborate on any points I made?