Preface

This document describes the functionality provided by the EC2 plugin.

See the Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

The EC2 plugin is a Deployit plugin that supports launching, provisioning and terminating hosts and environments on the EC2 platform.

The EC2 plugin is part of the Deployit Cloud Pack. For more information about the Cloud Pack, see the Deployit Cloud Pack Manual.

Features

• Launching and terminating EC2 instances from Deployit;
• Combining EC2 instances into environments which can be used for application deployment;
• Registering middleware on EC2 instances as part of a created environment.

Requirements

• Deployit requirements

  • Deployit: version 3.9+
  • Other Deployit Plugins: cloud-plugin

• Infrastructural requirements

  • EC2 credentials: AWS key and secret for accessing the EC2 platform via its API.

Usage scenarios

This section describes the most common usage scenarios, further sections contain more detailed configuration instructions.

Creating a single host

In its simplest form, the EC2 plugin can launch a single instance on EC2 and register it in Deployit as a CI of type ec2.SshHost (when connecting to the host using SSH) or ec2.CifsHost (when connecting using CIFS). The resulting host CI can contain middleware CIs that are present on the host and can be used as normal containers for deployment. The host can also be destroyed, which causes Deployit to terminate the EC2 instance and remove the host CI and its children from the repository.

There is a special CI type ec2.HostTemplate which is used as a template to define all information about the future host.

Creating an environment

The EC2 plugin can combine several hosts into a cloud.Environment CI. This type of CI behaves similar to udm.Environment and can immediately be used for application deployment. Analogous to the single-host scenario, a special CI type cloud.EnvironmentTemplate is used to define which host to create and allows the user to fine-tune the set of members which will end up in the new environment.

Provisioning instantiated hosts

When launching an instance on EC2, the AMI it is based on may already have the desired middleware installed. If this is the case, a launched host will be ready for use as soon as it has finished booting. It is also possible to provision a host using Puppet, Chef or a shell command after launching it. This is supported via the the notion of marker file. If the host template specifies a marker file, Deployit will poll the launched instance for its presence. When the file is found on the instance filesystem, Deployit will conclude the host is up and ready for deployment. The location of the marker file can be configured in the ec2.HostTemplate.

See the section on the marker file in the Cloud Pack Manual for additional details on the polling process.

Note:

• it is the responsibility of the AMI to invoke the provisioning process and to create the marker file when provisioning is completed, signaling that the host and middleware is ready for deployment.
• marker files are only supported on Unix-based AMIs.

Configuration instructions

EC2 credentials

The EC2 plugin requires access to the AWS key and secret to access the EC2 API. These credentials are specified under the Configuration root node in the repository using a ec2.Credentials CI. The CI has a control task validateCredentials that can test that the credentials can be used to communicate with EC2.

Host template

The next step is to define host template CIs (ec2.HostTemplate). A host template describes a single host that can be launched on EC2. In addition to the generic host template properties, the EC2 host template allows some EC2-specific properties:

See the Cloud Pack Manual for the generic properties.

Here is an example of an EC2 host descriptor:

<#escape x as x?xml>
  <list>
    <ec2.SshHost id="${hostsPath}/${hostTemplate.name}_${hostAddress}">
      <template ref="${hostTemplate.id}"/>
      <cloudId>${cloudId}</cloudId>
      <address>${hostAddress}</address>
      <#if hostTemplate.privateKeyFile??><privateKeyFile>${hostTemplate.privateKeyFile}</privateKeyFile></#if>
      <username>${hostTemplate.username}</username>
      <#if hostTemplate.password??><password>${hostTemplate.password}</password></#if>
      <os>${hostTemplate.os}</os>
      <connectionType>${hostTemplate.connectionType}</connectionType>
    </ec2.SshHost>
    <www.ApacheHttpdServer id="${hostsPath}/${hostTemplate.name}_${hostAddress}/httpd">
      <host ref="${hostsPath}/${hostTemplate.name}_${hostAddress}"/>
      <startCommand>sudo apachectl stop</startCommand>
      <startWaitTime>3</startWaitTime>
      <stopCommand>sudo apachectl stop</stopCommand>
      <stopWaitTime>3</stopWaitTime>
      <restartCommand>sudo apachectl restart</restartCommand>
      <restartWaitTime>10</restartWaitTime>
      <defaultDocumentRoot>/var/www</defaultDocumentRoot>
      <configurationFragmentDirectory>/etc/apache2/conf.d</configurationFragmentDirectory>
    </www.ApacheHttpdServer>
  </list>
</#escape>

Every ec2.HostTemplate CI provides a validateDescriptor control task which processes the Freemarker template, parses the resulting XML and reports errors if something is wrong. No actual changes are made to the repository during execution of this control task.

Please note that:

• EC2 hosts which you define here should be either ec2.SshHost or ec2.CifsHost.
• The ec2.SshHost or ec2.CifsHost in the template must contain the XML fragments for address, cloudId and template. These are needed for the proper functioning of the plugin.
• Since XML is being generated you have to make sure that values are properly encoded. You can achieve this by enclosing the template in <#escape x as x?xml>...</#escape>, or alternatively use ${exampleKey?xml}. See the Freemarker documentation for details.

Environment template

Host templates can be collected in an environment template (cloud.EnvironmentTemplate).

Analogous to the host template, the environment template also specifies a special property xmlDescriptor which describes the contents of the new environment.

Here is an example of an environment descriptor:

<#escape x as x?xml>
  <list>
    <cloud.Environment id="${environmentId}">
      <members>
        <#list hosts as h>
          <ci ref="${h.id}" />
          <#if h.name?starts_with("Apache")>
            <ci ref="${h.id}/httpd" />
          </#if>
        </#list>
      </members>
    </cloud.Environment>
  </list>
</#escape>

Please note that:

• You should always use <list> as a parent XML element even if you define only one CI;
• validateDescriptor task processes template with an empty set as a value of the hosts variable.
• It is possible to include other CIs in addition to the environment, such as dictionaries.
• Here as well, you need to pay attention to XML quoting.

Using the EC2 plugin

Please see the Cloud Pack manual for instructions on how to use the environment and host templates provided in the EC2 plugin.