Overview and basic concepts

• CDN (Content Delivery Network) is a geographically distributed network that helps you deliver your application content fast and secure to the end-users across the globe.
• By distributing and caching content across 310+ globally dispersed Points of Presence (PoPs - also called edge locations) you can significantly decrease the latency of data delivery as well as reduce load on your application.
• CDN helps you improve security with automatic TLS and defends your application against DDoS attacks at no additional costs.

CDN explained

CDN can be seen as a layer between your application(origin) and clients connecting to the application.

• Instead of clients sending request directly to your application (origin - bucket, http-api-gateway or application-load-balancers), they send request to CDN.
• CDN delivers the request from the client to the closest CDN PoP (Point of Presence) edge location.
• CDN PoP gets a response from your application (origin).
• CDN PoP sends the response to the client. At the same time it caches the response.
• On subsequent requests from clients, CDN PoP can respond immediately using the cached response (cache hit).
• You can control which responses should be cached and for how long. Read section Caching configuration for more information.

Basic usage

In Stacktape, you can use CDN by configuring it on the specified resource (bucket, http-api-gateway or application-load-balancers). This resource then becomes the main origin for the CDN, which means that the requests sent to the CDN will be forwarded to this resource.

YAML
Typescript
Copy
resources:
  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true

You can also configure route rewrites to forward specified paths to other origins (other than the main origin). This enables you to have hybrid infrastructures where some requests are routed to bucket (to get the static content) and others are routed to http-api-gateway API (to get the dynamic content).

CDN with bucket

With bucket you can enable CDN using two lines.

YAML
Typescript
Copy
resources:
  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true

By default, CDN caches content returned from the bucket for 6 months.

Most comon use case for using CDN with a bucket is using the bucket to serve your static website:

• Stacktape can automatically set-up correct cache-control headers for your static content when uploading the content to the bucket.

• See Cache control section to understand how to control the caching behavior.

CDN with http-api-gateway

With http-api-gateway you can enable CDN using two lines.

YAML
Typescript
Copy
resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true

By default, CDN does not cache any content returned from the http-api-gateway, as it assumes that all content returned by http-api-gateway is dynamic. You can control caching behaviour by sending the cache control header within response from http-api-gateway. See Cache control section for more information.

CDN with application-load-balancer

With http-api-gateway you can enable CDN using two lines. If your application-load-balancer uses custom listeners you need to specify the port of a listener to which the CDN should deliver traffic.

YAML
Typescript
Copy
resources:
  myApiGateway:
    type: application-load-balancer
    properties:
      cdn:
        enabled: true

By default, CDN does not cache any content returned from the application-load-balancer, as it assumes that all content returned by application-load-balancer is dynamic. You can control caching behaviour by sending the cache control header within response from application-load-balancer. See Cache control section for more information.

Custom domain names

YAML
Typescript
Copy
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        customDomains:
          - domainName: mydomain.com

Edge lambda functions

For more information refer to Edge lambda functions page.

YAML
Typescript
Copy
resources:
  authFunction:
    type: edge-lambda-function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: auth-function.ts

  myBucket:
    type: bucket
    properties:
      cdn:
        enabled: true
        edgeFunctions:
          onRequest: authFunction

Cache control

There are 2 ways to control caching behavior of the CDN:

1. By using cache-control header in the responses from your origins.

   • cache-control header is automatically detected by the CDN and the response is cached based on the directives in the header.
   • to see how to configure cache-control header, refer to respective sections for bucket or http-api-gateway/application-load-balancer
   • this approach gives you fine-grained control over caching behavior and is recommended.

2. By setting (minTTL, maxTTL, defaultTTL) in CDN caching options.

   • this approach lets you set basic caching rules, but is overall less flexible.
   • see section CDN cache options

Cache-Control header with buckets

You can set cache-control header by setting metadata on the objects uploaded to your bucket.

Stacktape can set the correct cache-control headers automatically when uploading objects to your bucket, if you:

• choose to upload your objects using directory upload functionality,
• use one of the headers presets. The header presets are made for most common use-cases, but you are also able to customize them and set your own headers.

YAML
Typescript
Copy
resources:
  myBucket:
    type: bucket
    properties:
      directoryUpload:
        directoryPath: my-web/build
        headersPreset: static-website
      cdn:
        enabled: true

Cache-Control header with http-api-gateway/application-load-balancer

When using CDN with a http-api-gateway or an application-load-balancer, you can set cache-control header by sending it with response from your application.

Consider following example:

YAML
Typescript
Copy
resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true

  myFunction:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: hello.ts
      events:
        - type: http-api-gateway
          properties:
            httpApiGatewayName: myApiGateway
            method: GET
            path: /hello

Copy
export default async (event, context) => {
  return {
    statusCode: 200,
    statusDescription: '200 OK',
    isBase64Encoded: false,
    headers: {
      'Content-Type': 'text/plain',
      'Cache-Control': 'max-age=30'
    },
    body: 'Hello !!!'
  };
};

Similar configuration could be done with aplication-load-balancer. Or you could swap the function for a container-workload since the response format is same.

To understand directives in the cache-control header and how to use them, refer to MDN docs.

CDN caching options

Caching options enable you to specify default caching behavior for your CDN.

You can specify different caching options for each route rewrite. This gives you ability to set different default caching options for different routes.

If you do not specify caching options, Stacktape uses default caching options (depending on the target origin):

In the following example:

• We are setting default TTL for the default route to 60 seconds (1 minute).
• Every request, with URL path starting with /static has default TTL 604800 seconds (1 week).
• If responses from origin do not contain cache-control header, default TTL is used.

YAML
Typescript
Copy
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        cachingOptions:
          defaultTTL: 60
        routeRewrites:
          - path: /static/*
            cachingOptions:
              defaultTTL: 604800

Controlling cache key

The cache key is the unique identifier for every object in the cache. It determines whether a client request results in a cache hit. A cache hit occurs when a client request generates the same cache key as a prior request, and the object for that cache key is in the CDN PoP location's cache. If the object is in the cache and is valid, it can be served to client without sending request to the origin.

• A cache key can be configured to include headers, cookies, or query params.
• Every part of request that is included in a cache key is automatically forwarded to the origin. If you wish to forward parts of request to the origin but NOT include them in the cache key, use forwarding options
• Cache key can be controlled by using cacheKeyParameters within caching options.

If you do not specify cache key, Stacktape uses default cache key (depending on the target origin):

Example usage: If your origin uses the Accept-Language HTTP header in client requests to return different content based on the client’s language, you might want to include this header in the cache key.

YAML
Typescript
Copy
resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true
        cachingOptions:
          cacheKeyParameters:
            headers:
              whitelist:
                - Accept-Language

CDN forwarding options

Forwarding options specify which parts of a request get forwarded to the origin. You can also filter which types (methods) of requests are forwarded.

Different forwarding options can be specified for each route rewrite.

If no forwarding options are specified, Stacktape uses default forwarding options (depending on the target origin):

YAML
Typescript
Copy
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        forwardingOptions:
          allowedMethods:
            - 'GET'
            - 'POST'

Route rewrites

Route rewrites can be used to route incoming requests to different origins: I.e., instead of forwarding a request to the main origin (the one CDN is attached to), the request can be forwarded to some other origin (http-api-gateway, bucket, application-load-balancer or a custom origin).

Routing to bucket

In the following example:

• we are routing all requests with url path starting with /static to the bucket myBucket.
• all other requests are routed to the http-api-gateway myHttpApi (default origin).

YAML
Typescript
Copy
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /static/*
            routeTo:
              type: bucket
              properties:
                bucketName: myBucket
                disableUrlNormalization: true

  myBucket:
    type: 'bucket'

Routing to application-load-balancer

In the following example:

• we are routing all requests with url path starting with /app2 to the application-load-balancer myLoadBalancer.
• all other requests are routed to the http-api-gateway myHttpApi (default origin).

YAML
Typescript
Copy
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /app2/*
            routeTo:
              type: 'application-load-balancer'
              properties:
                loadBalancerName: myLoadBalancer

  myLoadBalancer:
    type: 'application-load-balancer'

Routing to http-api-gateway

In the following example:

• we are routing all requests with url path starting with /app2/ to the http-api-gateway appApiGateway.
• all other requests are routed to the http-api-gateway myHttpApi (default origin).

YAML
Typescript
Copy
resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /app2/*
            routeTo:
              type: 'http-api-gateway'
              properties:
                httpApiGatewayName: appApiGateway

  appApiGateway:
    type: 'http-api-gateway'

Routing to custom origin

In the following example:

• we are routing all request with url path starting with /external to the custom origin (my-custom-origin.example.com).
• all other requests are routed to the application-load-balancer myLoadBalancer.

YAML
Typescript
Copy
resources:
  myLoadBalancer:
    type: 'application-load-balancer'
    properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /external/*
            routeTo:
              type: custom-origin
              properties:
                domainName: my-custom-origin.example.com

Automatic invalidation

By default Stacktape invalidates the CDN cache after each deploy. This means that the cache is flushed and new requests will result in requests to the origin. This in turn ensures that only new content is served to the clients.

You can disable automatic invalidation by setting invalidateAfterDeply to false.

YAML
Typescript
Copy
resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true
        invalidateAfterDeploy: false

Setting price class

You can set price class to reduce the costs for your CDN. Setting price class affecs the number locations (PoPs) from which the CDN serves traffic.

YAML
Typescript
Copy
resources:
  myApiGateway:
    type: http-api-gateway
    properties:
      cdn:
        enabled: true
        cloudfrontPriceClass: PriceClass_200

API reference