feat(cli): telemetry opt-out command (#579)

Fixes #575 

Enables users of the CDK CLI to opt out of CDK CLI telemetry collection.
More details in the [RFC](aws/aws-cdk-rfcs#734).

Telemetry will be enabled by default.

The following command will disable it, local to your CDK App:
`cdk cli-telemetry --disable`

The following command will enable it again:
`cdk cli-telemetry --enable`

To globally enable/disable telemetry add `{ "cli-telemetry": false }` to
the context values of your `~/.cdk.json` file.

> At the time of writing this PR - the CDK CLI still does not yet send
any telemetry data. We are providing the opt-out capability now to give
enough time to opt-out in advance if they so choose.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

---------

Signed-off-by: github-actions <[email protected]>
Co-authored-by: github-actions <[email protected]>
Co-authored-by: Kaizen Conroy <[email protected]>
Co-authored-by: Kaizen Conroy <[email protected]>

Author: 3 people

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/cli-telemetry/cdk-cli-telemetry-adds-context-value.integtest.ts

@@ -0,0 +1,51 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { integTest, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'CLI Telemetry adds context value to cdk.context.json',
+  withDefaultFixture(async (fixture) => {
+    const contextFile = path.join(fixture.integTestDir, 'cdk.context.json');
+    const context = {
+      existedBefore: 'this was here',
+    };
+    await fs.writeFile(
+      contextFile,
+      JSON.stringify(context),
+    );
+    try {
+      await fixture.cdk(['cli-telemetry', '--disable']);
+      const newContext = JSON.parse((await fs.readFile(
+        contextFile,
+      )).toString());
+      expect(newContext).toEqual({
+        ...context,
+        ['cli-telemetry']: false,
+      });
+
+      // Test that cli-telemetry enable works too
+      await fixture.cdk(['cli-telemetry', '--enable']);
+      const newerContext = JSON.parse((await fs.readFile(
+        contextFile,
+      )).toString());
+      expect(newerContext).toEqual({
+        ...context,
+        ['cli-telemetry']: true,
+      });
+
+      // Test that cli-telemetry --no-enable works (equals --disable)
+      await fixture.cdk(['cli-telemetry', '--no-enable']);
+      const newestContext = JSON.parse((await fs.readFile(
+        contextFile,
+      )).toString());
+      expect(newestContext).toEqual({
+        ...context,
+        ['cli-telemetry']: false,
+      });
+    } finally {
+      await fs.unlink(path.join(fixture.integTestDir, 'cdk.context.json'));
+    }
+  }),
+);

packages/@aws-cdk/user-input-gen/lib/convert-to-user-input-gen.ts

@@ -159,7 +159,7 @@ function buildConfigArgs(config: CliConfig): string {
     'const userInput: UserInput = {',
     'globalOptions,',
     ...(Object.keys(config.commands).map((commandName) => {
-      return `'${commandName}': ${kebabToCamelCase(commandName)}Options,`;
+      return `'${kebabToCamelCase(commandName)}': ${kebabToCamelCase(commandName)}Options,`;
     })),
     '}',
     '',

packages/aws-cdk/lib/cli/cdk-toolkit.ts

@@ -195,6 +195,12 @@ export class CdkToolkit {
     await this.props.configuration.saveContext();
   }
 
+  public async cliTelemetry(enable: boolean) {
+    this.props.configuration.context.set('cli-telemetry', enable);
+    await this.props.configuration.saveContext();
+    info(`Telemetry ${enable ? 'enabled' : 'disabled'}`);
+  }
+
   public async diff(options: DiffOptions): Promise<number> {
     const stacks = await this.selectStacksForDiff(options.stackNames, options.exclusively);
 

packages/aws-cdk/lib/cli/cli-config.ts

@@ -44,7 +44,7 @@ export async function makeConfig(): Promise<CliConfig> {
       'unstable': { type: 'array', desc: 'Opt in to unstable features. The flag indicates that the scope and API of a feature might still change. Otherwise the feature is generally production ready and fully supported. Can be specified multiple times.', default: [] },
     },
     commands: {
-      list: {
+      'list': {
         arg: {
           name: 'STACKS',
           variadic: true,
@@ -56,7 +56,7 @@ export async function makeConfig(): Promise<CliConfig> {
           'show-dependencies': { type: 'boolean', default: false, alias: 'd', desc: 'Display stack dependency information for each stack' },
         },
       },
-      synth: {
+      'synth': {
         arg: {
           name: 'STACKS',
           variadic: true,
@@ -69,7 +69,7 @@ export async function makeConfig(): Promise<CliConfig> {
           quiet: { type: 'boolean', alias: 'q', desc: 'Do not output CloudFormation Template to stdout', default: false },
         },
       },
-      bootstrap: {
+      'bootstrap': {
         arg: {
           name: 'ENVIRONMENTS',
           variadic: true,
@@ -97,7 +97,7 @@ export async function makeConfig(): Promise<CliConfig> {
           'previous-parameters': { type: 'boolean', default: true, desc: 'Use previous values for existing parameters (you must specify all parameters on every deployment if this is disabled)' },
         },
       },
-      gc: {
+      'gc': {
         description: 'Garbage collect assets. Options detailed here: https://github.com/aws/aws-cdk-cli/tree/main/packages/aws-cdk#cdk-gc',
         arg: {
           name: 'ENVIRONMENTS',
@@ -112,7 +112,7 @@ export async function makeConfig(): Promise<CliConfig> {
           'bootstrap-stack-name': { type: 'string', desc: 'The name of the CDK toolkit stack, if different from the default "CDKToolkit"', requiresArg: true },
         },
       },
-      deploy: {
+      'deploy': {
         description: 'Deploys the stack(s) named STACKS into your AWS account',
         options: {
           'all': { type: 'boolean', desc: 'Deploy all available stacks', default: false },
@@ -193,7 +193,7 @@ export async function makeConfig(): Promise<CliConfig> {
           variadic: true,
         },
       },
-      rollback: {
+      'rollback': {
         description: 'Rolls back the stack(s) named STACKS to their last stable state',
         arg: {
           name: 'STACKS',
@@ -219,7 +219,7 @@ export async function makeConfig(): Promise<CliConfig> {
           },
         },
       },
-      import: {
+      'import': {
         description: 'Import existing resource(s) into the given STACK',
         arg: {
           name: 'STACK',
@@ -255,7 +255,7 @@ export async function makeConfig(): Promise<CliConfig> {
           },
         },
       },
-      watch: {
+      'watch': {
         description: "Shortcut for 'deploy --watch'",
         arg: {
           name: 'STACKS',
@@ -308,7 +308,7 @@ export async function makeConfig(): Promise<CliConfig> {
           'concurrency': { type: 'number', desc: 'Maximum number of simultaneous deployments (dependency permitting) to execute.', default: 1, requiresArg: true },
         },
       },
-      destroy: {
+      'destroy': {
         description: 'Destroy the stack(s) named STACKS',
         arg: {
           name: 'STACKS',
@@ -320,7 +320,7 @@ export async function makeConfig(): Promise<CliConfig> {
           force: { type: 'boolean', alias: 'f', desc: 'Do not ask for confirmation before destroying the stacks' },
         },
       },
-      diff: {
+      'diff': {
         description: 'Compares the specified stack with the deployed stack or a local template file, and returns with status 1 if any difference is found',
         arg: {
           name: 'STACKS',
@@ -339,7 +339,7 @@ export async function makeConfig(): Promise<CliConfig> {
           'import-existing-resources': { type: 'boolean', desc: 'Whether or not the change set imports resources that already exist', default: false },
         },
       },
-      drift: {
+      'drift': {
         description: 'Detect drifts in the given CloudFormation stack(s)',
         arg: {
           name: 'STACKS',
@@ -349,28 +349,28 @@ export async function makeConfig(): Promise<CliConfig> {
           fail: { type: 'boolean', desc: 'Fail with exit code 1 if drift is detected' },
         },
       },
-      metadata: {
+      'metadata': {
         description: 'Returns all metadata associated with this stack',
         arg: {
           name: 'STACK',
           variadic: false,
         },
       },
-      acknowledge: {
+      'acknowledge': {
         aliases: ['ack'],
         description: 'Acknowledge a notice so that it does not show up anymore',
         arg: {
           name: 'ID',
           variadic: false,
         },
       },
-      notices: {
+      'notices': {
         description: 'Returns a list of relevant notices',
         options: {
           unacknowledged: { type: 'boolean', alias: 'u', default: false, desc: 'Returns a list of unacknowledged notices' },
         },
       },
-      init: {
+      'init': {
         description: 'Create a new, empty CDK project from a template.',
         arg: {
           name: 'TEMPLATE',
@@ -383,7 +383,7 @@ export async function makeConfig(): Promise<CliConfig> {
           'lib-version': { type: 'string', alias: 'V', default: undefined, desc: 'The version of the CDK library (aws-cdk-lib) to initialize the project with. Defaults to the version that was current when this CLI was built.' },
         },
       },
-      migrate: {
+      'migrate': {
         description: 'Migrate existing AWS resources into a CDK app',
         options: {
           'stack-name': { type: 'string', alias: 'n', desc: 'The name assigned to the stack created in the new project. The name of the app will be based off this name as well.', requiresArg: true },
@@ -411,15 +411,15 @@ export async function makeConfig(): Promise<CliConfig> {
           'compress': { type: 'boolean', desc: 'Use this flag to zip the generated CDK app' },
         },
       },
-      context: {
+      'context': {
         description: 'Manage cached context values',
         options: {
           reset: { alias: 'e', desc: 'The context key (or its index) to reset', type: 'string', requiresArg: true, default: undefined },
           force: { alias: 'f', desc: 'Ignore missing key error', type: 'boolean', default: false },
           clear: { desc: 'Clear all context', type: 'boolean', default: false },
         },
       },
-      docs: {
+      'docs': {
         aliases: ['doc'],
         description: 'Opens the reference documentation in a browser',
         options: {
@@ -431,10 +431,10 @@ export async function makeConfig(): Promise<CliConfig> {
           },
         },
       },
-      doctor: {
+      'doctor': {
         description: 'Check your set-up for potential problems',
       },
-      refactor: {
+      'refactor': {
         description: 'Moves resources between stacks or within the same stack',
         arg: {
           name: 'STACKS',
@@ -463,6 +463,21 @@ export async function makeConfig(): Promise<CliConfig> {
           },
         },
       },
+      'cli-telemetry': {
+        description: 'Enable or disable anonymous telemetry',
+        options: {
+          enable: {
+            type: 'boolean',
+            desc: 'Enable anonymous telemetry',
+            conflicts: 'disable',
+          },
+          disable: {
+            type: 'boolean',
+            desc: 'Disable anonymous telemetry',
+            conflicts: 'enable',
+          },
+        },
+      },
     },
   };
 }

packages/aws-cdk/lib/cli/cli.ts

@@ -454,6 +454,15 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
         ioHost.currentAction = 'notices';
         return cli.acknowledge(args.ID);
 
+      case 'cli-telemetry':
+        ioHost.currentAction = 'cli-telemetry';
+        if (args.enable === undefined && args.disable === undefined) {
+          throw new ToolkitError('Must specify either \'--enable\' or \'--disable\'');
+        }
+
+        const enable = args.enable ?? !args.disable;
+        return cli.cliTelemetry(enable);
+
       case 'init':
         ioHost.currentAction = 'init';
         const language = configuration.settings.get(['language']);

packages/aws-cdk/lib/cli/convert-to-user-input.ts

@@ -275,6 +275,13 @@ export function convertYargsToUserInput(args: any): UserInput {
         STACKS: args.STACKS,
       };
       break;
+
+    case 'cli-telemetry':
+      commandOptions = {
+        enable: args.enable,
+        disable: args.disable,
+      };
+      break;
   }
   const userInput: UserInput = {
     command: args._[0],
@@ -472,6 +479,10 @@ export function convertConfigToUserInput(config: any): UserInput {
     mappingFile: config.refactor?.mappingFile,
     revert: config.refactor?.revert,
   };
+  const cliTelemetryOptions = {
+    enable: config.cliTelemetry?.enable,
+    disable: config.cliTelemetry?.disable,
+  };
   const userInput: UserInput = {
     globalOptions,
     list: listOptions,
@@ -494,6 +505,7 @@ export function convertConfigToUserInput(config: any): UserInput {
     docs: docsOptions,
     doctor: doctorOptions,
     refactor: refactorOptions,
+    cliTelemetry: cliTelemetryOptions,
   };
 
   return userInput;

packages/aws-cdk/lib/cli/io-host/cli-io-host.ts

@@ -19,6 +19,7 @@ type CliAction =
 | 'docs'
 | 'notices'
 | 'version'
+| 'cli-telemetry'
 | 'none';
 
 export interface CliIoHostProps {

packages/aws-cdk/lib/cli/parse-command-line-arguments.ts

@@ -907,6 +907,21 @@ export function parseCommandLineArguments(args: Array<string>): any {
           desc: 'If specified, the command will revert the refactor operation. This is only valid if a mapping file was provided.',
         }),
     )
+    .command('cli-telemetry', 'Enable or disable anonymous telemetry', (yargs: Argv) =>
+      yargs
+        .option('enable', {
+          default: undefined,
+          type: 'boolean',
+          desc: 'Enable anonymous telemetry',
+          conflicts: 'disable',
+        })
+        .option('disable', {
+          default: undefined,
+          type: 'boolean',
+          desc: 'Disable anonymous telemetry',
+          conflicts: 'enable',
+        }),
+    )
     .version(helpers.cliVersion())
     .demandCommand(1, '')
     .recommendCommands()

packages/aws-cdk/lib/cli/user-configuration.ts

@@ -38,6 +38,7 @@ export enum Command {
   DOCTOR = 'doctor',
   REFACTOR = 'refactor',
   DRIFT = 'drift',
+  CLI_TELEMETRY = 'cli-telemetry',
 }
 
 const BUNDLING_COMMANDS = [

packages/aws-cdk/lib/cli/user-input.ts

@@ -128,6 +128,11 @@ export interface UserInput {
    * Moves resources between stacks or within the same stack
    */
   readonly refactor?: RefactorOptions;
+
+  /**
+   * Enable or disable anonymous telemetry
+   */
+  readonly cliTelemetry?: CliTelemetryOptions;
 }
 
 /**
@@ -1452,3 +1457,24 @@ export interface RefactorOptions {
    */
   readonly STACKS?: Array<string>;
 }
+
+/**
+ * Enable or disable anonymous telemetry
+ *
+ * @struct
+ */
+export interface CliTelemetryOptions {
+  /**
+   * Enable anonymous telemetry
+   *
+   * @default - undefined
+   */
+  readonly enable?: boolean;
+
+  /**
+   * Disable anonymous telemetry
+   *
+   * @default - undefined
+   */
+  readonly disable?: boolean;
+}