How to programmatically connect a Client Master to CJOC?

Issue

  • I want to programmatically instantiate and connect a CloudBees Jenkins Enterprise Client Master to a CloudBees Jenkins Operations Center (CJOC) server. This is typically needed when creating Client Masters using Chef, Puppet, Ansible, AWS Cloud Formation or Azure ARM Templates.

WARNING: API subject to change or replacement in the future.

Environment

  • CloudBees Jenkins Operations Center
  • CloudBees Jenkins Enterprise

Resolution

You can programmatically connect a Client Master to CJOC. To do so, you have to do the following - preferably in that order:

  1. Execute a Groovy script on CJOC to declare the Client Master
  2. Start/Restart the Client Master with specific Java system properties in the startup parameters

On the sample below, we will use the following values:

  • CJOC Server
  • URL: https://operations-center.jenkins.example.com
  • Client Master to create
  • Name: my-client-master
    • This name is visible in the user interface of CloudBees Jenkins Platform
  • Id: 5
    • Arbitrary integer
    • This internal identifier is not visible
    • The identifier clientMaster.name + '-' + clientMaster.id - also known as idName - must be unique.
  • Grant Id: fjs2ktwfgd
    • Arbitrary secret shared between Operations Center and the Client Master to establish the connection. This secret is no longer used once the connection is established.
    • Using a random value is recommended

1. Declare the Client Master on CJOC

Run a Groovy script on CJOC to declare the Client Master.

You can also declare a Client Master by only providing its name and print the value you need:

import com.cloudbees.opscenter.server.model.ClientMaster
import com.cloudbees.opscenter.server.model.OperationsCenter

def clientMasterName = "my-client-master"

// Create Client Master Declaration
ClientMaster clientMaster = OperationsCenter.instance.createClientMaster(clientMasterName)

// Another way to create a ClientMaster is as follow
//ClientMaster cm = Jenkins.instance.createProject(ClientMaster.class, clientMasterName)

if (OperationsCenter.instance.getConnectedMasterByName(clientMaster.idName)!=null){
    println "Created ClientMaster '${clientMaster.name}' known as '${clientMaster.idName}'"
    println "-DMASTER_INDEX=${clientMaster.id}'"
    println "-DMASTER_NAME=${clientMaster.name}'"
    println "-DMASTER_GRANT_ID=${clientMaster.grantId}'"
} else {
    println "[ERROR:]" + clientMasterName + "has not been created in CJOC"
}

Or you can declare a Client Master and set properties:

// Imports
import com.cloudbees.opscenter.server.model.ClientMaster
import com.cloudbees.opscenter.server.model.ConnectedMaster
import com.cloudbees.opscenter.server.model.OperationsCenter
import com.cloudbees.opscenter.server.properties.ConnectedMasterLicenseServerProperty
import jenkins.model.Jenkins

// Input parameters
def clientMasterName = "my-client-master"
def clientMasterId = 5
def clientMasterGrantId = "fjs2ktwfgd"
def clientMasterLicenseStrategy = new ConnectedMasterLicenseServerProperty.FloatingExecutorsStrategy() // or  ConnectedMasterLicenseServerProperty.NoLicensingStrategy();

// Create Client Master Declaration
ClientMaster cm = OperationsCenter.instance.createClientMaster(clientMasterName)

// Another way to create a ClientMaster is as follow
//ClientMaster cm = Jenkins.instance.createProject(ClientMaster.class, clientMasterName)

//Set Client Master properties
cm.setId(clientMasterId)
cm.setIdName(ConnectedMaster.createIdName(clientMasterId, clientMasterName))
cm.setGrantId(clientMasterGrantId)
cm.getProperties().replace(new ConnectedMasterLicenseServerProperty(clientMasterLicenseStrategy))
cm.save()

if (OperationsCenter.instance.getConnectedMasterByName(cm.idName)!=null){
    println "Created ClientMaster '${cm.name}' known as '${cm.idName}'"
    println "-DMASTER_INDEX=${cm.id}'"
    println "-DMASTER_NAME=${cm.name}'"
    println "-DMASTER_GRANT_ID=${cm.grantId}'"
} else {
    println "[ERROR:]" + clientMasterName + "has not been created in CJOC"
}

2. Add CJOC connection details in the startup parameters of the Client Master

Add CJOC connection details in the JVM startup parameters of the Client Master:

-DMASTER_ENDPOINT="https://my-client-master.jenkins.example.com"
-DMASTER_OPERATIONSCENTER_ENDPOINT="https://operations-center.jenkins.example.com"
-DMASTER_INDEX="5"
-DMASTER_NAME="my-client-master"
-DMASTER_GRANT_ID="fjs2ktwfgd"

You can use the optional startup parameter -DMASTER_OPERATIONSCENTER_CERTS to define the SSL Certificate used by the HTTP endpoint of CJOC if the endpoint uses HTTPS and if the SSL certificate is not trusted by the JVM SSL trust store.

Troubleshooting

The following groovy provides information about the client masters ( id, idName, grantId) defined in the CJOC. It must therefore be run on the CJOC:

import com.cloudbees.opscenter.server.model.OperationsCenter

OperationsCenter.instance.getConnectedMasters().each {
    println "${it.name}"
    println " id: ${it.id}"
    println " idName: ${it.idName}"
    println " grantId: ${it.grantId}"
}
Have more questions? Submit a request

4 Comments

  • 0
    Avatar
    Yeun nah Tan

    Is there a place that I can get the documentation of CJOC APIs?

  • 0
    Avatar
    Denys Digtiar

    Hi Yeun,

    Correct me if I am wrong but based on the context it looks like you are looking for Java API documentation. I am afraid we do not publish it at the moment. 

    You can find REST APIs documented here in Knowledgebase and in the Documentation.

  • 0
    Avatar
    Neil Houston

    Hi Denys,

    I cannot find the rest api documentation specific to CJOC anywhere...

    Do you have a link?

    If it's not currently possible; can you backlog the ability to create clientmasters via the rest api?

  • 0
    Avatar
    Denys Digtiar

    No, the documentation is not extensive. A few examples are:

    REST API in RBAC

    Scripting Templates

    The Client Master is special type of project, therefore it should be possible to follow the below KB to create it:

    How to create a job using the REST API and cURL?

    However as this article highlights, create a project is not enough, you need to establish the connection between two. 

    What was the original reason you asked for the API documentation?

    It will probably be easier to move this discussion to the support ticket.

Please sign in to leave a comment.