logoStacktape docs




Buckets

Overview and basic concepts

  • Buckets allow you to persistently store files.
  • A Bucket is a collection of "objects". An object is a file and any metadata (headers, tags,...) that describes that file.
  • Buckets are easy to use, reliable, durable and highly available. They are powered by AWS S3 object storage service.
  • Buckets are serverless. They scale automatically to meet your needs and you are paying only for the files saved (not unused capacity).
  • Buckets have a flat structure instead of a hierarchy like you would find in a file system. However, you can simulate a "folder hierarchy" by using a common prefix. For example, all objects stored with a name that starts with photos/ prefix will be shown in the same "folder" in the AWS console.

When to use

  • Buckets can be used to host websites, store user-generated content, store data for Big data analytics, serve as data lakes, backup and restore, archives, etc.

  • Because of performance reasons, object storage in general is not optimal for use-cases that require very low read/write latency.

Advantages

  • Easy to use - AWS S3 has a simple, HTTP-based API. You can also easily manipulate your objects using an AWS SDK.

  • Serverless - Bucket automatically scales to meet your needs. You don't have to worry about scaling your storage size and are paying only for the files saved.

  • Reliabile & highly available - S3 Buckets are designed for 99.999999999% (11 9’s) of data durability. Files (objects) are stored across multiple physical locations (Availability zones).

  • Storage flexibility - You can store your files in multiple storage classes. Different storage classes have different latencies, pricing and durability.

  • Access control - You can easily control who can access your bucket.

  • Supports encryption - Supports server-side encryption.

  • Integrations - You can easily trigger a function or a batch-job in a reaction to a bucket event.

Disadvantages

  • Performance - Compared to using a block storage (physical disk attached to a machine), reading/write operations are significantly slower.

Basic usage

resources:
myBucket:
type: bucket
myFunction:
type: function
properties:
packageConfig:
filePath: path/to/my/lambda.ts
environment:
- name: BUCKET_NAME
value: $Param('myBucket', 'Bucket::Name')
accessControl:
allowAccessTo:
- myBucket

Lambda function connected to a bucket

import { S3 } from '@aws-sdk/client-s3';
const s3 = new S3({});
// getObject returns a readable stream, so we need to transform it to string
const streamToString = (stream) => {
const chunks = [];
return new Promise((resolve, reject) => {
stream.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
stream.on('error', (err) => reject(err));
stream.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
});
};
const handler = async (event, context) => {
await s3.putObject({
Bucket: process.env.BUCKET_NAME,
Key: 'my-file.json',
Body: JSON.stringify({ message: 'hello' }) // or fs.createReadStream('my-source-file.json')
});
const res = await s3.getObject({
Bucket: process.env.BUCKET_NAME,
Key: 'my-file.json'
});
const body = await streamToString(res.Body);
};
export default handler;

Lambda function that uploads and downloads a file from a bucket

Directory upload

  • Allows you to upload a specified directory to the bucket on every deployment
  • After the upload is finished, your bucket will contain the contents of the local folder.
  • Files are uploaded using parallel, multipart uploads.

Existing contents of the bucket will be deleted and replaced with the contents of the local directory. You should not use directoryUpload for buckets with application-generated or user-generated content.

resources:
myBucket:
type: bucket
properties:
autoSyncDirectory: '../public'

Uploads the public folder to the bucket on every deployment

directoryPath
Required

Path to the directory that should be uploaded to the bucket

Type: string

  • After the sync is finished, your bucket will contain the contents of the local folder.
  • Path is relative to current working directory.

Existing contents of the bucket will be deleted and replaced with the contents of the local directory. You should not use bucket with autoSync enabled for application-generated or user-generated content.

filters

Filters allow you to set properties of files (objects) that match the filter pattern

Type: Array of DirectoryUploadFilter

skipFiles

Configures which files should be skipped from upload (glob patterns).

Type: Array of string

  • Relative to the directoryPath

Adding metadata

  • You can add metadata to uploaded files. You can configure headers and tags.
  • Filters allow you to configure properties of files (objects) that match the filter pattern.
  • Configurable properties:
    • headers: when a client makes a request for an object, these headers will be added to the HTTP response. If you are using a CDN, all headers will be forwarded. If you are using the bucket to host a website, this can be for example used to add cache-control headers on a per-file basis (different cache behavior for different file types).
    • tags: can be used to filter specific objects, for example in Lifecycle rules.
DirectoryUploadFilter  API reference
Parent API reference: DirectoryUpload
includePattern
Required

Configures which files should be handled by this filter (glob pattern)

Type: string

  • Relative to the directoryPath

excludePattern

Configures which files should be excluded from this filter, even if they match the include pattern (glob pattern)

Type: string

  • Relative to the directoryPath

headers

Configures HTTP headers for files (objects) that match this filter

Type: Array of KeyValuePair

  • If you are using a CDN, these headers will be forwarded to the client.
  • This can be used to implement HTTP caching for your static content.

tags

Tags to apply to the files that match this filter

Type: Array of KeyValuePair

  • Tags help you to categorize your objects. They can also be used to filter objects when using lifecycleRules
  • To learn more about object tagging, refer to AWS Docs

A single file (object) can have only one tag with the same key.

Encryption

  • If enabled, all objects uploaded to the bucket will be server-side encrypted using the AES256 algorithm.

resources:
myBucket:
type: bucket
properties:
encryption: true

Cors

  • Web browsers use CORS (Cross-Origin Resource Sharing) to block the website from making requests to a different origin (server) than the one the website is served from. This means that if you make a request from a website served from https://my-website.s3.eu-west-1.amazonaws.com/ to https://my-api.my-domain.com, the request will fail.

  • If you enable CORS and do not specify any cors rules, the default rule with following configuration is used:

    • AllowedMethods: GET, PUT, HEAD, POST, DELETE
    • AllowedOrigins: '*'
    • AllowedHeaders: Authorization, Content-Length, Content-Type, Content-MD5, Date, Expect, Host, x-amz-content-sha256, x-amz-date, x-amz-security-token
  • When the bucket receives a preflight request from a browser, it evaluates the CORS configuration for the bucket and uses the first CORS rule that matches the incoming browser request to enable a cross-origin request. For a rule to match, the following conditions must be met:

    • The request's Origin header must match one of allowedOrigins element.
    • The request method (for example, GET or PUT) or the Access-Control-Request-Method header in case of a preflight OPTIONS request must be one of the allowedMethods.
    • Every header listed in the request's Access-Control-Request-Headers header on the preflight request must match one of headers allowedHeaders.

resources:
myBucket:
type: bucket
properties:
cors:
enabled: true

BucketCorsConfig  API reference
Parent API reference: Bucket
enabled
Required

Enables CORS (Cross-Origin Resource Sharing) HTTP headers for the bucket

Type: boolean

  • If you enable CORS and do not specify any cors rules, default rule with following configuration is used:
    • AllowedMethods: GET, PUT, HEAD, POST, DELETE
    • AllowedOrigins: '*'
    • AllowedHeaders: Authorization, Content-Length, Content-Type, Content-MD5, Date, Expect, Host, x-amz-content-sha256, x-amz-date, x-amz-security-token

corsRules
Required

List of CORS rules

Type: Array of BucketCorsRule

  • Web browsers use CORS (Cross-Origin Resource Sharing) to block the website from making requests to a different origin (server) than the one the website is served from. This means that if you make a request from a website served from https://my-website.s3.eu-west-1.amazonaws.com/ to https://my-api.my-domain.com, the request will fail.

  • If you enable CORS and do not specify any cors rules, the default rule with following configuration is used:

    • AllowedMethods: GET, PUT, HEAD, POST, DELETE
    • AllowedOrigins: '*'
    • AllowedHeaders: Authorization, Content-Length, Content-Type, Content-MD5, Date, Expect, Host, x-amz-content-sha256, x-amz-date, x-amz-security-token
  • When the bucket receives a preflight request from a browser, it evaluates the CORS configuration for the bucket and uses the first CORS rule that matches the incoming browser request to enable a cross-origin request. For a rule to match, the following conditions must be met:

    • The request's Origin header must match one of allowedOrigins element.
    • The request method (for example, GET or PUT) or the Access-Control-Request-Method header in case of a preflight OPTIONS request must be one of the allowedMethods.
    • Every header listed in the request's Access-Control-Request-Headers header on the preflight request must match one of headers allowedHeaders.

BucketCorsRule  API reference
Parent API reference: BucketCorsConfig
allowedOrigins

Origins to accepts cross-domain requests from

Type: Array of string

  • Origin is a combination of scheme (protocol), hostname (domain), and port of the URL
  • Examples of same origin: http://example.com/app1:80 http://example.com/app2
  • Examples of a different origin: http://example.com/app1 https://example.com/app2

allowedHeaders

Allowed HTTP headers

Type: Array of string

  • Each header name in the Access-Control-Request-Headers header of a preflight request must match a corresponding entry in the rule.

allowedMethods

Allowed HTTP methods

Type: Array of string ENUM

Possible values: *DELETEGETHEADPATCHPOSTPUT

exposedResponseHeaders

Response headers that should be made available to scripts running in the browser, in response to a cross-origin request

Type: Array of string

maxAge

Time in seconds that browser can cache the response for a preflight request

Type: number

Versioning

  • If enabled, bucket keeps multiple variants of an object.
  • This can help you to recover objects from an accidental deletion/overwrite, or to store multiple objects with the same name.

resources:
myBucket:
type: bucket
properties:
versioning: true

Object lifecycle rules

  • Lifecycle rules allow you to configure what happens to your objects after a configured period of time.
  • They can be deleted, transitioned to another storage class, etc.
  • These rules can be applied to only a subset of objects in the bucket using path prefix and object tags.

Storage class transition

  • By default, all objects are in the standard (general purpose) class.
  • Depending on your access patterns, you can transition your objects to a different storage class to save costs.
  • To better understand differences between storage classes, refer to AWS Docs
  • To learn more about storage class transitions, refer to AWS Docs

resources:
myBucket:
type: bucket
properties:
lifecycleRules:
- type: class-transition
properties:
daysAfterUpload: 90
storageClass: 'GLACIER'

Bucket configured to transfer all objects to GLACIER storage class 90 days after being uploaded

ClassTransition  API reference
Parent API reference: Bucket
type
Required

No description

Type: string "class-transition"

properties.daysAfterUpload
Required

Number of days after the object is transitioned to another storage class

Type: number

  • Relative to the date uploaded
  • Depending on how often you need to access your objects, transitioning them to another storage can lead to a significant price reduction.

properties.storageClass
Required

Storage class to transition to

Type: string ENUM

Possible values: DEEP_ARCHIVEGLACIERINTELLIGENT_TIERINGONEZONE_IASTANDARD_IA

  • By default, all objects are in the standard (general purpose) class.
  • Depending on your access patterns, you can transition your objects to a different storage class to save costs.
  • To better understand differences between storage classes, refer to AWS Docs
  • To learn more about storage class transitions, refer to AWS Docs

properties.prefix

Prefix of the objects to which the lifecycle rule is applied

Type: string

properties.tags

Tags of the objects to which the lifecycle rule is applied

Type: Array of KeyValuePair

  • To learn more about tagging objects, refer to AWS Docs

Expiration

Allows you to delete objects from the bucket after the specified amount of days after upload.

Expiration  API reference
Parent API reference: Bucket
type
Required

No description

Type: string "expiration"

properties.daysAfterUpload
Required

Number of days after the object is considered expired

Type: number

  • Relative to the date uploaded

properties.prefix

Prefix of the objects to which the lifecycle rule is applied

Type: string

properties.tags

Tags of the objects to which the lifecycle rule is applied

Type: Array of KeyValuePair

  • To learn more about tagging objects, refer to AWS Docs

This can be useful in cases if objects become irrelevant for you after some time. These objects can be deleted, thus saving you storage costs.

The following example shows:

  • All uploaded objects are transferred to GLACIER storage class 90 days after upload.
  • After 365 days, objects are completely deleted.

resources:
myBucket:
type: bucket
properties:
lifecycleRules:
- type: class-transition
properties:
daysAfterUpload: 90
storageClass: 'GLACIER'
- type: expiration
properties:
daysAfterUpload: 365

Non-current version class transition

Allows you to transition versioned objects into a different storage class.

NonCurrentVersionClassTransition  API reference
Parent API reference: Bucket
type
Required

No description

Type: string "non-current-version-class-transition"

properties.daysAfterVersioned
Required

Number of days after the non-current object is transitioned to another storage class

Type: number

  • Relative to date it became non-current (old)
  • Depending on how often you need to access your objects, transitioning them to another storage can lead to a significant price reduction.

properties.storageClass
Required

Storage class to transition to

Type: string ENUM

Possible values: DEEP_ARCHIVEGLACIERINTELLIGENT_TIERINGONEZONE_IASTANDARD_IA

  • To learn more about storage classes and transitions, refer to AWS Docs

properties.prefix

Prefix of the objects to which the lifecycle rule is applied

Type: string

properties.tags

Tags of the objects to which the lifecycle rule is applied

Type: Array of KeyValuePair

  • To learn more about tagging objects, refer to AWS Docs

Same as class transition rule but applied to old versions of objects. This can be useful when you want to archive old versions of an object after some time to save you costs.

The following example shows:

  • all versioned objects are transferred to GLACIER storage class 10 days after they are versioned (become non-current version).

resources:
myBucket:
type: bucket
properties:
versioning: true
lifecycleRules:
- type: non-current-version-class-transition
properties:
daysAfterVersioned: 10
storageClass: 'DEEP_ARCHIVE'

Non-current version expiration

Allows you to delete old versions of objects from the bucket after the specified amount of days after they are versioned.

NonCurrentVersionExpiration  API reference
Parent API reference: Bucket
type
Required

No description

Type: string "non-current-version-expiration"

properties.daysAfterVersioned
Required

Number of days after the non-current object becomes expired.

Type: number

  • Relative to date it became non-current (old)
  • This rule is effective only if the bucket has versioning enabled.

properties.prefix

Prefix of the objects to which the lifecycle rule is applied

Type: string

properties.tags

Tags of the objects to which the lifecycle rule is applied

Type: Array of KeyValuePair

  • To learn more about tagging objects, refer to AWS Docs

This can be useful if you only need to keep older versions of objects for some time and then they can be deleted thus saving you storage costs.

The following example shows:

  • all versioned objects are deleted ten days after being version (become non-current version).

resources:
myBucket:
type: bucket
properties:
versioning: true
lifecycleRules:
- type: non-current-version-expiration
properties:
daysAfterVersioned: 10

Abort incomplete multipart upload

Allows you to stop multipart uploads that do not complete within a specified number of days after being initiated.

AbortIncompleteMultipartUpload  API reference
Parent API reference: Bucket
type
Required

No description

Type: string "abort-incomplete-multipart-upload"

properties.daysAfterInitiation
Required

Number of days after the in-complete upload is aborted, and it's parts deleted

Type: number

  • Relative to the start of multipart upload

properties.prefix

Prefix of the objects to which the lifecycle rule is applied

Type: string

properties.tags

Tags of the objects to which the lifecycle rule is applied

Type: Array of KeyValuePair

  • To learn more about tagging objects, refer to AWS Docs

When a multipart upload is not completed within the timeframe, it becomes eligible for an abort operation, and Amazon S3 stops the multipart upload (and deletes the parts associated with the multipart upload, thus saving you costs).

The following example shows:

  • all incomplete uploads are stopped (and parts deleted) 5 days after initiation of multipart upload.

resources:
myBucket:
type: bucket
properties:
lifecycleRules:
- type: abort-incomplete-multipart-upload
properties:
daysAfterInitiation: 5

Accessibility

  • Configures who can access the bucket.
BucketAccessibility  API reference
Parent API reference: Bucket
accessibilityMode
Default: 'private'Required

Configures pre-defined accessibility modes for the bucket

Type: string ENUM

Possible values: privatepublic-readpublic-read-write

  • Allows you to easily configure the most commonly used access patterns.
  • Available modes:
    • public-read-write - Everyone can read from and write to the bucket.
    • public-read - Everyone can read from the bucket. Only workloads and entities with sufficient IAM permissions can write to the bucket.
    • private - (default) Only workloads and entities with sufficient IAM permissions can read from or write to the bucket.
  • For funtions, batch jobs and container workloads, you can grant required IAM permissions to read/write from the bucket using allowsAccessTo or iamRoleStatements in their configuration.

accessPolicyStatements

Advanced access configuration that leverages IAM policy statemns

Type: Array of BucketPolicyIamRoleStatement

  • Gives fined-grained access control to the bucket

Accessibility modes

  • Allows you to easily configure the most commonly used access patterns.
  • Available modes:
    • public-read-write - Everyone can read from and write to the bucket.
    • public-read - Everyone can read from the bucket. Only workloads and entities with sufficient IAM permissions can write to the bucket.
    • private - (default) Only workloads and entities with sufficient IAM permissions can read from or write to the bucket.
  • For funtions, batch jobs and container workloads, you can grant required IAM permissions to read/write from the bucket using allowsAccessTo or iamRoleStatements in their configuration.

Access policy statements

resources:
myBucket:
type: bucket
properties:
accessibility:
restrictAccess: private
accessPolicyStatements:
- Resource:
- $Param('myBucket', 'Bucket::Arn')
Action:
- 's3:ListBucket'
Principal: '*'

BucketPolicyIamRoleStatement  API reference
Parent API reference: BucketAccessibility
Principal
Required

No description

Type: UNSPECIFIED

Resource
Required

List of resources we want to access

Type: Array of string

  • See AWS reference here.

Sid

Statement identifier.

Type: string

  • See AWS reference here.

Effect

Effect of the statement

Type: string

  • See AWS reference here.

Action

List of actions allowed/denied by the statement

Type: Array of string

see AWS reference here.

Condition

No description

Type: UNSPECIFIED

CDN

  • CDN is a globally distributed network that can cache reponses from your bucket 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.
BucketCdnConfiguration  API reference
Parent API reference: Bucket
enabled
Required

Enables the CDN

Type: boolean

optimizeForSinglePageApp

Optimizes the bucket to serve a SPA (Single Page Application)

Type: boolean

Automatically configures the CDN to effectively serve a single page application. This does 3 things:

  • Configures cache for the objects served by the CDN. Objects are cached at the edge location. If the cache expires, it's downloaded from the origin bucket again.
  • Configures HTTP cache-control headers (used for browser caching).
  • Automatically invalidates the CDN cache after every deployment.

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

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:
myBucket:
type: bucket
properties:
cdn:
enabled: true

Custom domain

  • Stacktape allows you to connect your custom domain to the CDN.
  • If your domain DNS records are controlled by AWS Route 53, Stacktape automatically generates correct TLS certificates for your domain and creates DNS records.
  • 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. you can provision certificate by specifying customCertificateArn and specifying disableDnsRecordCreation
DomainConfiguration  API reference
Parent API reference: BucketCdnConfiguration
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:
myBucket:
type: bucket
properties:
cdn:
enabled: true
domainNames:
- domainName: mydomain.com

Route rewrites

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

CdnRouteRewrite  API reference
Parent API reference: BucketCdnConfiguration
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 /images to the bucket myBucket2 which contains all of our images. All other requests are routed to the bucket myBucket.

resources:
myBucket:
type: bucket
properties:
cdn:
enabled: true
routeRewrites:
- path: /images/*
routeTo:
type: bucket
properties:
bucketName: myBucket2
disableUrlNormalization: true
myBucket2:
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 /api to the load-balancer myLoadBalancer. All other requests are routed to the bucket myBucket.

resources:
myBucket:
type: bucket
properties:
cdn:
enabled: true
routeRewrites:
- path: /api/*
routeTo:
type: 'application-load-balancer'
properties:
loadBalancerName: myLoadBalancer
listenerPort: 443
myLoadBalancer:
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

The following example shows:

  • CDN configuration in which we are routing all requests with URL path starting with /api to the http-api-gateway appApiGateway.
  • All other requests are routed to the bucket myBucket.

resources:
myBucket:
type: bucket
properties:
cdn:
enabled: true
routeRewrites:
- path: /api/*
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
Parent API reference: (BucketCdnConfiguration or CdnRouteRewrite)
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 604800 seconds (7 days).
  • Every request with URL path ending with .*jpg will be cached for 2592000 seconds (30 days).

resources:
myBucket:
type: bucket
properties:
cdn:
enabled: true
cachingOptions:
defaultTTL: 604800
routeRewrites:
- path: '*.jpg'
cachingOptions:
defaultTTL: 2592000

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
Parent API reference: (BucketCdnConfiguration or CdnRouteRewrite)
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.

resources:
myBucket:
type: bucket
properties:
cdn:
enabled: true
forwardingOptions:
allowedMethods:
- 'GET'

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