How to create a Kubernetes Managed controller programmatically

Issue

How to create a Kubernetes Managed controller programmatically.

Environment

Resolution

The recommended solution is to follow Creating items with CasC for the operations center.

Workarounds

For the following workarounds, the /casc-items/create-items is still a valid solution when the Resolution does not fit with your use case (imperative controller creation instead of declarative). The groovy script createManagedcontrollerK8s.groovy approach is not supported, but is kept here for historical purposes for clients running out of support product versions:

Create Using Configuration as Code (CasC) HTTP API

The CasC HTTP API includes the /casc-items/create-items endpoint for creating new items on Operations Center to include Managed controllers.

See Managed controller CasC example. The controller.yaml example should be modified as needed.

You need to post the modified version of the controller.yaml file to the /casc-items/create-items CasC HTTP API endpoint on CJOC. The following is an example:

curl -XPOST \
    --user $USER:$TOKEN \
    "https://my-operation-center.com/casc-items/create-items" \
     -H "Content-Type:text/yaml" \
    --data-binary @/cloudbees-managed-controller/controller.yaml

The path query string parameter may be used to create the Managed controller in a specific folder on operations center. However, that folder must already exist. To create the item at the root of the operations center, you can omit this parameter.

See the Configuration as Code (CasC) HTTP API reference documentation for more details on the /casc-items/create-items endpoint.

Create Using Groovy

The easiest approach would be by using a Groovy script.

See createManagedcontrollerK8s.groovy. This script can be modified as needed.

If you need access to the source code then please see Custom Plugins: APIs and Javadocs of CloudBees Jenkins Enterprise plugins

The classes used in the provided script are coming from the operations-center-server plugin.

You can find your version of the plugin by looking at the Plugin Manager on the CJOC instance and searching for operations-center-server under the Installed tab.

Create via the Script Console

You can execute the groovy script using the Script Console under Managed Jenkins Script Console.

Create via the Jenkins CLI

You can execute a groovy script via the groovy command and passing the script to the standard input:

java -jar jenkins-cli.jar \
    -auth $USER:$TOKEN \
    -s $CJOC_URL/ \
    groovy = < createManagedcontrollerK8s.groovy

Create via the REST API

You can execute a groovy script via the /scriptText endpoint and pass the script via a bash command:

curl -v -XPOST \
    -u $USER:$TOKEN \
    --data-urlencode "script=$(<./createManagedcontrollerK8s.groovy)" \
    "$CJOC_URL/scriptText"

See Script Console - Remote Access for more details.

Create remotely using config files

You can also create a Managed controller remotely, by either using the REST API, or by using the Jenkins CLI to create the job.

This approach is a bit cumbersome, as some fields are auto-generated (id, idName, grantId, identity, encodedName) and must be unique. This means that several calls must be made to adjust a controller configuration.

You would need to do the following:

Create a job
Get the job config file
Update the config file (preserve auto-generated fields)
Post the updated config file

Create via the Jenkins CLI

You need to create a config.xml to pass to the create-job command. The following is an example:

java -jar jenkins-cli.jar \
    -auth $USER:$TOKEN \
    -s $CJOC_URL/ \
    create-job $CONTROLLER_NAME < my-k8s-managed-controller.xml

java -jar jenkins-cli.jar \
    -auth $USER:$TOKEN \
    -s $CJOC_URL/ \
    k8s-managed-controller-provision-and-start $CONTROLLER_NAME

Create via the REST API

You need to pass a config.xml to the /createItem endpoint. The following is an example:

curl -v -XPOST \
    -u $USER:$TOKEN \
    -H "Content-Type:text/xml" \
    --data-binary @my-k8s-managed-controller.xml \
    "$CJOC_URL/createItem?name=$CONTROLLER_NAME"

curl -v -XPOST \
    -u $USER:$TOKEN \
    "$CJOC_URL/job/$CONTROLLER_NAME/provisionAndStartAction"