x-elbv2¶

This module allows you to define Application and Network Load-Balancers (Gateways not tested yet), and define which of your services should receive traffic, and add settings such as health check etc.

Syntax¶

x-elbv2:
  lbA:
    Properties: {}
    MacroParameters: {}
    Services: []
      - name: str
        protocol: str
        port: int
        healthcheck: str
    Listeners: []

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: {}

Ingress¶

Similar syntax as for ECS Services Ingress, allow you to define Ingress.

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

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

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.

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

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.

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)

Target Groups¶

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:
      S3Logs: bucket:/prefix
      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
        healthcheck: 5000:HTTP:/healthcheck:200,201
      - name: bignicefamily:app01
        port: 5000
        healthcheck: 5000:HTTP:/path/to/healthcheck:200,201
      - name: youtoo:rproxy
        port: 80
        healthcheck: 5000:HTTP:5:2:15:3:/ping.This.Method:200,201

  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

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