Skip to content

Commit 1e0ca31

Browse files
KristinaPetersonKristinaPeterson
committed
Add documentation for cdk flags usage and examples.
1 parent 111a237 commit 1e0ca31

File tree

2 files changed

+245
-0
lines changed

2 files changed

+245
-0
lines changed

‎v2/guide/ref-cli-cmd-flags.adoc‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
include::attributes.txt[]
2+
3+
// Attributes
4+
[.topic]
5+
[#ref-cli-cmd-flags]
6+
= `cdk flags`
7+
:keywords: {aws} CDK, {aws} CDK CLI, CDK Toolkit, IaC, Infrastructure as code, {aws} Cloud, {aws} CloudFormation, cdk flags, feature flags
8+
9+
[abstract]
10+
--
11+
View and modify your feature flag configurations for the CDK CLI.
12+
--
13+
14+
// Content start
15+
16+
View and modify your feature flag configurations for the CDK CLI.
17+
18+
Feature flags control the behavior of the CDK CLI and you can use them to enable or disable specific features. Use the `cdk flags` command to view your current feature flag configurations and modify them as needed.
19+
20+
[WARNING]
21+
====
22+
23+
The `cdk flags` command is in development for the {aws} CDK. The current features of this command are considered production-ready and safe to use. However, the scope of this command and its features are subject to change. Therefore, you must opt in by providing the `unstable=flags` option to use this command.
24+
25+
====
26+
27+
[#ref-cli-cmd-flags-usage]
28+
== Usage
29+
30+
[source,none,subs="verbatim,attributes"]
31+
----
32+
$ cdk flags <arguments> <options>
33+
----
34+
35+
[#ref-cli-cmd-flags-args]
36+
== Arguments
37+
38+
[#ref-cli-cmd-flags-args-flagname]
39+
*FLAGNAME*::
40+
The name of the specific feature flag that you want to view or modify.
41+
+
42+
_Type_: String
43+
+
44+
_Required_: No
45+
46+
[#ref-cli-cmd-flags-options]
47+
== Options
48+
49+
For a list of global options that work with all CDK CLI commands, see xref:ref-cli-cmd-options[Global options].
50+
51+
[#ref-cli-cmd-flags-options-set]
52+
`--set <BOOLEAN>`::
53+
Modify a feature flag configuration.
54+
55+
[#ref-cli-cmd-flags-options-all]
56+
`--all <BOOLEAN>`::
57+
Modify or view all feature flags.
58+
59+
[#ref-cli-cmd-flags-options-recommended]
60+
`--recommended <BOOLEAN>`::
61+
Change flags to recommended states.
62+
63+
[#ref-cli-cmd-flags-options-default]
64+
`--default <BOOLEAN>`::
65+
Change flags to default states.
66+
67+
[#ref-cli-cmd-flags-options-unconfigured]
68+
`--unconfigured <BOOLEAN>`::
69+
Modify unconfigured feature flags.
70+
71+
[#ref-cli-cmd-flags-options-value]
72+
`--value <STRING>`::
73+
The value to set the feature flag configuration to.
74+
+
75+
_requiresArg_: true
76+
77+
[#ref-cli-cmd-flags-options-safe]
78+
`--safe <BOOLEAN>`::
79+
Enable all feature flags that do not impact your application.
80+
81+
[#ref-cli-cmd-flags-options-interactive]
82+
`--interactive, -i <BOOLEAN>`::
83+
Interactive option for the flags command.
84+
85+
[#ref-cli-cmd-flags-examples]
86+
== Examples
87+
88+
[#ref-cli-cmd-flags-examples-1]
89+
=== View feature flag configurations
90+
91+
Run `cdk flags` to view a report of your feature flag configurations that differ from our recommended states. Unconfigured flags are labeled with `<unset>` to indicate that the flag currently has no value. The flags are displayed in the following order:
92+
93+
* Flags set to a value that doesn't match our recommended value
94+
* Flags that you haven't configured
95+
96+
[source,bash,subs="verbatim,attributes"]
97+
----
98+
$ cdk flags --unstable=flags
99+
Feature Flag Recommended User
100+
* @aws-cdk/... true false
101+
* @aws-cdk/... true false
102+
* @aws-cdk/... true <unset>
103+
----
104+
105+
You can also run `cdk flags --all` to see a report of all feature flags in the following order:
106+
107+
* Flags set to a value that matches our recommended value
108+
* Flags set to a value that doesn't match our recommended value
109+
* Flags that you haven't configured
110+
111+
[source,none,subs="verbatim,attributes"]
112+
----
113+
$ cdk flags --unstable=flags --all
114+
Feature Flag Recommended User
115+
@aws-cdk/... true true
116+
* @aws-cdk/... true false
117+
* @aws-cdk/... true false
118+
* @aws-cdk/... true <unset>
119+
----
120+
121+
[#ref-cli-cmd-flags-examples-2]
122+
=== Modify feature flag values
123+
124+
To modify your feature flags interactively, run `cdk flags --interactive` (or `cdk flags -i`) to view a list of menu options.
125+
126+
To change every feature flag to our recommended value, run `cdk flags --set --recommended --all`. This command keeps your feature flag configuration up-to-date with the latest CDK feature flag configurations. Be aware that running this command can potentially overwrite existing configured values.
127+
128+
[source,none,subs="verbatim,attributes"]
129+
----
130+
$ cdk flags --unstable=flags --set --recommended --all
131+
Feature Flag Recommended Value User Value
132+
* @aws-cdk/... true false
133+
* @aws-cdk/... true false
134+
* @aws-cdk/... true <unset>
135+
Synthesizing...
136+
Resources
137+
[~] AWS::S3::Bucket MyBucket
138+
└─ [~] Properties
139+
└─ [~] Encryption
140+
...
141+
Number of stacks with differences: 2
142+
Do you want to accept these changes? (y/n) y
143+
Resynthesizing...
144+
----
145+
146+
If you want to preserve the state of your existing configured flags, run `cdk flags --set --recommended --unconfigured`. This option changes only the unconfigured feature flags to our recommended values.
147+
148+
[source,none,subs="verbatim,attributes"]
149+
----
150+
$ cdk flags --unstable=flags --set --recommended --unconfigured
151+
Feature Flag Recommended Value User Value
152+
* @aws-cdk/... true <unset>
153+
* @aws-cdk/... true <unset>
154+
Synthesizing...
155+
Resources
156+
[~] AWS::S3::Bucket MyBucket
157+
└─ [~] Properties
158+
└─ [~] Encryption
159+
├─ [-] None
160+
└─ [+] ServerSideEncryptionConfiguration:
161+
- ...
162+
...
163+
Number of stacks with differences: 2
164+
Do you want to accept these changes? (y/n) y
165+
Resynthesizing...
166+
----
167+
168+
If you want to ensure that any unconfigured feature flags don't interfere with your application, run the `cdk flags --set --default --unconfigured` command to change the unconfigured flags to their default values. For example, if `@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021` is unconfigured, a notification displays after running `cdk synth`. However, if you set the flag to its default state (false), it will be configured, turned off, and not impact your application.
169+
170+
[source,none,subs="verbatim,attributes"]
171+
----
172+
$ cdk flags --unstable=flags --set --default --unconfigured
173+
Feature Flag Recommended Value User Value
174+
* @aws-cdk/... true <unset>
175+
* @aws-cdk/... true <unset>
176+
Synthesizing...
177+
178+
Do you want to accept these changes? (y/n) y
179+
Resynthesizing...
180+
----
181+
182+
[#ref-cli-cmd-flags-examples-3]
183+
=== Inspect specific feature flags
184+
185+
==== View more information about a flag
186+
187+
In addition to running `cdk flags` and `cdk flags --all` to view your feature flag configuration, you can also utilize `cdk flags "FLAGNAME"` to inspect a specific feature flag and find out what the flag does. This can be helpful in cases where you want to understand a particular flag and its impact on your application.
188+
189+
[source,none,subs="verbatim,attributes"]
190+
----
191+
$ cdk flags --unstable=flags "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021"
192+
Description: Enable this feature flag to have cloudfront distributions use the security policy TLSv1.2_2021 by default.
193+
Recommended Value: true
194+
User Value: true
195+
----
196+
197+
==== Filter flags by substring
198+
199+
You can also run `cdk flags substring` to view all matching feature flags. If there is only one feature flag that matches that substring, specific details are displayed.
200+
201+
[source,none,subs="verbatim,attributes"]
202+
----
203+
$ cdk flags --unstable=flags ebs
204+
@aws-cdk/aws-ec2:ebsDefaultGp3Volume
205+
Description: When enabled, the default volume type of the EBS volume will be GP3
206+
Recommended Value: true
207+
User Value: true
208+
----
209+
210+
If multiple flags match the substring, all matching flags are displayed in a table. If you enter multiple substrings, all matching flags that contain any of the substrings are returned.
211+
212+
[source,none,subs="verbatim,attributes"]
213+
----
214+
$ cdk flags --unstable=flags s3 lambda
215+
Feature Flag Recommended User
216+
* @aws-cdk/s3... true false
217+
* @aws-cdk/lambda... true false
218+
* @aws-cdk/lambda... true <unset>
219+
----
220+
221+
==== Modify a specific flag
222+
223+
If you need to modify the value of a flag and want to make sure you're setting it to a correct and supported state, run `cdk flags --set "FLAGNAME" --value="state"`.
224+
225+
[source,none,subs="verbatim,attributes"]
226+
----
227+
$ cdk flags --unstable=flags --set "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021" --value="true"
228+
Synthesizing...
229+
Resources
230+
[~] AWS::CloudFront::Distribution MyDistribution
231+
└─ [~] Properties
232+
└─ [~] DefaultSecurityPolicy
233+
├─ [-] TLSv1.0
234+
└─ [+] TLSv1.2_2021
235+
- ...
236+
Number of stacks with differences: 2
237+
Do you want to accept these changes? (y/n) y
238+
Resynthesizing...
239+
----

‎v2/guide/ref-cli-cmd.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,10 @@ Inspect and display useful information about your local CDK project and developm
6363
`xref:ref-cli-cmd-drift[drift]`::
6464
Detect configuration drift for resources that you define, manage, and deploy using CDK.
6565

66+
[#ref-cli-cmd-commands-flags]
67+
`xref:ref-cli-cmd-flags[flags]`::
68+
View and modify your feature flag configurations for the CDK CLI.
69+
6670
[#ref-cli-cmd-commands-import]
6771
`xref:ref-cli-cmd-import[import]`::
6872
Use {aws} CloudFormation resource imports to import existing {aws} resources into a CDK stack.
@@ -370,6 +374,8 @@ include::ref-cli-cmd-doctor.adoc[leveloffset=+1]
370374

371375
include::ref-cli-cmd-drift.adoc[leveloffset=+1]
372376

377+
include::ref-cli-cmd-flags.adoc[leveloffset=+1]
378+
373379
include::ref-cli-cmd-gc.adoc[leveloffset=+1]
374380

375381
include::ref-cli-cmd-import.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)