Buckets provide a way to store and retrieve any amount of data, at any time, from anywhere on the web. They are a good choice for a variety of use cases, including hosting websites, storing user-generated content, and for backup and disaster recovery.

A bucket is a collection of objects, where an object is a file and any metadata that describes it. Buckets have a flat structure, but you can simulate a folder hierarchy by using a common prefix for your object names (e.g., photos/).

Under the hood, Stacktape uses Amazon S3 for buckets.

When to use them

Buckets are ideal for storing large amounts of data. They are not recommended for use cases that require very low read/write latency.

Advantages

• Easy to use: S3 provides a simple, HTTP-based API.
• Serverless: Buckets scale automatically, and you only pay for what you use.
• Highly available and durable: S3 is designed for 99.999999999% (eleven 9s) of data durability, storing objects across multiple Availability Zones.
• Flexible storage classes: You can choose from multiple storage classes with different latencies, prices, and durability characteristics.
• Access control: You can easily control who can access your bucket.
• Encryption: Supports server-side encryption.
• Integrations: You can trigger a function or a batch job in response to bucket events.

Disadvantages

• Performance: Read and write operations are significantly slower than with block storage (a physical disk attached to a machine).

Basic usage

resources:
  myBucket:
    type: bucket

  myFunction:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my/lambda.ts
      environment:
        - name: BUCKET_NAME
          value: $ResourceParam('myBucket', 'arn')
      connectTo:
        - myBucket

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;

Directory upload

You can automatically upload the contents of a local directory to a bucket during deployment.

resources:
  myBucket:
    type: bucket
    properties:
      directoryUpload:
        directoryPath: ../public

Adding metadata

You can add metadata, such as headers and tags, to the files you upload. This is useful for setting Cache-Control headers for a static website or for filtering objects in lifecycle rules.

Encryption

If enabled, all objects uploaded to the bucket will be encrypted on the server side using the AES-256 algorithm.

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

CORS

You can configure Cross-Origin Resource Sharing (CORS) to allow web applications from other domains to access the resources in your bucket.

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

Versioning

You can enable versioning to keep a complete history of all object versions. This is useful for protecting against accidental deletions or overwrites.

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

CDN

You can place an AWS CloudFront CDN in front of your bucket to cache its content in edge locations around the world, reducing latency for your users. This is a common pattern for serving static websites.

For more information, see the CDN documentation.

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

Object lifecycle rules

Lifecycle rules allow you to automate the management of your objects. You can define rules to transition objects to different storage classes or delete them after a certain period.

Storage class transition

You can transition objects to a different storage class to save costs. For example, you can move infrequently accessed data to a cheaper, long-term storage class like Glacier.

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

Expiration

You can configure objects to be automatically deleted after a specified number of days.

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

Non-current version class transition

You can transition previous versions of an object to a different storage class.

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

Non-current version expiration

You can automatically delete previous versions of an object after a specified number of days.

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

Abort incomplete multipart upload

You can abort multipart uploads that do not complete within a specified number of days to avoid storing incomplete object parts.

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

Accessibility

You can control who can access your bucket and its objects.

Accessibility modes

Access policy statements

For fine-grained control, you can define custom access policy statements. This requires knowledge of AWS IAM. For examples, see the AWS documentation.

resources:
  myBucket:
    type: bucket
    properties:
      accessibility:
        accessibilityMode: private
        accessPolicyStatements:
          - Resource:
              - $ResourceParam('myBucket', 'arn')
            Action:
              - 's3:ListBucket'
            Principal: '*'

Referenceable parameters

API reference