Add Commander Steps to Jenkins Jobs

After you have installed the Commander Jenkins plugin and configured its connection to your Commander installation (see Configure the Commander Jenkins Plugin), 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 doesn't 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, select Add build step > Commander Services.

    Adding the Commander Services build step.

  4. In the Commander Services section that's added, select the build step that you want to use from the Action drop-down and configure it as appropriate. You can select any of the following actions:

    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.

  5. After you have configured a Commander build step, drag it to the appropriate spot in your build job.
  6. 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.

Jenkins Request New Service

To have the build step to request the service, 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's 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 won't 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.

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 VCOMMANDER_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.

Jenkins Wait for Service Request Completion

Run Command Workflow

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

Jenkins Run Command Workflow

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

  • Target Type: The types of target that you want to run the command workflow on. These can be:
    • Any Target Type — Select this option if you want to use the command workflow for any type of service or cloud account.
    • Auto Scaling Group
    • Database
    • Load Balancer
    • Cloud Account
    • Stack
    • Virtual Service
    • VM
    • No Inventory Target

    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.

  • Select the types of services or infrastructure that you want the command workflow to be run on
  • Target Name —  The name of the target that you want to run the command workflow on. You can use the name of an existing target 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, ${VCOMMANDER_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 VCOMMANDER_WORKFLOW_TASK_ID environment variable is created, which provides the ID of the task running the workflow.

    • If cleared — Jenkins won't 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_ID environment 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 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