Deployment Packages

Introduction

A deployment package is a way to enable users to quickly deploy Java or .NET applications to any environment using CloudBees Flow. A deployment package is a .zip file that is made up of a manifest file and one or more components that make up an application. This manifest file will have the required inputs to create application and environment mappings automatically in CloudBees Flow. In addition to creating models, it is even possible to trigger application deployments.

A deployment package can be generated as part of any Continuous Integration (CI) automation (even with third-party CI tools such Jenkins, TFS, or TeamCity). Also, anyone with a zip utility and a text editor can manually create a deployment package.

Once the deployment package is created, there are multiple options to consume it to generate the application and environment for deployment:

  • Use the Deployment Package Manager from the Service Catalog UI

  • From Jenkins using the CloudBees Flow plugin

  • Use the Deployment Package Manager API

    • From the CLI

    • From any other third-party CI tool

Creating a Deployment Package

Deployment packages can be created automatically as part of a CI process, or they can be created manually by hand.

Manifest File (manifest.json)

The manifest file is a JSON metadata file that describes the application and its contents. You can find a sample manifest.json file at https://www.github.com/electric-cloud/DeploymentPackageManager/tree/master/SampleManifests.

Here is a sample manifest.json file for deploying a Java WAR file to JBoss:

{
   "application":{
      "name":"Application Name",
      "version":"1.0",
      "components":{
         "component":[
            {
               "artifact":{
                  "artifactType":"JBOSS",
                  "artifactName":"org.ec:jboss",
                  "artifactVersion":"1.0",
                 "artifactFileName": "jboss-as-helloworld.war"
               }
            }
         ]
      }
   }
}

Following are the attributes in the sample file above:

Attribute Descriptions

Name

Name of the application you want to create.

Version

Version of the application. You should increment the version each time a new build is created.

artifactType

Type of the component. For example, JBOSS, Tomcat, WEBSPHERE, or WEBLOGIC.

artifactName

Component artifact name. This follows the maven GAV ( groupId , artifactKey , and version ) naming convention.

artifactVersion

Version of the component. You should increment the component version each time a new artifact is created.

artifactFileName

Name of the component artifact file.

Automatically Deploying the Application from the Deployment Package

A manifest file can optionally include environment and application tier to environment tier mapping information. See the sample manifest.json file that is described above. If this additional information is provided, then the Deployment Package Manager will create the environment, complete the environment mapping, and deploy the application.

Components

Components map to physical files that are generated as part of a Jenkins CI build or a Maven build. For example, jboss-helloworld.war. CloudBees Flow supports Java application deployment to JBoss, Tomcat, WebSphere, and WebLogic as well as .NET application deployment to a Microsoft IIS server. If components are provided as part of the zip file, they will be automatically published as artifacts in the CloudBees Flow Artifact Repository. Component physical files are optional when you create the deployment package. Users can always specify references to the actual files in the manifest json file.

Creating the Zip File

Once you have created the manifest.json file and the components, you simply zip these files into a .zip file of your choice.This .zip file is called the deployment package.

hello.zip

|-- manifest.json

|-- jboss-helloworld.war

For a continuous delivery (CD) use case, the continuous integration build will generate this package and publish it to the artifact repository.

Deployment Package Manager

This is a special type of catalog item that allows deployment of Java or .NET applications quickly using CloudBees Flow. This item is included in CloudBees Flow. This is useful for consuming deployment package zip files manually.

Before you can create this catalog item, you must create the deployment package outside of CloudBees Flow. See Creating a Deployment Package to create a deployment package.

Once you have created the deployment package, you can then leverage the Deployment Package Manager catalog item to create an application model that corresponds to the uploaded application package with no or very little knowledge of CloudBees Flow.

Using the Deployment Package Manager from the Service Catalog UI

Click the Service Catalog button to view all the catalogs that are available to you as an end user. Select the Deployment Package Manager. You are prompted you to upload the deployment package. Once you click OK, the system starts processing the package:

03000003

As part of the package processing, the system publishes the component file included in the package to the artifact repository using the artifactName and version specified in the manifest file. Once all the components are published, the system generates an application that orchestrates the deployment of each of these components using an application process.

Once the application is created, you can deploy the application to any environment by completing the application mapping.

Deployment Package Manager API

You use this API to invoke the Deployment Package Manager to create an application model and deploy it to any existing environment. The model is based on the deployment package from the CLI and from external applications such as Jenkins.

From the CLI

You can call the createApplicationFromDeploymentPackage API from the CLI in order to create an application from a deployment package. Following is the usage:

createApplicationFromDeploymentPackage <artifactGroup> <artifactKey> <artifactVersion> <artifactFileName>
[--dslString <dslString>]
[--retrieveToFolder <retrieveToFolder>]
[--dslFile <dslFile>]

The API assumes you have already uploaded your package to the CloudBees Flow artifact repository following the GAV ( Group-artifactKey-version ) naming convention as described above.

ectool createApplicationFromDeploymentPackage org.ec hello 1.0 hellopackage.zip --retrieveToFolder /tmp

The DSL used by the package manager is defaulted from the Service Catalog item that is referenced by the following custom server property value in the Automation Platform: Administration > Server > ec_selfservice > defaultPackageManagerCatalogItem > Deployment Package Manager.

Integrating with the Jenkins Plugin

While CloudBees Flow itself can be used as an enterprise level continuous integration platform, it can be easily integrated with all the leading third-party CI platforms. The example below describes how to invoke actions in CloudBees Flow from Jenkins CI.

CloudBees Flow has bidirectional integration with Jenkins:

  1. Jenkins plugin on the CloudBees Flow side: This plugin lets you trigger Jenkins jobs from CloudBees Flow. For details, see https://electric-cloud.com/plugins/directory/p/jenkins .

  2. CloudBees Flow plugin for Jenkins: This plugin lets you launch various actions in CloudBees Flow from Jenkins using Jenkins post-build actions such as:

    1. Create Application from Deployment Package to CloudBees Flow: Allows for seamless deployment of a package from Jenkins CI to CloudBees Flow. This post-build action can be used to push deployment packages to CloudBees Flow after a build is completed. This action creates the application in CloudBees Flow and can also deploy to its environments.

    2. Publish Artifact to CloudBees Flow: This post-build action lets you publish artifact outputs of Jenkins builds to the CloudBees Flow Artifact Repository.

    3. Run Pipeline in CloudBees Flow: This post-build action lets you trigger a pipeline in CloudBees Flow from a Jenkins job or a pipeline.

      For more information, see https://plugins.jenkins.io/electricflow.

The following example focuses on Post-Build’ action - Create Application from Deployment Package to CloudBees Flow.

Installing and Configuring the Jenkins Plugin

This plugin is available in the Jenkins Plugin Manager and can be downloaded and installed similar to any other Jenkins plugin:

03000004

To use and integrate with CloudBees Flow, you must create configurations in Jenkins. To do so, navigate to Manage Jenkins > Configure System and go to the CloudBees Flow section.

One or more configurations can be created to connect to and call APIs into CloudBees Flow. For each configuration, specify the following attributes:

  • Configuration Name : Name of the CloudBees Flow configuration

  • Server URL : URL for the CloudBees Flow Server. For example, https://<cloudbees-flow-server>

  • REST API Version : Version for the CloudBees Flow REST API. For example, v1

  • User Name : User name in CloudBees Flow

  • User Password : Password for the above user

03000005

Using the Plugin for the Jenkins Project

The CloudBees Flow plugin installs a post-build action named “CloudBees Flow - Create/Deploy Application from Deployment Package,” which can be added to your Jenkins project. This action will be available as a drop-down:

03000006

This build action has the following parameters:

03000007

  • Configuration: Name of the CloudBees Flow configuration. This points to the URL and credentials for the CloudBees Flow system. For details, see the plugin page at https://plugins.jenkins.io/electricflow .

  • Deployment Package Path: Location or path for the deployment package to be published to CloudBees Flow. For example, the target folder where the build output files are located. This folder should contain:

  • Manifest file (manifest.json): This a JSON file that describes details of the application, its components, and artifacts. If the manifest file contains details for the environment and environment mappings, then CloudBees Flow will deploy to that environment automatically. See https://github.com/electric-cloud/DeploymentPackageManager/tree/master/SampleManifests for examples of manifest files.

  • Build artifacts files: The actual build outputs such as binaries, packages, .war/ear/jar or .NET files.

As a developer or integrator, follow these steps:

  1. Create a manifest file, manifest.json, in your source control system. See https://github.com/electric-cloud/hello-world-war for an example. Also see https://github.com/electric-cloud/DeploymentPackageManager/tree/master/SampleManifests for examples of manifest files.

  2. If the manifest.json file has environment information, then ensure that the environment, environment tiers, and resources are defined in CloudBees Flow so that the automated deployment flow works.

  3. If the Jenkins build is already set up for your SCM project, ensure that the manifest.json file is copied to the Deployment Package Path (such as the target/folder). Also ensure that the WAR file (or any build artifact) is copied to the same folder. For example, the target/ folder should have the following content:

    target/
    |-- manifest.json
    |-- helloworld.war

    Note that manifest.json would have a reference to helloworld.war. Both application and component versions in the manifest.json file should be incremented based on the build number or otherwise.

  4. Choose Add Post-build Action > CloudBees Flow - Create/Deploy Application from the Deployment Package (see the screenshot above).

  5. Fill in the CloudBees Flow Configuration field and the Deployment Package Path field (such as the target).

After the above steps are complete, then the next Jenkins build will execute the action to create and/or deploy the application into CloudBees Flow.

For More Information