AWS CodePipeline plugin

AWS CodePipeline is the Amazon Web Services continuous delivery service. It facilitates modelling and automation of the software release process.

Using the AWS CodePipeline plugin for XL Deploy, you can use XL Deploy as an additional deployment option for the AWS CodePipeline. This means that CodePipeline users can leverage the deployment capabilities of XL Deploy for deployments of existing enterprise applications to on-demand, on-premises, and hybrid cloud environments hosted in Amazon EC2 and other clouds.

This topic describes how to use XL Deploy with AWS CodePipeline.

Create a sample pipeline in AWS CodePipeline

This section describes how to create a sample pipeline in AWS CodePipeline to demonstrate a deployment action using XL Deploy.

Step 1 - Log in to AWS CodePipeline

Go to the AWS Management Console, select AWS CodePipeline, and click Get started to create a pipeline.

AWS CodePipeline homepage

Step 2 - Create the sample pipeline

To create the sample pipeline:

  1. In Pipeline name, enter petclinic-pipeline.

    Create a pipeline - Step 1

  2. Click Next step.

  3. Choose a source code provider.

    In a well-developed pipeline, you would refer to application source code here, which would be compiled and packaged in a deployable artifact during a build step. This example demonstrates a deployment step, so the source location points to a Deployment ARchive (DAR) file, which is the XL Deploy standard input format. To learn more about DAR files, see Prepare your application for XL Deploy.

    For this example, select the Amazon S3 Source provider and set the Amazon S3 location to s3://petclinic-packages/PetClinic-1.0.dar.

    Create a pipeline - Step 2

  4. Click Next step.

  5. Choose a build provider to build the artifact.

    In this example, the source code location already points to a deployable artifact (the DAR file), so select No Build.

    Create a pipeline - Step 3

  6. Choose a deployment provider: select the Deployment provider AWS CodeDeploy.

    Note: By default, when using AWS CodePipeline, you can only select AWS CodeDeploy or AWS Elastic Beanstalk. XL Deploy is not available during the pipeline creation stage. You must first create a pipeline with an AWS deployment provider, then edit the pipeline to change the provider to XL Deploy. This procedure will be described in step 3.

    Create a pipeline - Step 4

  7. Click Next step.

  8. Provide the AWS Service Role that you will use for AWS CodePipeline. This gives AWS CodePipeline permission to use resources in your account. You can create a new role or use an existing role.

    Create a pipeline - Step 5

  9. Click Next step.

  10. Review the AWS CodePipeline details and click Create pipeline to create the pipeline.

Step 3 - Create an XL Deploy custom action

To use XL Deploy as a deployment provider in AWS CodePipeline, you must create a custom action.

To create a custom action:

  1. Install the AWS Command Line Interface (CLI).
  2. In the AWS CLI:
  3. Execute the following command:

    $ aws codepipeline create-custom-action-type --cli-input-json http://git.io/vYpaN

    Or

  4. Execute the following command using the direct link:

    $ aws codepipeline create-custom-action-type --cli-input-json https://gist.githubusercontent.com/xlcommunity/41c394a82547af62363f/raw/2970533d229115e4f1a6e75946fe62ace2271234/aws-codepipeline-xl-deploy-action.json    

    Step 4 - Add XL Deploy as the deployment provider

After the pipeline is created, you will be redirected to the petclinic-pipeline page.

To change the deployment provider to XL Deploy:

  1. Click Edit to edit the pipeline.

    Edit pipeline

  2. Click the X icon to delete the AWS deployment provider action from the Beta stage, then confirm the deletion.

    Delete AWS deployment provider action

  3. Click Action to add a new action.

  4. Select the Deploy Action Category.

  5. Set the Action name to petclinicdeployment.

  6. In the Deployment provider field, select XL-Deploy.

    Select XL Deploy deployment provider

  7. To configure the XL Deploy action, set the Deployment Package Name to Applications/PetClinic and Deployment Package Version to 1.0.

    This package contains the files and resources that make up a version of the application, as well as a manifest file (deployit-manifest.xml) that describes the package contents.

  8. In the Environment Id field, enter Environments/dev.

    An environment is a grouping of infrastructure and middleware items such as hosts, servers, clusters, and so on. The environment is the target of the deployment. The environment ID must match the ID of an existing environment in XL Deploy. For more information, see Create an environment in XL Deploy.

    XL Deploy action - Package and environment details

  9. In the XL Deploy URL field, enter the XL Deploy installation URL. AWS CodePipeline uses this URL to provide a link to your XL Deploy server in the CodePipeline user interface.

  10. In the XL Deploy Username field, enter the ID of the user that should be used to deploy the deployment package to the target environment. This user must have sufficient permissions in XL Deploy to perform this deployment. For more information, see Overview of security in XL Deploy.

  11. In the XL Deploy Password field, enter the password for the user.

  12. In the XL Deploy Server Key field, provide a key to identify the XL Deploy server. If you have multiple XL Deploy servers in your organization, this key will be used to identify which XL Deploy server picks up the CodePipeline task.

    XL Deploy action - XL Deploy installation details

    Note: The input artifact is optional for the XL Deploy action. If it is specified, XL Deploy will attempt to import the specified input artifact, the deployment package, into its internal repository before starting the deployment.

    After a deployment package has been imported in XL Deploy, you can deploy it to other target environments without importing it again. In a pipeline, only the first deployment action needs to import the new deployment package. For subsequent deployment actions that deploy the same package to environments further down the pipeline, no input artifact is specified.

  13. Click Add action to add the XL Deploy action to the pipeline.

  14. Click Save pipeline changes.

    Pipeline with XL Deploy action

Configure XL Deploy for AWS CodePipeline

This section describes how to configure XL Deploy to communicate with AWS CodePipeline and execute deployment jobs.

Step 1 - Install XL Deploy

Install and start XL Deploy.

Note: This procedure will also install an Apache Tomcat server that will be used with the sample CodePipeline pipeline.

Step 2 - Download and install the XL Deploy AWS CodePipeline plugin

To install the XL Deploy AWS CodePipeline plugin:

  1. Download the plugin from the XebiaLabs Software Distribution site. Note: A customer account is required to access this URL.
  2. Copy the plugin file to the plugins directory in your XL Deploy installation.
  3. Restart XL Deploy.

Step 3 - Create the environment in XL Deploy

To create an environment where the application will be deployed:

  1. In the top navigation bar, click Explorer.
  2. Hover over Environments, click Menu button, then New > Environment.
  3. Click Create environment.
  4. In the Name field, enter dev.
  5. In the common section, click the Containers field, then select the Tomcat virtual host from the list of containers.
  6. Click Save and close.

Step 4 Create an AWS CodePipeline job worker

An AWS CodePipeline job worker will poll AWS CodePipeline every minute for jobs that are assigned to this XL Deploy server, as determined by the XL Deploy server key.

To create an AWS CodePipeline job worker:

  1. In the top navigation bar, click Explorer.

  2. In the left pane, hover over Configuration, click Menu button, then select New > aws > CodePipelineJobWorker.

    Create awscodepipeline.CodePipelineJobWorker

  3. Enter the configuration details for the job worker.

    Configure awscodepipeline.CodePipelineJobWorker

  4. Click Save and close.

Step 5 Start the pipeline

To start the AWS CodePipeline pipeline, you must execute a manual command or make a commit. To start the pipeline manually:

  1. Install the AWS command-line client on your computer.
  2. Open a command line and execute:

    aws codepipeline start-pipeline-execution --name petclinic-pipeline

    Step 6 Deployment

After you start the pipeline, you will see actions in an In Progress state in the AWS CodePipeline interface. XL Deploy will poll for jobs with the deployment pipeline group dev-deployments. When a job is available, the XL Deploy action state will change to In Progress.

XL Deploy action in progress

The XL Deploy AWS CodePipeline job worker will pick up the job and perform the deployment. After the application is deployed, you can see it in the Deployment Workspace under the dev environment.

Deployed application in XL Deploy

You can also see the PetClinic application running on your Tomcat server at http://<TOMCAT_SERVER_URL>/petclinic/.

In the AWS CodePipeline interface, you will see that the XL Deploy action state is Succeeded.

XL Deploy action succeeded