Creating a Staging Environment – Customizing AWS Elastic Beanstalk

In this post we shall create a new AWS Elastic Beanstalk environment, not using the Amazon’s Elastic Beanstalk console but by using a bash script file. Amazon’s console is convenient and quite easy to use. But for a serious production website we cannot be manually providing all the required input to launch a new Beanstalk environment.The script staging-create.sh is used to create a new staging environment. The idea is to provide all the required input, specify the environment name in a particular format and choose the Beanstalk CNAME for the environment. When the Beanstalk creates the new environment and deploys the application then our main setup script app-setup.sh gets executed on that new EC2 instance. If the CNAME chosen is myAppName-staging then the application should become available at myAppName-staging.elasticbeanstalk.com. If using Route53 then the main setup script would ensure that the application also becomes available at myAppName-staging.myDomainName.com and the leader EC2 instance becomes available at ec2.myAppName-staging.myDomainName.com.

Let us have our directory structure and you should be hearing the sound of life sprouting in the “deployment” directory.

Let us get into the details of staging-create.sh. The most important point with this script is it makes use of the configuration data file beanstalk-configuration.txt which is a JSON file and is located in our “data” directory. The command elastic-beanstalk-create-environment is used to create the new environment and using the option “-f configuration-file-name“, we use the configurations specified in our configuration file overriding some of the default values. Please note that our configuration file does not provide values for all the options. Instead it provides only those that we intend to override. For all other options we use the values provided by the solution stack specified for the “-s” option. Also please observe that we do not have to provide the actual AWS credentials and the real values would get set by our main setup script during the deployment.

Here are the contents of beanstalk-configuration.txt.

[
    {
        "Namespace": "aws:autoscaling:launchconfiguration", 
        "OptionName": "InstanceType", 
        "ResourceName": null, 
        "Value": "t1.micro"
    }, 
    {
        "Namespace": "aws:autoscaling:launchconfiguration", 
        "OptionName": "SecurityGroups", 
        "ResourceName": "AWSEBAutoScalingLaunchConfiguration", 
        "Value": "ec2-mySecgroup"
    }, 
    {
        "Namespace": "aws:autoscaling:launchconfiguration", 
        "OptionName": "EC2KeyName", 
        "ResourceName": "AWSEBAutoScalingLaunchConfiguration", 
        "Value": "myKeyPairName"
    }, 
    {
        "Namespace": "aws:elasticbeanstalk:application:environment",
        "OptionName": "AWS_ACCESS_KEY_ID",
        "ResourceName": null,
        "Value": "AWS_ACCESS_KEY_ID"
    },
    {
        "Namespace": "aws:elasticbeanstalk:application:environment",
        "OptionName": "AWS_SECRET_KEY",
        "ResourceName": null,
        "Value": "AWS_SECRET_KEY"
    },
    {
        "Namespace": "aws:elasticbeanstalk:hostmanager", 
        "OptionName": "LogPublicationControl", 
        "ResourceName": null, 
        "Value": "false"
    }, 
    {
        "Namespace": "aws:elb:loadbalancer", 
        "OptionName": "LoadBalancerHTTPSPort", 
        "ResourceName": "AWSEBLoadBalancer", 
        "Value": "OFF"
    }, 
    {
        "Namespace": "aws:elb:loadbalancer", 
        "OptionName": "SSLCertificateId", 
        "ResourceName": "AWSEBLoadBalancer", 
        "Value": null
    }, 
    {
        "Namespace": "aws:elb:policies", 
        "OptionName": "Stickiness Policy", 
        "ResourceName": "AWSEBLoadBalancer", 
        "Value": "true"
    }, 
    {
        "Namespace": "aws:elb:policies", 
        "OptionName": "Stickiness Cookie Expiration", 
        "ResourceName": "AWSEBLoadBalancer", 
        "Value": "1800"
    }, 
    {
        "Namespace": "aws:elb:healthcheck", 
        "OptionName": "Interval", 
        "ResourceName": "AWSEBLoadBalancer", 
        "Value": "30"
    }, 
    {
        "Namespace": "aws:elb:healthcheck", 
        "OptionName": "Timeout", 
        "ResourceName": "AWSEBLoadBalancer", 
        "Value": "5"
    }, 
    {
        "Namespace": "aws:elasticbeanstalk:application", 
        "OptionName": "Application Healthcheck URL", 
        "ResourceName": "AWSEBLoadBalancer", 
        "Value": "/myHealthCheck.html"
    }, 
    {
        "Namespace": "aws:autoscaling:asg", 
        "OptionName": "MaxSize", 
        "ResourceName": "AWSEBAutoScalingGroup", 
        "Value": "1"
    }, 
    {
        "Namespace": "aws:autoscaling:asg", 
        "OptionName": "MinSize", 
        "ResourceName": "AWSEBAutoScalingGroup", 
        "Value": "1"
    }, 
    {
        "Namespace": "aws:elasticbeanstalk:sns:topics", 
        "OptionName": "Notification Endpoint", 
        "ResourceName": null, 
        "Value": "dev-team@myDomain.com"
    } 
]

At hudku.com we use the solution stack “64bit Amazon Linux running Tomcat 7“. The command elastic-beanstalk-list-available-solution-stacks can be used to get the list of all the available solution stacks and you can use the one you are interested in.

To mention the few main options that we try to set are the type of EC2 instance, the name of the EC2 security group, the security key pair we intend to use for logging on to the EC2 instance using ssh, the minimum and maximum size of Auto Scaling group, Load Balancer health check URL, notification email id, etc.

By default, Beanstalk creates and uses its own EC2 security group. In addition to that we want our EC2 security group to be added so that whatever settings we have specified to our security group also come into force. For example this is useful if we need to access an Amazon RDS instance where we have set the appropriate permissions for our security group.

Next the script expects the source bundle we intend to deploy to be present in a particular location. For example the script aws-credentials-setup.sh expected the file secrets.zip in the directory “secrets” created under the deployment directory of the Amazon S3 private bucket. The deployment directory and the name of the private bucket were provided by the variables ELASTICBEANSTALK_APP_PRIVATE_S3_BUCKET and ELASTICBEANSTALK_APP_DEPLOY_DIR specified in the file “.elastic-beanstalk-app“.

In the same way this script expects the directory “war” to be present under the deployment directory and it is expected to contain a file with “.war” extension. There should be only one such file, otherwise the script cannot make up its mind on which file to deploy, becomes tipsy but quits before doing anything nasty.

The history or the versioning of source bundles is conveniently provided by Beanstalk and hence we do not have to worry about it.

The script obtains the name of the only war file present in the directory and also its creation timestamp. We use the current date-time for specifying the name of the new environment to be created.

As we need to specify unique names for the application label and the environment name, using the timestamp of the source bundle and the current date-time, we can guarantee the uniqueness as well as leave ourselves some audit trail on which source bundle is being used and when exactly we created the beanstalk environment.

Next the script checks using elastic-beanstalk-describe-application-versions to see whether any application version with the same label exists and checks further to see if it is being used in any beanstalk environment. If so, then the script pauses with a warning message.

This is just a simple check to ensure that we are not trying to repeat the creation of an environment or we have not forgotten to upload the new source bundle before trying to create the environment or to let ourselves know in case if it happened to be one of those rare days where we might have had beer one too many.

But it is quite possible that a development environment could be running the same version of the application and we are trying to now launch a staging environment in which case we could answer “Yes” to the script’s prompt and proceed further.

If it is a new source bundle then the script copies the source bundle from the deployment directory of our private Amazon S3 bucket to the S3 bucket used by Elastic Beanstalk. Then using the command elastic-beanstalk-create-application-version a new application version is created. These two steps are skipped if the application version has been created already.

Then the script executes elastic-beanstalk-create-environment to create the new beanstalk environment. We try to supply a CNAME for example, myAppName-staging if it is not already in use. For staging, we are not supposed to have more than one environment, but in case of development environment it might be possible that an environment already exists and we are trying to create another development environment.

If the script is successful then the new beanstalk environment would get created and the new version of the application that got deployed would be waiting to get tested. In the next post let us discuss the script that terminates an environment.

If you do not have time to leave your comments then do not worry. We shall try to read and understand the unwritten words. But may be you could consider moving the mouse cursor over those social buttons and clicking them. It is just a humble request and I shall promise that those buttons will not take you to any kind of donations page.

Here is the source code of staging-create.sh.

#!/bin/bash


# Execute "export DEBUG=1" to debug this script.
# Set value to 2 to debug this script and the scripts called within this script.
# Set value to 3,4,5 and so on to increase the nesting level of the scripts to be debugged.
[[ $DEBUG -gt 0 ]] && set -x; export DEBUG=$(($DEBUG - 1))


#
# Creates a new Elastic Beanstalk Staging environment
#


# include all the utility scripts
source $ELASTICBEANSTALK_APP_SCRIPT_DIR/include/include.sh


display_usage()
{
    echo -e "\nUsage: $0 [beanstalk-config-file-name]\n"
}

# Check the argument count
if ([ $# -gt 1 ]) then
    display_usage
    exit 2
fi


# Use the default config file and CNAME if not supplied
fileBeanstalkConfig=$ELASTICBEANSTALK_APP_DATA_DIR/beanstalk-configuration.txt
envCNAME="${ELASTICBEANSTALK_APP_NAME}_staging"

# If parameter is supplied then alter the default values
if ([ ! -z "$1" ]) then
    fileBeanstalkConfig=$1
    envCNAME="${ELASTICBEANSTALK_APP_NAME}-dev"
fi

# Check if the beanstalk configuration file exists
if ([ ! -f $fileBeanstalkConfig ]) then
    echo "Error: Beanstalk configuration file $fileBeanstalkConfig does not exist."
    exit 1
fi


warFileDirInPrivateBucket=$ELASTICBEANSTALK_APP_PRIVATE_S3_BUCKET/$ELASTICBEANSTALK_APP_DEPLOY_DIR/war

if ([ $(s3cmd ls s3://$warFileDirInPrivateBucket/ | grep "\.war" | wc -l) -gt 1 ]) then
    echo "Error: Found more than one war file in 's3://$warFileDirInPrivateBucket/'"
    echo -e "Files found are\n$(s3cmd ls s3://$warFileDirInPrivateBucket/ | grep "\.war")"
    exit 1
fi

warFileInfo=$(s3cmd ls s3://$warFileDirInPrivateBucket/ | grep "\.war")
if ([ -z "$warFileInfo" ]) then
    echo "Error: Could not find war files in 's3://$warFileDirInPrivateBucket/'"
    exit 1
fi

warFileName=$(echo ${warFileInfo} | awk '{print $4}' | sed "s|^s3:.*/||g")

# Get the UTC datetime of war file
warFileDateTime=$(echo ${warFileInfo} | awk '{print $1," ",$2}')

# Convert datetime in UTC to IST which is what gets displayed in our S3 console
warFileDateTime=$(date +'%Y%m%d-%H%M' -d "${warFileDateTime} -05:30")


# Use the current datetime to be used in the environment name
envDateTime=$(date +'%Y-%m-%d %H:%M')
envDateTime=$(date +'%Y%m%d-%H%M' -d "${envDateTime} -05:30")


filename=$(basename "$warFileName")
extension="${filename##*.}"
filename="${filename%.*}"

# Make version name using file name and datetime
appNewVersionFileName="${filename}-${warFileDateTime}.${extension}"

# Check if the application version has already been created
lblAppNewVersion=$(elastic-beanstalk-describe-application-versions -l lbl_${appNewVersionFileName} | grep -o lbl_${appNewVersionFileName})
if ([ ! -z "$lblAppNewVersion" ]) then

    # Check if this war file is already deployed in some environment
    existingURL=$($ELASTICBEANSTALK_APP_SCRIPT_DIR/util/elastic-beanstalk-get-elb-url-from-app-version.sh $lblAppNewVersion)
    if ([ ! -z "$existingURL" ]) then
        echo "WARNING: The war file ${warFileName} is already deployed at URL $existingURL"
        answer=$(promptDefaultNo)
        if ([ "$answer" == "n" ]) then
            exit 3
        fi
    fi
    
fi



# If the application version does not exist then copy the war file and create a new application version
if ([ -z "$lblAppNewVersion" ]) then
    # Copy war file to beanstalk bucket
    s3cmd --config=/root/.s3cfg cp s3://$warFileDirInPrivateBucket/$warFileName s3://${ELASTICBEANSTALK_S3_BUCKET}/$appNewVersionFileName

    # Create the application version from the copied war file
    elastic-beanstalk-create-application-version -a $ELASTICBEANSTALK_APP_NAME -l lbl_${appNewVersionFileName} -d desc_${appNewVersionFileName} -s ${ELASTICBEANSTALK_S3_BUCKET}/${appNewVersionFileName}
fi


# Try to supply CNAME to Beanstalk while creating the new environment
sCNAMEOption="-c $envCNAME"

# If CNAME is already in use then we cannot use it
ipCNAME=$(getIPOfURL "$envCNAME.elasticbeanstalk.com")
if ([ ! -z "$ipCNAME" ]) then
    sCNAMEOption=""
fi

# Launch the new environment
elastic-beanstalk-create-environment -a $ELASTICBEANSTALK_APP_NAME -l lbl_${appNewVersionFileName} -e env-${envDateTime} -s "64bit Amazon Linux running Tomcat 7" -f $fileBeanstalkConfig $sCNAMEOption