Jenkins Execution Engine

The default execution engine in XPRESSO is Jenkins which serves as the workflow engine to manage/provide a CI/CD solution/process to execute Job Requests on a server using the provided Test Harness. Jenkins is highly extensible; functionality can be extended through the installation of plugins. There are three specific Jenkins plugins designed to work with XPRESSO (see below for details).

About the Jenkins Execution Engine

Jenkins is a self-contained, open source, orchestration and automation execution engine (server) used to automate the various tasks related to the building, testing, delivery, and deployment of software. Jenkins enables developers to automate this process as much as possible.

Jenkins has the following attributes that apply to XPRESSO:

• Deployment/Setup:

  • You can configure multiple/concurrent Jenkins Execution Engines for a Group.

  • The Jenkins Execution Engine operational state is set automatically in XPRESSO based on the reachability between XPRESSO and Jenkins. Jenkins Operational states are not configurable.

  • You can use a Jenkins slave (agent) node as part of your deployment with XPRESSO. Builds will automatically be distributed to the slave.

  • XPRESSO Jobs are executed on the master Jenkins execution engine and any connected slave nodes by default.

  • You can use the Restrict the execution on Jenkins Node parameter on the New Job configuration form to allows you to designate which Slave Jenkins execution node(s) should be used for offloading instead of the default mode of executing to any slave nodes that have less resources or test cases waiting to execute.

  • Once you register your Jenkins Engine Instance in XPRESSO, you can specify which engine to use in the Job Profile associated with each Job Run.

  • Group Administrators can set the default preference for the preferred Jenkins Engine Instance for a Group in the Environment Preference. Users always have the option to override the default setting.

• Execution:

  • Jenkins launches each Job run as a new "build".

  • Creates and maintains Jenkins projects based on job/profile parameters.

  • When a Job Run completes, Jenkins uploads the test results back into XPRESSO automatically.

• Loss of Jenkins Connectivity: In the event your Jenkins Engine goes offline during a Job Run (for example, a power outage), XPRESSO is designed to:

  • Wait for the Jenkins Engine to come back online within a configured (internal) time frame (approximately 20 minutes).

  • If connectivity is re-established within the specified time frame, the Job Run will continue to execute.

  • If connectivity is lost beyond the specified time frame, XPRESSO places the Jenkins Engine into a disable state and no longer reports on the status of the Jenkins Engine; this reduces the traffic and resource pinging (potentially endless) between Jenkins and XPRESSO. Log and history files are left intact.

  • When the Jenkins Engines comes back online, the Group Admin must change the Jenkins Engine configuration state back to Enabled to re-establish communications. See Performing Operations on Jenkins Engine Instances below for details.

Execution Behavior

During execution, XPRESSO automatically creates one project per Job/Profile in this format: $INSTANCEID-$JOB-$UUID. Each Job Run (build) performs using the standard Jenkins user (typically, jenkins). This is a Jenkins default behavior. These project files are synced and automatically maintained by XPRESSO.

CAUTION!
Do not attempt to modify the associate Jenkins project file as this may cause all subsequent Job Runs with the associate Job/Profile to terminate.

Jenkins Operational/Deployment Requirements

You need the following prerequisites to register a Jenkins Engine Instance in XPRESSO:

1. Jenkins v2.80+ with Java v1.8 (Java SE 8).

2. If your testbed is in a DMZ'ed lab, the Jenkins Engine Instance requires a network interface connecting to your lab LAN.

3. Ensure your Jenkins deployment has the appropriate resources for the amount of Job Runs you plan to execute on it.

4. Ensure your Jenkins Engine Instance can access your test harness. This also applies if you are using a slave Jenkins deployment.

5. Ensure the Jenkins user has the correct permissions to the files and directories associated with the Jenkins Engine Instance. This also applies if you are using a slave Jenkins deployment.

Jenkins Plugin Requirements

Jenkins plugins are the primary means of enhancing the functionality of Jenkins to suit an organization or user-specific automation needs. There are many plugins available for Jenkins; the following specific Jenkins plugins are used with XPRESSO and pyATS:

• Pipeline Plugin: Used to execute XPRESSO Jobs or Profiles as a Jenkins Pipeline job. This plugin is may already be installed by default.

NOTE:
Refer to the Jenkins user documentation for information about how to install these plugins with Jenkins.

Initial Jenkins Setup Requirements

Prior to registering a Jenkins execution engine in XPRESSO, you need to make sure the related-backend equipment is deployed and reachable:

• For External Users: Refer to this [website] (https://www.jenkins.io/doc/book/installing/) for information about installing Jenkins in your organization.

• For Cisco Users:

  • Refer to the Cisco Engineering IT (ENGIT) website to open a ticket to start the onboarding process to setup a Jenkins Instance.

  • Refer to this website for information about how to copy Jenkins Build images for use with XPRESSO.

Making a Request to Register a New Jenkins Engine Instance

This sub-topic only applies to Member and Privilege Member Roles. See the above plugin and setup requirement sub-topics for the prerequisites tasks that must be in place before a Jenkins Engine can be registered in XPRESSO.

You can view all current registered Jenkins Engine Instances on the Registered Engine Instances page.

In the event your Jenkins Engine is not registered in XPRESSO, you can make a request to the Group Administrator to add (register) it.

To Make a Request to Register a New Jenkins Engine Instance:

1. From the Main Navigation Bar, choose ENVIRONMENT→Execution Engines to open the Registered Engine Instances page.

2. Click the Request New Engine button located on the top-right side of the page. The Request New Engine Instance form appears.

3. Configure the Name parameter and click the Send Request button. The request is forwarded to the Group Admin for processing.

Registering a New Jenkins Engine Instance

You need to register your Jenkins Engine Instance in XPRESSO so you can execute your Job Runs on them. Only a Group Admin or System Admin can register a new Jenkins Engine Instance:

To Register a New Jenkins Engine Instance:

1. From the Main Navigation Bar, choose ENVIRONMENT→Execution Engines to open the Registered Engine Instances page.

2. Click the Add Engine Instance button located on the top-right side of the page. The Add a New Execution Engine Instance page appears.

3. Configure the following required parameters:

• Name: Provide a unique identifier for the Jenkins Engine Instance.

• URL: A fully qualified URL needs to be indicated including domain name and port. For example: http://xpresso.cisco.com:8080.

NOTE:
You must ensure the same fully qualified URL is set properly in your Jenkins instance. To validate the URL is configured correctly: login to your Jenkins instance using an account with administrative access, click Manage Jenkins→Configure System and ensure a fully qualified URL is used under the Jenkins Location→Jenkins URL options.

• Site: Select the geo-location of the Jenkins Engine Instance from the pull-down window.

• Building: Enter the specific building(s) in the selected geo-location of the Jenkins Engine Instance.

• User ID: Enter a User ID used to authenticate the new Jenkins Engine Instance for example: admin.

• Jenkins API token: Enter the API token used to authenticate with Jenkins. Follow this guide for information about how to obtain a Jenkins API token.

NOTE:
The XPRESSO API automation token can only be used to interact with XPRESSO REST APIs and cannot be used for any API token fields within the XPRESSO application itself. For example, when creating a new Jenkins Engine Instance, you are required to enter the API automation token obtained from Jenkins itself, not the XPRESSO-generated API automation token.

4. Click Save. The new Jenkins Engine instance appears in the list of Registered Engine Instances.

Performing Operations on Jenkins Engine Instances

Only the Group Admin and System Admin can perform operations on a registered Jenkins Engine Instance.

To Perform Operations on a Jenkins Engine Instance:

1. From the Main Navigation Bar, choose ENVIRONMENT→Execution Engines to open the Registered Engine Instances page. All Engine Instances registered to your Group display.

2. Locate and highlight the Jenkins Engine Instance that you want to perform the operation on and click the appropriate floating action button (Edit | Delete | Enable | Disable | Maintenance) located to the right of the selected Instance.

If you click the Edit button, you can only edit the following Jenkins Engine Instance details: URL | Configuration State | Building | Site of the Instance. For any other changes you want to make, you must delete the Instance and recreate it.

3. Click the Save button.

Integrating DevAT Jobs

Refers to Integrating DevAT Jobs

Other Related Jenkins Information

Refer to the following topics for other related Jenkins information:

• See "Configuring Job Request Attributes" for information about how to configure a Job Request to specify which Jenkins Execution Instance to use for a Job Run.

• See "Environment Preference" for information about how to set the default preference as to which is the preferred Jenkins Execution Instance to use for a Group.

• See "Operational and Configuration States" for information about the configuration states that apply to Jenkins Engine Instances.

• See "Environment REST APIs" for information about Execution Engine APIs.