Skip to main content

Bootstrapping

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.


Bootstrap stack

The above resources are defined in a CloudFormation stack named SSTBootstrap. It contains the following resources:

Resource NameResource TypeDescription
CustomS3AutoDeleteObjectsCustomResourceProviderHandler9D90184FAWS::Lambda::FunctionThis Lambda function automatically deletes objects within the S3 bucket when they are no longer needed.
CustomS3AutoDeleteObjectsCustomResourceProviderRole3B1BD092AWS::IAM::RoleThis IAM Role is used by the Lambda function to have necessary permissions to delete objects from S3.
useast124D14E4B (name varies depending on region)AWS::S3::BucketThis S3 bucket is used to store critical information about the apps, including app metadata and stack metadata.
useast1AutoDeleteObjectsCustomResourceE0E6054B (name varies depending on region)Custom::S3AutoDeleteObjectsThis Custom Resource is used to enable automatic deletion of objects within the S3 bucket.
useast1PolicyE57DC004 (name varies depending on region)AWS::S3::BucketPolicyThis S3 Bucket Policy grants the necessary permissions for the relevant roles to access the bucket during SST deployments.
MetadataHandlerBEE7179CAWS::Lambda::FunctionThis Lambda function is used to handle metadata operations such as collecting and uploading metadata to the S3 bucket.
MetadataHandlerServiceRole24408145AWS::IAM::RoleThis IAM Role is used by the MetadataHandler Lambda function to have necessary permissions to perform its operations.
MetadataHandlerServiceRoleDefaultPolicy03477988AWS::IAM::PolicyThis IAM Policy grants the MetadataHandlerServiceRole the necessary permissions to perform its operations.
MetadataRule1BDDB4A9AWS::Events::RuleThis EventBridge rule triggers the MetadataHandler Lambda function based on CloudFormation events.
MetadataRuleAllowEventRuleSSTBootstrapMetadataHandler013639BCFC7CDC4BAWS::Lambda::PermissionThis 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 sst.config.ts.


App metadata

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 appMetadata/app.{appName}/stage.{stageName}.json.


Stack metadata

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 appMetadata/app.{appName}/stage.{stageName}/stack.{stackName}.json.


CDK bootstrap

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:

Resource NameResource TypeDescription
CdkBootstrapVersionAWS::SSM::ParameterThis SSM Parameter stores the bootstrap version used by the CDK to manage resources.
CloudFormationExecutionRoleAWS::IAM::RoleThis IAM Role is used by AWS CloudFormation to deploy stacks on your behalf.
ContainerAssetsRepositoryAWS::ECR::RepositoryThis ECR Repository is used to store Docker images that are used by your CDK application.
DeploymentActionRoleAWS::IAM::RoleThis IAM Role is used to deploy AWS CDK apps. It's assumed by the CDK Toolkit during the deployment.
FilePublishingRoleAWS::IAM::RoleThis IAM Role is used to publish file assets to AWS S3 during the CDK app deployment.
FilePublishingRoleDefaultPolicyAWS::IAM::PolicyThis IAM Policy grants the FilePublishingRole the necessary permissions to publish file assets to AWS S3.
ImagePublishingRoleAWS::IAM::RoleThis IAM Role is used to publish Docker images to AWS ECR during the CDK app deployment.
ImagePublishingRoleDefaultPolicyAWS::IAM::PolicyThis IAM Policy grants the ImagePublishingRole the necessary permissions to publish Docker images to AWS ECR.
LookupRoleAWS::IAM::RoleThis IAM Role is used for performing environment lookups (reading AWS CloudFormation exports and other information).
StagingBucketAWS::S3::BucketThis S3 Bucket is used to store file and zip assets that are used by your CDK application.
StagingBucketPolicyAWS::S3::BucketPolicyThis 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.

  1. Configure the CDK bootstrap stack template: This involves changing various aspects such as the stack name and qualifier, in the sst.config.ts file.

    sst.config.ts
    config(input) {
    return {
    cdk: {
    qualifier: "my-team",
    fileAssetsBucketName: "my-team-CDKToolkit",
    customPermissionsBoundary: "my-team-pb",
    toolkitStackName: "custom-cdk-bootstrap-stack-name",
    }
    }
    },

    When configured, Stack synthesizers are automatically configured for all stacks in your app.

  2. 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.