logoStacktape docs




Application Load Balancers

Overview and basic concepts

  • Application Load balancer is an entry-point to your application. Load balancer routes traffic to your application and integrates easily with workloads of your stack: functions, batch-jobs or container-workloads.
  • Application load balancers are used to communicate with your workloads using the HTTP protocol.
  • You can offload SSL/TLS (HTTPS) termination to the load-balancer instead of handling it as a part of your application.
  • You can easily configure custom domain names or put CDN in front of your application-load-balancer.

When to use

An application load balancer is a good fit for many cloud applications. Whether your backend is running on container-workloads or functions thanks to high throughput and low latency, an application load balancer is ideal for high load fast performing applications.

Advantages

  • Predictable pricing - Application load balancers have a predictable pricing model which can be found here. Even though application-load-balancers have fixed base price per month (as opposed to http-api-gateways, where you only pay for requests), when traffic is high application-load-balancer can be cheaper.
  • Scaling - Application load balancer is designed to handle traffic as it grows and can load balance millions of requests/sec.
  • Health checks - When an application load balancer is used with container-workloads, the load balancer periodically checks the health of target containers. It only sends requests to healthy ones and automatically notifies container-workload to replace unhealthy containers.
  • Content based routing - If your application is composed of several individual services, application-load-balancer can route a request to a service based on the content of the request such as Host field, Path URL, HTTP header, HTTP method, Query string or Source IP address.
  • Ease of use - Integrate with workloads of your stack with few lines of config
  • Security - You can offload SSL/TLS (HTTPS) termination to the load-balancer instead of handling it as a part of your application. This means that any communication between load-balancer and client can be encrypted.

Disadvantages

  • Fixed price base - You are paying ~20$/month for application-load-balancer even if it is sitting idle. When you have low traffic application or do NOT need the advantages that application-load-balancer offers, you might try using http-api-gateway

Simple usage

ApplicationLoadBalancer  API reference
type
Required

No description

Type: string "application-load-balancer"

properties.listeners
Required
properties.interface
Default: 'internet'

Configures accessibility of the Load balancer

Type: string ENUM

Possible values: internalinternet

  • internet: Load balancer is accessible from the internet
  • internal: Load balancer is accessible only from within the same VPC network To learn more about VPCs, refer to Stacktape docs

properties.customDomains

Configures custom domains for this Load balancer

Type: Array of string

  • Stacktape allows you to connect your custom domains.
  • If your domain DNS records are already controlled by AWS Route 53, simply configure domainNames. Stacktape will automatically generate correct TLS certificates for your domain.
  • If your domain DNS records are NOT controlled by AWS:
    1. Add your domain to your AWS account. You can use the domain-add command. If you are migrating domain which is currently in use, refer to AWS Docs guide.
    2. (optional) Configure your custom certificate by specifying customCertificateArn and specifying disableDnsRecordCreation

properties.cdn

Configures AWS Cloudfront CDN (Content Delivery Network) to be in front of your Application Load Balancer

Type: ApplicationLoadBalancerCdnConfiguration

  • CDN is a globally distributed network that can cache reponses from your Application Load Balancer at the edge - close to your users.
  • AWS Cloudfront has 205 edge locations on 6 continents.
  • The CDN is used to:
    • reduce latency & improve load times
    • reduce bandwidth costs
    • reduce the amount of traffic coming to the origin
  • The "origin" is the resource connected to the CDN. CDN caches responses from the origin at the edge for specified amount of time.
  • If the content requested by the client is in the CDN cache, the CDN immediately returns it to the client without making a request to the origin.
  • If the content is NOT in the cache, the CDN makes a request to the Origin. The response from the origin is then forwarded to the client, and cached at the edge.
  • The CDN has its own URL endpoint.

overrides

Overrides one or more properties of the specified child resource.

Type: Object

  • Child resouces are specified using their descriptive name (e.g. DbInstance or Events.0.HttpApiRoute).
  • To see all configurable child resources for given Stacktape resource, use stacktape stack-info --detailed command.
  • To see the list of properties that can be overriden, refer to AWS Cloudformation docs.

The following example shows a simple application-load-balancer with a single listener exposed.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS

Configure listeners

Listeners provide a way to expose ports of application-load-balancer. They makes application-load-balancer accessible from the outside and forward traffic to workloads (functions, container-workloads, batch-jobs) of your stack.

ApplicationLoadBalancerListener  API reference
Parent API reference: ApplicationLoadBalancer
protocol
Required

Protocol used for the listener

Type: string ENUM

Possible values: HTTPHTTPS

  • If HTTPS protocol is used, listener needs to have SSL/TLS certificates configured. This can be achieved in 2 ways:
    • Configure customDomains to make Stacktape automatically generate and use SSL/TLS certificates.
    • Configure customCertificateArns to use custom certificate (referenced by their ARN - Amazon Resource Name)

port
Required

Port number on which the listener is accessible

Type: number

  • By default, HTTPS connections use port 443 and HTTP connections use port 80.

customCertificateArns

Used to configure custom SSL/TLS certicates

Type: Array of string

  • Configuring certifacates is not necessary, if you specify customDomains or you don't use HTTPS protocol for this listener.

whitelistIps

Limits accessibility of the listener to only specific IP addresses

Type: Array of string

  • By default all IP addresses are whitelisted.

defaultAction

Configures the behavior of the listener for request that cannot be matched to any integration.

Type: LbRedirect

  • At the moment, only default action supported is redirect.

Following example shows application-load-balancer with one listeners. HTTPS listener at port 443.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS

Default listener action

Default listener action determines what to do with a request that does not match any event integration associated with this listener (see integrating with workloads).

Redirect

LbRedirect  API reference
Parent API reference: ApplicationLoadBalancerListener
type
Required

Type of the default action

Type: string "redirect"

properties.statusCode
Required

HTTP redirect code

Type: string ENUM

Possible values: HTTP_301HTTP_302

  • Use HTTP_301 for permanent redirect
  • Use HTTP_302 for temporary redirect

properties.path

Absolute path to redirect to.

Type: string

  • Starting with the leading "/".
  • Not percent-encoded.

properties.query

Query parameters for the redirect.

Type: string

  • URL-encoded when necessary, but not percent-encoded.
  • Do not include the leading "?", as it is automatically added.
  • Use

properties.port

Port for the redirect.

Type: number

  • You can specify a value from 1 to 65535 or #{port}.

properties.host

Hostname for the redirect.

Type: string

  • Not percent-encoded.

properties.protocol

Protocol for the redirect.

Type: string ENUM

Possible values: HTTPHTTPS

  • Must be HTTP, HTTPS, or #{protocol}.
  • You cannot redirect HTTPS to HTTP.

The following example extends the previous one and shows application-load-balancer with two listeners:

  • HTTPS listener at port 443
  • HTTP listener at port 80. HTTP listener has default redirect action configured. This means that any HTTP request is automatically redirected to its HTTPS version.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
- port: 80
protocol: HTTP
defaultAction:
type: redirect
properties:
statusCode: HTTP_301
protocol: HTTPS
port: 443

Integrating with workloads

To integrate, add an event integration to the workload.

The following example extends the previous one and shows:

  • container-workload mySingleContainer with event integration which delivers all requests incoming to myLoadBalancer's listener on port 443 to the container.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
- port: 80
protocol: HTTP
defaultAction:
type: redirect
properties:
statusCode: HTTP_301
protocol: HTTPS
port: 443
mySingleContainer:
type: 'container-workload'
properties:
containers:
- name: myCont
imageConfig:
filePath: containers/ts-container.ts
environment:
- name: port
value: '80'
events:
- type: application-load-balancer
properties:
loadBalancerName: myLoadBalancer
listenerPort: 443
containerPort: 80
priority: 2
paths:
- '*'

More information on integrating workloads with application load balancer can be found:

Domain names

Domains can be easily controlled by Stacktape.

If your domain DNS records are controlled by AWS Route 53, Stacktape automatically generates correct TLS certificates for your domain and assign them to listeners.

If your domain DNS records are NOT controlled by AWS:

  1. migrate domain with a help of domain-add command (if you are migrating domain which is currently in use, please readAWS docs).
  2. you can provision certificate by specifying customCertificateArns for your listener.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
domainNames:
- my-app.mydomain.com
listeners:
- port: 443
protocol: HTTPS

Cdn

ApplicationLoadBalancerCdnConfiguration  API reference
Parent API reference: ApplicationLoadBalancer
listenerPort
Required

Listener port to which the CDN traffic will be forwarded

Type: number

enabled
Required

Enables the CDN

Type: boolean

originDomainName

Configures origin domain name usef for forwarding to load balancer

Type: string

  • This is only neccessary if the load balancer has no customDomains attached and the listener uses customCertificateArns

cachingOptions

Configures custom caching options

Type: CdnCachingOptions

  • Configures the caching behavior of your edge distribution (what & when should stay in cache, and when to refetch it from the origion)

forwardingOptions

Configures which parts of the request are forwarded to the origin (headers, query parameters, cookies etc.)

Type: CdnForwardingOptions

routeRewrites

Enables you to redirect specific requests to a different origin

Type: Array of CdnRouteRewrite

  • Each incoming request to the CDN is first evaluated against route rewrites. The requested path is compared with path pattern specified in route rewrite.
  • If the requested path matches the path pattern specified by route rewrite, the request is sent to the configured route.
  • Route rewrites are evaluated in order. The first match is where the request will be sent to.
  • If no match is found, request is sent to the default origin (the one that the CDN is attached to).

Example use cases:

  • Most of the content you are serving is a static content served from a bucket (static website). Some content however needs to be rendered dynamically by a lambda function. You can route paths that need to be rendered dynamically to the lambda function through http-api-gateway.
  • You want to cache your jpg files longer than other files. You can create route rewrite that will catch every path ending with jpg and set custom caching options for these paths.

customDomains

Custom domain names to connect to this CDN distribution

Type: Array of DomainConfiguration

cloudfrontPriceClass
Default: 'PriceClass_All'

Configures locations from which the CDN serves traffic

Type: string ENUM

Possible values: PriceClass_100PriceClass_200PriceClass_All

  • Higher price class results in more locations that serve your traffic.
  • This can result in better performance, but is more costly.
  • Example: If your users are located only in US & Europe, you can save money by configuring PriceClass_100
  • To learn more about price classes, refer to AWS docs

defaultRoutePrefix

Prefixes requests to the origin with specified prefix

Type: string

  • Example: If the CDN receives a request with path /my/resource/url, the request will be sent to the origin as <>/my/resource/url

errorDocument

Custom error document URL

Type: string

  • Error document is requested by the CDN if the original request to the origin responds with an error code 403, 404 or 500.
  • Example: /error.html

indexDocument
Default: '/index.html'

Custom index (root) document served for requests with path /

Type: string

invalidateAfterDeploy
Default: true

Invalidates the CDN cache after each deployment

Type: boolean

  • This prevents serving outdated content to your users
  • If you choose to invalidate the cache, CDN will flush all the cached content and new requests will result in a request to the origin (bucket, application-load-balancer or http-api-gateway)

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
cdn:
enabled: true
listenerPort: 443

Cdn domain names

Domains can be easily controlled by Stacktape.

If your domain DNS records are controlled by AWS Route 53, Stacktape automatically generates correct TLS certificates for your domain.

If your domain DNS records are NOT controlled by AWS:

  1. migrate domain with a help of domain-add command (if you are migrating domain which is currently in use, please readAWS docs).
  2. you can provision certificate by specifying customCertificateArn and specifyingdisableDnsProvision
DomainConfiguration  API reference
domainName
Required

Fully qualified (absolute) domain name.

Type: string

customCertificateArn

ARN of a custom certificate to be provisioned with this domain

Type: string

  • Stacktape generates certificates for all your domains.
  • If you want to use a custom certificate (managed within your AWS account), you can specify its ARN (Amazon Resource Name).

disableDnsRecordCreation
Default: true

Enables creation of a DNS record

Type: boolean

  • Stacktape creates a DNS record by default for all of your domains.
  • If you want to configure DNS records on your own, set this to false.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
cdn:
enabled: true
listenerPort: 443
domainNames:
- domainName: something.mydomain.com

Route rewrites

Route rewrites can be used to route incoming requests to different origins: I.e., instead of forwarding a request to the application-load-balancer, the request can be forwarded to another origin (http-api-gateway, bucket or application-load-balancer).

CdnRouteRewrite  API reference
path
Required

Path to be adjusted by this route rewrite

Type: string

  • You can use wildcards for your path patterns to match multiple paths.
  • To learn more about path patterns, refer to AWS docs

routePrefix

Prefixes every request to the origin with the specified prefix

Type: string

  • Example: If the CDN receives a request with path /my/resource/url, the request will be sent to the origin as <>/my/resource/url

routeTo

Configures the origin to which the route rewrite forwards requests

Type: (CdnLoadBalancerRoute or CdnHttpApiGatewayRoute or CdnBucketRoute)

  • If not set, the default origin (the one this CDN is attached to) is used

cachingOptions

Configuires custom caching options for this route rewrite

Type: CdnCachingOptions

  • Configures the caching behavior of your edge distribution (what & when should stay in cache, and when to refetch it from the origion)

forwardingOptions

Enables you to redirect specific requests to a different origin

Type: CdnForwardingOptions

  • Forwarding options enable you to set which parts of the request are forwarded to the origin (headers, query params, cookies etc.)

Routing to a bucket

CdnBucketRoute  API reference
Parent API reference: CdnRouteRewrite
type
Required

No description

Type: string "bucket"

properties.bucketName
Required

Name of the bucket

Type: string

properties.disableUrlNormalization
Default: true

Disables URL normalization (ability to use clean urls without the .html extension)

Type: boolean

  • URL normalization is enabled by default.
  • URL normalization is useful when you want to serve HTML files from the bucket
  • When the URL normalization is enabled, the CDN is able to fetch correct HTML files from the bucket even when incomplete URL is used (without the .html extension)
  • This enables you to use URLs such as <>/about instead of urls <>/about.html or <>/about/index.html

In the following example we are routing all request with url path starting with /static to the bucket myBucket which contains our static content. All other requests are routed to the application-load-balancer myLoadBalancer.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
cdn:
enabled: true
listenerPort: 443
routeRewrites:
- path: /static/*
routeTo:
type: bucket
properties:
bucketName: myBucket
disableUrlNormalization: true
myBucket:
type: 'bucket'

Routing to application-load-balancer

CdnLoadBalancerRoute  API reference
Parent API reference: CdnRouteRewrite
type
Required

No description

Type: string "application-load-balancer"

properties.loadBalancerName
Required

Name of the Load balancer

Type: string

properties.listenerPort
Required

Port of the Load balancer listener

Type: number

properties.originDomainName

Explicitly sets the origin domain name you wish to use when forwarding to load balancer

Type: string

  • This is only neccessary if the load balancer has no customDomains attached and listener uses customCertificateArns

In the following example we are routing all request with url path starting with /app2 to the application-load-balancer myLoadBalancer2. All other requests are routed to the application-load-balancer myLoadBalancer.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
cdn:
enabled: true
listenerPort: 443
routeRewrites:
- path: /app2/*
routeTo:
type: 'application-load-balancer'
properties:
loadBalancerName: myLoadBalancer
listenerPort: 443
myLoadBalancer2:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS

Routing to http-api-gateway

CdnHttpApiGatewayRoute  API reference
Parent API reference: CdnRouteRewrite
type
Required

No description

Type: string "http-api-gateway"

properties.httpApiGatewayName
Required

Name of the HTTP Api Gateway

Type: string

In the following example we are routing all request with url path starting with /app2 to the http-api-gateway appApiGateway. All other requests are routed to the application-load-balancer myLoadBalancer.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
cdn:
enabled: true
listenerPort: 443
routeRewrites:
- path: /app2/*
routeTo:
type: 'http-api-gateway'
properties:
httpApiGatewayName: appApiGateway
appApiGateway:
type: 'http-api-gateway'

Caching options

Caching options enable you to specify caching settings for your CDN.

You can specify different cache options for each route rewrite. This gives you the ability to cache different types of content differently.

If you do not specify caching options, Stacktape uses default caching options.

CdnCachingOptions  API reference
cacheMethods

Only responses to the requests with these methods will be cached

Type: Array of string ENUM

Possible values: GETHEADOPTIONS

  • Possible values are:
    • ['GET', 'HEAD']
    • ['GET', 'HEAD', 'OPTIONS']

minTTL

The minimum amount of time in seconds that the objects will stay in the CDN cache before another request is sent to the origin

Type: number

  • To learn more about cache expiration, refer to AWS Docs

maxTTL

The maximum amount of time in seconds that the objects will stay in the CDN cache before another request is sent to the origin

Type: number

  • To learn more about cache expiration, refer to AWS Docs

defaultTTL

The default amount of time in seconds that the objects will stay in the CDN cache before another request is sent to the origin

Type: number

  • To learn more about cache expiration, refer to AWS Docs

disableCompression
Default: false

Disables compression of the objects served by the CDN

Type: boolean

  • Compression is enabled by default.
  • Compression can significantly reduce the size of the responses from the CDN. In some cases, less than a quarter the size of the original. This can result in a better performance and lower transfer costs.
  • The CDN compresses objects using the Gzip and Brotli compression methods.
  • If the viewer supports both formats, Brotli version is used.
  • The client must indicate that it acceps compressed files using the Accept-Encoding HTTP header.
  • To learn more about compression, refer to AWS Docs

cacheKeyParameters

Configures HTTP headers, cookies, and URL query strings to include in the cache key

Type: CdnCacheKey

  • The values included in the cache key are automatically forwarded in the requests that the CDN sends to the origin.

The following example shows:

  • CDN configuration in which we are setting default TTL for the default route to 60 seconds (1 minute).
  • every request, with URL path starting with /static, will be cached for 604800 seconds (1 week).

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
cdn:
enabled: true
listenerPort: 443
cachingOptions:
defaultTTL: 60
routeRewrites:
- path: /static/*
cachingOptions:
defaultTTL: 604800

Specify cache key

The cache key section specifies which parts of a request are included in the cache key.

By default, requests are cached only based on the path.

A cache key can be configured to include headers, cookies, or query params.

CdnCacheKey  API reference
Parent API reference: CdnCachingOptions
cookies

Configures cookies that will be included in the cache key

Type: CacheKeyCookies

  • The cookies included in the cache key are automatically forwarded in the requests that the CDN sends to the origin.
  • By default no cookies are included in the cache key.

headers

Configures headers that will be included included in the cache key

Type: CacheKeyHeaders

  • The headers included in the cache key are automatically forwarded in the requests that the CDN sends to the origin.
  • By default no headers (except Accept-Encoding for compression to work) are included in the cache key.

queryString

Configures query parameters that will be included in the cache key

Type: CacheKeyQueryString

  • The query params included in the cache key are automatically forwarded in the requests that the CDN sends to the origin.
  • By default no query params are included in the cache key.

Cache key headers

CacheKeyHeaders  API reference
Parent API reference: CdnCacheKey
none

No headers are included in the cache key

Type: boolean

whitelist

Only the headers listed are included in the cache key

Type: Array of string

Cache key cookies

CacheKeyCookies  API reference
Parent API reference: CdnCacheKey
none

No cookies are included in the cache key

Type: boolean

whitelist

Only the listed cookies are included in the cache key

Type: Array of string

allExcept

All cookies except the ones listed are included in the cache key

Type: Array of string

all

All cookies are included in the cache key

Type: boolean

Cache key query string

CacheKeyQueryString  API reference
Parent API reference: CdnCacheKey
all

All query params are included in the cache key

Type: boolean

none

No query params are included in the cache key

Type: boolean

whitelist

Only the query parameters listed are included in the cache key

Type: Array of string

Forwarding options

Forwarding options specify which parts of a request get forwarded to the origin.

Different forwarding options can be specified for each route rewrite.

If no forwarding options are specified, Stacktape uses default forwarding options.

CdnForwardingOptions  API reference
customRequestHeaders

Adds static headers that the CDN will add to all requests sent to the origin

Type: Array of CdnCustomRequestHeader

allowedMethods

Configured methods that will be forwarded by the CDN to the origin

Type: Array of string ENUM

Possible values: DELETEGETHEADOPTIONSPATCHPOSTPUT

  • If not set, all methods are forwarded

cookies

Configured cookies forwarded to the origin

Type: ForwardCookies

  • If not set, all cookies are forwarded
  • All cookies that are part of the cache key (see cachingOptions) are automatically forwarded to the origin.

headers

Configured headers will be forwarded to the origin

Type: ForwardHeaders

  • If not set, all headers are forwarded
  • All headers that are part of the cache key (see cachingOptions) are automatically forwarded to the origin.

queryString

Configured query params will be forwarded to the origin

Type: ForwardQueryString

  • If not set, all query string parameters are forwarded
  • All query string parameters that are part of the cache key (see cachingOptions) are automatically forwarded to the origin.

In the following example we are configuring CDN to only forward requests with methods GET and

POST.

resources:
myLoadBalancer:
type: 'application-load-balancer'
properties:
listeners:
- port: 443
protocol: HTTPS
cdn:
enabled: true
listenerPort: 443
forwardingOptions:
allowedMethods:
- 'GET'
- 'POST'

Forwarding headers

ForwardHeaders  API reference
Parent API reference: CdnForwardingOptions
none

No headers are forwarded to the origin

Type: boolean

whitelist

Only the headers listed are forwarded to the origin

Type: Array of string

allViewer

All viewer headers are forwarded to the origin

Type: boolean

allViewerAndWhitelistCloudFront

All viewer headers and additional listed CDN headers are forwarded to the origin

Type: Array of string

Forwarding cookies

ForwardCookies  API reference
Parent API reference: CdnForwardingOptions
none

No cookies are forwarded to the origin

Type: boolean

whitelist

Only the cookies listed are forwarded to the origin

Type: Array of string

all

All cookies are forwarded to the origin

Type: boolean

Forwarding query string

ForwardQueryString  API reference
Parent API reference: CdnForwardingOptions
all

All query params are forwarded to the origin

Type: boolean

none

No query params are forwarded to the origin

Type: boolean

whitelist

Only the query parameters listed are forwarded to the origin

Type: Array of string

API reference

CdnCustomRequestHeader  API reference
Parent API reference: CdnForwardingOptions
headerName
Required

Name of the header

Type: string

value
Required

Value of the header

Type: string