managing-aws-cdk

name	managing-aws-cdk
description	Use when working with Aws Cdk — aWS CDK infrastructure-as-code management. Covers synth, diff, deploy, bootstrap, context values, construct inspection, and stack dependencies. Use when managing CDK applications, reviewing synthesized templates, comparing deployments, or debugging construct issues.
connection_type	aws-cdk
preload	false

AWS CDK Management Skill

Manage and inspect AWS CDK applications, stacks, and synthesized CloudFormation templates.

MANDATORY: Discovery-First Pattern

Always list stacks and synth before deploying.

Phase 1: Discovery

#!/bin/bash

echo "=== CDK Version ==="
cdk --version 2>/dev/null

echo ""
echo "=== Available Stacks ==="
cdk list --long 2>/dev/null

echo ""
echo "=== CDK Context ==="
cdk context --json 2>/dev/null | jq '.' | head -20

echo ""
echo "=== Project Structure ==="
cat cdk.json 2>/dev/null | jq '{app: .app, context: .context}' || \
cat cdk.json 2>/dev/null | head -20

Core Helper Functions

#!/bin/bash

# CDK wrapper
cdk_cmd() {
    cdk "$@" --no-color 2>&1
}

# Synth and inspect template
cdk_synth_json() {
    local stack="$1"
    cdk synth "$stack" --quiet --json 2>/dev/null
}

# Get resource count from synthesized template
cdk_resource_count() {
    local stack="$1"
    cdk_synth_json "$stack" | jq '.Resources | length'
}

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Use --json or --quiet to suppress banner output
• Pipe synth output through jq for filtering
• Never dump full synthesized templates -- extract resource summaries

Common Operations

Synthesize and Inspect

#!/bin/bash
STACK="${1:-}"

echo "=== Synthesizing ==="
if [ -n "$STACK" ]; then
    cdk synth "$STACK" --quiet --json 2>/dev/null | jq '{
        Resources: (.Resources | to_entries | map({key: .key, type: .value.Type}) | from_entries),
        ResourceCount: (.Resources | length),
        Outputs: (.Outputs | keys),
        Parameters: (.Parameters | keys)
    }'
else
    cdk synth --quiet 2>&1 | tail -5
    echo ""
    echo "=== All Stack Resource Counts ==="
    for stack in $(cdk list 2>/dev/null); do
        COUNT=$(cdk synth "$stack" --quiet --json 2>/dev/null | jq '.Resources | length')
        echo "$stack: $COUNT resources"
    done
fi

Diff (Compare Deployed vs Local)

#!/bin/bash
STACK="${1:-}"

echo "=== CDK Diff ==="
if [ -n "$STACK" ]; then
    cdk diff "$STACK" --no-color 2>&1 | head -60
else
    echo "Diffing all stacks..."
    cdk diff --no-color 2>&1 | head -80
fi

Deploy (with Safety)

#!/bin/bash
STACK="${1:?Stack name required}"
DRY_RUN="${2:-true}"

if [ "$DRY_RUN" = "true" ]; then
    echo "=== DRY RUN: Showing what would deploy ==="
    cdk diff "$STACK" --no-color 2>&1 | head -50
    echo ""
    echo "To actually deploy, confirm with dry_run=false"
else
    echo "=== Deploying $STACK ==="
    cdk deploy "$STACK" --require-approval=broadening --no-color 2>&1 | tail -30
fi

Bootstrap Status

#!/bin/bash
ACCOUNT="${1:-$(aws sts get-caller-identity --query Account --output text 2>/dev/null)}"
REGION="${2:-$(aws configure get region 2>/dev/null)}"

echo "=== Bootstrap Stack Status ==="
aws cloudformation describe-stacks --stack-name CDKToolkit \
    --query 'Stacks[0].{Status:StackStatus,Version:Parameters[?ParameterKey==`BootstrapVersion`].ParameterValue|[0],Qualifier:Parameters[?ParameterKey==`Qualifier`].ParameterValue|[0]}' \
    --output table 2>/dev/null

echo ""
echo "=== Bootstrap Bucket ==="
aws cloudformation describe-stack-resources --stack-name CDKToolkit \
    --query 'StackResources[?ResourceType==`AWS::S3::Bucket`].{Id:LogicalResourceId,Physical:PhysicalResourceId}' \
    --output table 2>/dev/null

echo ""
echo "=== Bootstrap Version ==="
CURRENT=$(aws ssm get-parameter --name /cdk-bootstrap/hnb659fds/version \
    --query 'Parameter.Value' --output text 2>/dev/null || echo "not found")
echo "Current bootstrap version: $CURRENT"

Construct and Dependency Analysis

#!/bin/bash
echo "=== Stack Dependencies ==="
cdk list --long 2>/dev/null

echo ""
echo "=== Construct Tree ==="
STACK="${1:-$(cdk list 2>/dev/null | head -1)}"
cdk synth "$STACK" --quiet 2>/dev/null
cat cdk.out/tree.json 2>/dev/null | jq '
    .tree.children | to_entries[] |
    {id: .key, construct: .value.constructInfo.fqn, children: (.value.children // {} | keys)}
' | head -40

Safety Rules

• NEVER deploy without reviewing diff first -- always run cdk diff before cdk deploy
• Use --require-approval=broadening to require confirmation for security-sensitive changes
• Bootstrap before first deploy -- cdk bootstrap required per account/region
• Review IAM changes carefully -- CDK auto-generates IAM policies that may be overly permissive
• Use cdk destroy with caution -- it removes all resources in the stack

Output Format

Present results as a structured report:

Managing Aws Cdk Report
═══════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• Context values: CDK caches context lookups (VPC IDs, AMIs) -- stale context causes drift -- use cdk context --reset
• Construct IDs: Changing construct IDs causes resource replacement -- review diff carefully
• Asset bundling: Lambda/Docker assets require local tooling (Docker, esbuild) -- build errors are common
• Cross-stack references: Removing exported values breaks dependent stacks -- remove consumers first
• Bootstrap version: Newer CDK versions may require re-bootstrapping -- check version compatibility
• Hotswap limitations: --hotswap skips CloudFormation for speed but may leave stack in inconsistent state
• Snapshot tests: CDK snapshot tests break on any template change -- update snapshots after intentional changes
• L1 vs L2 constructs: L1 (Cfn*) constructs mirror CloudFormation directly; L2 constructs add defaults that may surprise