AWS CodePipeline plugin

This topic describes how to use Deploy with AWS CodePipeline.

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

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

Step 2 - Create the sample pipeline

To create the sample pipeline:

1. In Pipeline name, enter petclinic-pipeline.

   

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 Deploy standard input format. To learn more about DAR files, see Prepare your application for Deploy.

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

   

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.

   

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. 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 Deploy. This procedure will be described in step 3.

1. Click Next step.

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

   

3. Click Next step.

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

Step 3 - Create a Deploy custom action

To use 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:

• Execute the following command:

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

Or

• 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 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 Deploy:

1. Click Edit to edit the pipeline.

   

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

   

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.

   

7. To configure the 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 Deploy. For more information, see Create an environment in Deploy.

   

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

10. In the 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 Deploy to perform this deployment. For more information, see Overview of security in Deploy.

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

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

    

note

The input artifact is optional for the Deploy action. If it is specified, 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 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.

1. Click Add action to add the Deploy action to the pipeline.

2. Click Save pipeline changes.

   

Configure Deploy for AWS CodePipeline

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

Step 1 - Install Deploy

Install and start 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 Deploy AWS CodePipeline plugin

To install the Deploy AWS CodePipeline plugin:

1. Download the plugin from the Deploy/Release Software Distribution site.

note

A customer account is required to access this URL.

1. Copy the plugin file to the plugins directory in your Deploy installation.
2. Restart Deploy.

Step 3 - Create the environment in Deploy

To create an environment where the application will be deployed:

1. In the side navigation bar, click Explorer.
2. Hover over Environments, click , 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 Deploy server, as determined by the Deploy server key.

To create an AWS CodePipeline job worker:

1. In the side navigation bar, click Explorer.

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

   

3. Enter the configuration details for the job worker.

   

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. Deploy will poll for jobs with the deployment pipeline group dev-deployments. When a job is available, the Deploy action state will change to In Progress.

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

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 Deploy action state is Succeeded.