Skip to content

Gradle plugin for EC2 Container Service provisioning

License

Notifications You must be signed in to change notification settings

n3integration/gradle-ecs-plugin

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

29 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

gradle-ecs-plugin

Codeship Status for n3integration/gradle-ecs-plugin Download

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.

Usage

The AWS credentials are pulled from either environment variables or from a ~/.aws/credentials file. Refer to Amazon's official documentation for more information.

Prerequisites

Tested with Gradle versions 2.12+.

Project Configuration

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'

Security Token Service

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"		
	}
}

ECS Cluster Definitions

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"]
        }
      }
    }
  }
}

Container Definitions

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

Task Types

The following task types are available.

  1. CreateCluster
  2. Up
  3. Scale
  4. Down
  5. DeleteCluster

CreateCluster

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"
}

Up

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.

Entire Cluster
task up(type: Up) {
    cluster = "dev"
}
Single Container
task dbUp(type: Up) {
    cluster = "dev"
    container {
        name = "redis"
        image = "redis"
        instances = 1
        ports = ["6379:6379"]
    }		
}

Scale

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
    }
}

Down

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.

Entire Cluster
task down(type: Down) {
    cluster = "dev"
}
Single Container
task dbDown(type: Up) {
    cluster = "dev"
    container {
        name = "redis"
    }
}

DeleteCluster

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"
}