Jenkins Integration

Overview

The CloudCenter Suite Jenkins plugin provides integration between Jenkins and Workload Manager by allowing users to directly launch deployments from the Jenkins server using application profiles and deployment environments defined within Workload Manager.  Additionally, users can upgrade an existing deployment by specifying upgrade scripts for each tier.

Prerequisites

  • The supported Jenkins versions for use with the Workload Manager Jenkins plugin must be Jenkins 1.64 or later.

  • The required Java version for the Jenkins server must be Java SE 8 or later.

  • The the Jenkins project used to specify your deployment must be a "freestyle" project.

  • You must have admin privileges and access to the Suite Admin to generate the required CloudCenter Suite API access key.

  • If you attach any aging/suspension/security policies to a Workload Manager deployment environment referenced by the Jenkins project, you must toggle the switch for the selected policy in the Deployment Environment > Policy Settings tab to Not visible to user to ensure that the policy is automatically attached to the deployment (see screenshot below).

Install the Jenkins Client Plugin

  1. Download the CloudCenter Suite Jenkins Client Plugin (.hpl file) from https://software.cisco.com/download/home/286323192/type/286309561/release/
  2. Login to CloudCenter Suite with administrator credentials to obtain your API ID and access key as explained in API Key.
  3. In Jenkins, go to Manage Jenkins > Manage Plugins > Advanced > Upload Plugin (see screenshots below) and upload the Jenkins Client Plugin you downloaded in step 1.




Submit a Job

  1. After you install the Jenkins Client Plugin, from the Jenkins dashboard, create a new "Freestyle Project" or select an existing project. This brings you to the Configuration screen for the project.
  2. Scroll down to the "Build" section of the Configuration screen, click Add Build Step, and select "Cisco CloudCenter Suite App Deployment Client" from the dropdown As shown in the screenshot below


  3. Once the Cisco client is selected, a new section shows up under the Build section for entering the CloudCenter Suite API credentials as shown in the screenshot below.

    Enter the the credentials as described in the table below and then click Validate Connection.

    ParameterDescription
    Cisco CloudCenter Suite URLThe URL of the CloudCenter Suite UI.
    Username

    The user ID returned from the get API Key dialog.

    AccessKey

    The API Access Key returned from the get API Key dialog.

  4. Once the validation succeeds, a new section appears below the API credential fields containing the Workload Manager deployment details fields as shown in the screenshot below.


    Use the dropdown menus to populate each field in the Cisco client plugin input parameters, and complete the fields for "Choose to copy your binaries" and "Choose the Deployment Behavior", as described in the table below. When done, click Save

    ParameterDescription
    Deploy to ProjectUse this flag to deploy to a project, instead of a general deployment environment (see Project and Phase Management for additional context).
    Project NameIf you select the Deploy to Project flag, this parameter is displayed and the list of projects are fetched from CloudCenter Suite. Based on this parameter value, only applications associated with this project are filtered out in the Application Version field.
    Project PhaseBased on the project name, a dropdown list of all Phases in that project are displayed. Use this value in the Deployment Environment field to filter the project.
    Application Name

    From the dropdown list of applications listed in the Workload Manager UI, select the required application to deploy.

    After entering your credentials, be prepare to wait for some time as the Application Management APIs APIs may take a while to load.

    Application VersionBased on your application, select the application version from this dropdown list.
    Deployment EnvironmentSelect the required deployment environment to deploy your application. Be sure to verify and check all default settings like default cloud, default instance type, and so forth as Workload Manager uses these default settings for each deployment.
    Cloud Type

    Select one cloud type from this dropdown list of cloud types that are present in your deployment environment.

    Cloud AccountThe cloud account with which you deploy the application.
    Instance Type

    Select a single instance type as the default instance type.

    TagsA comma-separated list of tags associated with this job.
    AppParameters

    A comma-separated list of key-value pairs to pass as global parameters. For example:
    abcd=wow, cdef=cliqrRocks

    CloudCenter includes the $BUILD_ID, $BUILD_NUMBER, $BUILD_TAG, $JOB_NAME, and if available, $BUILD_TIMESTAMP from other plugins. (See The jenkinsBuildId Macro below).

    You can add a variable in this section to fetch parameters that are shared by other jobs. For example:
    abc=${BUILD_PARENT_NUMBER} or abc=$BUILD_PARENT_NUMBER

    You also have the option to retrieve parameters from the $WORKSPACE/appParams file that contains multiple lines of key-value parameter pairs. You can then uses these parameters to pass passwords or other sensitive information without displaying them in the Workload Manager UI.

    Choose the binaries to be CopiedIdentifies if the files must be copied to an external location
    • Copy Binaries to External Location – all your binaries will be available under /tmp/app1/latest
    • Don't copy Binaries – the binaries will not be copied to any other location
    Choose the Deployment Behavior

    You can only do this once for deployments.

    • Create a new Deployment on every Build: This option creates a brand new deployment for every build.
    • Stop Old Deployment if exists: This option creates a brand new deployment for every build and stops the older deployment if it exists.
    • Update Existing Deployment (Create new if doesn't Exist):
      • Updates a previous deployment that was launched from the Workload Manager Jenkins plugin during a previous build for the same project.
      • If the previous deployment is still in progress (job) and is not yet in the Running state, the Workload Manager Jenkins plugin waits till the deployment is in the running state before triggering an update (see Deployment, VM, and Container States for additional context).
      • If the previous deployments ends up as an error or if that deployment is stopped or cancelled from the Workload Manager UI, the Workload Manager Jenkins plugin launches a new deployment as part of the Update process.
      • If this is the first build, the Workload Manager Jenkins plugin creates a new Deployment and from the next successful build it uses the existing deployment.
      • UpdateScripts: A comma separated list of tierName:scriptToExecute scripts that are executed in the order mentioned here. For example: AppCluster:/shared/app/petclinic/update.sh,Database:/shared/app/updatemysql.sh, AppCluster:/shared/app/startServer.sh
        You can also use the Workload Manager jenkinsBuildId parameter in your update script as explained in Using the jenkinsBuildId parameter in UpdateScripts below.

      • Wait For Deployment And Export Details: Waits for Deployment to enter the Running state and exports the Job Details to the $WORKSPACE/userenv file

  5. After saving the project configuration, you are brought to the main screen for your project. From your project's main screen, click the Build Now menu selection to launch your deployment.
  6. Open a browser tab to login to your Workload Manager UI and navigate to the Deployments list page. Your newly launched deployment will appear in the list. 

Using the jenkinsBuildId macro in the Binaries to be Copied path name

The Workload Manager $BUILD_ID or %jenkinsBuildId% macro will inject the Jenkins build ID into the userenv file for each tier in the deployment. The %jenkinsBuildId% macro is not an application-specific macro. This Workload Manager-defined macro applies only to those deployments that are launched using the Jenkins plugin. Any deployment triggered by the Jenkins plugin will automatically have jenkinsBuildId in the userenv file for each tier in the deployment and this jenkinsBuildId can be used to reference the right binaries in the repo/storage. For example, if a web server has a previous war file path set to /shared/app/petclinic/latest/, then this war file (petclinic.war) can now use this macro to point to /shared/app/petclinic/%jenkinsBuildId%/petclinic.war. In update deployment scenarios, the jenkinsBuildId macro will update the jenkinsBuildId value in the userenv file for each tier in the deployment.



  • No labels
© 2017-2019 Cisco Systems, Inc. All rights reserved