Network Load Balancers



A Network Load Balancer (NLB) serves as a single point of contact for clients and distributes incoming traffic across multiple targets. It operates at the transport layer (layer 4) and is ideal for load balancing TCP traffic where extreme performance is required.

NLBs can be integrated with multi-container workloads, offload SSL/TLS termination, and be configured with custom domain names.

Under the hood, Stacktape uses AWS Network Load Balancer.

When to use them

NLBs are a good choice for applications that use TCP protocols other than HTTP/S. If your application uses HTTP or HTTPS, an Application Load Balancer is a better choice.

Advantages

  • Predictable pricing: NLBs have a predictable pricing model, which can be more cost-effective than HTTP API Gateways for high-traffic applications.
  • Scalability: NLBs can handle millions of requests per second and scale automatically as traffic grows.
  • Health checks: When used with container workloads, an NLB periodically checks the health of each container and only routes traffic to healthy ones.
  • Ease of use: You can integrate an NLB with your compute resources with just a few lines of configuration.
  • Security: You can offload SSL/TLS termination to the load balancer, encrypting traffic between the client and the NLB.

Disadvantages

  • Fixed cost: NLBs have a fixed monthly cost (around $20/month), even if they are idle.
  • Limited integrations: NLBs can only be integrated with multi-container workloads.

Basic usage

NetworkLoadBalancerAPI reference
typeRequired
No description

Type: string "network-load-balancer"

properties.listenersRequired

Listeners define which ports and protocols (TCP/TLS) this load balancer accepts traffic on.

Type: Array of NetworkLoadBalancerListener

properties.interfaceDefault: internet

internet (public) or internal (VPC-only).

Type: string ENUM

Possible values: internalinternet

properties.customDomains

Custom domains.

Type: Array of string or Array of DomainConfiguration

By default, Stacktape creates DNS records and TLS certificates for each domain. If you manage DNS yourself, set disableDnsRecordCreation and provide customCertificateArn.

Backward compatible format string[] is still supported.

overrides

Escape hatch to modify the underlying CloudFormation resources Stacktape creates.

Type: Object

Use dot-notation paths to override specific properties on any child resource. Find resource logical IDs with stacktape stack-info --detailed.

overrides:
  MyDbInstance:
    Properties.StorageEncrypted: true
resources:
  myLoadBalancer:
    type: 'network-load-balancer'
    properties:
      listeners:
        - port: 8080
          protocol: TLS

  myWorkload:
    type: 'multi-container-workload'
    properties:
      containers:
        - name: container1
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: containers/ts-container.ts
          events:
            - type: network-load-balancer
              properties:
                loadBalancerName: myLoadBalancer
                listenerPort: 8080
                containerPort: 8080
      resources:
        cpu: 0.25
        memory: 512

A Network Load Balancer with a multi-container workload integration.


Integrating with compute resources

You can forward traffic from an NLB to a multi-container workload. Each integration must specify the load balancer, the listener port, and the container port.

resources:
  myLoadBalancer:
    type: 'network-load-balancer'
    properties:
      listeners:
        - port: 8080
          protocol: TLS

  myWorkload:
    type: 'multi-container-workload'
    properties:
      containers:
        - name: container1
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: containers/ts-container.ts
          events:
            - type: network-load-balancer
              properties:
                loadBalancerName: myLoadBalancer
                listenerPort: 8080
                containerPort: 8080
      resources:
        cpu: 0.25
        memory: 512

For more information, see the documentation on integrating NLBs with multi-container workloads.


Custom domain names

You can use a custom domain for your NLB. If you don't have one, you can register one through Stacktape.

If you already have a domain, you can either let Stacktape manage it (if you use AWS Route 53 for DNS) or use a third-party DNS provider.

For more details, see the Domains and Certificates page.

Using Stacktape to manage domains and certs

By default, Stacktape creates DNS records and TLS certificates for each domain. If you manage DNS yourself, set disableDnsRecordCreation and provide customCertificateArn.

Backward compatible format string[] is still supported.

resources:
  myLoadBalancer:
    type: 'network-load-balancer'
    properties:
      customDomains:
        - my-app.mydomain.com
      listeners:
        - port: 8080
          protocol: TLS

Using a 3rd-party DNS

To use a domain from a provider like GoDaddy or Cloudflare:

  1. Create or import a TLS certificate for your domain in the AWS Certificate Manager console and copy its ARN.
  2. Configure a listener on your load balancer to use the custom certificate.
  3. After deploying, find the NLB's domain name in the Stacktape Console.
  4. In your DNS provider's dashboard, create a CNAME or ALIAS record pointing to the NLB's domain name.
resources:
  myLoadBalancer:
    type: 'network-load-balancer'
    properties:
      listeners:
        - port: 8080
          protocol: TLS
          customCertificateArns:
            - arn:aws:acm:eu-west-1:999999999999:certificate/8ab817b5-c4fa-4b1d-8b72-d6082cb40351

  myWorkload:
    type: 'multi-container-workload'
    properties:
      containers:
        - name: container1
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: containers/ts-container.ts
          events:
            - type: network-load-balancer
              properties:
                loadBalancerName: myLoadBalancer
                listenerPort: 8080
                containerPort: 8080
      resources:
        cpu: 0.25
        memory: 512

Listeners

Listeners check for connection requests from clients, using the protocol and port that you configure.

Listeners define which ports and protocols (TCP/TLS) this load balancer accepts traffic on.

NetworkLoadBalancerListenerAPI referenceParent:NetworkLoadBalancer
protocolRequired

TCP (raw) or TLS (encrypted). TLS requires a certificate (auto-created with customDomains or via customCertificateArns).

Type: string ENUM

Possible values: TCPTLS

portRequired

Port this listener accepts traffic on.

Type: number

customCertificateArns

ARNs of your own ACM certificates. Not needed if using customDomains or TCP protocol.

Type: Array of string

whitelistIps

Restrict access to specific IP addresses/CIDRs. Default: all IPs allowed.

Type: Array of string

resources:
  myLoadBalancer:
    type: 'network-load-balancer'
    properties:
      customDomains:
        - my-app.mydomain.com
      listeners:
        - port: 8080
          protocol: TLS
        - port: 8081
          protocol: TCP
        - port: 8082
          protocol: TLS

A Network Load Balancer with three listeners.

Custom TLS certificates

You can configure a listener to use a custom TLS certificate.

resources:
  myLoadBalancer:
    type: 'network-load-balancer'
    properties:
      listeners:
        - port: 8080
          protocol: TLS
          customCertificateArns:
            - arn:aws:acm:eu-west-1:999999999999:certificate/8ab817b5-c4fa-4b1d-8b72-d6082cb40351

  myWorkload:
    type: 'multi-container-workload'
    properties:
      containers:
        - name: container1
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: containers/ts-container.ts
          events:
            - type: network-load-balancer
              properties:
                loadBalancerName: myLoadBalancer
                listenerPort: 8080
                containerPort: 8080
      resources:
        cpu: 0.25
        memory: 512

Referenceable parameters

The following parameters can be easily referenced using $ResourceParam directive directive.

To learn more about referencing parameters, refer to referencing parameters.

domain
  • default domain name of load balancer

  • Usage: $ResourceParam('<<resource-name>>', 'domain')
customDomains
  • Comma-separated list of custom domain names assigned to the Load balancer (only available if you use custom domain names)

  • Usage: $ResourceParam('<<resource-name>>', 'customDomains')