Issue

• I want to create a node with the REST API

Environment

• CloudBees Jenkins Enterprise (CJE)
• CloudBees Jenkins Enterprise - Managed controller (CJE-MM)
• CloudBees Jenkins Team (CJT)
• CloudBees Jenkins Platform - Client controller (CJP-CM)
• cURL
• Remote access API

Resolution

The following is a generic solution using a JSON parameter:

curl -L -s -o /dev/null -w "%{http_code}" -u "${JENKINS_USER}:${JENKINS_PASSWORD_OR_API_TOKEN}" -H "Content-Type:application/x-www-form-urlencoded" -H "Jenkins-Crumb:${JENKINS_CRUMB}" -X POST -d 'json=${JSON_OBJECT}' "${JENKINS_URL}computer/doCreateItem?name=${NODE_NAME}&type=hudson.slaves.DumbSlave"

With the following variables:

Here is an example of a JSON object for an SSH node (produced with CJP-CM 2.107.3.4 and SSH Build Agents plugin 1.26):

{
    "Jenkins-Crumb": "${JENKINS_CRUMB}",
    "": [
        "hudson.plugins.sshslaves.SSHLauncher",
        "hudson.slaves.RetentionStrategy$Always"
    ],
    "launcher": {
        "": "2",
        "$class": "hudson.plugins.sshslaves.SSHLauncher",
        "credentialsId": "d436fff1-af1c-45df-8cb6-3907d119b8fa",
        "host": "host",
        "javaPath": "",
        "jvmOptions": "",
        "launchTimeoutSeconds": "",
        "maxNumRetries": "",
        "port": "22",
        "prefixStartSlaveCmd": "",
        "suffixStartSlaveCmd": "",
        "retryWaitTime": "",
        "sshHostKeyVerificationStrategy": {
            "$class": "hudson.plugins.sshslaves.verifiers.ManuallyTrustedKeyVerificationStrategy",
            "requireInitialManualTrust": true,
            "stapler-class": "hudson.plugins.sshslaves.verifiers.ManuallyTrustedKeyVerificationStrategy"
        },
        "stapler-class": "hudson.plugins.sshslaves.SSHLauncher"
    },
    "retentionStrategy": {
        "$class": "hudson.slaves.RetentionStrategy$Always",
        "stapler-class": "hudson.slaves.RetentionStrategy$Always"
    },
    "type": "hudson.slaves.DumbSlave",
    "mode": "NORMAL",
    "name": "${NODE_NAME}",
    "numExecutors": "1",
    "remoteFS": "/home/jenkins",
    "nodeDescription": "Agent node description",
    "labelString": "agent-node-label",
    "nodeProperties": {
        "stapler-class-bag": "true"
    }
}

Tips to get the JSON

The format of the JSON object depends on the configuration of the node you want to create but also the configuration of your master (i.e. version of core and plugins). There is a way to retrieve the JSON object corresponding to the desired configuration using the browser developer tool. For more information about the Browser developer tools can be found in the article Required Data: Rendering Problems or Loading Issues.

Different browser have different tools, most of them are similar and enable to capture the request body of HTTP requests which is what we want. Following is an example with Chrome:

• Go to the Manage Jenkins > Manage Nodes page

• Click on “New Node”, select “Permanent Agent”, give it a name and click on “OK”. You should now be on the node’s configuration page:

  

• Configure the node with the values you want but DON’T SAVE YET!

• Open the browser developer tools console with Right Click > Inspect

• You should see the [developer console] appear:

  

• Switch to the Network tab

• Click the Clean button (second button at the top left of the Network tab)

• Keep the console open and click on “Save” in Jenkins to save the form

You should see lots of requests appearing, one of them - the top one - is “doCreateItem”:

• Click on the doCreateItem record (a panel should appear on the right)
• In the right panel, ensure that you are on the “Headers” tab and scroll down to the bottom to access the Form Data section where you should see the field json.

This JSON is the format the the Jenkins instance is expecting. Attributes can be set accordingly.

Note: You can also use a XML file instead of a JSON.