Commander Jenkins Plugin

Jenkins plugins allow you to integrate additional applications and tools with your Jenkins automation server and add functionality to the Jenkins build process.

Embotics provides a plugin for Jenkins automation servers (Jenkins version 1.651.3 or greater). The Commander Jenkins plugin allows you to configure a Jenkins build job to request virtual services and run command workflows in a Commander instance (version 7.0.0 or greater) as part of building, deploying and installing a project.

Using the Commander Jenkins plugin, you can add any of the following build steps to freestyle projects:

• request virtual services
• run command workflows
• wait steps to ensure that requests or workflows have sufficient time to complete

The Commander plugin enables more effective continuous integration and delivery for improved DevOps capabilities. Using the Commander plugin allows you to quickly add Commander build steps — you don't need to create lengthy and complex scripts to include in your Jenkins job.

For example, with the help of the Commander plugin you can create a Jenkins job with Commander build steps that each day would delete the test virtual machine from the previous day, submit a service request to deploy a new VM, and install the most recent build of your software on the new VM.

Using the Commander plugin, involves the following tasks:

• Installing the Commander plugin from the HPI file
• Configuring the plugin's connection to Commander
• Adding Commander Steps to Jenkins Jobs

Configuring the Commander Jenkins Plugin

Pre-requisites:

Download Jenkins Plugin

To use the Commander Jenkins plugin, you must install the plugin and configure its connection to a Commander instance.

Installing the Commander plugin from the HPI file

Embotics provides the Commander plugin as a self-contained .hpi file. You can install the plugin through the Jenkins plugin manager.

1. From the left side panel on your Jenkins dashboard, click Manage Jenkins, then click Manage Plugins.
2. In the Jenkins Plugin Manager, click the Advanced tab.
3. In the Upload Plugin section, navigate to the commander-jenkinsplugin.hpi file, and then click Open.
4. Click Upload.

   The Installing Plugins/Upgrades page displays the progress of the plugin installation.

Configuring the plugin's connection to Commander

After the Commander plugin is installed in Jenkins, you must configure it to communicate with your Commander installation. Only one vCommander installation can be added to a Jenkins automation server.

1. From the left side-panel on your Jenkins dashboard, click Manage Jenkins, then click Configure System.
2. Scroll down to the Commander section.
3. In the Commander URLfield, enter the URL where Commander is installed.

   The URL pattern is https://<host_or_ip_address> (for example, https://automationvc3.qa.yourcompany.com:443).

4. Add new credentials or use any existing Commander or Service Portal user credentials that the plugin will use to access Commander. These credentials are maintained in the Jenkins Credential plugin and are available system-wide in Jenkins.

   You can only select one set of user credentials for the connection to Commander.

   • To add new credentials, click Add > Jenkins. In the Jenkins Credentials Providerdialog, specify a valid username and password for accessing the Commander instance. The username and password may be global (the default) or exist within a domain that is defined in Jenkins. Then click Add.
   • To use username/password credentials that have already been added to Jenkins Credentials Provider, from the Credentialslist, select a username/password credential.

     The credentials that are displayed are filtered based on domain. This means that only credentials that are relevant for the Commander URL will be displayed.

5. If you're using credentials for a Commander user account, leave the Organization Name field blank. However, if you're using credentials for a Service Portal user account, you must enter the name of the organization the user account belongs to.
6. Click the Test Connection button.
7. If the configured connection passes, save the configuration.

Adding Commander Steps to Jenkins Jobs

After you have installed the Commander Jenkins plugin and configured its connection to your Commander installation, you can add Commander build steps in freestyle and multi-configuration Jenkins projects.

You can add multiple Commander build steps to a project, and they can be added before and after other common build steps. Standard Jenkins environment variables may be used to pass data/parameters between Commander build steps to non-commander build steps.

The following procedure only provides information on the Commander build steps that you can add to a Jenkins project. It does not provide guidance on basic Jenkins project configuration or scripting.

To add Commander build steps to a Jenkins project, do the following:

1. From the Jenkins dashboard, select your project.
2. Click Configure.
3. After you project loads, on the General tab, scroll down to the Build section, choose Add build step > Commander Services.

   

4. In the Commander Services section that is added, select the build step that you want to use from the Actiondrop-down and configure it as appropriate. You can choose any of the following actions:
   • Request New Service
   • Wait For Service Request Completion. This step can be used when a Request New Service step has already been added to the job.
   • Run Command Workflow
   • Wait for Command Workflow Completion. This step can be used when a Run Command Workflow has already been added to the job.

5. Click the links above for detailed information for each build step.

   You can add multiple Commander build steps. You can also add them before or after other Jenkins build steps. However, their order is significant, especially for the Wait for Completion build steps, as explained below.

   For each Commander build step, you can adjust the default Timeout and Polling Interval values to best suit your Jenkins job and your network requirements.

6. After you have configured a Commander build step, drag it to the appropriate spot in your build job.
7. When you have finished adding the required build steps, click Save or Apply to save your changes.

Request New Service

This build step allows the Jenkins job to request an existing service (for example, a Windows VM or CentOS VM) from the Commander instance's Service Catalog.

For the build step to request the service, you must configure the following:

• Service Name: In this field enter the name of the service exactly as it's listed in the Commander Service Catalog, then click Lookup.

  An existing service is returned as a JSON payload in the JSON Service Request field, as shown in the example above. If there is no matching service, an error is returned.

• JSON Service Request: This field displays a service request that is successfully looked-up as a JSON payload. You can adjust some configuration parameters of the payload as appropriate for the service request. For example, you might adjust the requested number of CPUs or physical memory if the service request permits these values to be configured by users requesting the service.

  You may also use environment variables in the text. Regular Jenkins syntax will be used to resolve the variables — either "$xyz", "${xyz}" or "${a.b}" but not "$a.b", while ignoring "$". Note that the plugin performs no verification of the input.

• Wait For Completion: Enable or clear this option to set whether you want the build job to wait for the request's completion before executing the next build step.
  • If enabled: Jenkins will wait for the request's completion before executing the next build step. That is, execute the service request synchronously.

    For synchronous requests, the build console log will provide details about the request. If it's successful, COMMANDER_REQUESTED_SERVICEx_COMPONENTy_NAME and COMMANDER_REQUESTED_SERVICEx_COMPONENTy_TYPE environment variables are created, which indicate the deployed component name and type. x is the service index and y is the component index. Indexes start from 1.

  • If cleared: Jenkins will not wait for the request's completion before executing the next build step. That is, execute the service request asynchronously.

    For an asynchronous execution, you may add a separate Wait For Service Request Completion build step at some point in the job after a Request New Service step to check the service request's results. For more information see Wait For Service Request Completion below.

• After a service request is made, a COMMANDER_REQUESTED_SERVICE_ID environment variable is generated that provides an ID for the service request. This service ID can be used by other build steps.

Commander service requests may take a few minutes to complete. If required, you can adjust the Timeout and Polling values. Also, if you're using an asynchronous execution, you can add a separate Wait For Service Request Completion build step.

Wait For Service Request Completion

If you add an async Commander service request step, your job can perform some parallel processing after the service request is started. However, you can also add a separate Wait For Service Request Completion step later, to ensure that the service request completes before attempting other steps that may be dependent on it.

If you add a Wait For Service Request Completion action, the Request ID field must provide the COMMANDER_REQUESTED_SERVICE_ID of the aysnc service request that the wait is for. If there are multiple async Commander service requests in the job, the Wait For Service Request Completion step will obtain the service ID of the last request.

Run Command Workflow

This build step enables your Jenkins job to run a Command Workflow in Commander.

For the build step to run a command workflow, you must configure the following:

• Target Type: The types of service you want to run the command workflow on. These can be an auto-scaling group, database, load balancer, stack, virtual service, or VM. You may also use environment variables in this field. Regular Jenkins syntax is used to resolve variables— either "$xyz", "${xyz}" or "${a.b}" but not "$a.b", while ignoring "$". Note that the plugin performs no verification of the input.
• Target Name: The name of the service you want to run the command workflow on. You can use the name of an existing service in the Commander service catalog. You may also use environment variables in this field. For example, you can use an environment variable created from a previous build step in the same job (for example,${COMMANDER_REQUESTED_SERVICE1_COMPONENT1_NAME}).
• Workflow Name: The name of an existing Commander workflow to run.
• Wait For Completion: Enable or clear this option to set whether you want the build job to wait for the workflow's completion before executing the next build step.
  • If enabled: Jenkins will wait for the workflow's completion before executing the next build step (that is, execute the workflow synchronously).

    For synchronous requests, the build console log will provide details about the workflow. If it's successful, a COMMANDER_WORKFLOW_TASK_ID environment variable is created, which provides the ID of the task running the workflow.

  • If cleared: Jenkins will not wait for the workflow's completion before executing the next build step (that is, execute the workflow asynchronously).

    For an asynchronous execution, you can add a separate Wait For Command Workflow build step after a Run Command Workflow step to check the workflow's results.

When the Jenkins build requests the workflow, it creates a COMMANDER_WORKFLOW_TASK_IDenvironment variable that will be shown in the build console log.

Wait for Command Workflow Completion

If you add an async Commander command workflow step, your job can perform some parallel processing after the command workflow is started. However, you can also add a separate Wait For Command Workflow Completion step later, to ensure that the workflow completes before attempting other steps that may be dependent on it.

If you add a Wait For Command Workflow Completion action, the Request ID field must provide the COMMANDER_WORKFLOW_TASK_ID of the aysnc command workflow that the wait is for. If there are multiple async command workflows in the job, this wait step will obtain the task ID of the last workflow.