Skip to content

Commit add2ae7

Browse files
vivian12300vivian12300
authored
docs: update README for cdk flags command (#789)
This PR adds information about the `cdk flags` command to 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 17ebf86 commit add2ae7

File tree

1 file changed

+143
-0
lines changed

1 file changed

+143
-0
lines changed

‎packages/aws-cdk/README.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1238,6 +1238,149 @@ that can be set in many different ways (such as `~/.cdk.json`).
12381238
$ # Check the current status of telemetry
12391239
$ cdk cli-telemetry --status
12401240
```
1241+
### `cdk flags`
1242+
1243+
View and modify your feature flag configurations.
1244+
1245+
Run `cdk flags` to see a report of your feature flag configurations that differ from our recommended states. Unconfigured flags will be labelled with `<unset>` to show that flag currently has no value. The flags are displayed to you in the following order:
1246+
1247+
1. flags whose states do not match our recommended values
1248+
2. flags that are not configured at all
1249+
1250+
```shell
1251+
$ cdk flags --unstable=flags
1252+
Feature Flag Recommended User
1253+
* @aws-cdk/... true false
1254+
* @aws-cdk/... true false
1255+
* @aws-cdk/... true <unset>
1256+
```
1257+
1258+
Alternatively, you can also run `cdk flags --all` to see a report of all feature flags in the following order:
1259+
1260+
1. flags whose states match our recommended values
1261+
2. flags whose states do not match our recommended values
1262+
3. flags that are not configured at all
1263+
1264+
```shell
1265+
$ cdk flags --unstable=flags --all
1266+
Feature Flag Recommended User
1267+
@aws-cdk/... true true
1268+
* @aws-cdk/... true false
1269+
* @aws-cdk/... true false
1270+
* @aws-cdk/... true <unset>
1271+
```
1272+
1273+
### Modifying your feature flag values
1274+
1275+
To modify your feature flags interactively, you can run `cdk flags --interactive` (or `cdk flags -i`) to view a list of menu options.
1276+
1277+
To change every single feature flag to our recommended value and potentially overwrite existing configured values, run `cdk flags --set --recommended --all`. To keep feature flag configuration up-to-date with the latest CDK feature flag configurations, use this command.
1278+
1279+
```shell
1280+
$ cdk flags --unstable=flags --set --recommended --all
1281+
Feature Flag Recommended Value User Value
1282+
* @aws-cdk/... true false
1283+
* @aws-cdk/... true false
1284+
* @aws-cdk/... true <unset>
1285+
Synthesizing...
1286+
Resources
1287+
[~] AWS::S3::Bucket MyBucket
1288+
└─ [~] Properties
1289+
└─ [~] Encryption
1290+
...
1291+
Number of stacks with differences: 2
1292+
Do you want to accept these changes? (y/n) y
1293+
Resynthesizing...
1294+
```
1295+
1296+
If you would prefer your existing configured flags untouched, this option only changes the unconfigured feature flags to our recommended values, run `cdk flags --set --recommended --unconfigured`. This only changes the unconfigured feature flags to our recommended values.
1297+
1298+
```shell
1299+
$ cdk flags --unstable=flags --set --recommended --unconfigured
1300+
Feature Flag Recommended Value User Value
1301+
* @aws-cdk/... true <unset>
1302+
* @aws-cdk/... true <unset>
1303+
Synthesizing...
1304+
Resources
1305+
[~] AWS::S3::Bucket MyBucket
1306+
└─ [~] Properties
1307+
└─ [~] Encryption
1308+
├─ [-] None
1309+
└─ [+] ServerSideEncryptionConfiguration:
1310+
- ...
1311+
...
1312+
Number of stacks with differences: 2
1313+
Do you want to accept these changes? (y/n) y
1314+
Resynthesizing...
1315+
```
1316+
1317+
If you want to ensure the unconfigured flags do not interfere with your application, `cdk flags --set --default --unconfigured` changes the unconfigured feature flags to its default values. For example, if `@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021` is unconfigured, it leads to the notification appearing after running `cdk synth`. However, if you set the flag to its default state (false), it will be configured, turned off, and have no impact on your application whatsoever.
1318+
1319+
```shell
1320+
$ cdk flags --unstable=flags --set --default --unconfigured
1321+
Feature Flag Recommended Value User Value
1322+
* @aws-cdk/... true <unset>
1323+
* @aws-cdk/... true <unset>
1324+
Synthesizing...
1325+
1326+
Do you want to accept these changes? (y/n) y
1327+
Resynthesizing...
1328+
```
1329+
1330+
### Inspect a specific feature flag
1331+
1332+
#### View more information about a flag
1333+
1334+
Besides 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 a specific flag does. This can be helpful in cases where you want to understand a particular flag and its impact on your application.
1335+
1336+
```shell
1337+
$ cdk flags --unstable=flags "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021"
1338+
Description: Enable this feature flag to have cloudfront distributions use the security policy TLSv1.2_2021 by default.
1339+
Recommended Value: true
1340+
User Value: true
1341+
```
1342+
1343+
#### Filter flags by substring
1344+
1345+
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 will be displayed.
1346+
1347+
```shell
1348+
$ cdk flags --unstable=flags ebs
1349+
@aws-cdk/aws-ec2:ebsDefaultGp3Volume
1350+
Description: When enabled, the default volume type of the EBS volume will be GP3
1351+
Recommended Value: true
1352+
User Value: true
1353+
```
1354+
1355+
If there are multiple flags matching the substring, a table with all matching flags will be displayed. If you enter multiple substrings, all matching flags
1356+
that contain any of those substrings will be returned.
1357+
1358+
```shell
1359+
$ cdk flags --unstable=flags s3 lambda
1360+
Feature Flag Recommended User
1361+
* @aws-cdk/s3... true false
1362+
* @aws-cdk/lambda... true false
1363+
* @aws-cdk/lambda... true <unset>
1364+
```
1365+
1366+
#### Modify a particular flag
1367+
1368+
If you need to modify the value of this flag and want to make sure you’re setting it to a correct and supported state, run `cdk flags --set "#FLAGNAME#" --value="#state#"`.
1369+
1370+
```shell
1371+
$ cdk flags --unstable=flags--set "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021" --value="true"
1372+
Synthesizing...
1373+
Resources
1374+
[~] AWS::CloudFront::Distribution MyDistribution
1375+
└─ [~] Properties
1376+
└─ [~] DefaultSecurityPolicy
1377+
├─ [-] TLSv1.0
1378+
└─ [+] TLSv1.2_2021
1379+
- ...
1380+
Number of stacks with differences: 2
1381+
Do you want to accept these changes? (y/n) y
1382+
Resynthesizing...
1383+
```
12411384

12421385
## Global Options
12431386

0 commit comments

Comments
 (0)