services.x-network

services:
  serviceA:
    x-network:
      x-ecs_connect: {}
      AssignPublicIp: bool
      Ingress: {}
      x-cloudmap: {}

AssignPublicIp

This flag allows to assign an Elastic IP to the container when using awsvpc networking mode.

Hint

Make sure to set your service to be in a subnet that use an Internet Gateway , such as PublicSubnets , otherwise routing won’t work.

Tip

See Deploy services with EIP on public subnets to have a full example of how to implement this feature.

Tip

To select which subnets to place the services, see networks

x-ecs_connect (1.1.0)

This configuration section allows you to define ECS Service Connect configuration. It’s made up of two options, Properties and MacroParameters

Properties must match exactly the ECS Service Connect properties and must be all valid to work.

Attention

No changes to input or validation will be made when set. Be sure to have everything valid.

MacroParameters however, is an attempt at creating a shorthand syntax to this.

service connect - client only

You might have applications that you want to act only as clients to other services. This will only tell ECS to make sure to provision the Service Connect sidecar which will be there to handle the proxy-ing to server services.

To enable the client config, you simply need to enable the feature as show below

x-cloudmap:
  PrivateNamespace:
    Name: compose-x.internal

services:
  yelb-ui:
    x-network:
      AssignPublicIp: true
      x-ecs_connect:
        MacroParameters:
          x-cloudmap: PrivateNamespace
      Ingress:
        ExtSources:
          - IPv4: 0.0.0.0/0
            Name: ANY

service connect - server

For services that you want to act as client & server, you need to declare which ports you want to declare to Service Connect. That’s mandatory.

For example, we have the following two services: appserver will act as both a client and a server. It will serve requests for our yelb-ui service (the client above), and a client to the redis-server

x-cloudmap:
  PrivateNamespace:
    Name: compose-x.internal

services:
  yelb-appserver:
    image: mreferre/yelb-appserver:0.7
    depends_on:
      - redis-server
    ports:
      - 4567:4567
    environment:
      redishost: redis-server
    x-network:
      Ingress:
        Services:
          - Name: yelb-ui
      x-ecs_connect:
        MacroParameters:
          service_ports:
            tcp_4567:
              DnsName: yelb-appserver
              CloudMapServiceName: yelb-appserver
          x-cloudmap: PrivateNamespace


  redis-server:
    image: redis:4.0.2
    ports:
      - 6379:6379
    x-network:
      x-ecs_connect:
        MacroParameters:
          service_ports:
            tcp_6379:
              DnsName: redis-server
              CloudMapServiceName: redis-server
          x-cloudmap: PrivateNamespace
      Ingress:
        Services:
          - Name: yelb-appserver

Hint

See the full connect example uses to perform functional testing of the feature.

Ingress

This allows you to define specific ingress control from external sources to your environment. For example, if you have to whitelist IP addresses that are to be allowed communication to the services, you can list these, and indicate their name which will be shown in the EC2 security group description of the ingress rule.

Ingress Syntax reference

Ingress:
  ExtSources: []
  AwsSources: []
  Myself: True/False

Ingress Example

services:
  app01:
    x-network:
      Ingress:
        ExtSources:
          - IPv4: 0.0.0.0/0
            Name: all
          - IPv4: 1.1.1.1/32
            Source_name: CloudFlareDNS
        AwsSources:
          - Type: SecurityGroup
            Id: sg-abcd
          - Type: PrefixList
            Id: pl-abcd
        Myself: True/False

Tip

You can define the SG from another AWS account by setting AccountOwner in the Security group definition.

Tip

You can define which ports to open per source using the Ports list.

Hint

If you enter a port number that is not in the Ports list, it will be ignored.

Hint

The protocol is automatically detected based on the port definition. By default, it is TCP

Hint

To see details about the Ingress for Load Balancers, refer to Ingress

Hint

When using an ALB, you do not need to define that ALB security group etc., all inbound rules will be defined automatically to allow the ALB to communicate with your service!

x-cloudmap

Refer to x-cloudmap for more details on how to use it.

Map VPC subnets to docker-compose networks

AWS VPC to network mapping

networks:
  internal:
    x-vpc: InteralCustomSubnets

x-vpc:
  VpcId:
    Tags: []
  AppSubnets:
    Tags: []
  PublicSubnets:
    Tags: []
  StorageSubnets:
    Tags: []
  InteralCustomSubnets:
    Tags: []

services:
  serviceA:
    networks: [internal]

JSON Schema

Model

services.x-network specification

services.x-network
The services.x-network specification for ComposeX
type	object
properties
AssignPublicIp	Enables assigning a public IP address to the service tasks.
	type	boolean
AdditionalSecurityGroups	Define additional security groups to use.
	type	object
	patternProperties
	^[a-zA-Z0-9._-]+$	The definition of the security group to use
		oneOf	The security group ID to use. It must belong to the same VPC you are deploying to
			type	string
			pattern	^sg-[a-z0-9]+$
			x-resources.common.spec.json#/definitions/Lookup
	additionalProperties	False
x-ecs_connect	#/definitions/ecsConnect
x-cloudmap	oneOf	When you want to register the service into CloudMap. First port listed in ports[] used.
		type	string
		#/definitions/cloudMapMappingDefinition
Ingress	ingress.spec.json
additionalProperties	False
definitions
ecsConnect	type	object
	properties
	Properties	Literal properties to set as in https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service-serviceconnectconfiguration.html
		type	object
	MacroParameters	#/definitions/ecsConnectMacroParameters
ecsConnectMacroParameters	Mapping for connect ports, allowing to create 1 service connect server alias per port
	type	object
	properties
	x-cloudmap	Name of the namespace defined in the x-cloudmap root level to use.
		type	string
	service_ports	type	object
		patternProperties
		^x-
		^[a-zA-Z0-9-_]+$	#/definitions/ecsConnectMacroPorts
		additionalProperties	False
	additionalProperties	False
ecsConnectMacroPorts	ECS Compose-X Shorthand syntax to configure ECS Connect.
	type	object
	properties
	DnsName	DNS name for the clients to find this service
		type	string
	CloudMapServiceName	Optional - Set the name of the service as it appears in the CloudMap namespace
		type	string
		maxLength	64
	appProtocol	https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_PortMapping.html
		type	string
		pattern	http|http2|grpc
	patternProperties
	x-*
	additionalProperties	True
cloudMapMappingDefinition	Allows you to register the service to multiple registries, and/or use a specific port.
	type	object
	patternProperties
	[a-zA-Z0-9-_.]+$	The name of the object is the name of the x-cloudmap::<map>.
		type	object
		properties
		Port	The port to register in SRV record
			type	number
			maximum	65535
			minimum	0
		Name	Name of the service. Do not include the cloudmap hostname. Overrides the ecs.task.family.hostname deploy label
			type	string
		additionalProperties	False
	additionalProperties	False

Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "id": "services.x-network",
  "$id": "services.x-network.spec.json",
  "type": "object",
  "title": "services.x-network specification",
  "description": "The services.x-network specification for ComposeX",
  "additionalProperties": false,
  "properties": {
    "AssignPublicIp": {
      "type": "boolean",
      "description": "Enables assigning a public IP address to the service tasks."
    },
    "AdditionalSecurityGroups": {
      "description": "Define additional security groups to use.",
      "type": "object",
      "additionalProperties": false,
      "patternProperties": {
        "^[a-zA-Z0-9._-]+$": {
          "description": "The definition of the security group to use",
          "oneOf": [
            {
              "type": "string",
              "description": "The security group ID to use. It must belong to the same VPC you are deploying to",
              "pattern": "^sg-[a-z0-9]+$"
            },
            {
              "$ref": "x-resources.common.spec.json#/definitions/Lookup"
            }
          ]
        }
      }
    },
    "x-ecs_connect": {
      "$ref": "#/definitions/ecsConnect"
    },
    "x-cloudmap": {
      "oneOf": [
        {
          "type": "string",
          "description": "When you want to register the service into CloudMap. First port listed in ports[] used."
        },
        {
          "$ref": "#/definitions/cloudMapMappingDefinition"
        }
      ]
    },
    "Ingress": {
      "$ref": "ingress.spec.json"
    }
  },
  "definitions": {
    "ecsConnect": {
      "type": "object",
      "oneOf": [
        {
          "required": [
            "Properties"
          ]
        },
        {
          "required": [
            "MacroParameters"
          ]
        }
      ],
      "properties": {
        "Properties": {
          "type": "object",
          "description": "Literal properties to set as in https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-service-serviceconnectconfiguration.html"
        },
        "MacroParameters": {
          "$ref": "#/definitions/ecsConnectMacroParameters"
        }
      }
    },
    "ecsConnectMacroParameters": {
      "type": "object",
      "additionalProperties": false,
      "description": "Mapping for connect ports, allowing to create 1 service connect server alias per port",
      "properties": {
        "x-cloudmap": {
          "type": "string",
          "description": "Name of the namespace defined in the x-cloudmap root level to use."
        },
        "service_ports": {
          "type": "object",
          "additionalProperties": false,
          "patternProperties": {
            "^x-": {},
            "^[a-zA-Z0-9-_]+$": {
              "$ref": "#/definitions/ecsConnectMacroPorts"
            }
          }
        }
      },
      "required": [
        "x-cloudmap"
      ]
    },
    "ecsConnectMacroPorts": {
      "type": "object",
      "description": "ECS Compose-X Shorthand syntax to configure ECS Connect.",
      "additionalProperties": true,
      "properties": {
        "DnsName": {
          "type": "string",
          "description": "DNS name for the clients to find this service"
        },
        "CloudMapServiceName": {
          "type": "string",
          "maxLength": 64,
          "description": "Optional - Set the name of the service as it appears in the CloudMap namespace"
        },
        "appProtocol": {
          "description": "https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_PortMapping.html",
          "type": "string",
          "pattern": "http|http2|grpc"
        }
      },
      "patternProperties": {
        "x-*": {}
      }
    },
    "cloudMapMappingDefinition": {
      "type": "object",
      "description": "Allows you to register the service to multiple registries, and/or use a specific port.",
      "additionalProperties": false,
      "patternProperties": {
        "[a-zA-Z0-9-_.]+$": {
          "type": "object",
          "description": "The name of the object is the name of the x-cloudmap::<map>.",
          "additionalProperties": false,
          "required": [
            "Port"
          ],
          "properties": {
            "Port": {
              "description": "The port to register in SRV record",
              "type": "number",
              "minimum": 0,
              "maximum": 65535
            },
            "Name": {
              "type": "string",
              "description": "Name of the service. Do not include the cloudmap hostname. Overrides the ecs.task.family.hostname deploy label"
            }
          }
        }
      }
    }
  }
}