vCommander 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 vCommander Jenkins plugin allows you to configure a Jenkins build job to request virtual services and run command workflows in a vCommander instance (version 7.0.0 or greater) as part of building, deploying and installing a project.

Using the vCommander 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 vCommander plugin enables more effective continuous integration and delivery for improved DevOps capabilities. Using the vCommander plugin allows you to quickly add vCommander 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 vCommander plugin you can create a Jenkins job with vCommander 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 vCommander plugin, involves the following tasks:

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


Configuring the vCommander Jenkins Plugin

Pre-requisites:

Download Jenkins Plugin


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

Installing the vCommander plugin from the HPI file

Embotics provides the vCommander 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 vcommander-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 vCommander

After the vCommander plugin is installed in Jenkins, you must configure it to communicate with your vCommander 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 vCommander section.
  3. In the vCommander URL field, enter the URL where vCommander 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 vCommander or Service Portal user credentials that the plugin will use to access vCommander. 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 vCommander.

    • To add new credentials, click Add > Jenkins. In the Jenkins Credentials Providerdialog, specify a valid username and password for accessing the vCommander 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 Credentials list, 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 vCommander URL will be displayed.

  5. If you're using credentials for a vCommander user account, leave the Organization Namefield 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 vCommander Steps to Jenkins Jobs

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

You can add multiple vCommander 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 vCommander build steps to non-Vcommander build steps.

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

To add vCommander 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 > vCommander Services.

    vCommander Services

  4. In the vCommander Services section that is added, select the build step that you want to use from the Action drop-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 vCommander 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 vCommander 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 vCommander 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 vCommander instance's Service Catalog.

Jenkins Request New Service

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 vCommander 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, VCOMMANDER_REQUESTED_SERVICEx_COMPONENTy_NAME and VCOMMANDER_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 VCOMMANDER_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.

vCommander 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 vCommander 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 VCOMMANDER_REQUESTED_SERVICE_ID of the aysnc service request that the wait is for. If there are multiple async vCommander service requests in the job, the Wait For Service Request Completion step will obtain the service ID of the last request.

Jenkins Wait for Service Request Completion

Run Command Workflow

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

Jenkins Run Command Workflow

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 vCommander 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,${VCOMMANDER_REQUESTED_SERVICE1_COMPONENT1_NAME}).
  • Workflow Name: The name of an existing vCommander 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 VCOMMANDER_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 VCOMMANDER_WORKFLOW_TASK_IDenvironment variable that will be shown in the build console log.

Wait for Command Workflow Completion

If you add an async vCommander 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 VCOMMANDER_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.

Jenkins Wait for Command Workflow Completion