Configuration Guide

Name: CDK Insights
Author: CDK Insights

Learn how to configure CDK Insights to match your workflow. Set up output formats, analysis options, and customize behavior with the .cdk-insights.json configuration file.

Configuration Overview

CDK Insights can be configured using a .cdk-insights.json file in your CDK project root. This allows you to:

Set default output formats and analysis options
Configure CI/CD behavior and error handling
Limit analysis to specific services or stacks
Customize the analysis workflow for your team

Configuration settings can be overridden by command-line flags, giving you flexibility for different use cases.

Configuration Options

Option	Type	Default	Description
`stackName`	string	`""`	Default stack name to analyze
`output`	string	`"table"`	Default output format for analysis results
`services`	array	`[]`	Limit analysis to specific AWS services
`ruleFilter`	array	`[]`	Filter findings by rule categories
`failOnCritical`	boolean	`true`	Exit with error code when critical issues are found
`synth`	boolean	`false`	Run cdk synth before analysis
`summaryOnly`	boolean	`false`	Only show summary in console
`redact`	boolean	`false`	Redact sensitive resource names in output
`withIssue`	boolean	`false`	Create GitHub issues for findings (markdown output only)
`noCache`	boolean	`false`	Disable cache and force fresh analysis
`cache`	object	`{"enabled": true, "ttl": 300000, "maxSize": 1000}`	Cache configuration object

Configuration Examples

Basic Configuration

Simple setup for development workflow

Use Case:

Daily development and testing

{
  "output": "table",
  "failOnCritical": true,
  "services": []
}

CI/CD Configuration

Configuration optimized for continuous integration

Use Case:

Automated pipeline analysis

{
  "output": "json",
  "failOnCritical": true,
  "synth": true,
  "noCache": true
}

Team Reporting

Configuration for team collaboration and reporting

Use Case:

Weekly team reports and documentation

{
  "output": "markdown",
  "synth": true,
  "withIssue": true
}

Security Focus

Configuration focused on security analysis

Use Case:

Security audits and compliance checks

{
  "output": "summary",
  "failOnCritical": true,
  "services": [
    "IAM",
    "S3",
    "Lambda"
  ],
  "ruleFilter": [
    "Security"
  ]
}

Creating a Configuration File

Create the Configuration File

Create a .cdk-insights.json file in your CDK project root directory.

touch .cdk-insights.json

Add Configuration Options

Add your desired configuration options to the file.

{
  "output": "markdown",
  "failOnCritical": true,
  "all": true
}

Test Your Configuration

Run CDK Insights to verify your configuration is working correctly.

cdk-insights scan

Best Practices

Project-Specific Configuration

Create a .cdk-insights.json file in each CDK project root for project-specific settings

Example: .cdk-insights.json in your CDK project directory

Team Consistency

Share configuration files with your team to ensure consistent analysis across environments

Example: Commit .cdk-insights.json to version control

Environment-Specific Settings

Use different configurations for development, staging, and production environments

Example: Different failOnCritical settings per environment

Documentation

Document your configuration choices to help team members understand the setup

Example: Add comments explaining complex configuration options

Configuration Precedence

CDK Insights follows a specific order when determining which configuration to use:

Note: Some options like all, ci, and yes are CLI-only flags and cannot be saved to configuration files.

Command Line Flags

Highest priority - overrides all other settings

Interactive Prompts

User choices during CLI execution (when not in CI mode)

.cdk-insights.json File

Project-specific configuration file

Default Values

Built-in defaults when no other configuration exists

Common Configuration Issues

❌ "Invalid JSON in .cdk-insights.json"

Make sure your configuration file contains valid JSON syntax.

# Validate JSON syntax
cat .cdk-insights.json | jq .

❌ "Configuration not being applied"

Ensure the .cdk-insights.json file is in the correct location (CDK project root).

# Check file location
ls -la .cdk-insights.json

❌ "Unknown configuration option"

Verify that you're using supported configuration options.

# Check available options
cdk-insights --help

Ready to Configure CDK Insights?

Set up your configuration file to customize CDK Insights for your workflow and team needs.

Advanced Options Output Formats