Skip to content

Latest commit

 

History

History
138 lines (96 loc) · 4.62 KB

storage.md

File metadata and controls

138 lines (96 loc) · 4.62 KB

Storage

The storage construct deploys S3 buckets to store files.

Quick start

serverless plugin install -n serverless-lift
service: my-app
provider:
  name: aws

constructs:
    avatars:
        type: storage

plugins:
    - serverless-lift

On serverless deploy, a preconfigured S3 bucket will be created.

How it works

The storage construct creates and configures the S3 bucket for production:

  • Files stored in the bucket are automatically encrypted (S3 takes care of encrypting and decrypting data on the fly, without change to our applications).
  • File versioning is enabled to prevent any accidental data loss. Old versions are automatically purged after 30 days to avoid extra costs.
  • Storage costs are optimized automatically via intelligent tiering.

To learn more about the architecture of this construct, read this article.

Variables

All storage constructs expose the following variables:

  • bucketName: the name of the deployed S3 bucket
  • bucketArn: the ARN of the deployed S3 bucket

This can be used to reference the bucket from Lambda functions, for example:

constructs:
    avatars:
        type: storage

functions:
    myFunction:
        handler: src/index.handler
        environment:
            BUCKET_NAME: ${construct:avatars.bucketName}

How it works: the ${construct:avatars.bucketName} variable will automatically be replaced with a CloudFormation reference to the S3 bucket.

Permissions

By default, all the Lambda functions deployed in the same serverless.yml file will be allowed to read/write into the bucket.

In the example below, there are no IAM permissions to set up: myFunction will be allowed to read and write into the avatars bucket.

constructs:
    avatars:
        type: storage

functions:
    myFunction:
        handler: src/index.handler
        environment:
            BUCKET_NAME: ${construct:avatars.bucketName}

Automatic permissions can be disabled: read more about IAM permissions.

Configuration reference

Encryption

By default, files are encrypted using the default S3 encryption mechanism (free).

Alternatively, for example to comply with certain policies, it is possible to use KMS:

constructs:
    avatars:
        # ...
        encryption: kms

Lifecycle rules

You can configure custom S3 lifecycle rules to automatically delete or transition objects:

constructs:
    avatars:
        type: storage
        lifecycleRules:
            - prefix: tmp/
              expirationInDays: 1
            - prefix: cache/
              expirationInDays: 7

The configuration maps directly to CloudFormation LifecycleConfiguration Rules with the following conveniences:

  • Status: Enabled is added by default (can be overridden)
  • Property names can be written in camelCase (e.g. expirationInDays) or PascalCase (e.g. ExpirationInDays)

These rules are added to the default lifecycle rules that Lift adds (intelligent tiering and old version cleanup).

Extensions

You can specify an extensions property on the storage construct to extend the underlying CloudFormation resources. In the exemple below, the S3 Bucket CloudFormation resource generated by the avatars storage construct will be extended with the new AccessControl: PublicRead CloudFormation property.

constructs:
    avatars:
        type: storage
        extensions:
            bucket:
                Properties:
                    AccessControl: PublicRead

Available extensions

Extension key CloudFormation resource CloudFormation documentation
bucket AWS::S3::Bucket Link

More options

Feel like a common extension pattern should be implemented as part of the construct configuration? Open a GitHub issue.