x-elbv2

This module is a rework in-depth of the previous lb_type property in x-configs aimed to allow a lot more detailed configuration, and in the future, to allow more detailed LB configuration, to allow pointing to Lambda or use Cognito to authenticate etc.

Syntax

x-elbv2:
  lbA:
    Properties: {}
    Settings:
      timeout_seconds: int
      desync_mitigation_mode: str
      drop_invalid_header_fields: bool
      http2: bool
      cross_zone: bool
    Services:
      - name: str
        protocol: str
        port: int
        healthcheck: str

Properties

These as for every other x-resource is to re-use the similar properties as described in the CFN definition of a Load Balancer v2.

Although once again, the aim of ECS ComposeX is to take a lot of the complexity away from the user. The only two properties that are really necessary to set are

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 IP addressed will automatically be provisioned too.

MacroParameters

Ingress

Similar syntax as for ECS Services Ingress, allow you to define Ingress (only applies to ALB).

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

Settings

Once again in an effort of making configuration shorter and easier, here as the options you can simply indicate.

  • timeout_seconds: 60

  • desync_mitigation_mode: defensive

  • drop_invalid_header_fields: True

  • http2: False

  • cross_zone: True

These settings are just a shorter notation for the LB Attributes

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)

ECS ComposeX custom properties

Targets

List of targets to send the requests to.

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: {}
    Settings:
     S3Logs: bucket:/prefix
     timeout_seconds: 60
     desync_mitigation_mode: defensive
     drop_invalid_header_fields: True
     http2: False
     cross_zone: True
    MacroParameters:
      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

    Services:
      - name: bignicefamily:rproxy
        port: 80
        healthcheck: 5000:HTTP:/healthcheck:200,201
      - name: bignicefamily:app01
        port: 5000
        healthcheck: 5000:HTTP:/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
    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