Beanstalk

This document contains information about the Beanstalk service supported in Handel. This Handel service provisions an Elastic Beanstalk application, which consists of an auto-scaling group fronted by an Elastic Load Balancer.

Service Limitations

No WAR support

This Handel Beanstalk service does not yet support Java WAR stack types. Support is planned to be added in the near future.

Limited Tagging Support

Attention

CloudFormation doesn’t allow Beanstalk tags to be modified after initial environment creation. Beanstalk just recently added support for updating tags, but CloudFormation doesn’t yet support that feature change for Beanstalk.

Until this support is added, if you try to modify your tags element after your environment is created, your CloudFormation stack will fail to update.

Parameters

Parameter Type Required Default Description
type string Yes   This must always be beanstalk for this service type.
path_to_code string Yes   The location of your code to upload to Beanstalk. This can be a directory (which will be zipped up) or a single file (such as a deployable Java WAR file). If this points to a directory containing a Dockerrun.aws.json file or points to a Dockerrun.aws.json file then the following Dockerrun.aws.json Replacement Tags will be substituted.
solution_stack string Yes   The ElasticBeanstalk solution stack you wish to use. This determines what AMI your application runs on. See Elastic Beanstalk Supported Platforms for the list of solution stacks.
description string No Application. The description of the application.
key_name string No None The name of the EC2 keypair to use for SSH access to the instance.
auto_scaling AutoScaling No   The configuration to use for scaling up and down
instance_type string No t2.micro The EC2 instance type on which your application will run.
health_check_url string No / The URL the ELB should use to check the health of your application.
routing Routing No   The Routing element details what kind of routing you want to your Beanstalk service
environment_variables EnvironmentVariables No   Any user-specified environment variables to inject in the application.
tags Resource Tags No   Any tags you want to apply to your Beanstalk environment

Dockerrun.aws.json Replacement Tags

Tag Description
<aws_account_id> The account_id from the account config file specified at deployment.
<aws_region> The region from the account config file specified at deployment.
<handel_app_name> The name of the Handel application
<handel_environment_name> The name of the Handel environment that the deployed service is contained in.
<handel_service_name> The name of the Handel service being deployed.

AutoScaling

The auto_scaling section is defined by the following schema:

auto_scaling: # Optional
  min_instances: <integer> # Optional. Default: 1
  max_instances: <integer> # Optional. Default: 1
  scaling_policies: # Optional
  - type: <up|down>
    adjustment:
      type: <string> # Optional. Default: 'ChangeInCapacity'.
      value: <number> # Required
      cooldown: <number> # Optional. Default: 300.
    alarm:
      namespace: <string> # Optional. Default: 'AWS/EC2'
      dimensions: # Optional. Default: Your auto-scaling group dimensions.
        <string>: <string>
      metric_name: <string> # Required
      statistic: <string> # Optional. Default: 'Average'
      comparison_operator: <string> # Required
      threshold: <number> # Required
      period: <number> # Optional. Default: 300
      evaluation_periods: <number> # Optional. Default: 5

Tip

Auto-scaling in AWS is based off the CloudWatch service. Configuring auto-scaling can be a bit daunting at first if you haven’t used CloudWatch metrics or alarms.

See the below Example Handel Files section for some examples of configuring auto-scaling.

EnvironmentVariables

The EnvironmentVariables element is defined by the following schema:

environment_variables:
  <YOUR_ENV_NAME>: <your_env_value>

<YOUR_ENV_NAME> is a string that will be the name of the injected environment variable. <your_env_value> is its value. You may specify an arbitrary number of environment variables in this section.

Routing

The Routing element is defined by the following schema:

routing:
  type: <http|https>
  https_certificate: <string> # Required if you select https as the routing type
  dns_names:
   - <string> # Optional

The dns_names section creates one or more dns names that point to this load balancer. See DNS Records for more.

Example Handel Files

Simple Beanstalk Service

This Handel file shows a simply-configured Beanstalk service with most of the defaults intact:

version: 1

name: my-beanstalk-app

environments:
  dev:
    webapp:
      type: beanstalk
      path_to_code: .
      solution_stack: 64bit Amazon Linux 2016.09 v4.0.1 running Node.js
      environment_variables:
        MY_INJECTED_VAR: myValue

Auto-Scaling On Service CPU Utilization

This Handel file shows a Beanstalk service auto-scaling on its own CPU Utilization metric. Note that in the alarm section you can leave off things like namespace and dimensions and it will default to your Beanstalk service for those values:

version: 1

name: beanstalk-example

environments:
  dev:
    webapp:
      type: beanstalk
      path_to_code: .
      solution_stack: 64bit Amazon Linux 2017.03 v4.1.0 running Node.js
      auto_scaling:
        min_instances: 1
        max_instances: 2
        scaling_policies:
        - type: up
          adjustment:
            value: 1
            cooldown: 60
          alarm:
            metric_name: CPUUtilization
            comparison_operator: GreaterThanThreshold
            threshold: 70
            period: 60
        - type: down
          adjustment:
            value: 1
            cooldown: 60
          alarm:
            metric_name: CPUUtilization
            comparison_operator: LessThanThreshold
            threshold: 30
            period: 60

Auto-Scaling On Queue Size

This Handel file shows a Beanstalk service scaling off the size of a queue it consumes:

version: 1

name:  my-beanstalk-app

environments:
  dev:
    webapp:
      type: beanstalk
      path_to_code: .
      solution_stack: 64bit Amazon Linux 2017.03 v4.1.0 running Node.js
      auto_scaling:
        min_instances: 1
        max_instances: 2
        scaling_policies:
        - type: up
          adjustment:
            value: 1
          alarm:
            namespace: AWS/SQS
            dimensions:
              QueueName: my-beanstalk-app-dev-queue-sqs
            metric_name: ApproximateNumberOfMessagesVisible
            comparison_operator: GreaterThanThreshold
            threshold: 2000
        - type: down
          adjustment:
            value: 1
          alarm:
            namespace: AWS/SQS
            dimensions:
              QueueName: my-beanstalk-appe-dev-queue-sqs
            metric_name: ApproximateNumberOfMessagesVisible
            comparison_operator: LessThanThreshold
            threshold: 100
      dependencies:
      - queue
    queue:
      type: sqs

Depending on this service

The Beanstalk service cannot be referenced as a dependency for another Handel service.

Events produced by this service

The Beanstalk service does not produce events for other Handel services to consume.

Events consumed by this service

The Beanstalk service does not consume events from other Handel services.