ecs_composex.ecs package


ecs_composex.ecs.docker_tools module

Docker compose integration related function, wrapping transformation to Container definition.

ecs_composex.ecs.docker_tools. find_closest_fargate_configuration ( cpu , ram , as_param_string = False ) [source]

Function to get the closest Fargate CPU / RAM Configuration out of a CPU and RAM combination.

  • cpu ( int ) – CPU count for the Task Definition

  • ram ( int ) – RAM in MB for the Task Definition

  • as_param_string ( bool ) – Returns the value as a CFN Fargate Configuration.


ecs_composex.ecs.docker_tools. find_closest_ram_config ( ram , ram_range ) [source]

Function to find the closest RAM configuration

  • ram ( int ) – amount of RAM we are trying to match up

  • ram_range ( list ) – List of possible values for Fargate


the closest amount of RAM.

Return type


ecs_composex.ecs.docker_tools. handle_bytes_units ( value , factor ) [source]

Function to handle KB use-case

ecs_composex.ecs.docker_tools. import_time_values_to_seconds ( time_string , as_tuple = False ) [source]

Function to parse strings with h/m/s

  • time_string ( str ) –

  • as_tuple ( bool ) – Whether or not return a tuple (hours, minutes, seconds)


The number of seconds or tuple of time breakdown as ints

Return type

int, tuple(int, int, int)

ecs_composex.ecs.docker_tools. set_memory_to_mb ( value ) [source]

Returns the value of MB. If no unit set, assuming MB :param value: the string value :rtype: int or Ref(AWS_NO_VALUE)

ecs_composex.ecs.ecs_cluster module

ecs_composex.ecs.ecs_cluster. add_ecs_cluster ( root_stack , settings ) [source]

Function to create the ECS Cluster.


cluster identifier

ecs_composex.ecs.ecs_cluster. define_cluster ( cluster_def ) [source]

Function to create the cluster from provided properties.


cluster_def ( dict ) –



Return type


ecs_composex.ecs.ecs_cluster. get_default_cluster_config ( ) [source]

Function to get the default defined ECS Cluster configuration



Return type


ecs_composex.ecs.ecs_cluster. import_from_x_aws_cluster ( compose_content ) [source]

Function to handle and override settings if x-aws-cluster is defined.




ecs_composex.ecs.ecs_cluster. lookup_ecs_cluster ( session , cluster_lookup ) [source]

Function to find the ECS Cluster.

  • session ( boto3.session.Session ) – Boto3 session to make API calls.

  • cluster_lookup – Cluster lookup definition.


ecs_composex.ecs.ecs_conditions module

Parameters relating to ECS.

This is a crucial part as all the titles, maked _T are string which are then used the same way across all imports, which gives consistency for CFN to use the same names, which it heavily relies onto.

You can change the names values so you like so long as you keep it Alphanumerical [a-zA-Z0-9]

ecs_composex.ecs.ecs_iam module

ecs_composex.ecs.ecs_iam. add_service_roles ( task_family ) [source]

Function to create the IAM roles for the ECS task


task_family ( ecs_composex.common.compose_services.ComposeFamily ) – The task family to add the roles to

ecs_composex.ecs.ecs_iam. define_service_containers ( service_template ) [source]

Function to set the containers list from the service_task definition object


service_template ( troposphere.Template ) – the task definition


list of containers

Return type


ecs_composex.ecs.ecs_params module

Parameters bound to ecs_composex.ecs This is a crucial part as all the titles, maked _T are string which are then used the same way across all imports, which gives consistency for CFN to use the same names, which it heavily relies onto.

You can change the names values so you like so long as you keep it [a-zA-Z0-9]

ecs_composex.ecs.ecs_params. get_import_service_group_id ( remote_service_name ) [source]

Function to return the ImportValue(Sub()) for given ecs_service name

ecs_composex.ecs.ecs_predefined_alarms module

Module to define well known / pre-defined alarms for ECS Services

ecs_composex.ecs.ecs_scaling module

Module to help generate target scaling policies for given alarms.

class ecs_composex.ecs.ecs_scaling. ServiceScaling ( services ) [source]

Bases: object

Class to group the configuration for Service scaling

defined = False
target_scaling_keys = ['CpuTarget', 'MemoryTarget', 'TgtTargetsCount']
ecs_composex.ecs.ecs_scaling. define_new_config ( config , key , new_config ) [source]
ecs_composex.ecs.ecs_scaling. define_step_adjustment ( pre_upper , ordered , cfn_steps ) [source]
ecs_composex.ecs.ecs_scaling. generate_alarm_scaling_out_policy ( service_name , service_template , scaling_def , scaling_source = None ) [source]

Function to create the scaling out policy based on steps

  • service_name ( str ) – The name of the service/family

  • service_template ( troposphere.Template ) –

  • scaling_def ( dict ) –

  • scaling_source ( str ) –


The scaling out policy

Return type


ecs_composex.ecs.ecs_scaling. generate_scaling_out_steps ( steps , target ) [source]

Function to generate the scaling steps

  • steps ( list ) –

  • target ( tropsphere.applicationautoscaling.ScalingTarget ) – The defined max in the Scalable Target


ecs_composex.ecs.ecs_scaling. handle_defined_target_scaling_props ( prop , config , key , new_config ) [source]
ecs_composex.ecs.ecs_scaling. handle_defined_x_aws_autoscaling ( configs , service ) [source]

Function to sort out existing or not x-aws-autoscaling in the deploy section


ecs_composex.ecs.ecs_scaling. handle_range ( config , key , new_range ) [source]

Function to handle Range.

ecs_composex.ecs.ecs_scaling. handle_target_scaling ( config , key , new_config ) [source]

Function to handle merge of target tracking config

ecs_composex.ecs.ecs_scaling. merge_family_services_scaling ( services ) [source]
ecs_composex.ecs.ecs_scaling. rectify_scaling_steps ( cfn_steps ) [source]

Function to rectify settings to avoid errors


cfn_steps ( list ) –

ecs_composex.ecs.ecs_scaling. reset_to_zero_policy ( service_name , service_template , scaling_def , scaling_source = None ) [source]

Defines a policy allowing to reset to 0 containers.

  • service_name

  • service_template

  • scaling_def ( dict ) –

  • scaling_source


ecs_composex.ecs.ecs_scaling. validate_steps_definition ( steps , unordered ) [source]

Validates that the steps definition is correct

  • steps ( list ) – list of step definitions

  • unordered ( list ) – list of steps, unordered.

ecs_composex.ecs.ecs_service module

Functions to build the ECS Service Definition

class ecs_composex.ecs.ecs_service. Service ( family , settings ) [source]

Bases: object

Class representing the service from the Docker compose file and translate it into AWS ECS Task Definition and Service.

  • links ( list ) – the links used for DependsOn of the service stack

  • dependencies ( list ) – list of services used for the DependsOn of the service stack

  • config ( ServiceConfig ) – The service configuration

  • task_definition ( troposphere.ecs.TaskDefinition ) – The service task definition for ECS

  • eips ( list<troposphere.ec2.EIP> ) – list of AWS EC2 EIPs which are used for the public NLB

  • service_attrs ( dict ) – Attributes defined to expand the troposphere.ecs.ServiceDefinition from prior settings.

generate_service_definition ( family , settings ) [source]

Function to generate the Service definition. This is the last step in defining the service, after all other settings have been prepared.

ecs_composex.ecs.ecs_service. add_service_default_sg ( template ) [source]

Adds a default security group for the microservice.

ecs_composex.ecs.ecs_service. add_service_to_map ( family , settings ) [source]

Method to create a new Service into CloudMap to represent the current service and add entry into the registry

ecs_composex.ecs.ecs_service. create_scalable_target ( family ) [source]

Method to automatically create a scalable target

ecs_composex.ecs.ecs_service. define_deployment_options ( family , settings , kwargs ) [source]

Function to define the DeploymentConfiguration


ecs_composex.ecs.ecs_service. define_placement_strategies ( ) [source]

Function to generate placement strategies. Defaults to spreading across all AZs


list of placement strategies

Return type


ecs_composex.ecs.ecs_service. define_public_mapping ( eips , azs ) [source]

Function to get the public mapping for NLB

  • eips ( list ( troposphere.ec2.EIP ) ) – list of EIPSs

  • azs ( list ) – list of AZs to created EIPs into



ecs_composex.ecs.ecs_service. define_service_ingress ( family , settings ) [source]

Function to define microservice ingress.

ecs_composex.ecs.ecs_service. define_tracking_target_configuration ( target_scaling_config , config_key ) [source]

Function to create the configuration for target tracking scaling

  • target_scaling_config ( dict ) –

  • config_key ( str ) –


ecs_composex.ecs.ecs_service. generate_service_template_outputs ( family ) [source]

Function to generate the Service template outputs

ecs_composex.ecs.ecs_service_config module

Module for the ServiceConfig Class which is used for Container, Task and Service definitions.

class ecs_composex.ecs.ecs_service_config. ServiceConfig ( family , settings ) [source]

Bases: object

Class specifically dealing with the configuration and settings of the ecs_service from how it was defined in the compose file

  • keys ( list ) – List of valid settings for a service in Docker compose syntax reference

  • service_config_keys ( list ) – list of extra configuration that apply to services.

  • UseCloudmap ( bool ) – Indicates whether or not the service will be added to the VPC CloudMap

  • use_alb ( bool ) – Indicates to use an AWS Application LoadBalancer (ELBv2, type application)

  • use_nlb ( bool ) – Indicates to use an AWS Application LoadBalancer (ELBv2, type network)

  • is_public ( bool ) – Indicates whether the service should be accessible publicly

debug ( ) [source]

ecs_composex.ecs.ecs_service_network_config module

Module to help with defining the network settings for the ECS Service based on the family services definitions.

class ecs_composex.ecs.ecs_service_network_config. ServiceNetworking ( family ) [source]

Bases: ecs_composex.ingress_settings.Ingress

Class to group the configuration for Service network settings

add_lb_ingress ( family , lb_name , lb_sg_ref ) [source]

Method to add ingress rules from other AWS Sources


add_self_ingress ( family ) [source]

Method to allow communications internally to the group on set ports


family ( ecs_composex.common.compose_services.ComposeFamily ) –


merge_networks ( family ) [source]

Method to merge network

merge_services_ports ( family ) [source]

Function to merge two sections of ports


family ( ecs_composex.common.compose_services.ComposeFamily ) –


self_key = 'Myself'
ecs_composex.ecs.ecs_service_network_config. add_independant_rules ( dst_family , service_name , root_stack ) [source]
ecs_composex.ecs.ecs_service_network_config. handle_aws_sources ( existing_sources , new_sources ) [source]

Function to handle merge of aws sources between two services for one family :param existing_sources: :param new_sources: :return:

ecs_composex.ecs.ecs_service_network_config. handle_ext_sources ( existing_sources , new_sources ) [source]
ecs_composex.ecs.ecs_service_network_config. handle_ingress_rules ( source_config , ingress_config ) [source]
ecs_composex.ecs.ecs_service_network_config. handle_merge_services_props ( config , network , network_config ) [source]

Function to handle properties assignment for network settings

  • config ( tuple ) –

  • network ( dict ) –

  • network_config ( dict ) –


ecs_composex.ecs.ecs_service_network_config. handle_services ( existing_sources , new_sources ) [source]

Function to merge source services definitions

  • existing_sources ( list ) –

  • new_sources ( list ) –


ecs_composex.ecs.ecs_service_network_config. merge_services_network ( family ) [source]
ecs_composex.ecs.ecs_service_network_config. set_compose_services_ingress ( root_stack , dst_family , families , settings ) [source]

Function to crate SG Ingress between two families / services. Presently, the ingress rules are set after all services have been created


ecs_composex.ecs.ecs_stack module

class ecs_composex.ecs.ecs_stack. ServiceStack ( name , stack_template , stack_parameters = None , file_name = None , ** kwargs ) [source]

Bases: ecs_composex.common.stacks.ComposeXStack

Class to identify specifically a service stack

ecs_composex.ecs.ecs_stack. associate_services_to_root_stack ( root_stack , settings , vpc_stack = None ) [source]

Function to generate all services and associate their stack to the root stack


ecs_composex.ecs.ecs_stack. handle_families_dependencies ( settings , families_post ) [source]

Function to handle family to family services based on docker compose depends_on


ecs_composex.ecs.ecs_template module

Core ECS Template building

ecs_composex.ecs.ecs_template. add_clusterwide_security_group ( template ) [source]

Function to generate the ecs_service Load Balancers (if Any)

ecs_composex.ecs.ecs_template. create_log_group ( family ) [source]

Function to create a new Log Group for the services :return:

ecs_composex.ecs.ecs_template. generate_services ( settings ) [source]

Function to handle creation of services within the same family.


settings ( ecs_composex.common.settings.ComposeXSettings ) –


ecs_composex.ecs.ecs_template. get_service_family_name ( services_families , service_name ) [source]

Function to return the root family name, representing the service stack name.

  • services_families

  • service_name


service stack name

Return type


ecs_composex.ecs.ecs_template. initialize_service_template ( service_name ) [source]

Function to initialize the base template for ECS Services with all parameters and conditions necessary for CFN to work properly


service_name ( str ) – Name of the ecs_service as defined in ComposeX File



Return type


Module contents

Core module for ECS ComposeX.

This module is going to parse each ecs_service and each x-resource key from the compose file (hence ComposeX) and determine its

  • ServiceDefinition

  • TaskDefinition

  • TaskRole

  • ExecutionRole

It is going to also, based on the labels set in the compose file

  • Add the ecs_service to Service Discovery via AWS CloudMap

  • Add load-balancers to dispatch traffic to the microservice