Gradle plugin for Elastic Container Service (ECS) provisioning. This project was heavily inspired by docker-compose. Don't see a feature that you would really like to see in your environment? Create an issue. Pull requests are also welcome.
The AWS credentials are pulled from either environment variables or from a ~/.aws/credentials
file. Refer to Amazon's official documentation for more information.
Tested with Gradle versions 2.12+.
The following should be placed at the head of your build.gradle
file to include the plugin dependency into your Gradle project.
buildscript {
repositories {
jcenter()
}
dependencies {
classpath "com.n3integration:gradle-ecs-plugin:0.7.0"
}
}
apply plugin: 'aws-ecs'
If you are using the Security Token Service and have predefined roles, you can specify the role ARN as well as the STS endpoint (optional) and a session name (optional). The default values are displayed below.
ecs {
assumeRole {
endpoint = "sts.us-east-1.amazonaws.com"
roleArn = "arn:aws:iam::012345678901:role/Developer"
sessionName = "session"
}
}
Although the plugin takes care of setting up most of the infrastructure, it is assumed that the security groups and subnets already exist. When provisioning the ec2 instances, auto scaling groups are leveraged. This allows the infrastructure to be more resilient to failure, but requires additional infrastructure to respond to scaling events (e.g. CloudWatch Alarms bound to a Lambda service).
Although the current implementation does not configure an auto scaling policy, future revisions may. By default, the Amazon ECS-optimized AMI for the us-east-1 region is configured for new ec2 instances. If you are running in a region other than us-east-1, reference the following documentation to identify which optimized AMI is available for your region. Although you are not limited to the Amazon Linux AMIs, other Linux operating systems are supported on a best effort basis. RedHat variants (e.g. CentOS/RHEL) configurations have been tested against v7.x.
Additionally, t2.micro
ec2 instances are provisioned if an instanceType
is not specified. For environments that have policies in place to track ec2 instances, one or more tag
blocks can be defined.
ecs {
clusters {
dev {
region = "us-west-1"
instanceSettings {
ami = "ami-68106908"
securityGroups = ["sg-abcd1234"]
iamInstanceProfileArn = "arn:aws:iam::01234567890123:instance-profile/EcsDeveloper"
autoScaling {
min = 1
max = 1
subnetIds = ["subnet-abcd123"]
}
}
containers {
"dockercloud-hello-world" {
instances = 1
image = "dockercloud/hello-world"
ports = ["80:8080"]
}
}
}
test {
region = "us-east-1"
instanceSettings {
instanceType = "t2.small"
securityGroups = ["sg-1234abcd"]
iamInstanceProfileArn = "arn:aws:iam::01234567890123:instance-profile/EcsTester"
autoScaling {
min = 2
max = 4
subnetIds = ["subnet-123abcd", "subnet-234bcde"]
}
tag {
key = "meta"
value = "DO NOT DELETE"
}
}
containers {
"dockercloud-hello-world" {
cpu = 10
memory = 64
instances = 2
image = "dockercloud/hello-world"
ports = ["80:80"]
}
}
}
}
}
The following container properties are available:
- image
- The docker image. Required
- group
- Creates a logical group of containers. Optional
- hostname
- The container hostname. Optional
- instances
- The number of container instances to launch. Required
- cpu
- The amount of CPU to reserve for the container. Optional
- memory
- The amount of memory (in mb) to reserve for the container. Optional
- ports
- A list of port mappings (i.e. containerPort:hostPort). Optional
- entryPoint
- The container entry point. Optional
- cmd
- The container's default command. Optional
- links
- A list to zero or more container instances. Must be linked through a logical group. Optional
- environment
- A mapping of environment variables available to the container. Optional
The following task types are available.
- CreateCluster
- Up
- Scale
- Down
- DeleteCluster
Creates a new Elastic Container Service cluster. If an autoScaling
group is provided for the cluster, one or more ec2 instances are provisioned using the specified image
(or the default ECS-optimized AMI for the us-east-1 region) according to the autoScaling
definition. Additionally, a private key file – ~/.ecs/<cluster name>.pem
– is created for the cluster's ec2 instances. This key is reused when recreating a cluster, even after the cluster has been deleted. It must be manually removed from AWS. This task references named clusters defined within the ecs.clusters
block.
task createCluster(type: CreateCluster) {
cluster = "dev"
}
Registers and starts the containers associated with the task's cluster
. This task references named clusters defined within the ecs.clusters
block if the container is left unspecified.
task up(type: Up) {
cluster = "dev"
}
task dbUp(type: Up) {
cluster = "dev"
container {
name = "redis"
image = "redis"
instances = 1
ports = ["6379:6379"]
}
}
Scales the number of running containers with a cluster
. This task applies only to a single container.
task scale2x(type: Scale) {
cluster = "dev"
container {
name = "dockercloud-hello-world"
instances = 2
}
}
Unregisters and terminates the containers associated with the task's cluster
. This task references named clusters defined within the ecs.clusters
block if the container is left unspecified.
task down(type: Down) {
cluster = "dev"
}
task dbDown(type: Up) {
cluster = "dev"
container {
name = "redis"
}
}
Deletes an existing EC2 Container Service cluster. This task references named clusters defined within the ecs.clusters
block. If an autoScaling
group is defined for the cluster, it's associated ec2 instances will be terminated.
task deleteCluster(type: DeleteCluster) {
cluster = "dev"
}