CloudFront

There are 2 kinds of CloudFront distribution:

  • A ‘Web’ distribution that acts as a CDN for HTTP and HTTPS traffic
  • A ‘Streaming’ distribution that acts as a CDN for RTMP traffic

Serving content over HTTP and HTTPS

Web distributions act an “origin pull” based content delivery network. This means they work a bit like a caching proxy like varnish.

There are several pieces that need configuring. Together these pieces are called a Distribution Config. They are:

  • How should the distribution listen for traffic. What ports, what certs, what domains.
  • What backend servers can traffic be sent to. These are origins.
  • How should traffic be mapped from a request to an origin. For example, you might have a application cluster at / and a search cluster at /search. These are called cache behaviours, and can also change how aggressively you cache based on the URL.

Note

CloudFront configuration changes are slow

Any configuration changes to a distribution are slow - taking around 15 minutes. If using blue/green type techniques during deployment it is best to not do that switch at the CloudFront tier of your stack.

class Distribution

The minimum distribution is:

distribution = self.aws.add_distribution(
    name='www.example.com',
    origins=[{
        "name": "www",
        "domain_name": "backend.example.com",
    }],
    default_cache_behavior={
        "target_origin": "www",
    },
)
name

The name of the distribution. This should be the primary domain that it responds to.

comment

Any comments you want to include about the distribution.

aliases

Alternative domain names that the distribution should respond to.

root_object

The default URL to serve when the users hits the root URL. For example if you want to serve index.html when the user hits www.yoursite.com then set this to ‘/index.html’. The default is ‘/’

enabled

Whether or not this distribution is active. A distribution must be enabled before it can be accessed by a client. It must be disabled before it can be deleted.

origins

A list of Origin resources that the Distribution acts as a front-end for.

default_cache_behavior

How the proxy should behave when none of the rules in behaviors have been applied.

behaviors

A list of CacheBehavior rules about how to map incoming requests to origins.

error_responses

A list of ErrorResponse rules that customize the content that is served for various error conditions.

logging

A LoggingConfig resource that describes how CloudFront should log.

price_class

The price class. By default PriceClass_100 is used, which is the cheapest.

ssl_certificate

A ServerCertificate.

ssl_support_method

If this is set to sni-only then CloudFront uses the SNI mechanism. This only works on browsers newer than IE6. If you need maximum compatibility set it to vip. Your distribution will be assigned its own dedicated IP addresses, negating the need to use SNI. However, this is much more expensive.

ssl_minimum_protocol_version

The default value is TLSv1. To decrease the security of your system you can instead set this to SSLv3. This is strongly discouraged.

Serving content from an S3 bucket

You can pass a S3Origin to a CloudFront distribution to have it serve content from an S3 bucket. If you have a bucket called my-test-bucket then this looks like:

bucket = aws.add_bucket(name="my-test-bucket")

distribution = self.aws.add_distribution(
    name='www.example.com',
    origins=[{
        "name": "www",
        "bucket": bucket,
    }],
    default_cache_behavior={
        "target_origin": "www",
    },
)

You cannot use SSL for an S3 bucket backend - even if using HTTPS between the client and CloudFront, the connection between CloudFront and S3 will always be over unencrypted HTTP.

class S3Origin
name

A name for this backend service. This is used when defining cache behaviors.

bucket

A Bucket to serve content from.

origin_access_identity

Serving content from a backend HTTP or HTTPS service

CloudFront can act as a proxy for any HTTP or HTTP service. Just pass a CustomOrigin to a CloudFront distribution. For example, to serve content from backend.example.com on port 8080 abd 8443:

distribution = self.aws.add_distribution(
    name='www.example.com',
    origins=[{
        "name": "www",
        "domain_name": "backend.example.com",
        "http_port": 8080,
        "https_port": 8043,
    }],
    default_cache_behavior={
        "target_origin": "www",
    },
)
class CustomOrigin
name

A name for this backend service. This is used when defining cache behaviors.

domain_name

A backend server to contact.

http_port

The port that is serving HTTP content. The default value is 80.

https_port

The port that is serving HTTPS content. The default value is 443.

protocol

Specifies what protocol is used to contact this origin server. The default is match-viewer. This means that the backend is contacted with TLS if your client is using https. A less secure option is http-only which can be used to send even secure and confidential traffic in the clear to your backend.

ssl_policy

Specifies the permitted backend ssl versions. Defaults to SSLv3 and TLSv1.

You can also directly connect to an elb load balancer:

.. attribute:: load_balancer

    A `touchdown.aws.elb.LoadBalancer` instance to send HTTP or HTTP
    traffic to.

Cache behaviours

Particularly if you are using CloudFront in front of your entire site you might want different caching policies from different URL’s. For example, there is no need to pass the query string or any cookies to the part of your site that serves CSS. This helps to improve cacheability.

class CacheBehavior
target_origin

The name of a S3Origin or CustomOrigin that this behaviour applies to.

forward_query_string

Whether or not to forward the query string to the origin server.

forward_headers

A whitelist of HTTP headers to forward to the origin server.

If you want to forward all headers you can set this to ['*']. If you set it to an empty list no headers will be sent.

forward_cookies

A list of cookies to forward to the origin server.

If you want to forward all cookies you can set this to ['*']. If you set it to an empty list no cookies will be sent.

viewer_protocol_policy

If set to https-only then all traffic will be forced to use TLS. If set to redirect-to-https then all HTTP traffic will be redirected to the https version of the url. allow-all passes on traffic to the origin using the same protocol as the client used.

default_ttl
min_ttl

The minimum amount of time to cache content for.

max_ttl
compress
allowed_methods

The HTTP methods that are passed to the backend.

cached_methods

The HTTP methods that might be cached. For example, it’s unlikely that you would ever cache a POST request.

smooth_streaming

Whether or not to turn on smooth streaming.

Error handling

class ErrorResponse
error_code

A HTTP error code to replace with static content. For example, 503.

response_page_path

A page to serve from your domain when this error occurs. If / was served by your application and /static was served from S3 then you would want to serve the page from /static, otherwise it is likely your error page would go down when your site went down.

response_code

By default this is the same as the error_code. However you can transform it to a completely different HTTP status code - even 200!

min_ttl

How long can this error be cached for? It can be useful to set this to a low number for very busy sites - as it can act as a pressure release valve. However it is safest to set it to 0.

Access logging

class LoggingConfig

CloudFront can log some information about clients hitting the CDN and sync those logs to an S3 bucket periodically.

enabled

By default this is False. Set it to True to get CDN logs.

include_cookies

Set to True to include cookie information in the logs.

bucket

A Bucket.

path

A path within the S3 bucket to store the incoming logs.

Serving media over RTMP

A streaming distribution allows you to serve static media to your visitors over RTMP. You will need to serve the media player over HTTP(S) so you will probably use a streaming distribution in conjunction with a standard CloudFront distribution.

RTMP requests are accepted on ports 1935 and port 80. This is not configurable.

CloudFront supports:

  • RTMP
  • RTMPT (RTMP over HTTP)
  • RTMPE (Encrypted RTMP)
  • RTMPTE (Encrypted RTMP over HTTP)
class StreamingDistribution
name

The name of the streaming distribution. This should be the primary domain that it responds to.

comment

Any comments you want to include about the distribution.

aliases

Alternative names that the distribution should respond to.

enabled

Whether or not this distribution is active.

origin

A S3Origin that describes where to stream media from.

logging

A StreamingLoggingConfig resource that describes how CloudFront should log.

price_class

The price class. By default PriceClass_100 is used, which is the cheapest.

class StreamingLoggingConfig
enabled

By default this is False. Set it to True to get CDN logs.

bucket

A Bucket.

path

A path within the S3 bucket to store the incoming logs.