SBT plugin providing support for publishing Docker applications to Amazon Elastic Beanstalk.
Supports AWS Dockerrun file versions 1 and 2.
Version 2 can be used to expose multiple service ports for a single or multi container image.
Add the following to you project/plugins.sbt
file
addSbtPlugin("com.dbrsn" % "sbt-elastic-beanstalk" % "0.3.1")
See ElasticBeanstalkPlugin.scala for configuration options and default values.
The plugin provides the following tasks
ebsStageDockerrunFiles
- stages dockerrun files toproject-name/target/aws/
ebsPublishDockerrunFiles
- publishes dockerrun files to S3ebsPublishAppVersions
- publish current application version to elasticbeanstalk
Use this task to locally inspect the dockerrun files to be published to AWS.
Dockerrun files will be written to project-name/target/aws
This task publishes the dockerrun files to the configured S3 bucket.
This task associates the application version with the dockerrun files which then makes them available to elastic beanstalk for depoloyment.
This step depends on ebsPublishDockerrunFiles
which must be run first.
Dockerrun files contain JSON formatted configuration, and are specific to Elastic Beanstalk. They describe how to deploy a docker container as an Elastic Beanstalk application.
Version 1 should typically be used to define single container docker applications that expose a single port.
Single container applications that need to expose multiple ports should use the V2 specification instead.
See AWS Dockerrun V1 for further information regarding the V1 format.
Version 2 defines applications with
- one or more docker containers
- more than one service port
By default the plugin supports a single container docker application exposing multiple service ports.
Version 2 includes a mandatory container memory allocation which is set automatically according to the AWS Instance type.
If your environments all use the same EC2 instance type you can configure this as follows
ebsContainerMemory := 1024, // Memory expressed in MiB
ebsEC2InstanceTypes := Set.empty // Instance types can be omitted
Note - memory must be set to half the RAM for your instance. See A note about memory below.
You can also follow the steps for multiple instance types below and configure a single instance type instead.
If you deploy to environments with multiple instance types you can configure
this via the ebsEC2InstanceTypes
property as follows
ebsEC2InstanceTypes := Set(T2.Micro, T2.Small, T2.Medium, T2.Large)
Note - the
ebsContainerMemory
property will be ignored and predefined memory settings defined in EC2InstanceTypes will be used instead.
A dockerrun file will be generated for each instance type you declare with
filenames of the form appVersion-instanceType.json
. You can verify this
locally by running the ebsStageDockerrunFiles
task.
Example list of dockerrun files for the instance types configured above
./onboarding-service/target/aws/0.1.36-t2.large.json
./onboarding-service/target/aws/0.1.36-t2.medium.json
./onboarding-service/target/aws/0.1.36-t2.micro.json
./onboarding-service/target/aws/0.1.36-t2.small.json
Sample dockerrun file for an application exposing 3 service ports running on a t2 small instance.
{
"AWSEBDockerrunVersion": 2,
"authentication": {
"bucket": "ovo-docker-apps",
"key": ".dockercfg"
},
"containerDefinitions": [
{
"name": "onboarding-service",
"image": "ovotech/onboarding-service:0.1.36",
"memory": 1024,
"essential": true,
"portMappings": [
{
"hostPort": 80,
"containerPort": 8080
},
{
"hostPort": 8081,
"containerPort": 8081
},
{
"hostPort": 2551,
"containerPort": 2551
}
]
}
]
}
A note about memory
In the example above we see that memory is set to 1024MiB. However a T2 Small instance has 2048MiB.
The plugin must set the memory value here to half the available amount because this value is passed to the docker run command via the -m option. By default docker will set the cgroup configuration value
memory.memsw.limit_in_bytes
to double the value passed in via the -m parameter.For this reason we must specify half the amount we actually want to allocate.
The plugin uses memory values defined in EC2InstanceTypes which assume that a single application wishes to be allocated all memory available on a given instance.
Refer to links at the end of this README for further information.
See AWS Dockerrun V2 for further information regarding the V2 format.