Vertx Deploy Logo

Introduction

Tooling to deploy Vert.X applications, generic artifacts and (application) configuration onto cloud based instances (Ec2).

Installation / Configuration

Docker

for deploy mod 3.0.5 docker run --net=[networkname] --name vertx-deploy msoute/vertx-deploy:3.0.5 for the latest docker run --net=[networkname] --name vertx-deploy msoute/vertx-deploy:devel

Installation.

Install as any other application with max 1 verticle instance. Init.d scripts are provided for Red Hat and debian based systems. install as vertx (debian|redhat.vertx) and vertx-deploy (debian|redhat.vertx.deploy). Place defaults in /etc/defaults/vertx and configure as needed.

The configured system user needs sudo access to the init.d vertx script and any (test) command. The user also needs write access to directories configured for artifacts

note Prior to Vert.x 3.2.1 a custom distribution needs to be used since the maven service factory depended on an older version of httpclient.

Configuration

{
    "vertx.home":"/opt/sw/vertx/current",
    "artifact.storage": "/opt/data/repo/",
    "http.authUser": "...",
    "http.authPass": "...",
    "maven.repo.uri": "...",
    "aws.region", "eu-west-1",
    "aws.as.register.maxduration":10,
}

Deploy configuration

Deploy artifacts.

The plugin uses the projects pom to determine what artifacts need to be deployed. There are three types of artifacts (in the order of deployment)

To instruct the plugin to deploy an artifact (application, artifact or config) it only needs to be added as a dependency to the pom.xml. The plugin ignores all dependencies specified in parent poms or transitive.

Vert.x Application artifact

...
<dependency>
    <groupId>[groupId]</groupId>
    <artifactId>[artifactId]</artifactId>
    <version>[version]</version>
</dependency>
...

Applications are started using the vert.x CLI start method. all non config or static artifacts are regarded as vert.x applications.

Config artifact

<dependency>
    <groupId>[groupId]</groupId>
    <artifactId>[artifactId]</artifactId>
    <version>[version]</version>
    <classifier>[classifier]</version>
    <type>config</type>
</dependency>

These artifacts will be unpacked to the location specified in artifact_context.xml (See appendix creating an artifact). Always before static artifacts or applications identified by type config

Static artifact

<dependency>
    <groupId>[groupId]</groupId>
    <artifactId>[artifactId]</artifactId>
    <version>[version]</version>
    <classifier>site</version>
    <type>zip</type>
</dependency>

These artifacts will be unpacked to the location specified in artifact_context.xml (See appendix creating an artifact). Always after config artifacts and before applications identified by classifier site

Maven Plugin Configuration

...
<plugin>
    <groupId>nl.jpoint.vertx-deploy-tools</groupId>
    <artifactId>vertx-deploy-maven-plugin</artifactId>
    <version>3.0.0-SNAPSHOT</version>
    <configuration>
        <region>eu-west-1</region>
        <credentialsId>credentials</credentialsId>
        <port>6789</port>
        <deployConfigurations>
            ...
        </deployConfigurations>
    </configuration>
</plugin>
...

DeployConfigurations

Multiple targets can be configured. The target configuration can be selected with -Ddeploy.target=

Default Deploy Configuration Options

Aws Configuration Options

Aws AutoScaling Configuration Options

CloudWatch metrics

Auto Scaling deploy strategies.

Aws OpsWorks Configuration Options

Mojos

General Mojo parameters

mvn deploy:deploy

The default mojo. Based on configuration it wil deploy to a set of configured instances, instances in an OpWorks layer or instances in an auto scaling group. When deploying to an OpsWorks based set of instances the deploy application can be configured to wait for every instance to come InService on an elb before continuing.

During deploys to an auto scaling group the plugin wil first try to deploy Standby instances and put those back into service. This can be overridden with ignoreInStandby

When an instance is put InStandby for deployment it wil decrement the desired capacity of the auto scaling group with 1. This can be overridden ( decrementDesiredCapacity ). Note that an auto scaling group will always try to conform to the configured desired amount i.e. it wil launch a new instance.

Note : During a deploy to an auto scaling group the deploy application temporarily suspends the following auto scaling policies : ScheduledActions , Terminate and ReplaceUnhealthy. These processes are resumed after the deploy finished (or fails). If the maven task is killed during the deploy those processes are not automatically. This can be fixed either by running a new deploy or with the AWS CLI

Note : The plugin assumes that a deploy is ready when an instance reaches the status InService on all elb's or when no elb's are attached in the auto scaling group. The default ELB health check does not guarantee any application to be ready and listening. A custom elb health-check needs to be configured.

Maven options :

mvn deploy:deploy-direct

Deploys to a single instance. For example when an instance comes online tools like puppet can instruct a remote Jenkins instance to schedule a build to deploy a set of modules to the newly created instance. This mojo ignores deploy.activeTarget

mvn deploy:deploy-single

Deploys a single artifact to a DeployTarget

mvn deploy-single-as

Deploys to an autoscaling group mvn target options (-D):

mvn deploy:as-enable

Mojo to add one instance to an as_group if current instances size equals 0.

Vert.X Module Configuration

Examples

Deploy to multiple instances in an auto-scaling group with ELB support.

The following target configuration wil deploy to all instances in the as-group autoscaling-group-id and check if each instance reached the inService status on the ELB's it is a member of. If the instance does not reach the inService status within 5 minutes the build wil fail and the remaining instances wil nog be updated

<deployConfiguration>
    <target>[target]</target>
    <testScope>false</testScope>
    <restart>true</restart>
    <elb>true</elb>
    <autoScaling>true</autoScaling>
    <autoScalingGroupId>autoscaling-group-id</autoScalingGroupId>
</deployConfiguration>

Creating (config) artifacts.

Artifacts other than vert.x applications can be constructed in a similar way by using the maven-assembly-plugin. These artifacts are extracted on the targeted instance. A config file in the artifact root dir (artifact_context.xml) instructs the application where and how to extract the artifact.

<?xml version="1.0"?>
<artifact>
    <baselocation>...</baselocation>
    <testCommand>...</testCommand>
    <restartCommand>...</restartCommand>
    <checkContent>true|false</checkContent>
</artifact>

Service Configuration files

During startup of a service a per service config file is read to overide / set per service config variables. The Directory in which these config files reside can be configured with config.location. The config files are matched by [groupId]:[artifactId] or [groupId]~[artifactId]. The config file is in default properties format.

If an config option exists it wil override the configured default.

Phone Home

Applications deployed through the deploy application should report to the deploy application if de deploy was successful or failed. All verticles can do this by sending a request to http://localhost:[port]/deploy/update?id=[id]&status=[ok|error]&errormessage=[message]

The deploy application adds an JVM property that indicates on what port the deploy application is running (vertxdeploy.port)

If an application reports an error the deploy wil fail, the same error is reported back to the maven pluging.

Auto(scaling)discover deploys

If autoscaling is setup the deploy application can try to auto-discover what needs to be deployed on initial run. In order to do this the maven plugin will store all needed data (version, scope) as a tag on the autoscaling group. The deploy application wil read these tags and create a deploy command.

deploy.as.properties

Typed deploys

Split deploys into artifact and application only deploys. TODO: More info

Comma separated list of build options that who's values are stored in order to execute an autodiscover deploy. i.e. If a build uses a propertie ${target.env} in its pom the resovled value needs to be persisted to an autoscaling group tag in order for an autodiscover deploy to deploy the exact same version.

AWS IAM Policy

The following AWS actions are needed for the maven plugin

    "autoscaling:CreateOrUpdateTags"
    "autoscaling:DescribeAutoScalingGroups"
    "autoscaling:DetachInstances"
    "autoscaling:ResumeProcesses"
    "autoscaling:SetDesiredCapacity"
    "autoscaling:SuspendProcesses"
    "autoscaling:UpdateAutoScalingGroup"
    "ec2:DescribeInstances"
    "elasticloadbalancing:DescribeInstanceHealth"

The following AWS actions are needed for the deploy applications

    "elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
    "elasticloadbalancing:DescribeInstanceHealth",
    "elasticloadbalancing:RegisterInstancesWithLoadBalancer",
    "elasticloadbalancing:DescribeLoadBalancers",
    "autoscaling:DescribeAutoScalingInstances",
    "autoscaling:DescribeLoadBalancers",
    "autoscaling:DescribeTags",
    "autoscaling:EnterStandby",
    "autoscaling:ExitStandby"

Changelog

3.8.5

3.5.5

3.5.4

3.5.3

3.5.1

3.5.0

3.5.1

3.5.0

3.3.3

3.3.2

3.5.0

3.3.1

3.3.0

3.2.4

3.2.3

3.2.2

3.2.1

3.2.0

3.1.0

3.0.5

3.0.4

3.0.3

3.0.2

3.0.1

3.0.0

1.2.1

1.2.0

Note Source level changed to 1.8

1.1.15

1.1.14

1.1.12