x-elbv2

Syntax

x-elbv2:
  lbA:
    Properties: {}
    MacroParameters: {}
    Listeners: []
    Services: []

Tip

You can find the test files here to use as reference for your use-case.

Properties

For this particular resource, the only attributes that match the CFN definition that ECS Compose-X will import are

All other settings are automatically generated for you based on the network and security definitions you have defined in the services and targets section.

Subnets associations can be overridden in the Settings.Subnets section. See Subnets for more details.

Hint

For Application Load Balancers, a new security group will be created automatically. Subnets are selected automatically based on the scheme you indicated. If selected a public NLB, the EIP addressed will automatically be provisioned too.

MacroParameters

ELBv2 Macro Parameters
timeout_seconds: int
desync_mitigation_mode: str
drop_invalid_header_fields: bool
http2: bool
cross_zone: bool
Ingress: {}

Attributes shortcuts

These settings are just a shorter notation for the LB Attributes

Shorthand

AttributeName

LB Type

timeout_seconds

idle_timeout.timeout_seconds

ALB

desync_mitigation_mode

routing.http.desync_mitigation_mode

ALB

drop_invalid_header_fields

routing.http.drop_invalid_header_fields.enabled

ALB

http2

routing.http2.enabled

ALB

cross_zone

load_balancing.cross_zone.enabled

NLB

Ingress

Similar syntax as for ECS Services Ingress, allow you to define Ingress. See the Ingress JSON Schema definition .

Tip

When using NLB, ingress must be defined at the service level, as NLB do not have a SecurityGroup

Ingress Syntax
Ingress:
  ExtSources: []
  AwsSources: []
ExtSources syntax
ExtSources:
  - Name: str (if any non alphanumeric character set, will be deleted)
    Description: str
    IPv4: str
AwsSources syntax
AwsSources:
  - Type: SecurityGroup|PrefixList (str)
    Id: sg-[a-z0-9]+|pl-[a-z0-9]+
    Lookup: {}

Tip

You can use either Id or Lookup to identify the SecurityGroups. Check out the Lookup syntax reference

Services

This follows the regular pattern of having the name of the service and access, only this time in a slightly different format. The services represent the Target Group definition of your service. Once again, in an attempt to keep things simple, you do not have to indicate all of the settings exactly as CFN does.

The Targets will automatically be pointing towards the ECS Service tasks.

Syntax

name: <family name:container name>
protocol: <str>
port : <int>
healthcheck: <str>
TargetGroupAttributes: list|map

JSON Schema definition

name

Given that you can now re-use one of the service in the docker-compose file multiple times for multiple ECS Services in multiple Task definitions, and ECS to ELBv2 supports to route traffic to a specific container in the task definition, you have to indicate the service name in the following format

# name: <family_name>:<service_name>
name: youtoo:app01
name: app03:app03

Hint

If you service is not associated to a family via deploy labels, the family name is the same as the service name.

protocol

The Target Group protocol

port

The port of the target to send the traffic to

Hint

This port is the port used by the Target Group to send traffic to, which can be different to your healthcheck port.

healthcheck

The healthcheck properties can be defined in the same fashion as defined in the Target Group definition. However, it is also possible to shorten the syntax into a simple string

(port:protocol)(:healthy_count:unhealthy_count:intervals:timeout)?(:path:http_codes)?

Note

The last part, for path and HTTP codes, is only valid for ALB

TargetGroupAttributes

In order to set Target Group specific settings, you can use CFN TargetGroupAttributes properties.

In AWS CFN, it is a list of Key/Value objects, so compose-x supports it that way.

Services:
  - name: app03:app03
    port: 5000
    healthcheck: 5000:TCP:7:2:15:5
    protocol: TCP
    TargetGroupAttributes:
      - Key: deregistration_delay.timeout_seconds
        Value: "30"
      - Key: proxy_protocol_v2.enabled
        Value: "true"
      - Key: preserve_client_ip.enabled
        Value: "true"

But in order to avoid duplicates and make the merge of compose files easier, you can also defined these properties into a map/dict structure and compose-x will automatically convert it to the CFN Expected format.

Services:
  - name: app03:app03
    port: 5000
    healthcheck: 5000:TCP:7:2:15:5
    protocol: TCP
    TargetGroupAttributes:
      deregistration_delay.timeout_seconds: "30"
      proxy_protocol_v2.enabled: "true"
      preserve_client_ip.enabled: "true"

Hint

Compose-X will, based on the type of Load Balancer, ensure that the properties you set are compatible with the LoadBalancer type and the values are valid / in range.

Property Name

LB Type

Allowed Values

deregistration_delay.timeout_seconds

ALL

Range(0,3600) Seconds

stickiness.enabled

  • ALB

  • NLB

  • “true”

  • “false”

stickiness.type

  • ALB

  • NLB

ALB:
  • lb_cookie

  • app_cookie

NLB:
  • source_ip

load_balancing.algorithm.type

  • ALB

  • round_robin

  • least_outstanding_requests

slow_start.duration_seconds

  • ALB

Range(30-900) Seconds

stickiness.app_cookie.cookie_name

  • ALB

String Cannot use or start with * AWSALB * AWSALBAPP * AWSALBTG

stickiness.app_cookie.duration_seconds

  • ALB

Range(1,604800) Seconds

stickiness.lb_cookie.duration_seconds

  • ALB

Range(1,604800) Seconds

lambda.multi_value_headers.enabled * Works only for Lambda targets

  • ALB

  • “true”

  • “false”

deregistration_delay.connection_termination.enabled

  • NLB

  • “true”

  • “false”

preserve_client_ip.enabled

  • NLB

  • “true”

  • “false”

proxy_protocol_v2.enabled

  • NLB

  • “true”

  • “false”

Listeners

You can define in a very simple way your Listener definition and cross-reference other resources, here, the services and ACM certificates you might be creating.

It has its own set of properties, custom to ECS ComposeX.

The following properties are identical to the original CFN definition.

JSON Schema definition

Hint

For certificates, you can also use x-acm to refer to an ACM certificate you are creating with this stack. It will automatically import the Certificate ARN and map it once created.

Hint

You can re-use the same ACM certificate defined in x-acm for multiple listeners. Make sure to have all the Alt. Subjects you need!

Warning

The certificate ARN must be valid when set, however, we are not checking that it actually exists.(yet)

Listener Targets

List of targets to send the requests to. These are equivalent to ELBv2::TargetGroup

name: <service_name> ie. app03:app03
access: <domain name and or path> ie. domain.net/path
cognito_auth: AuthenticateCognitoConfig

This represents the targets and simultaneously the Listener Rules to apply so that you can point to multiple services at once and implement these rules.

name

The name of the family and service in that family to send the requests to.

access

Allows you to define the conditions based on the path or domain name (or combination of both) that should be in place to forward requests.

If you only define the domain name, any path in that domain will be what’s matched.

AuthenticateCognitoConfig

Defines the AuthenticateCognitoConfig requirement condition / action.

AuthenticateOidcConfig

Similar to AuthenticateCognitoConfig but for OIDC providers. This allows to respect all the AuthenticateOidcConfig Properties as per CFN definition.

Tip

We highly recommend that you store the OIDC details into a secret in secrets manager!

Hint

For both AuthenticateCognitoConfig and AuthenticateOidcConfig, the rules defined in access will be set to come after the authenticate action.

Examples

---
# ELBv2 creation for services


x-dns:
  PublicZone:
    Name: lambda-my-aws.io
    Use: ZABCDEFGHIS0123

x-acm:
  public-acm-01:
    Properties:
      DomainName: test.lambda-my-aws.io
      DomainValidationOptions:
        - HostedZoneId: ZABCDEFGHIS0123
          DomainName: test.lambda-my-aws.io
      SubjectAlternativeNames:
        - anothertest.lambda-my-aws.io
        - yet.another.test.lambda-my-aws.io
      ValidationMethod: DNS

x-elbv2:
  lbA:
    Properties:
      Type: application
    MacroParameters:
      timeout_seconds: 60
      desync_mitigation_mode: defensive
      drop_invalid_header_fields: True
      http2: False
      cross_zone: True
      Ingress:
        ExtSources:
          - IPv4: "0.0.0.0/0"
            Description: ANY
          - IPv4: "1.1.1.1/32"
            Description: CLOUDFLARE
            Name: CLOUDFLARE
    Listeners:
      - Port: 80
        Protocol: HTTP
        DefaultActions:
          - Redirect: HTTP_TO_HTTPS
      - Port: 443
        Protocol: HTTP
        Certificates:
          - x-acm: public-acm-01
        Targets:
          - name: bignicefamily:app01
            access: /somewhere
      - Port: 8080
        Protocol: HTTP
        Certificates:
          - x-acm: public-acm-01
          - CertificateArn: arn:aws:acm:eu-west-1:012345678912:certificate/102402a1-d0d2-46ff-b26b-33008f072ee8
        Targets:
          - name: bignicefamily:rproxy
            access: /
          - name: youtoo:rproxy
            access: /stupid
          - name: bignicefamily:app01
            access: thereisnospoon.ews-network.net:8080/abcd/test.html

    Services:
      - name: bignicefamily:rproxy
        port: 80
        protocol: HTTP
        healthcheck: 5000:HTTP:/healthcheck:200,201
      - name: bignicefamily:app01
        port: 5000
        healthcheck: 5000:HTTP:/path/to/healthcheck:200,201
        protocol: HTTP
        TargetGroupAttributes:
          - Key: stickiness.enabled
            Value: "false"
          - Key: load_balancing.algorithm.type
            Value: least_outstanding_requests
      - name: youtoo:rproxy
        port: 80
        healthcheck: 5000:HTTP:5:2:15:3:/ping.This.Method:200,201
        protocol: HTTP
        TargetGroupAttributes:
          stickiness.enabled: "false"
          load_balancing.algorithm.type: least_outstanding_requests

  lbC:
    Properties:
      Scheme: internet-facing
      Type: network
    MacroParameters:
      cross_zone: True
    Settings: {}
    Listeners:
      - Port: 8080
        Protocol: TCP
        Targets:
          - name: app03:app03
            access: /
      - Port: 8081
        Protocol: TCP
        Certificates:
          - x-acm: public-acm-01
        Targets:
          - name: app03:app03
            access: /
    Services:
      - name: app03:app03
        port: 5000
        healthcheck: 5000:TCP:7:2:15:5
        protocol: TCP
        TargetGroupAttributes:
          deregistration_delay.timeout_seconds: "30"
          proxy_protocol_v2.enabled: "true"
          preserve_client_ip.enabled: "true"
#          - Key: deregistration_delay.timeout_seconds
#            Value: "30"
#          - Key: proxy_protocol_v2.enabled
#            Value: "true"
#          - Key: preserve_client_ip.enabled
#            Value: "true"
ELBv2 with
x-elbv2:
  authLb:
    Properties:
      Scheme: internet-facing
      Type: application
    Settings: {}
    Listeners:
      - Port: 8080
        Protocol: HTTP
        Targets:
          - name: app03:app03
            access: /
      - Port: 8081
        Protocol: HTTP
        Targets:
          - name: app03:app03
            access: /
            AuthenticateOidcConfig:
              Issuer: "{{resolve:secretsmanager:/oidc/azuread/app001:SecretString:Issuer}}"
              AuthorizationEndpoint: "{{resolve:secretsmanager:/oidc/azuread/app001:SecretString:AuthorizationEndpoint}}"
              TokenEndpoint: "{{resolve:secretsmanager:/oidc/azuread/app001:SecretString:TokenEndpoint}}"
              UserInfoEndpoint: "{{resolve:secretsmanager:/oidc/azuread/app001:SecretString:UserInfoEndpoint}}"
              ClientId: "{{resolve:secretsmanager:/oidc/azuread/app001:SecretString:ClientId}}"
              ClientSecret: "{{resolve:secretsmanager:/oidc/azuread/app001:SecretString:ClientSecret}}"
              SessionCookieName: "my-cookie"
              SessionTimeout: 3600
              Scope: "email"
              AuthenticationRequestExtraParams":
                display": "page"
                prompt": "login"
              OnUnauthenticatedRequest: "deny"
    Services:
      - name: app03:app03
        port: 5000
        healthcheck: 5000:HTTP:7:2:15:5
        protocol: HTTP