The process of creating resources in your AWS account before you can deploy SST apps into them.
SST needs to know about the current state of your app. To do this, it stores information about the app, including app metadata and stack metadata, during each deployment. This information is gathered by a Lambda function that listens to CloudFormation stack deploy events. Then after collecting the information, the Lambda function uploads and stores it in an S3 bucket.
The above resources are defined in a CloudFormation stack named
SSTBootstrap. It contains the following resources:
|This Lambda function automatically deletes objects within the S3 bucket when they are no longer needed.
|This IAM Role is used by the Lambda function to have necessary permissions to delete objects from S3.
|useast124D14E4B (name varies depending on region)
|This S3 bucket is used to store critical information about the apps, including app metadata and stack metadata.
|useast1AutoDeleteObjectsCustomResourceE0E6054B (name varies depending on region)
|This Custom Resource is used to enable automatic deletion of objects within the S3 bucket.
|useast1PolicyE57DC004 (name varies depending on region)
|This S3 Bucket Policy grants the necessary permissions for the relevant roles to access the bucket during SST deployments.
|This Lambda function is used to handle metadata operations such as collecting and uploading metadata to the S3 bucket.
|This IAM Role is used by the MetadataHandler Lambda function to have necessary permissions to perform its operations.
|This IAM Policy grants the MetadataHandlerServiceRole the necessary permissions to perform its operations.
|This EventBridge rule triggers the MetadataHandler Lambda function based on CloudFormation events.
|This permission allows the EventBridge rule to invoke the MetadataHandler Lambda function.
The bootstrap stack is deployed per AWS account per region. This means that deploying multiple SST apps in the same AWS account and region will result in only one
SSTBootstrap stack being created in that region.
You can configure the bootstrap stack, such as the stack name and tags, in
The app metadata stores information about the mode in which the app is running, whether it is in dev mode (
sst start) or in production mode (
sst deploy). Apps are deployed differently in dev vs production. SST uses the app metadata to warn the user if it is switching from dev to production, or vice versa.
App metadata is stored in the S3 bucket at
The stack metadata includes information about the constructs created in each stack. The information is used by:
- SST Console
- Config to look up the functions that need to be restarted when updating secret values
- sst bind to look up the resources bound to the functions and sites
Stack metadata is stored in the S3 bucket at
SST is built on top of AWS CDK, which also has its own bootstrapping process. The CDK bootstrapping process is similar to SST. Each AWS account and region needs to be bootstrapped only once. You can read more about CDK bootstrapping process.
By default, the bootstrap stack is named
CDKToolkit, and contains the following resources:
|This SSM Parameter stores the bootstrap version used by the CDK to manage resources.
|This IAM Role is used by AWS CloudFormation to deploy stacks on your behalf.
|This ECR Repository is used to store Docker images that are used by your CDK application.
|This IAM Role is used to deploy AWS CDK apps. It's assumed by the CDK Toolkit during the deployment.
|This IAM Role is used to publish file assets to AWS S3 during the CDK app deployment.
|This IAM Policy grants the FilePublishingRole the necessary permissions to publish file assets to AWS S3.
|This IAM Role is used to publish Docker images to AWS ECR during the CDK app deployment.
|This IAM Policy grants the ImagePublishingRole the necessary permissions to publish Docker images to AWS ECR.
|This IAM Role is used for performing environment lookups (reading AWS CloudFormation exports and other information).
|This S3 Bucket is used to store file and zip assets that are used by your CDK application.
|This S3 Bucket Policy grants the necessary permissions for the relevant roles to access the staging bucket during CDK deployments.
There are two ways to customize the bootstrapping resources.
Configure the CDK bootstrap stack template: This involves changing various aspects such as the stack name and qualifier, in the
Stack synthesizersare automatically configured for all stacks in your app.
Modify the bootstrap template: If the first method does not offer the level of customization needed, the bootstrap template can be directly modified. This is especially useful when you need to avoid creating certain resources in the stack.
To customize, you first need to fetch the bootstap template:
cdk bootstrap --show-template > template.yaml
You can then modify the template according to your needs, and deploy the adjusted template:
cdk bootstrap --template template.yaml
When you run
cdk bootstrap, SST will use the stack you've manually bootstrapped.