|
| 1 | +# Troubleshoot AWS CDK bootstrapping issues<a name="bootstrapping-troubleshoot"></a> |
| 2 | + |
| 3 | +Troubleshoot common issues when bootstrapping your environment with the AWS Cloud Development Kit \(AWS CDK\)\. |
| 4 | + |
| 5 | +For an introduction to bootstrapping, see [AWS CDK bootstrapping](bootstrapping.md)\. |
| 6 | + |
| 7 | +For instructions on bootstrapping, see [Bootstrap your environment for use with the AWS CDK](bootstrapping-env.md)\. |
| 8 | + |
| 9 | +## When bootstrapping using the default template, you get a 'CREATE\_FAILED' error for the Amazon S3 bucket<a name="bootstrapping-troubleshoot-s3-bucket-name"></a> |
| 10 | + |
| 11 | +When bootstrapping using the AWS CDK Command Line Interface \(CDK CLI\) `cdk bootstrap` command with the default bootstrap template, you receive the following error: |
| 12 | + |
| 13 | +``` |
| 14 | +CREATE_FAILED | AWS::S3::Bucket | BucketName already exists |
| 15 | +``` |
| 16 | + |
| 17 | +Before troubleshooting, ensure that you are using the latest version of the CDK CLI\. |
| 18 | ++ To check your version, run `cdk --version`\. |
| 19 | ++ To install the latest version, run `npm install -g aws-cdk`\. |
| 20 | + |
| 21 | +After installing the latest version, try bootstrapping your environment again\. If you still receive the same error, continue with troubleshooting\. |
| 22 | + |
| 23 | +### Common causes<a name="bootstrapping-troubleshoot-s3-bucket-name-causes"></a> |
| 24 | + |
| 25 | +When you bootstrap your environment, the AWS CDK generates physical IDs for your bootstrap resources\. For more information, see [Resource IDs created during bootstrapping](bootstrapping-env.md#bootstrapping-env-default-id)\. |
| 26 | + |
| 27 | +Unlike the other bootstrap resources, Amazon S3 bucket names are global\. This means that each bucket name must be unique across all AWS accounts in all AWS Regions within a partition\. For more information, see [Buckets overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucket.html) in the *Amazon S3 User Guide*\. Therefore, the most common cause of this error is that the physical ID generated as your bucket name already exists somewhere within the partition\. This could be within your account or another account\. |
| 28 | + |
| 29 | +The following is an example bucket name: `cdk-hnb659fds-assets-012345678910-us-west-1`\. While unlikely, due to the qualifier and account ID being a part of the name, it is possible that this name for an Amazon S3 bucket is used by another AWS account\. Since bucket names are globally scoped, it can’t be used by you if its used by a different account in the same partition\. Most likely, a bucket with the same name exists somewhere in your account\. This could be in the Region you are attempting to bootstrap, or another Region\. |
| 30 | + |
| 31 | +Generally, the resolution is to locate this bucket in your account and determine what to do with it, or customize bootstrapping to create bootstrap resources of a different name\. |
| 32 | + |
| 33 | +### Resolution<a name="bootstrapping-troubleshoot-s3-bucket-name-resolution"></a> |
| 34 | + |
| 35 | +First, determine if a bucket with the same name exists within your AWS account\. Using an AWS identity with valid permissions to lookup Amazon S3 buckets in your account, you can do this in the following ways: |
| 36 | ++ Use the AWS Command Line Interface \(AWS CLI\) `aws s3 ls` command to view a list of all your buckets\. |
| 37 | ++ Look up bucket names for each Region in your account using the [Amazon S3 console](https://console.aws.amazon.com/s3)\. |
| 38 | + |
| 39 | +If a bucket with the same name exists, determine if it's being used\. If it's not being used, consider deleting the bucket and attempting to bootstrap your environment again\. |
| 40 | + |
| 41 | +If a bucket with the same name exists and you don't want to delete it, determine if it’s already associated with a bootstrap stack in your account\. You may have to check multiple Regions\. The Region in the Amazon S3 bucket name doesn’t necessarily mean that the bucket is in that Region\. To check if it’s associated with the `CDKToolkit` bootstrap stack, you can do either of the following for each Region: |
| 42 | ++ Use the AWS CLI `aws cloudformation describe-stack-resources --stack-name CDKToolkit --region Region` command to view the resources in your bootstrap stack and check if the bucket is listed\. |
| 43 | ++ In the [AWS CloudFormation console](https://console.aws.amazon.com/cloudformation), locate the `CDKToolkit` stack\. Then, on the **Resources** tab, check if the bucket exists\. |
| 44 | + |
| 45 | +If the bucket is associated with a bootstrap stack, determine if the bootstrap stack is in the same Region that you are attempting to bootstrap\. If it is, your environment is already bootstrapped and you should be able to start using the CDK to deploy applications into your environment\. If the Amazon S3 bucket is associated with a bootstrap stack in a different Region, you’ll need to determine what to do\. Possible resolutions include renaming the existing Amazon S3 bucket, deleting the current Amazon S3 bucket if its not being used, or using a new name for the Amazon S3 bucket you are attempting to create\. |
| 46 | + |
| 47 | +If you are unable to locate an Amazon S3 bucket with the same name in your account, it may exist in a different account\. To resolve this, you’ll need to customize bootstrapping to create new names for all of your bootstrap resources or for just your Amazon S3 bucket\. To create new names for all bootstrap resources, you can modify the qualifier\. To create a new name for only your Amazon S3 bucket, you can provide a new bucket name\. |
| 48 | + |
| 49 | +To customize bootstrapping, you can use options with the CDK CLI `cdk bootstrap` command or by modifying the bootstrap template\. For instructions, see [Customize AWS CDK bootstrapping](bootstrapping-customizing.md)\. |
| 50 | + |
| 51 | +If you customize bootstrapping, you will need to apply the same changes to synthesis before you can properly deploy an application\. For instructions, see [Customize CDK stack synthesis](configure-synth.md#bootstrapping-custom-synth)\. |
| 52 | + |
| 53 | +For example, you can provide a new qualifier with `cdk bootstrap`: |
| 54 | + |
| 55 | +``` |
| 56 | +$ cdk bootstrap --qualifier abcde0123 |
| 57 | +``` |
| 58 | + |
| 59 | +The following is an example Amazon S3 bucket name that will be created with this modification: `cdk-abcde0123-assets-012345678910-us-west-1`\. All bootstrap resources created during bootstrapping will use this qualifier\. |
| 60 | + |
| 61 | +When developing your CDK app, you must specify your custom qualifier in your synthesizer\. This helps the CDK with identifying your bootstrap resources during synthesis and deployment\. The following is an example of customizing the default synthesizer for your stack instance: |
| 62 | + |
| 63 | +------ |
| 64 | +#### [ TypeScript ] |
| 65 | + |
| 66 | +``` |
| 67 | +new MyStack(this, 'MyStack', { |
| 68 | + synthesizer: new DefaultStackSynthesizer({ |
| 69 | + qualifier: 'abcde0123', |
| 70 | + }), |
| 71 | +}); |
| 72 | +``` |
| 73 | + |
| 74 | +------ |
| 75 | +#### [ JavaScript ] |
| 76 | + |
| 77 | +``` |
| 78 | +new MyStack(this, 'MyStack', { |
| 79 | + synthesizer: new DefaultStackSynthesizer({ |
| 80 | + qualifier: 'abcde0123', |
| 81 | + }), |
| 82 | +}) |
| 83 | +``` |
| 84 | + |
| 85 | +------ |
| 86 | +#### [ Python ] |
| 87 | + |
| 88 | +``` |
| 89 | +MyStack(self, "MyStack", |
| 90 | + synthesizer=DefaultStackSynthesizer( |
| 91 | + qualifier="abcde0123" |
| 92 | +)) |
| 93 | +``` |
| 94 | + |
| 95 | +------ |
| 96 | +#### [ Java ] |
| 97 | + |
| 98 | +``` |
| 99 | +new MyStack(app, "MyStack", StackProps.builder() |
| 100 | + .synthesizer(DefaultStackSynthesizer.Builder.create() |
| 101 | + .qualifier("abcde0123") |
| 102 | + .build()) |
| 103 | + .build(); |
| 104 | +``` |
| 105 | + |
| 106 | +------ |
| 107 | +#### [ C\# ] |
| 108 | + |
| 109 | + |
| 110 | + |
| 111 | +``` |
| 112 | +new MyStack(app, "MyStack", new StackProps |
| 113 | +{ |
| 114 | + Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps |
| 115 | + { |
| 116 | + Qualifier = "abcde0123" |
| 117 | + }) |
| 118 | +}); |
| 119 | +``` |
| 120 | + |
| 121 | +------ |
| 122 | +#### [ Go ] |
| 123 | + |
| 124 | +``` |
| 125 | +func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack { |
| 126 | + var sprops awscdk.StackProps |
| 127 | + if props != nil { |
| 128 | + sprops = props.StackProps |
| 129 | + } |
| 130 | + stack := awscdk.NewStack(scope, &id, &sprops) |
| 131 | +
|
| 132 | + synth := awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{ |
| 133 | + Qualifier: jsii.String("abcde0123"), |
| 134 | + }) |
| 135 | +
|
| 136 | + stack.SetSynthesizer(synth) |
| 137 | +
|
| 138 | + return stack |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +------ |
| 143 | + |
| 144 | +You can also specify the new qualifier in the `cdk.json` file of your CDK project: |
| 145 | + |
| 146 | +``` |
| 147 | +{ |
| 148 | + "app": "...", |
| 149 | + "context": { |
| 150 | + "@aws-cdk/core:bootstrapQualifier": "abcde0123" |
| 151 | + } |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +To modify only the Amazon S3 bucket name, you can use the `\-\-bootstrap\-bucket\-name` option\. The following is an example: |
| 156 | + |
| 157 | +``` |
| 158 | +$ cdk bootstrap --bootstrap-bucket-name 'my-new-bucket-name' |
| 159 | +``` |
| 160 | + |
| 161 | +When developing your CDK app, you must specify your new bucket name in your synthesizer\. The following is an example of customizing the default synthesizer for your stack instance: |
| 162 | + |
| 163 | +------ |
| 164 | +#### [ TypeScript ] |
| 165 | + |
| 166 | +``` |
| 167 | +new MyStack(this, 'MyStack', { |
| 168 | + synthesizer: new DefaultStackSynthesizer({ |
| 169 | + fileAssetsBucketName: 'my-new-bucket-name', |
| 170 | + }), |
| 171 | +}); |
| 172 | +``` |
| 173 | + |
| 174 | +------ |
| 175 | +#### [ JavaScript ] |
| 176 | + |
| 177 | +``` |
| 178 | +new MyStack(this, 'MyStack', { |
| 179 | + synthesizer: new DefaultStackSynthesizer({ |
| 180 | + fileAssetsBucketName: 'my-new-bucket-name', |
| 181 | + }), |
| 182 | +}) |
| 183 | +``` |
| 184 | + |
| 185 | +------ |
| 186 | +#### [ Python ] |
| 187 | + |
| 188 | +``` |
| 189 | +MyStack(self, "MyStack", |
| 190 | + synthesizer=DefaultStackSynthesizer( |
| 191 | + file_assets_bucket_name='my-new-bucket-name' |
| 192 | +)) |
| 193 | +``` |
| 194 | + |
| 195 | +------ |
| 196 | +#### [ Java ] |
| 197 | + |
| 198 | +``` |
| 199 | +new MyStack(app, "MyStack", StackProps.builder() |
| 200 | + .synthesizer(DefaultStackSynthesizer.Builder.create() |
| 201 | + .fileAssetsBucketName("my-new-bucket-name") |
| 202 | + .build()) |
| 203 | + .build(); |
| 204 | +``` |
| 205 | + |
| 206 | +------ |
| 207 | +#### [ C\# ] |
| 208 | + |
| 209 | + |
| 210 | + |
| 211 | +``` |
| 212 | +new MyStack(app, "MyStack", new StackProps |
| 213 | +{ |
| 214 | + Synthesizer = new DefaultStackSynthesizer(new DefaultStackSynthesizerProps |
| 215 | + { |
| 216 | + FileAssetsBucketName = "my-new-bucket-name" |
| 217 | + }) |
| 218 | +}); |
| 219 | +``` |
| 220 | + |
| 221 | +------ |
| 222 | +#### [ Go ] |
| 223 | + |
| 224 | +``` |
| 225 | +func NewMyStack(scope constructs.Construct, id string, props *MyStackProps) awscdk.Stack { |
| 226 | + var sprops awscdk.StackProps |
| 227 | + if props != nil { |
| 228 | + sprops = props.StackProps |
| 229 | + } |
| 230 | + stack := awscdk.NewStack(scope, &id, &sprops) |
| 231 | +
|
| 232 | + synth := awscdk.NewDefaultStackSynthesizer(&awscdk.DefaultStackSynthesizerProps{ |
| 233 | + FileAssetsBucketName: jsii.String("my-new-bucket-name"), |
| 234 | + }) |
| 235 | +
|
| 236 | + stack.SetSynthesizer(synth) |
| 237 | +
|
| 238 | + return stack |
| 239 | +} |
| 240 | +``` |
| 241 | + |
| 242 | +------ |
| 243 | + |
| 244 | +### Prevention<a name="bootstrapping-troubleshoot-s3-bucket-name-prevention"></a> |
| 245 | + |
| 246 | +**Proactively bootstrap your environments** <a name="bootstrapping-troubleshoot-s3-bucket-name-prevention-proactive"></a> |
| 247 | +If you don’t have reasons to customize bootstrapping or synthesis, we recommend that you use the default bootstrapping process and synthesizer, which work together automatically\. To do this, the default Amazon S3 bucket name that will be created during bootstrapping must not yet exist\. To prevent against this from happening, we recommend that you proactively bootstrap each Region for each AWS account that you plan to use\. You can do this before you ever plan on actually deploying CDK applications into the environment\. Specifically for the Amazon S3 bucket naming issue, this will create Amazon S3 buckets in each AWS environment and prevent others from using your Amazon S3 bucket name\. |
| 248 | + |
| 249 | +**Protect your account ID** <a name="bootstrapping-troubleshoot-s3-bucket-name-prevention-protect"></a> |
| 250 | +Limit the sharing of your account ID\. This will help to prevent bad actors from using your account ID to generate their own Amazon S3 bucket names\. |
0 commit comments