AWS Developer Blog

AWS Toolkit for Eclipse Integration with AWS CodeDeploy (Part 3)

In this part of the series, we will show you how easy it is to run deployment commands on your EC2 fleet with the help of the AWS CodeDeploy plugin for Eclipse.

Create AppSpec Template

  • First, let’s create a shell script that executes the command we need to run on our instances:

/home/hanshuo/stop-httpd-server-appspec/template/stop-httpd.sh

#!/bin/bash

service ##HTTPD_SERVICE_NAME## stop

To make it a little bit fancier, instead of hardcoding httpd as the service name, we instead use a place holder ##HTTPD_SERVICE_NAME##. Later, you will learn how this could help you create a configurable deployment task in Eclipse.

  • Next, inside the same directory, let’s create a simple AppSpec file that specifies our shell script as the command for the ApplicationStart lifecycle event.

/home/hanshuo/stop-httpd-server-appspec/template/appspec.yml

version: 0.0
os: linux
hooks:
  ApplicationStart:
    - location: stop-httpd.sh
      timeout: 300
      runas: root

This AppSpec file asks CodeDeploy to run stop-httpd.sh as the root user during the ApplicationStart phase of the deployment. Since this is the only phase mentioned, it basically tells the service to run this single script as the whole deployment process – that’s all we need! You can find more information about the AppSpec file in the AWS CodeDeploy Developer Guide.

  • Now that we have created our template which consists of all the necessary AppSpec and command script files. The final step is to create a metadata file for it, which is in a specific JSON format understood by the Eclipse plugin.

/home/hanshuo/stop-httpd-server-appspec/template.md

{
  "metadataVersion" : "1.0",
  "templateName" : "Stop Apache HTTP Server",
  "templateDescription" : "Stop Apache HTTP Server",
  "templateBasedir" : "/home/hanshuo/stop-httpd-server-appspec/template",
  "isCustomTemplate" : true,
  "warFileExportLocationWithinDeploymentArchive" : "/application.war",
  "parameters" : [
    {
      "name" : "Apache HTTP service name",
      "type" : "STRING",
      "defaultValueAsString" : "httpd",
      "substitutionAnchorText" : "##HTTPD_SERVICE_NAME##",
      "constraints" : {
        "validationRegex" : "[\S]+"
      }
    }
  ]
}
  • templateName, templateDescription – Specifies the name and description for this template
  • templateBasedir –  Specifies the base directory where your AppSpec file and the command scripts are located
  • isCustomTemplate – True if it is a custom template created by the user; this tells the plugin to treat templateBasedir as an absolute path.
  • warFileExportLocationWithinDeploymentArchive – Since this deployment task doesn’t actually consume any WAR file, we can specify any value for this attribute.
  • parameters – Specifies a list of all the configurable parameters in our template. In this case, we have only one parameter ##HTTPD_SERVICE_NAME##
    • ​name – The user-friendly name for the parameter
    • type – Either STRING or INTEGER
    • defaultValueAsString – The default value for this parameter
    • substitutionAnchorText – The place-holder text that represents this parameter in the template files; when copying the template files, the plugin will replace these place holders with the user’s actual input value
    • constraints – The constraints that will be used to validate user input; supported constraints are validationRegex (for STRING), minValue and maxValue (for INTEGER).

Ok, now we that have everything ready, let’s go back to Eclipse and import the AppSpec template we just created.

In the last page of the deployment wizard, click the Import Template button at the top-right corner of the page:

Then find the location of our template metadata file, and click Import.

The plugin will parse the metadata and create a simple UI view for the user input of the template parameter ##HTTPD_SERVICE_NAME##. Let’s just use the default value httpd, and click Finish.

After the deployment completes, all the httpd services running on your EC2 instances will be stopped. If you are interested in how your commands were executed on your hosts, or if you need to debug your deployment, the log output of your scripts can be found at /opt/codedeploy-agent/deployment-root/{deployment-group-ID}/{deployment-ID}/logs/scripts.log

In this example, you are expected to get the following log output. You can see that the httpd service was successfully stopped during the ApplicationStart event:

	2015-01-07 00:28:04 LifecycleEvent - ApplicationStart
	2015-01-07 00:28:04 Script - stop-httpd.sh
	2015-01-07 00:28:04 [stdout]Stopping httpd: [  OK  ]

In the future, if you ever want to repeat this operation on your EC2 instances, just kick off another deployment in Eclipse using the same Stop Apache HTTP Server template, and you are done!

You can use the AppSpec template system to create more complicated deployment tasks. For example, you can define your own template that deploys your Java web app to other servlet containers such us Jetty and JBoss. If you are interested in the Tomcat 7 running on Linux template we used in the walkthrough, you can find the source code in our GitHub repo.

Feel free to customize the source for your specific need, and keep in mind that we are always open to pull-requests if you want to contribute your own templates that might be useful for other Java developers.

Conclusion

The AWS CodeDeploy plugin for Eclipse allows you to easily initiate a deployment directly from your source development environment. It eliminates the need to repeat the manual operations of building, packaging and preparing revision. It also allows you to quickly set up an AppSpec template that represents a repeatable and configurable deployment task.

Give it a try and see whether it can improve how you deploy your Java web project to your EC2 instances. If you have any feedback or feature requests, tell us about them in the comments. We’d love to hear them!