aws-cdk-fargate-resources
This is a small helper library for typescript aws-cdk projects which defines all of the resources sizes for Fargate container instances, in a manner which can be typed checked statically at compile time. It also provides some helper methods for dividing those resources between containers within a task.
Installation
$ npm i @mhoc/aws-cdk-fargate-resources
Usage
In a construct:
import { FargateResources } from "@mhoc/aws-cdk-fargate-resources";
export interface {
resources: FargateResources;
}
export class MyConstruct extends cdk.Construct {
constructor(scope: cdk.Construct, id: string, props: MyConstructProps) {
super(scope, id);
const { resources } = props;
// proportions can be calculated by simple percentages, like so.
// this method always rounds the resulting values down to the nearest whole number.
const taskDef1 = new ecs.TaskDefinition(this, "TaskDefinition", {
cpu: resources.cpu.all,
memory: resources.memory.all,
containers: [
// maybe the first container wants 90%
{ cpu: resources.cpu.take(0.9), memory: resources.memory.take(0.9), /* ... */ },
// and the second container, 10%
{ cpu: resources.cpu.take(0.1), memory: reosurces.memory.take(0.1), /* ... */ },
// if the number provided is 1 or above, its treated as an absolute value, not a proportion.
// in other words, it just returns back the value you pass in. which isn't too valuable,
// except, it will runtime error if you try to specify an absolute value more-than the
// total resources allocated; something the cdk will already do after the stack is submitted
// to cloudformation, but at least this will do it before!
],
// ...
});
// alternativesly, the 'pie' methods can be used, which is more stateful; like divying up a pie
// to each container. this allows us to runtime-error not only if a single container asks for
// more resources than are totally available, but if all the containers collectively ask for
// more resources.
const cpuPie = resources.cpu.pie();
const memoryPie = resources.memory.pie();
const taskDef2 = new ecs.TaskDefinition(this, "TaskDefinition", {
cpu: resources.cpu.all,
memory: resources.memory.all,
containers: [
// if the number is less-than 1, its treated as a proportion, just like the .take() method
// above.
{ cpu: cpuPie.take(0.9), memory: memoryPie.take(0.9), /* ... */ },
// if the number is above 1, its treated as an absolute value; the same units
// CloudFormation/cdk exepcts. mvCPU cores for CPU, and megabytes for memory.
{ cpu: cpuPie.take(100), memory: memoryPie.take(128), /* ... */ },
// the unique quality of the pie methods is, if you try to take too much, they'll runtime
// error, before the stack is even submitted to cloudformation; fail fast!
{ cpu: cpuPie.take(0.7), memory: memoryPie.take(0.2), /* ... */ },
// Runtime Error: not enough pie!
// a .rest() method is also available, to simply give the final container in your list
// whatever resources are left over. if you're using proportions, sometimes the rounding can
// cause 1 or 2 resource units to be "left behind", even if your proportions add up to 1;
// this ensures every last drop of resources is used!
{ cpu: cpuPie.rest(), memory: memoryPie.rest(), /* ... */ },
// .rest() does not error if the remaining pie is 0; so, you can compose these methods to
// ensure the final container always gets at-least a certain amount of resources, plus
// whatever is left over.
{ cpu: cpuPie.take(100) + cpuPie.rest(), memory: memoryPie.take(256) + memoryPie.rest() }
],
// ...
});
}
}
And instantiating that construct:
import { FargateResources } from "@mhoc/aws-cdk-fargate-resources";
const new MyConstruct(app, "MyConstruct", {
// the best way to instantiate it: statically. this library exports static readonly members for
// every valid fargate configuration AWS offers. at least, since the last time the library was
// published :)
resources: FargateResources.cpu500m.mem2g,
// alternatively, you can fall back to the constructor
resources: new FargateResources(500, 2048),
});