Generate a deployment package

Introduction

A deployment package is a way to enable users to quickly deploy Java or .NET applications to any environment using CloudBees CD/RO. 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 CD/RO. 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 CD/RO 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.

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

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 CD/RO 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 CD/RO 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 service catalog item that allows deployment of Java or .NET applications quickly using CloudBees CD/RO. This item is included in CloudBees CD/RO. 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 CD/RO. 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 CD/RO.

Using the deployment package manager

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:

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 CD/RO 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 CD/RO 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 CD/RO from Jenkins CI.

CloudBees CD/RO has bidirectional integration with Jenkins:

Jenkins plugin on the CloudBees CD/RO side: This plugin lets you trigger Jenkins jobs from CloudBees CD/RO. For details, refer to the Jenkins plugin.
CloudBees CD/RO plugin for Jenkins: This plugin lets you launch various actions in CloudBees CD/RO from Jenkins using Jenkins post-build actions such as:
1. Create Application from Deployment Package to CloudBees CD/RO: Allows for seamless deployment of a package from Jenkins CI to CloudBees CD/RO. This post-build action can be used to push deployment packages to CloudBees CD/RO after a build is completed. This action creates the application in CloudBees CD/RO and can also deploy to its environments.
2. Publish Artifact to CloudBees CD/RO: This post-build action lets you publish artifact outputs of Jenkins builds to the CloudBees CD/RO Artifact Repository.
3. Run Pipeline in CloudBees CD/RO: This post-build action lets you trigger a pipeline in CloudBees CD/RO 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 CD/RO.

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. To use and integrate with CloudBees CD/RO, you must create configurations in Jenkins. To do so, navigate to Manage Jenkins Configure System and go to the CloudBees CD/RO section.

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

Configuration Name : Name of the CloudBees CD/RO configuration
Server URL : URL for the CloudBees CD/RO Server. For example, https://<cloudbees-flow-server>

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].
REST API Version : Version for the CloudBees CD/RO REST API. For example, v1
User Name : User name in CloudBees CD/RO
User Password : Password for the above user

Using the plugin for the Jenkins project

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

This build action has the following parameters:

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

Configuration: Name of the CloudBees CD/RO configuration. This points to the URL and credentials for the CloudBees CD/RO 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 CD/RO. 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 CD/RO 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:

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.
If the manifest.json file has environment information, then ensure that the environment, environment tiers, and resources are defined in CloudBees CD/RO so that the automated deployment flow works.
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.
Choose Add Post-build Action > CloudBees CD/RO - Create/Deploy Application from the Deployment Package (see the screenshot above).
Fill in the CloudBees CD/RO 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 CD/RO.

For more information

See the Deployment Package Manager video in the CloudBees YouTube channel .