Fjall Docs — deploy AWS infrastructure into your own account

Overview

S3Bucket extends the CDK Bucket with Fjall’s secure defaults: SSL enforcement, Block Public Access asserted on every deploy, automatic multipart-upload cleanup, and versioning driven by the application’s backup tier. One class covers private storage, static website hosting, and public read access.

Resource Class

import { S3Bucket } from "@fjall/components-infrastructure/lib/resources/aws/storage/s3";

Basic Usage

Standard Private Bucket

const bucket = new S3Bucket(this, "AppData", {
  bucketName: "api-app-data",
});

Website Hosting Bucket

websiteHosting requires appName. The website exports are keyed on the pair (app, bucket), so two applications with identically named buckets stay deployable side by side.

const website = new S3Bucket(this, "Website", {
  appName: "web",
  bucketName: "web-marketing-site",
  websiteHosting: {
    indexDocument: "index.html",
    errorDocument: "error.html",
  },
});

Public Read Bucket

const publicBucket = new S3Bucket(this, "PublicAssets", {
  bucketName: "web-public-assets",
  publicReadAccess: true,
});

Default Behaviour

Setting	Value	Detail
`enforceSSL`	Always `true`	Non-HTTPS requests are denied by bucket policy. Not overridable.
`removalPolicy`	`RETAIN` in production, `DESTROY` in every other environment	See Removal policy below.
`autoDeleteObjects`	Always `false`	Passing `true` is ignored and raises a synth warning. The CDK auto-delete custom resource is retired (ADR D4.3).
`blockPublicAccess`	`BLOCK_ALL` on non-public buckets	Asserted in the template on every deploy, so a bucket loosened by hand is healed on the next deploy.
`versioned`	Follows the effective backup tier	On for `resilient` and `enterprise`. Set by the application’s `backup.tier` or the per-bucket `backupVaultTier` override.
`bucketKeyEnabled`	`true` for KMS-encrypted buckets	Covers `BucketEncryption.KMS`, `KMS_MANAGED`, and a bare `encryptionKey`. DSSE is excluded: S3 Bucket Keys do not support dual-layer SSE-KMS.
Lifecycle rule `AbortIncompleteMultipartUploads`	Always added, 7 days	Abandoned multipart uploads accrue invisible storage cost forever without it. Added alongside any rules you supply.

Removal policy

The default is environment-aware, not fixed:

production resolves to RETAIN. The bucket survives stack deletion.
staging, development, platform, compliance, root resolve to DESTROY. The bucket is tagged for the deploy-time pre-empty pass, which empties it SDK-side before CloudFormation deletes it.
An unrecognised ENVIRONMENT value fails at synth rather than defaulting to DESTROY. A bare cdk synth with no environment signal falls back to DESTROY, because a template you only inspect deploys nothing.

Pass removalPolicy explicitly to override the default in either direction.

import { RemovalPolicy } from "aws-cdk-lib";

const bucket = new S3Bucket(this, "AppData", {
  bucketName: "api-app-data",
  removalPolicy: RemovalPolicy.RETAIN,
});

Configuration Options

Core Properties

Property	Type	Description	Default
`bucketName`	`string`	Bucket name	Auto-generated
`appName`	`string`	Owning Fjall application, the other half of the website-export key. Required with `websiteHosting`	-
`publicReadAccess`	`boolean`	Allow public read access	`false`
`websiteHosting`	`WebsiteHostingConfig`	Static website hosting config	-
`backupVaultTier`	`BackupTier`	Per-bucket tier override (`standard`, `resilient`, `enterprise`). Beats `appBackupTier` for the versioning default and the `fjall:disasterRecovery:tier` tag	App backup tier
`appBackupTier`	`BackupTier`	The owning application’s backup tier. Filled from the App on factory paths	-
`aliasTargetName`	`string`	Name a `fjallBucket(app, name)` alias target uses to import the website exports	`bucketName ?? id`
`resourcePolicyStatements`	`ResourcePolicyStatement[]`	Declarative bucket-policy statements, each appended via `addToResourcePolicy`	-
`removalPolicy`	`RemovalPolicy`	What happens on stack deletion	Environment-aware, see above
`versioned`	`boolean`	Enable object versioning	From the effective backup tier
`versioningExemption`	`S3VersioningExemption`	Why this bucket stays unversioned by design (`build-output`, `isr-cache`, `cold-tier`, `access-logs`). Stamped as the `fjall:s3:versioning-exempt` tag only while the resolved `versioned` is `false`	-
`eventBridgeEnabled`	`boolean`	Publish the bucket’s object events to the default EventBridge bus	On for a bucket in a backup plan

All standard CDK BucketProps are also supported. enforceSSL and autoDeleteObjects are the two exceptions: both are fixed by the construct.

StorageFactory.build() and CdnFactory fill appName and appBackupTier from the App automatically. Only direct new S3Bucket(...) or new Storage(...) construction needs to pass them.

WebsiteHostingConfig

Property	Type	Description	Default
`indexDocument`	`string`	Index document filename	Required
`errorDocument`	`string`	Error document filename	`"error.html"`

ResourcePolicyStatement

Property	Type	Description	Default
`effect`	`"Allow" \| "Deny"`	Statement effect	Required
`principals`	`string[]`	`"*"` for anonymous, otherwise IAM ARNs (account root, role, user)	Required
`actions`	`string[]`	S3 actions	Required
`sid`	`string`	Statement id	-
`resources`	`string[]`	Target ARNs	The bucket and all its objects
`conditions`	`Record<string, Record<string, string \| string[]>>`	IAM condition block	-

Service and Federated principals are not modelled. The TLS-only enforceSSL deny is applied separately and must not be listed here.

Use Cases

Private Application Storage

The default configuration creates a private bucket with SSL enforcement and BLOCK_ALL public access.

const bucket = new S3Bucket(this, "AppData", {
  bucketName: "api-app-data",
  removalPolicy: RemovalPolicy.RETAIN,
  lifecycleRules: [
    {
      id: "delete-old-versions",
      noncurrentVersionExpiration: Duration.days(90),
    },
  ],
});

Static Website Hosting

Set websiteHosting to serve the bucket as an S3 website. This turns on public read access and opens the bucket-policy halves of Block Public Access.

const website = new S3Bucket(this, "CorporateWebsite", {
  appName: "web",
  bucketName: "www.example.com",
  websiteHosting: {
    indexDocument: "index.html",
    errorDocument: "404.html",
  },
});

Two CloudFormation exports are emitted, WebsiteEndpoint and WebsiteHostedZoneId, both qualified by appName and the bucket name. Domain alias targets import that pair to point DNS at the website endpoint.

Public Asset Delivery

Set publicReadAccess: true for a publicly readable bucket.

const assets = new S3Bucket(this, "PublicAssets", {
  bucketName: "assets.example.com",
  publicReadAccess: true,
  cors: [
    {
      allowedMethods: [HttpMethods.GET, HttpMethods.HEAD],
      allowedOrigins: ["*"],
      allowedHeaders: ["*"],
      maxAge: 3000,
    },
  ],
});

Public buckets expose all contents to the internet. Never store sensitive data in a public bucket. Front the bucket with CloudFront when you need access control.

Public and website buckets open only the two policy halves of Block Public Access (blockPublicPolicy and restrictPublicBuckets). The ACL halves, blockPublicAcls and ignorePublicAcls, stay true, because access here is bucket-policy-based and ACLs are disabled on modern buckets.

Versioning Follows the Backup Tier

Versioning resolves from the bucket’s effective backup tier: the per-bucket backupVaultTier if set, otherwise the application’s backup.tier from App.getApp. Tiers resilient and enterprise turn versioning on. An explicit versioned wins over the tier in either direction. Buckets built through StorageFactory, the StaticSite site bucket, and the Buildkite artefact bucket inherit the application tier automatically.

// App level: every StorageFactory bucket in this app is versioned by default
const app = App.getApp("api", { backup: { tier: "resilient" } });
const media = app.addStorage(
  StorageFactory.build("Media", { encryption: "AES256" }),
);

// Per-bucket override on a direct construction
const bucket = new S3Bucket(this, "ResilientBucket", {
  backupVaultTier: "resilient",
});

When versioning turns on and you supply no lifecycleRules, the construct pairs it with a 30-day noncurrent-version expiry.

Supplying your own lifecycleRules replaces that auto-paired expiry. A versioned bucket with custom rules and no noncurrentVersionExpiration accumulates noncurrent versions forever. Carry noncurrentVersionExpiration: Duration.days(30) explicitly in your rule set.

A bucket in a backup plan publishes its object events

AWS Backup does not watch an S3 bucket to build its continuous backup. It subscribes to the bucket’s object events on the default EventBridge bus and replays them to keep the point-in-time window moving. The bucket-level setting that publishes those events is off unless something turns it on. So a bucket that is versioned, carries a backup tier and claims no exemption — the same three conditions that put it in the plan — has eventBridgeEnabled turned on for it. Reading one condition for both means a bucket cannot be selected into a plan whose events it does not publish.

With the setting off, AWS Backup’s managed rule stays enabled and receives nothing. The snapshot rules keep succeeding and the plan keeps reporting healthy, but the point-in-time window stops advancing past the first full backup. AWS documents that as silent — no notification, alert or backup job failure — and says it cannot detect the setting being turned off.

An explicit eventBridgeEnabled: false still wins: turning it off chooses snapshots over a point-in-time window, and the tier tag the plan selects on is untouched, so the bucket stays enrolled. Turning it on costs a Custom::S3BucketNotifications resource per bucket and one shared notification handler Lambda per stack, which is how CDK writes a bucket’s notification configuration.

Buckets unversioned by design

Some buckets hold contents that are rebuilt or expired rather than kept, and versioning them would only keep a billed copy of everything they discard: a build-output bucket, an ISR cache, a database’s cold tier, the stack’s shared access-log bucket. A construct that leaves such a bucket unversioned says so with versioningExemption, and the bucket carries the fjall:s3:versioning-exempt tag valued with that reason. Tags outlive the stack, so a posture scan can tell a bucket left unversioned on purpose from one that was forgotten. The tag is stamped only while the bucket’s resolved versioned is false: turn versioning on and the marker goes with it. The Payload pattern, the ClickHouse cold tier and the stack’s access-log bucket set it for you.

Advanced Configuration

Encryption

KMS-encrypted buckets get bucketKeyEnabled: true automatically, which cuts KMS request cost. Pass bucketKeyEnabled: false to opt out.

const key = new Key(this, "BucketKey");

const bucket = new S3Bucket(this, "EncryptedBucket", {
  encryption: BucketEncryption.KMS,
  encryptionKey: key,
});

Lifecycle Rules

const bucket = new S3Bucket(this, "ArchiveBucket", {
  versioned: true,
  lifecycleRules: [
    {
      id: "archive-old-objects",
      transitions: [
        {
          storageClass: StorageClass.INFREQUENT_ACCESS,
          transitionAfter: Duration.days(30),
        },
        {
          storageClass: StorageClass.GLACIER,
          transitionAfter: Duration.days(90),
        },
      ],
    },
    {
      // Carried explicitly: custom rules replace the auto-paired expiry
      id: "delete-old-versions",
      noncurrentVersionExpiration: Duration.days(30),
    },
  ],
});

The built-in AbortIncompleteMultipartUploads rule is added on top of these. Do not restate it.

Event Notifications

const bucket = new S3Bucket(this, "ProcessingBucket");

bucket.addEventNotification(
  EventType.OBJECT_CREATED,
  new LambdaDestination(processorFunction),
  { prefix: "uploads/", suffix: ".csv" },
);

bucket.addEventNotification(
  EventType.OBJECT_REMOVED,
  new SqsDestination(deletionQueue),
);

Access Control

Declarative Bucket Policy

resourcePolicyStatements keeps the policy in the props. The shape mirrors the generator’s S3ResourcePlanSchema.resourcePolicyStatements, so a bucket edited by the codemod engine and one written by hand look the same.

const bucket = new S3Bucket(this, "PolicyBucket", {
  resourcePolicyStatements: [
    {
      sid: "OfficeIpReadOnly",
      effect: "Allow",
      principals: ["*"],
      actions: ["s3:GetObject"],
      resources: [`arn:aws:s3:::${bucketName}/public/*`],
      conditions: {
        IpAddress: { "aws:SourceIp": ["203.0.113.0/24"] },
      },
    },
  ],
});

Imperative Bucket Policy

const bucket = new S3Bucket(this, "PolicyBucket");

bucket.addToResourcePolicy(
  new PolicyStatement({
    actions: ["s3:GetObject"],
    resources: [bucket.arnForObjects("public/*")],
    principals: [new AnyPrincipal()],
    conditions: {
      IpAddress: {
        "aws:SourceIp": ["203.0.113.0/24"],
      },
    },
  }),
);

IAM Permissions

const bucket = new S3Bucket(this, "AppData");

// Grant read access
bucket.grantRead(role);

// Grant write access
bucket.grantWrite(role, "uploads/*");

// Grant full access
bucket.grantReadWrite(role);

CORS Configuration

const bucket = new S3Bucket(this, "ApiUploads", {
  cors: [
    {
      allowedHeaders: ["Authorization", "Content-Type"],
      allowedMethods: [HttpMethods.GET, HttpMethods.PUT, HttpMethods.POST],
      allowedOrigins: ["https://app.example.com"],
      exposedHeaders: ["ETag"],
      maxAge: 3000,
    },
  ],
});

Monitoring

Access Logging

const logBucket = new S3Bucket(this, "LogBucket");

const bucket = new S3Bucket(this, "AppData", {
  serverAccessLogsBucket: logBucket,
  serverAccessLogsPrefix: "app-data-logs/",
});

Complete Example

import { S3Bucket } from "@fjall/components-infrastructure/lib/resources/aws/storage/s3";
import { Duration, RemovalPolicy } from "aws-cdk-lib";
import {
  BucketEncryption,
  HttpMethods,
  StorageClass,
} from "aws-cdk-lib/aws-s3";
import { PolicyStatement } from "aws-cdk-lib/aws-iam";

const appBucket = new S3Bucket(this, "ApplicationStorage", {
  bucketName: `${props.appName}-storage-${props.environment}`,

  // Overrides the environment-aware default in non-production too
  removalPolicy: RemovalPolicy.RETAIN,

  // Encryption
  encryption: BucketEncryption.S3_MANAGED,

  // Lifecycle. AbortIncompleteMultipartUploads is added by the construct.
  versioned: true,
  lifecycleRules: [
    {
      id: "archive-old-data",
      transitions: [
        {
          storageClass: StorageClass.INFREQUENT_ACCESS,
          transitionAfter: Duration.days(60),
        },
      ],
    },
    {
      id: "delete-old-versions",
      noncurrentVersionExpiration: Duration.days(30),
    },
  ],

  // CORS for the web app
  cors: [
    {
      allowedHeaders: ["*"],
      allowedMethods: [HttpMethods.GET, HttpMethods.PUT],
      allowedOrigins: [props.appDomain],
      maxAge: 3600,
    },
  ],
});

// Grant app permissions
appRole.addToPolicy(
  new PolicyStatement({
    actions: ["s3:GetObject", "s3:PutObject"],
    resources: [appBucket.arnForObjects("user-uploads/*")],
  }),
);

Best Practices

Set appName on any bucket with websiteHosting, or synth fails.
Set removalPolicy explicitly when a non-production bucket holds data you want to keep.
Carry noncurrentVersionExpiration in every custom rule set on a versioned bucket.
Use encryption for sensitive data, and leave bucketKeyEnabled at its default to keep KMS cost down.
Configure lifecycle transitions to move cold objects to cheaper storage classes.
Enable access logging for security audits.
Use least-privilege IAM grants over broad bucket policies.
Use websiteHosting and publicReadAccess rather than editing Block Public Access or bucket policies by hand.

Next Steps

ECR Repository

Store container images alongside object storage

Lambda Function

Process objects on upload with event notifications

IAM Role

Grant least-privilege access to bucket objects

Storage Factory

Create buckets with the StorageFactory pattern

​Overview

​Resource Class

​Basic Usage

​Standard Private Bucket

​Website Hosting Bucket

​Public Read Bucket

​Default Behaviour

​Removal policy

​Configuration Options

​Core Properties

​WebsiteHostingConfig

​ResourcePolicyStatement

​Use Cases

​Private Application Storage

​Static Website Hosting

​Public Asset Delivery

​Versioning Follows the Backup Tier

​A bucket in a backup plan publishes its object events

​Buckets unversioned by design

​Advanced Configuration

​Encryption

​Lifecycle Rules

​Event Notifications

​Access Control

​Declarative Bucket Policy

​Imperative Bucket Policy

​IAM Permissions

​CORS Configuration

​Monitoring

​Access Logging

​Complete Example

​Best Practices

​Next Steps

ECR Repository

Lambda Function

IAM Role

Storage Factory

Overview

Resource Class

Basic Usage

Standard Private Bucket

Website Hosting Bucket

Public Read Bucket

Default Behaviour

Removal policy

Configuration Options

Core Properties

WebsiteHostingConfig

ResourcePolicyStatement

Use Cases

Private Application Storage

Static Website Hosting

Public Asset Delivery

Versioning Follows the Backup Tier

A bucket in a backup plan publishes its object events

Buckets unversioned by design

Advanced Configuration

Encryption

Lifecycle Rules

Event Notifications

Access Control

Declarative Bucket Policy

Imperative Bucket Policy

IAM Permissions

CORS Configuration

Monitoring

Access Logging

Complete Example

Best Practices

Next Steps