bucket

S3 buckets in AWS are the standard way to store files within “buckets”. Stackattack creates S3 buckets with secure defaults including encryption and public access blocking.

import * as saws from "@stackattack/aws";

const ctx = saws.context();
const storage = saws.bucket(ctx);

export const storageBucket = storage.bucket;

Usage

After deploying a bucket, you can interact with it using:

AWS CLI:

# Upload a single file
aws s3 cp ./local-file.txt s3://your-bucket-name/remote-file.txt

# List bucket contents
aws s3 ls s3://your-bucket-name/

AWS SDK:

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: "us-east-1" });

await s3.send(new PutObjectCommand({
  Bucket: "your-bucket-name",
  Key: "path/to/file.json",
  Body: JSON.stringify({ message: "Hello World" }),
  ContentType: "application/json"
}));

Related Components

Buckets are a foundational component in AWS and integrate with several other components:

• static-site - Serves files stored in S3 publicly using Cloudfront as a CDN with support for framework-specific routing.
• s3-firehose - Sets up a Kinesis Firehose that can be used to buffer data and write it to S3 in chunks. This can be used to query it efficiently with tools that can read data directly from S3 such as Athena or Apache Spark.

Costs

S3 costs are all usage-based so you will not be charged if you create a bucket and never use it. S3 costs are broken down by:

• Data Transfer - This is the component that often makes costs really blow up unless handled carefully. Sending data to S3 is always free. However, transferring data out of S3 to the internet incurs charges of ~$0.09/GB. If data is transferred from S3 to many clients, this can add up quickly. Consider these cost reduction strategies:

  • Use S3 endpoints - The vpc component sets up VPC endpoints by default, so requests to S3 from your VPC will be made internally in AWS’s network and will not incur data transfer charges.
  • Consider CloudFront - Use the staticSite component or create your own CloudFront distribution to serve files publicly. The first 1TB of data transfer out to the internet from CloudFront is free each month; see CloudFront pricing for details.

• Data stored - The storage itself is relatively cheap, ~$0.023/GB/month. If you store 100GB of data in S3 and leave it there, you’ll be billed ~$2.30 each month. If you delete the data (including all versions, if versioning is enabled) from S3, you will not be charged for its storage anymore.

• Requests - You’ll be charged for each API call made to your S3 buckets, but this is also relatively cheap: ~$0.0004/1000 read (GET, SELECT) and ~$0.0005/1000 write (POST, PUT, etc.) requests. You will not be charged unless the requests can successfully pass authorization checks.

Note: Prices vary by region. See S3 Pricing for current rates.

bucket

Creates an S3 bucket with security best practices enabled by default, including encryption, public access blocking, and optional versioning.

function bucket(ctx: Context, args?: BucketArgs): BucketV2

Parameters

• ctx (Context) - The context for resource naming and tagging
• args? (BucketArgs) - Optional configuration arguments for the bucket

Returns

• (BucketV2) - Creates an S3 bucket with security best practices enabled by default, including encryption, public access blocking, and optional versioning.

Functions

bucketCors

Configures CORS settings for an S3 bucket.

function bucketCors(ctx: Context, args: BucketCorsArgs): BucketCorsConfigurationV2

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (BucketCorsArgs) - Configuration arguments for bucket CORS

Returns

• (BucketCorsConfigurationV2) - Configures CORS settings for an S3 bucket.

bucketEncryption

Configures server-side encryption for an S3 bucket using AES256.

function bucketEncryption(ctx: Context, args: BucketVersioningArgs): BucketServerSideEncryptionConfigurationV2

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (BucketVersioningArgs) - Configuration arguments for bucket encryption

Returns

• (BucketServerSideEncryptionConfigurationV2) - Configures server-side encryption for an S3 bucket using AES256.

bucketFiles

Uploads all files from a local directory to an S3 bucket with proper MIME types.

function bucketFiles(ctx: Context, args: BucketFilesArgs): Record<string, BucketObjectv2>

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (BucketFilesArgs) - Configuration arguments for the directory upload

Returns

• (Record<string, BucketObjectv2>) - Uploads all files from a local directory to an S3 bucket with proper MIME types.

bucketLifecycleRules

Configures lifecycle rules for an S3 bucket to automatically transition or expire objects.

function bucketLifecycleRules(ctx: Context, args: BucketLifecycleRulesArgs): BucketLifecycleConfigurationV2

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (BucketLifecycleRulesArgs) - Configuration arguments for bucket lifecycle rules

Returns

• (BucketLifecycleConfigurationV2) - Configures lifecycle rules for an S3 bucket to automatically transition or expire objects.

bucketObjectOwnership

Configures object ownership controls for an S3 bucket.

function bucketObjectOwnership(ctx: Context, args: BucketObjectOwnershipArgs): BucketOwnershipControls

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (BucketObjectOwnershipArgs) - Configuration arguments for bucket object ownership

Returns

• (BucketOwnershipControls) - Configures object ownership controls for an S3 bucket.

bucketPolicy

Creates a bucket policy that grants access to specified services and AWS accounts.

function bucketPolicy(ctx: Context, args: BucketPolicyArgs): BucketPolicy

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (BucketPolicyArgs) - Configuration arguments for the bucket policy

Returns

• (BucketPolicy) - Creates a bucket policy that grants access to specified services and AWS accounts.

bucketPublicAccessBlock

Blocks all public access to an S3 bucket for security.

function bucketPublicAccessBlock(ctx: Context, args: BucketVersioningArgs): BucketPublicAccessBlock

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (BucketVersioningArgs) - Configuration arguments for the bucket

Returns

• (BucketPublicAccessBlock) - Blocks all public access to an S3 bucket for security.

bucketServiceAccessPolicy

Creates an IAM policy that grants specified AWS services access to an S3 bucket.

function bucketServiceAccessPolicy(bucket: Input<BucketInput>, services: Input<string>[]): Output<GetPolicyDocumentResult>

Parameters

• bucket (Input<BucketInput>) - The S3 bucket to grant access to
• services (Input<string>[]) - AWS services that should be granted access

Returns

• (Output<GetPolicyDocumentResult>) - Creates an IAM policy that grants specified AWS services access to an S3 bucket.

bucketVersioning

Enables versioning on an S3 bucket.

function bucketVersioning(ctx: Context, args: BucketVersioningArgs): BucketVersioningV2

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (BucketVersioningArgs) - Configuration arguments for bucket versioning

Returns

• (BucketVersioningV2) - Enables versioning on an S3 bucket.

getBucketAttributes

Retrieves the full bucket attributes from various bucket input types.

function getBucketAttributes(input: Input<BucketInput>): Output<BucketV2 | Bucket | GetBucketResult>

Parameters

• input (Input<BucketInput>) - The bucket input (string, bucket resource, or bucket result)

Returns

• (Output<BucketV2 | Bucket | GetBucketResult>) - Retrieves the full bucket attributes from various bucket input types.

getBucketId

Extracts the bucket ID from various bucket input types.

function getBucketId(input: Input<BucketInput>): Output<string>

Parameters

• input (Input<BucketInput>) - The bucket input (string, bucket resource, or bucket result)

Returns

• (Output<string>) - Extracts the bucket ID from various bucket input types.

Interfaces

BucketArgs

Configuration arguments for creating an S3 bucket with optional features.

Properties

• allowCors? (boolean) - Whether to allow CORS requests
• bucket? (Input<string>) - Specify the name of your bucket. In general when using Pulumi, it’s preferred to specify name prefixes (bucketPrefix, or allow pulumi to generate the prefix for you) so that resources can be recreated before deleting them in the case where they need to replaced.
• bucketPrefix? (Input<string>) - Specify a prefix to use for the bucket name. If neither this nor bucket are specified, a prefix will be auto-generated based on the resource name
• encrypted? (boolean) - Whether to enable server-side encryption (defaults to true)
• forceDestroy? (Input<boolean>) - When deleting the bucket, delete all objects in the bucket first. This is dangerous and can cause unintentional data loss (particularly if used in conjunction with noProtect), but may be desirable for ephemeral buckets
• lifecycleRules? (BucketLifecycleRule[]) - Lifecycle rules to automatically manage object expiration
• noPrefix? (boolean) - Whether to skip adding a prefix to the resource name
• noProtect? (boolean) - Whether to disable deletion protection. Since buckets are stateful and deleting them can cause data loss, they are protected by default.
• objectOwnership? (Input<string>) - The object ownership setting for the bucket
• paths? (string[]) - Provide an array of path(s) to upload to the bucket
• policy? (Omit<BucketPolicyArgs, "bucket" | "noPrefix">) - Policy configuration for granting access to services and accounts
• public? (boolean) - Whether the bucket should allow public access
• versioned? (boolean) - Whether to enable versioning on the bucket

BucketCorsArgs

Arguments for configuring CORS on an S3 bucket.

Properties

• bucket (Input<BucketInput>) - The S3 bucket to configure CORS for
• corsRules? (Input<Input<BucketCorsConfigurationV2CorsRule>[]>) - Custom CORS rules (defaults to permissive rules if not specified)
• noPrefix? (boolean) - Whether to skip adding a prefix to the resource name

BucketFilesArgs

Configuration arguments for uploading a directory to an S3 bucket.

Properties

• bucket (BucketInput) - The target S3 bucket for the directory upload
• keyPrefix? (Input<string>) - Optional prefix to prepend to all S3 object keys
• noPrefix? (boolean) - Whether to skip adding ‘bucket-directory’ prefix to resource names
• paths (string[]) - Local filesystem path to the directory to upload

BucketLifecycleRule

Configuration for a single S3 bucket lifecycle rule.

Properties

• days (number) - Number of days after which objects expire
• id? (string) - Optional identifier for the lifecycle rule
• prefix? (boolean) - Whether to include prefix in the rule ID

BucketLifecycleRulesArgs

Arguments for configuring lifecycle rules on an S3 bucket.

Properties

• bucket (Input<BucketInput>) - The S3 bucket to configure lifecycle rules for
• noPrefix? (boolean) - Whether to skip adding a prefix to the resource name
• rules (BucketLifecycleRule[]) - Array of lifecycle rules to apply

BucketObjectOwnershipArgs

Properties

• bucket (Input<BucketInput>) - The S3 bucket to create an ownership resource for
• noPrefix? (boolean) - Whether to skip adding a prefix to the resource name
• objectOwnership (Input<string>) - Object ownership setting

BucketPolicyArgs

Arguments for creating a bucket policy that grants access to services and accounts.

Properties

• accounts? (Input<string>[]) - AWS account IDs that should be granted access to the bucket
• bucket (Input<BucketInput>) - The S3 bucket to create a policy for
• noPrefix? (boolean) - Whether to skip adding a prefix to the resource name
• services? (Input<string>[]) - AWS services that should be granted access to the bucket

BucketVersioningArgs

Arguments for configuring S3 bucket versioning.

Properties

• bucket (Input<BucketInput>) - The S3 bucket to configure versioning for
• noPrefix? (boolean) - Whether to skip adding a prefix to the resource name

Types

BucketInput

Union type representing different ways to reference an S3 bucket.

type BucketInput = string | aws.s3.BucketV2 | aws.s3.Bucket | aws.s3.GetBucketResult