Configuring the Jenkins plug-in

Obtain the Jenkins plug-in

You can find the Jenkins plug-in included with the Jenkins Observer image. For example:

JENKINS_OBSERVER_POD=(oc get po -l app.kubernetes.io/name=jenkins-observer -o jsonpath='{.items[0].metadata.name}')

echo {JENKINS_OBSERVER_POD}
evtmanager-topology-jenkins-observer-84c456f58c-jxlrj

To copy the plug-in from the image:

oc cp JENKINS_OBSERVER_POD:/opt/ibm/asm-observer-plugin-2.0.0-SNAPSHOT.hpi asm-observer-plugin-2.0.0-SNAPSHOT.hpi

ls asm-observer-plugin-2.0.0-SNAPSHOT.hpi
asm-observer-plugin-2.0.0-SNAPSHOT.hpi

Obtain credentials

The credentials for the API are dynamically created. If IBM Cloud Pak for Watson AIOps is installed with a release name of asm, then:

CREDS_USER=(oc get secret evtmanager-topology-asm-credentials -o jsonpath={.data.username} | base64 -d)
CREDS_PASS=(oc get secret evtmanager-topology-asm-credentials -o jsonpath={.data.password} | base64 -d)

Use the following command to print the UI API credentials:

echo CREDS_USER CREDS_PASS

Example user and password credentials returned:

aimanager-topology-aiops-user N8gJJGEfmmDnF6Q/1zg8NyAGKgQ9PmZQLhUSKd9/j54=

Obtain certificate

The following sample steps apply to the default router deployed on Red Hat OpenShift Container Platform. If more routers are used, adjust these steps. You perform these steps as cluster administrator.

Obtain the certificate:

oc get secret -n openshift-ingress router-certs-default -o jsonpath='{.data.tls\.crt}' | base64 -d > ocp-default-router.crt

Obtain the certificate key:

oc get secret -n openshift-ingress router-certs-default -o jsonpath='{.data.tls\.key}' | base64 -d > ocp-default-router.key

Convert to PKCS12:

openssl pkcs12 -export -out ocp-default-router.p12 -inkey ocp-default-router.key -in ocp-default-router.crt
Enter Export Password: enter-suitably-secure-password
Verifying - Enter Export Password: enter-suitably-secure-password

Ensure that the files you have extracted from Red Hat OpenShift Container Platform are securely deleted.

Obtain observer URL

Obtain the hostname as in the following example:

oc get routes -l app.kubernetes.io/name=jenkins-observer -o jsonpath='{.items[*].spec.host}'

The Jenkins plug-in defines Jenkins pipeline DSL steps that you use to instruct the Jenkins builds to generate and then send topology data to the Jenkins Observer. Use the DSL steps to send the notification to include Artifactory BuildInfo modules information, in order for the build products to be modeled. You create an observer instance, which then triggers the sending of the notification to the observer.

For information on configuring Jenkins Observer jobs, see the related tasks.

Important: You perform the following steps as Jenkins administrator.

Install the Jenkins plug-in

1. Log in to your Jenkins server with a user ID that has administration (management) permissions.

2. Navigate to Manage Jenkins > Manage Plugins and select the Advanced tab.

3. In the Upload Plugin section, upload and install the provided plug-in (asm-observer-plugin-2.0.0-SNAPSHOT.hpi)

Configure the Jenkins plug-in

1. Navigate to Manage Jenkins > Configure System and select the Agile Service Manager plugin.

2. Enter the Jenkins Observer URL obtained earlier in the Observer URL field.

3. Create credentials for IBM Cloud Pak for Watson AIOps using the Manage Jenkins > Credentials configuration page.

   Enter the credentials and the certificate details obtained earlier from the (or as the) cluster administrator.

   Auth Credentials Enter the username and password to authenticate with the Jenkins Observer at API level.

   Click ADD.

   Certificate Enter the PKCS12 format certificate to secure the communication between the Jenkins plug-in and the observer using SSL.

   Click ADD.

   For more detailed information on using the Jenkins Credentials feature, see the Jenkins site: https://jenkins.io/doc/book/using/using-credentials/

4. Enter a Default Tenant ID.

   The tenant to be used as default when sending information to IBM Cloud Pak for Watson AIOps (if it is not overridden in the build).

5. Enter a Default Job ID.

   The default job ID to be used when sending information to IBM Cloud Pak for Watson AIOps (if it is not overridden in the build). This represents the ID of the job the observer is running to process your information.

6. Click TEST CONNECTION to attempt to establish a connection with the observer using the configured credentials.

   If successful, a Connection successful! message is displayed. If unsuccessful, an error is returned.

   Note: The connection test does not verify the default job and tenant IDs.

Configuring your Jenkins build to notify IBM Cloud Pak for Watson AIOps

After configuring the installed plug-in in Jenkins, you integrate the provided functionality into your existing Jenkins build. The following two steps describe how to use scripted pipeline syntax to send your build information to the observer.

Remember: You perform the following two steps on your Jenkins build (and not the Jenkins Observer).

1. Create an instance of the IBM Cloud Pak for Watson AIOps observer communication object using the default credentials set during the configuration steps.

   def <my observer> = ASM.newObserver()
   

   Tip: Override credentials: to override any configured credentials (that is, the Jenkins credentials ID rather than the actual credentials themselves), you can use the following syntax:

   def <my observer> = ASM.newObserver
   authCredsId: 'auth-credentials-id', certCredsId: 'cert-credentials-id'
   

2. Send a build notification using the following syntax:

   ASM.notifyASM asmObserver: <my observer>
   

   Tip: You can override the default values for the tenant and job IDs:

   ASM.notifyASM tenantId: '<tenantId>', jobId: '<jobId>', asmObserver: <my observer>
   

   You can integrate the Jenkins plug-in with the Artifactory component using the modules information to model any artifacts the build has published to the repository:

   ASM.notifyASM asmObserver: <my observer>, artModules: <buildInfoObject>.getModules()
   

The following Jenkins file code sample shows the integration with IBM Cloud Pak for Watson AIOps. It starts with the declaration of the observer instance, and ends with the notification to IBM Cloud Pak for Watson AIOps. This notification should be added as a post / always block, so that the information is sent as the last operation of the build, and is sent regardless of the result of the build.

The optional try / catch around the notification to IBM Cloud Pak for Watson AIOps is included in this sample to avoid the build failing if the notification to IBM Cloud Pak for Watson AIOps fails.

The following sample also depicts the use of Artifactory to publish the build products, and how that information can be included in the notification to IBM Cloud Pak for Watson AIOps using the artModules parameter.

**def asm = ASM.newObserver()**
def buildInfo = Artifactory.newBuildInfo()
buildInfo.env.capture = true

… your build logic here …
**
post {
    always {
      script {
            try {
                 ASM.notifyASM asmObserver: asm, artModules: buildInfo.getModules()
            } catch (err) {
                echo An error ocurred sending a notification to ASM:  {err}"
            }
          }
      }
   }
}**

Tip: You can further refine your integration and visualization, as described here.

After you install and configure the Jenkins plug-in, configure the Jenkins Observer listen job.

You can further refine your IBM Cloud Pak for Watson AIOps system to take advantage of its topology and other customization functionality.

Refining Jenkins integration and visualization

You can extend your Jenkins integration with rules to merge data from different sources, custom topology display conventions, and the use of templates for the automated generation of topologies. For more information, see Additional Jenkins plug-in customization tasks.