feat: cdk debootstrap command#952
Conversation
- Wrap lines to stay under 150 character limit - Add blank lines around lists (MD032) - Remove multiple consecutive blank lines (MD012) - Fix table column alignment (MD060) - Remove trailing spaces (MD009)
|
|
||
| ##### Usage | ||
|
|
||
| When users want to debootstrap a particular account, they run: |
There was a problem hiding this comment.
Style: we are writing a user manual. So the person to address here is "you":
When YOU want to remove bootstrap resources from your account, run:
(I also removed the term debootstrap here, because understanding your sentence requires users to learn a new term "debootstrapping" is, and we can fairly easily replace it with just describing what that does)
| $ cdk debootstrap aws://123456789012/us-east-1 | ||
| ``` | ||
|
|
||
| If users want to multi-select environments interactively (discovers bootstrapped |
| 1. Empties the S3 staging bucket (all object versions) | ||
| 2. Deletes all images in the ECR container assets repository | ||
| 3. Deletes the CDKToolkit CloudFormation stack (which cascades IAM roles, KMS | ||
| key, SSM parameter) | ||
| 4. Deletes the orphaned S3 bucket (left behind due to its | ||
| `DeletionPolicy: Retain`) |
There was a problem hiding this comment.
Style: This is very mechanical of how you're going to achieve the goal. When you are addressing a user, it's usually more interesting to them WHAT the end result is, not HOW you're going to achieve it.
So: all bootstrapped resources, including the asset bucket and ECR repo and all files and images will be deleted. Because the bucket needs to be emptied before it can be deleted, the duration of this operation depends on how many objects are in the bucket.
There was a problem hiding this comment.
Agree, what is currently written looks like a procedure for that you will implement - which is more important to something like a technical design. For an RFC, it's OK to omit this level of detail, and focus on the high level. The end user cares more about the interface and the API, rather than the specific implementation steps.
| ##### Idempotency | ||
|
|
||
| The command is safe to re-run after partial failure. Each step checks current | ||
| state before acting: | ||
|
|
||
| - If the stack is already gone but the bucket still exists, it skips to bucket | ||
| cleanup | ||
| - If the bucket is already empty, it skips to the next step | ||
| - If everything is already removed, it exits cleanly |
There was a problem hiding this comment.
From the point of view of a user, this could be one line:
If the command gets interrupted, you can run it again and it will pick up where it left off.
| 2. Match each stack's `RoleARN` field against the pattern | ||
| `cdk-${Qualifier}-cfn-exec-role-${Account}-${Region}` | ||
| 3. Check stack parameters and template body for references to the bootstrap | ||
| bucket - `cdk-${Qualifier}-assets-${Account}-${Region}` and ECR repo - | ||
| `cdk-${Qualifier}-container-assets-${Account}-${Region}` | ||
| 4. If there is a match that means that stack depends on this bootstrap |
There was a problem hiding this comment.
I wouldn't do this.
You can get the actual resource names from the actual bootstrap stack stack.
You can then search for ACTUAL resource names in the template, parameters and configuration of all application stacks.
Why is that better?
- You still catch all the stacks you were planning to catch by looking up predefined names
- But you also catch the stacks where users customized the stack template and decided to rename the resources.
- And it's not much more work.
| **`cdk bootstrap --destroy`:** Adds a flag to the existing command. This flag | ||
| wouldn't just modify a command's behavior, but invert it. Also, | ||
| `cdk bootstrap --destroy --force` is three flags deep and is awkward from a UX | ||
| perspective. |
There was a problem hiding this comment.
I'm fine with it. It's not like this command is being used every day.
| - **Cross-account notification:** A mechanism to warn trusted accounts when a | ||
| bootstrap stack they depend on is about to be destroyed. |
There was a problem hiding this comment.
Nice and aspirational, but I don't think we can do this in practice.
There isn't a good way to "send a message to an account". In this case, I think we just trust the user to understand what they're doing.
| If users want to multi-select environments interactively (discovers bootstrapped | ||
| environments and presents a picker): | ||
|
|
||
| ```console | ||
| $ cdk debootstrap | ||
| ``` |
There was a problem hiding this comment.
This is an interesting choice, as it departs from the convention we use in cdk bootstrap - cdk bootstrap run without parameters inside of a CDK project does the following:
By default, the CDK CLI will bootstrap all environments referenced in the CDK app or will determine an environment from default sources. This could be an environment specified using the --profile option, from environment variables, or default AWS CLI sources.
ref: https://docs.aws.amazon.com/cdk/v2/guide/ref-cli-cmd-bootstrap.html
The RFC suggests an interactive mode, which we don't have for cdk bootstrap. One potential consideration is the use of this command in CI, where interactive mode would create problems.
Not necessarily saying that this needs to change, but flagging as a callout.
| **Prompt 1 - Dependency warning** : | ||
|
|
||
| This is shown when there are dependent stacks found. | ||
|
|
||
| ``` | ||
| ⚠️ The following stacks use this bootstrap and will no longer be deployable or destroyable via CDK: | ||
| - MyAppStack | ||
| - MyOtherStack | ||
|
|
||
| Do you want to continue? (y/N): |
There was a problem hiding this comment.
Will this prompt be shown if the user uses --yes?
| Are you sure you want to proceed? (y/N): | ||
| ``` | ||
|
|
||
| `--force` skips the dependency check entirely. `--yes` skips all interactive |
There was a problem hiding this comment.
I see that this answers my question above. But there is inconsistency in that we indicate "This prompt will always be shown unless the user uses --yes" for prompt 2 and not prompt 1. I recommend consolidating this, maybe just by removing the line I quoted.
| ##### Flags | ||
|
|
||
| | Flag | Description | | ||
| | --- | --- | | ||
| | `--force` | Skip the dependency check entirely | | ||
| | `--yes` | Skip all interactive prompts (global flag) | | ||
| | `--qualifier` | Target a non-default bootstrap stack (default: `hnb659fds`) | | ||
| | `--toolkit-stack-name` | Override the default stack name `CDKToolkit` | | ||
| | `--profile` | AWS named profile to use | |
There was a problem hiding this comment.
Maybe have an -i flag (--interactive option), or something like that, if offering interactive mode.
| This risk is mitigated by the dependency detection warning and the two | ||
| confirmation prompts. | ||
|
|
There was a problem hiding this comment.
We can also bootstrap again, right?
3 participants
This is a request for comments about
cdk debootstrapwhich removes the CDK bootstrap stack and all associated resources from an AWS environment that get created whencdk bootstrapis run.. See #949 for additional details.APIs are signed off by @{BAR_RAISER}.
By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache-2.0 license