Amazon ECS Concepts
External
Internal
Overview
Amazon Elastic Container Service (ECS) deploys Docker containers on a scalable cluster. The Docker images to be deployed typically come from Amazon ECR.
Launch Type
EC2 Launch Type
The EC2 launch type allows running a containerized applications on a cluster of Amazon EC2 instances.
Fargate Launch Type
The Fargate launch type allows running a containerized application without the need to provision and manage the backend infrastructure. It only requires registering a task definition. When that is available, Fargate launches the container.
Container
A container, in this context, is a Docker container, concept explained at length here:
Cluster
An Amazon ECS cluster is a regional, logical grouping of tasks and services. If the tasks or services in question use the EC2 launch type, the cluster is also a grouping of container instances - what does this mean? A default cluster is always available, but multiple clusters can be created in an account to keep your resources separate. A cluster cannot span regions. A cluster may contain task with both Fargate and EC2 launch types.
Relationship between a Cluster and a VPC
When a cluster is created, it has no explicit relationship with any VPC, it just "exists" in a region of an AWS account:
Cluster:
Type: AWS::ECS::Cluster
Properties:
ClusterName: ...
The relationship is defined as service level, which defines a dependency on a specific cluster and on a list of subnets, where the containers defined by tasks will connect to:
Service:
Type: AWS::ECS::Service
Properties:
ServiceName: ...
TaskDefinition: ...
Cluster: <cluster-name>
NetworkConfiguration:
AwsvpcConfiguration:
...
Subnets:
- <subnet-id-1>
- <subnet-id-2>
- ...
A subnet is a partition of VPC. This is how the relationship to a VPC is defined.
Cluster Configuration
Cluster Name
Must be unique within a region. If a name is not explicitly specified, one will be generated.
Cluster VPC
The relationship with a VPC is defined indirectly, via a service, as described in the "Relationship between a Cluster and a VPC" section.
Cluster Subnets
The relationship with subnets is defined indirectly, via a service, as described in the "Relationship between a Cluster and a VPC" section.
Cluster Operations
Task
An Amazon ECS task is a running instance of a container. A running task listens on ports, generates logs, and hopefully does useful work. Running tasks are created based on a task definition and are usually started by a service. However, a task can be manually run (Amazon ECS Console → Task Definitions → Actions → Run Task) after specifying the cluster, the number of tasks, the VPC and the subnet, which is equivalent with declaring a ephemeral service. The Amazon ECS task is equivalent with a Kubernetes pod, as multiple container definitions can be declared as part of the task definition.
Running Task
A running task is based on a task definition and it has an unique ID (e.g. e822d0018c324c47a2001e8ea6a76d4f). The running task has associated time statistics, such as "Created at" and "Started at". Also, stdout content generated while the task is running is available as Amazon ECS Console → Cluster → cluster-name → Tasks → task-id → Logs. Every time the task is started, it gets a new private IP, and if it was configured with one, a new public IP.
A running task may be started by a service. When a task has been started by a service, the task could be restarted (re-deployed) by navigating in console to the service, selecting the task, selecting the task in question and then "Stop"-ing it. A warning will pop up, saying that the task has been started by a service, but it can be safely stopped: the service will start a replacement. However, this is normally not necessary, the service detects failed tasks and starts new ones automatically.
Consolidate with Deployments.
Stopped Task
A list of stopped task can be accessed from the ECS Console → cluster-name → service-name → Tasks → Stopped.
Task Definition
An Amazon ECS task definition is a blueprint, or a configuration, for an application, and describes one or more containers through attributes. The task definition is used by a service to start tasks: a service declares a task definition name as part of its configuration:
ServiceDefinition:
Type: AWS::ECS::Service
Properties:
...
TaskDefinition: !Ref SomeTask
Task definitions exist outside clusters, and can be shared between clusters. Some task definition attributes are configured at the task level but the majority of attributes are configured per container. The task definition specifies the Docker image, how many containers to use for this task and the resource allocation for each container. To modify the task definition, a new revision must be created and then apply required changes to the task definition.
Revision
A new task revision is created when a task definition is modified. Each revision is identified by a revision number, and they are grouped together under the task definition's family.
Task Definition Configuration Elements
TaskDefinition:
Type: AWS::ECS::TaskDefinition
Properties:
Family: !Ref ApplicationName
RequiresCompatibilities: [ FARGATE ]
TaskRoleArn:
Fn::ImportValue: !Sub ${MicroworldName}-task-role-arn
ExecutionRoleArn:
Fn::ImportValue: !Sub ${MicroworldName}-task-execution-role-arn
NetworkMode: awsvpc
Cpu: '2048'
Memory: '4096'
ContainerDefinitions:
- Name: !Sub ${ApplicationName}-container
Cpu: '2048'
Memory: '4096'
Essential: 'true'
Environment:
- Name: SPRING_PROFILES_ACTIVE
Value: !Sub ${MicroworldName}-${EnvironmentName}-${ApplicationName}
- Name: SERVER_PORT
Value: !Ref ApplicationPort
Image: !Sub ${EcrRepositoryUri}:${CodebuildResolvedSourceVersion}
PortMappings:
- HostPort: !Ref ApplicationPort
ContainerPort: !Ref ApplicationPort
LogConfiguration:
LogDriver: awslogs
Options:
awslogs-group: !Sub /${MicroworldName}/${EnvironmentName}/${ApplicationName}
awslogs-region: !Sub ${AWS::Region}
awslogs-stream-prefix: task
Family
The family is a common name for multiple revisions of the same task definition, where each revision is specified by a revision number. It is referred to as "Task Definition Name" by the AWS Console or CloudFormation definition.
Compatibilities
The launch type used by the task. Currently, "FARGATE" and "EC2" are available as options.
Task Role
The task role is the IAM role that specifies a container's permissions at runtime. The task role allows the containers in the task to call the AWS APIs that are specified in its associated policies on the IAM user's behalf. If a task encounters permission problems, the task role is the first place to look. This is how a task role is created:
Task Execution Role
The task execution role is the IAM role that allows the containers in the task to pull container images, publish container logs to CloudWatch, upgrade the load balancer with the endpoint details of the containers, all on the IAM user's behalf. This is how a task execution role is created:
Network Mode
The Docker networking mode to use for the container in the task. Typically "awsvpc".
Task Memory
Expressed in MB. Also see container memory.
Task CPU
Expressed in millicores. Also see container CPU.
Container Definition
Multiple container definitions can be declared as part of the task definition, and this makes the task the equivalent of the Kubernetes pod. It makes sense to put multiple containers in the same Fargate task definition if containers share a common life cycle - they should be launched and terminated together, if containers are required to run on the same underlying host - they reference each over on a localhost port, or if containers share resources, such as data volumes.
Each container definition includes the following elements:
Container Name
The name of the container. Not to be confused with the image. This name will be used by the load balancers declared in the service definition to refer to this container.
Container Image
The name of the image to start a container. This string is passed directly to the Docker daemon. Images in the Docker Hub registry are available by default. Other repositories can also be specified using the <repository-url>/<image>:<tag> or <repository-url>/<image>@<digest> syntax.
Essential Flag
If the container is marked as "essential" and if that container fails or stops for any reason, all other containers that are part of the task are stopped. If the essential parameter of a container is marked as false, then its failure does not affect the rest of the containers in a task. If this parameter is omitted, a container is assumed to be essential. All tasks must have at least one essential container. If you have an application that is composed of multiple containers, you should group containers that are used for a common purpose into components, and separate the different components into multiple task definitions.
Container Memory
Also see task memory.
Container CPU
Also see task cpu.
Container Port Mappings
Container Environment
Container Log Configuration
An "awslogs-stream-prefix" is optional, if nothing is specified, the streams will be named container-name/3ad0d60e-193a-49e4-b004-5599134b067e
Task Definition Operations
Service
An Amazon ECS service allows running and maintain a specified number (the "desired count") of simultaneous instances of a task, created based on a task definition, in an ECS cluster. The service launches and maintains running tasks in the cluster. It detects stopped tasks and starts new ones to maintain the number of tasks specified in the service definition. If the number of tasks exceeds 1, a load balancer is required to distribute incoming traffic amongst sibling tasks. Unlike a task definition, a service only exists within a cluster, and cannot be shared between clusters. From this perspective, a service can be thought of as an instantiation context of a task, specifying the cluster, the VPC, subnet, security group, etc. An AWS ECS service is equivalent with a combination of a Kubernetes replication controller and a Kubernetes service, though the AWS service does not do the load balancing itself, it delegates it to a load balancer.
Service Configuration Elements
ServiceDefinition:
Type: AWS::ECS::Service
Properties:
ServiceName: !Sub ${MicroworldName}-${EnvironmentName}-${ApplicationName}
LaunchType: FARGATE
Cluster:
Fn::ImportValue: !Sub ${MicroworldName}-${EnvironmentName}-cluster-name
TaskDefinition: !Ref TaskDefinition
DesiredCount: 1
HealthCheckGracePeriodSeconds: 60
LoadBalancers:
- ContainerName: !Sub ${ApplicationName}-container
ContainerPort: !Ref ApplicationPort
TargetGroupArn: !Ref TargetGroup
NetworkConfiguration:
AwsvpcConfiguration:
AssignPublicIp: DISABLED
SecurityGroups:
- !Ref ServiceSecurityGroup
Subnets:
- Fn::ImportValue: !Sub ${MicroworldName}-${EnvironmentName}-subnet1-id
- Fn::ImportValue: !Sub ${MicroworldName}-${EnvironmentName}-subnet2-id
Service Name
Launch Type
It can be 'FARGATE' or 'EC2', for more details see Launch Type above.
Service Type
It ca be 'REPLICA' for a 'FARGATE' launch, or 'REPLICA' or 'DAEMON' an 'EC2' launch.
Cluster
Specifies the name of the cluster this service belongs to. A service cannot be shared among clusters, it belongs to a cluster and only one.
Task Definition
Specifies the task definition to be used while instantiating tasks for this service.
Desired Count
Health Check Grace Period
The health check grace period represents the period of time, in seconds, that the service should ignore unhealthy load balancing target health checks, container health checks, and Route 53 health checks after a task has first started. The configuration is only considered if the service is configured to use a load balancer. If tasks take a while to start and respond to health checks, a corresponding grace period should be specified. This grace period can prevent the ECS service scheduler from marking tasks as unhealthy and stopping them before they have time to come up. Also see Container Failure Detection.
Service Security Group
A security group is created to allow all public traffic to the service only on the container port specified. Security groups and network access can be further refined after the service creation.
The name of the security group can be changed at this stage, as well as the port configuration.
Service Load Balancing
Load balancing settings can only be configured on service creation. If the service is to be exposed as integration endpoint by the API Gateway, it needs a network load balancer.
Each load balancer declared in the service definition refers by name a container declared in a task definition. The value used as "ContainerName" must match the value of the container's name, as declared in the task definition.
Only one load balancer per service is supported.
TODO: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-load-balancing.html
Service Discovery and DNS
Updating existing services to configure service discovery for the first time or change the current configuration is not supported. Service discovery should be configured when the service is created.
If the service discovery was enabled for a service, the service's private IP address becomes resolvable as a internal DNS name in the namespace that was configured for the service. The DNS name is correctly resolved a newly-allocated IP address, should the backing task be restarted and get a new IP address.
Service Operations
Deployments
Consolidate with Running Tasks.
Rolling Update
A rolling update replaces the current version of the task in the service with a new version. To control the number of your service's tasks in the RUNNING state during a deployment, set the "minimum healthy percent" and "maxium healthy percent" values. This deployment configuration allows for AWS CLI command line redeployments.
Blue/Green Deployment
A blue/green deployment allows to verify a new version of the application before routing production traffic to it. Production traffic can be routed between new and old versions, closely monitor the deployment process, and quickly rollback a deployment if there is an issue.
Choosing a blue/green deployment for an ECS service will configure the service with a deployment controller of type "CODE_DEPLOY" - which means AWS CodeDeploy - and will also automatically create corresponding AWS CodeDeploy application and deployment group with default settings that can be updated later. This configuration is required if an (additional) AWS CodeDeploy deployment group is created for this service.
Container Failure Detection
See service health check grace period.
ECS Networking
CloudFormation
Auto Scaling
TODO