Amazon ECS Concepts

External

• https://docs.aws.amazon.com/AmazonECS/latest/developerguide
• Amazon ECS Application Architecture

Internal

• Amazon ECS

Overview

Amazon Elastic Container Service (ECS) is an AWS service to deploy and run Docker applications on a scalable cluster. ECS is the Amazon proprietary implementation of a generic infrastructure platform container cluster. The Docker images to be deployed typically come from Amazon ECR.

Launch Type

Amazon ECS Launch Types

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:

Docker Container

Cluster

Amazon ECS Clusters

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. The Amazon ECS Container Agent that manages containers and tasks on behalf of the cluster.

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

• Create a Cluster with Amazon Console
• Create a Cluster with CloudFormation

Amazon ECS Container Agent

Amazon ECS Container Agent

https://github.com/aws/amazon-ecs-agent

The Amazon ECS Container Agent is a component of Amazon ECS whose job is to manage containers on behalf of Amazon ECS. The ECS Container Agent is relevant for both Fargate end EC2 launch types. Containers use the Amazon ECS Container Agent to connect to the cluster. The agent is included in the ECS-optimized AMIs, but it can also be installed on any Amazon EC2 instance. The agent is also installed on the AWS managed infrastructure used for tasks using the Fargate launch type. In case of Fargate launch type-tasks, no additional configuration is needed by the agent.

Amazon ECS Task Metadata Endpoint

Amazon ECS Task Metadata Endpoint

The Amazon ECS container agent provides a method to retrieve various task metadata and Docker stats. This is referred to as the task metadata endpoint. The agent injects an environment variable called ECS_CONTAINER_METADATA_URI into each container in a task. The endpoint corresponding to the URI can be queried for task and container metadata. The following paths are available:

• ${ECS_CONTAINER_METADATA_URI} - this path returns metadata JSON for the container.
• ${ECS_CONTAINER_METADATA_URI}/task - this path returns metadata JSON for the task, including a list of the container IDs and names for all of the containers associated with the task. Also see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v3.html#task-metadata-endpoint-v3-response.
• ${ECS_CONTAINER_METADATA_URI}/stats - this path returns Docker stats JSON for the specific Docker container.
• ${ECS_CONTAINER_METADATA_URI}/task/stats - this path returns Docker stats JSON for all of the containers associated with the task.

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

Task Definitions

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

Task Definition 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

IAM Roles for Tasks

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. For more details on how authentication and authorization work inside a container see Authentication and Authorization inside a Container below.

This is how a task role is created:

Create an ECS Task Role

Task Execution Role

Task Execution IAM 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:

Create an ECS Task Execution Role

Network Mode

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

Container Defintions

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. If these considerations do not apply, containers should be defined in separate tasks so they can be scaled, provisioned, and deprovisioned separately.

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

• Create a Task Definition with Amazon Console
• Create a Task Definition with CloudFormation

Service

Service Reference

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

Service Definition Parameters

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

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.

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

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.

Elastic Load Balancing - Load Balancer Types

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.

Service Discovery Concepts

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

• Create a Service with Amazon Console
• Create a Service with CloudFormation

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

• Virtual Private Cloud (VPC)
• Subnet

CloudFormation

• CloudFormation Stack

Auto Scaling

TODO

Authentication and Authorization inside a Container

Also see Task Role above.