Skip to content

Commit 2fec6a4

Browse files
rix0rrrrix0rrr
authored
feat(app-staging-synthesizer): select different bootstrap region (#26129)
Allow selecting the region that was bootstrapped to be distinct from the region that the stack is being deployed to. Also in this PR, clarify the README. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent 40871ec commit 2fec6a4

File tree

4 files changed

+177
-123
lines changed

4 files changed

+177
-123
lines changed

‎packages/@aws-cdk/app-staging-synthesizer-alpha/README.md

+57-115
Original file line numberDiff line numberDiff line change
@@ -48,106 +48,44 @@ in your account.
4848

4949
## Bootstrap Model
5050

51-
Our current bootstrap model looks like this, when you run `cdk bootstrap aws://<account>/<region>` :
52-
53-
```text
54-
┌───────────────────────────────────┐┌────────────────────────┐┌────────────────────────┐
55-
│ ││ ││ │
56-
│ ││ ││ │
57-
│ ┌───────────────┐ ││ ┌──────────────┐ ││ ┌──────────────┐ │
58-
│ │Bootstrap Stack│ ││ │ CDK App 1 │ ││ │ CDK App 2 │ │
59-
│ └───────────────┘ ││ └──────────────┘ ││ └──────────────┘ │
60-
│ ││ ││ │
61-
│ ││ ││ │
62-
│ ┌───────────────────────────┐ ││ ┌────────────┐ ││ │
63-
│ │IAM Role for CFN execution │ ││┌────│ S3 Asset │ ││ │
64-
│ │ IAM Role for lookup │ │││ └────────────┘ ││ │
65-
│ │ IAM Role for deployment │ │││ ││ │
66-
│ └───────────────────────────┘ │││ ││ ┌─────────────┐ │
67-
│ │││ ┌──────────┼┼─────│ S3 Asset │ │
68-
│ │││ │ ││ └─────────────┘ │
69-
│ ┌───────────────────────────────┐ │││ │ ││ │
70-
│ │ IAM Role for File Publishing │ │││ │ ││ │
71-
│ │ IAM Role for Image Publishing │ │││ │ ││ │
72-
│ └───────────────────────────────┘ │││ │ ││ │
73-
│ │││ │ ││ │
74-
│ ┌─────────────────────────────┐ │││ │ ││ │
75-
│ │S3 Bucket for Staging Assets │ │││ │ ││ │
76-
│ │ KMS Key encryption │◀─┼┼┴────────────┘ ││ ┌────────────┐ │
77-
│ └─────────────────────────────┘ ││ ┌──────────┼┼───── │ ECR Asset │ │
78-
│ ││ │ ││ └────────────┘ │
79-
│ ││ │ ││ │
80-
│┌─────────────────────────────────┐││ │ ││ │
81-
││ECR Repository for Staging Assets◀┼┼─────────────┘ ││ │
82-
│└─────────────────────────────────┘││ ││ │
83-
│ ││ ││ │
84-
│ ││ ││ │
85-
│ ││ ││ │
86-
│ ││ ││ │
87-
│ ││ ││ │
88-
│ ││ ││ │
89-
└───────────────────────────────────┘└────────────────────────┘└────────────────────────┘
90-
```
91-
92-
Your CDK Application utilizes these resources when deploying. For example, if you have a file asset,
93-
it gets uploaded to the S3 Staging Bucket using the File Publishing Role when you run `cdk deploy`.
94-
95-
This library introduces an alternate model to bootstrapping, by splitting out essential CloudFormation IAM roles
96-
and staging resources. There will still be a Bootstrap Stack, but this will only contain IAM roles necessary for
97-
CloudFormation deployment. Each CDK App will instead be in charge of its own staging resources, including the
98-
S3 Bucket, ECR Repositories, and associated IAM roles. It works like this:
99-
100-
The Staging Stack will contain, on a per-need basis,
101-
102-
- 1 S3 Bucket with KMS encryption for all file assets in the CDK App.
103-
- An ECR Repository _per_ image (and its revisions).
104-
- IAM roles with access to the Bucket and Repositories.
105-
106-
```text
107-
┌─────────────────────────────┐┌───────────────────────────────────────┐┌───────────────────────────────────────┐
108-
│ ││ ││ │
109-
│ ┌───────────────┐ ││ ┌──────────────┐ ││ ┌──────────────┐ │
110-
│ │Bootstrap Stack│ ││ │ CDK App 1 │ ││ │ CDK App 2 │ │
111-
│ └───────────────┘ ││ └──────────────┘ ││ └──────────────┘ │
112-
│ ││┌──────────────────┐ ││┌──────────────────┐ │
113-
│ │││ ┌──────────────┐ │ │││ ┌──────────────┐ │ │
114-
│ │││ │Staging Stack │ │ │││ │Staging Stack │ │ │
115-
│ │││ └──────────────┘ │ │││ └──────────────┘ │ │
116-
│ │││ │ │││ │ │
117-
│ │││ │ │││ │ │
118-
│ │││┌────────────────┐│ ┌────────────┐│││┌────────────────┐│ ┌────────────┐│
119-
│ ││││ IAM Role for ││ ┌───│ S3 Asset │││││ IAM Role for ││ ┌───│ S3 Asset ││
120-
│ ││││File Publishing ││ │ └────────────┘││││File Publishing ││ │ └────────────┘│
121-
│ │││└────────────────┘│ │ ││││ IAM Role for ││ │ │
122-
│ │││ │ │ ││││Image Publishing││ │ │
123-
│┌───────────────────────────┐│││ │ │ │││└────────────────┘│ │ │
124-
││IAM Role for CFN execution ││││ │ │ │││ │ │ │
125-
││ IAM Role for lookup ││││ │ │ │││ │ │ │
126-
││ IAM Role for deployment ││││┌────────────────┐│ │ │││┌────────────────┐│ │ │
127-
│└───────────────────────────┘││││ S3 Bucket for ││ │ ││││ S3 Bucket for ││ │ │
128-
│ ││││ Staging Assets │◀─┘ ││││ Staging Assets │◀─┘ │
129-
│ │││└────────────────┘│ │││└────────────────┘│ ┌───────────┐│
130-
│ │││ │ │││ │ ┌───│ ECR Asset ││
131-
│ │││ │ │││┌────────────────┐│ │ └───────────┘│
132-
│ │││ │ ││││ ECR Repository ││ │ │
133-
│ │││ │ ││││ for Staging │◀──┘ │
134-
│ │││ │ ││││ Assets ││ │
135-
│ │││ │ │││└────────────────┘│ │
136-
│ │││ │ │││ │ │
137-
│ │││ │ │││ │ │
138-
│ │││ │ │││ │ │
139-
│ │││ │ │││ │ │
140-
│ │││ │ │││ │ │
141-
│ ││└──────────────────┘ ││└──────────────────┘ │
142-
└─────────────────────────────┘└───────────────────────────────────────┘└───────────────────────────────────────┘
143-
```
144-
145-
This allows staging resources to be created when needed next to the CDK App. It has the following
146-
benefits:
147-
51+
In our default bootstrapping process, when you run `cdk bootstrap aws://<account>/<region>`, the following
52+
resources are created:
53+
54+
- It creates Roles to assume for cross-account deployments and for Pipeline deployments;
55+
- It creates staging resources: a global S3 bucket and global ECR repository to hold CDK assets;
56+
- It creates Roles to write to the S3 bucket and ECR repository;
57+
58+
Because the bootstrapping resources include regional resources, you need to bootstrap
59+
every region you plan to deploy to individually. All assets of all CDK apps deploying
60+
to that account and region will be written to the single S3 Bucket and ECR repository.
61+
62+
By using the synthesizer in this library, instead of the
63+
`DefaultStackSynthesizer`, a different set of staging resources will be created
64+
for every CDK application, and they will be created automatically as part of a
65+
regular deployment, in a separate Stack that is deployed before your application
66+
Stacks. The staging resources will be one S3 bucket, and *one ECR repository per
67+
image*, and Roles necessary to access those buckets and ECR repositories. The
68+
Roles from the default bootstrap stack are still used (though their use can be
69+
turned off).
70+
71+
This has the following advantages:
72+
73+
- Because staging resources are now application-specific, they can be fully cleaned up when you clean up
74+
the application.
75+
- Because there is now one ECR repository per image instead of one ECR repository for all images, it is
76+
possible to effectively use ECR life cycle rules (for example, retain only the most recent 5 images)
77+
to cut down on storage costs.
14878
- Resources between separate CDK Apps are separated so they can be cleaned up and lifecycle
149-
controlled individually.
150-
- Users have a familiar way to customize staging resources in the CDK Application.
79+
controlled individually.
80+
- Because the only shared bootstrapping resources required are Roles, which are global resources,
81+
you now only need to bootstrap every account in one Region (instead of every Region). This makes it
82+
easier to do with CloudFormation StackSets.
83+
84+
For the deployment roles, this synthesizer still uses the Roles from the default
85+
bootstrap stack, and nothing else. The staging resources from that bootstrap
86+
stack will be unused. You can customize the template to remove those resources
87+
if you prefer. In the future, we will provide a bootstrap stack template with
88+
only those Roles, specifically for use with this synthesizer.
15189

15290
## Using the Default Staging Stack per Environment
15391

@@ -159,6 +97,10 @@ its staging resources. To use this kind of synthesizer, use `AppStagingSynthesiz
15997
const app = new App({
16098
defaultStackSynthesizer: AppStagingSynthesizer.defaultResources({
16199
appId: 'my-app-id',
100+
101+
// The following line is optional. By default it is assumed you have bootstrapped in the same
102+
// region(s) as the stack(s) you are deploying.
103+
deploymentIdentities: DeploymentIdentities.defaultBootstrapRoles({ bootstrapRegion: 'us-east-1' }),
162104
}),
163105
});
164106
```
@@ -232,7 +174,7 @@ assumable by the deployment role. You can also specify an existing IAM role for
232174
const app = new App({
233175
defaultStackSynthesizer: AppStagingSynthesizer.defaultResources({
234176
appId: 'my-app-id',
235-
fileAssetPublishingRole: BootstrapRole.fromRoleArn('arn:aws:iam::123456789012:role/S3Access'),
177+
fileAssetPublishingRole: BootstrapRole.fromRoleArn('arn:aws:iam::123456789012:role/S3Access'),
236178
imageAssetPublishingRole: BootstrapRole.fromRoleArn('arn:aws:iam::123456789012:role/ECRAccess'),
237179
}),
238180
});
@@ -242,14 +184,14 @@ const app = new App({
242184

243185
There are two types of assets:
244186

245-
- Assets used only during deployment. These are used to hand off a large piece of data to another
246-
service, that will make a private copy of that data. After deployment, the asset is only necessary for
247-
a potential future rollback.
187+
- Assets used only during deployment. These are used to hand off a large piece of data to another
188+
service, that will make a private copy of that data. After deployment, the asset is only necessary for
189+
a potential future rollback.
248190
- Assets accessed throughout the running life time of the application.
249191

250192
Examples of assets that are only used at deploy time are CloudFormation Templates and Lambda Code
251-
bundles. Examples of assets accessed throughout the life time of the application are script files
252-
downloaded to run in a CodeBuild Project, or on EC2 instance startup. ECR images are always application
193+
bundles. Examples of assets accessed throughout the life time of the application are script files
194+
downloaded to run in a CodeBuild Project, or on EC2 instance startup. ECR images are always application
253195
life-time assets. S3 deploy time assets are stored with a `deploy-time/` prefix, and a lifecycle rule will collect them after a configurable number of days.
254196

255197
Lambda assets are by default marked as deploy time assets:
@@ -275,9 +217,9 @@ const asset = new Asset(stack, 'deploy-time-asset', {
275217
});
276218
```
277219

278-
By default, we store deploy time assets for 30 days, but you can change this number by specifying
220+
By default, we store deploy time assets for 30 days, but you can change this number by specifying
279221
`deployTimeFileAssetLifetime`. The number you specify here is how long you will be able to roll back
280-
to a previous version of an application just by doing a CloudFormation deployment with the old
222+
to a previous version of an application just by doing a CloudFormation deployment with the old
281223
template, without rebuilding and republishing assets.
282224

283225
```ts
@@ -316,7 +258,7 @@ you can subclass `DefaultStagingStack`.
316258
```ts
317259
interface CustomStagingStackOptions extends DefaultStagingStackOptions {}
318260

319-
class CustomStagingStack extends DefaultStagingStack {
261+
class CustomStagingStack extends DefaultStagingStack {
320262
}
321263
```
322264

@@ -389,13 +331,13 @@ const app = new App({
389331

390332
Since this module is experimental, there are some known limitations:
391333

392-
- Currently this module does not support CDK Pipelines. You must deploy CDK Apps using this
393-
synthesizer via `cdk deploy`.
334+
- Currently this module does not support CDK Pipelines. You must deploy CDK Apps using this
335+
synthesizer via `cdk deploy`. Please upvote [this issue](https://github.com/aws/aws-cdk/issues/26118)
336+
to indicate you want this.
394337
- This synthesizer only needs a bootstrap stack with Roles, without staging resources. We
395338
haven't written such a bootstrap stack yet; at the moment you can use the existing modern
396-
bootstrap stack, the staging resources in them will just go unused.
339+
bootstrap stack, the staging resources in them will just go unused. You can customize the
340+
template to remove them if desired.
397341
- Due to limitations on the CloudFormation template size, CDK Applications can have
398-
at most 38 independent ECR images.
399-
- When you run `cdk destroy` (for example during testing), the staging bucket and ECR
400-
repositories will be left behind because CloudFormation cannot clean up non-empty resources.
401-
You must deploy those resources manually if you want to redeploy again using the same `appId`.
342+
at most 38 independent ECR images. Please upvote [this issue](https://github.com/aws/aws-cdk/issues/26119)
343+
if you need more than this.

0 commit comments

Comments
 (0)