The AWS CDK writes a file called `cdk.context.json` in your project. What goes into it, and should it be committed to version control?

## Which calls are lookups Most of the CDK never talks to AWS. A handful of calls do, during synthesis, and they are all named in a way that hints at it: - `ec2.Vpc.fromLookup(...)` — finds an existing VPC and its subnets and AZs; - `route53.HostedZone.fromLookup(...)` — finds a hosted zone id by domain name; - `ec2.MachineImage.lookup(...)` — resolves an AMI id by filter; - `ssm.StringParameter.valueFromLookup(...)` — reads a parameter's value at synthesis; - the stack's availability-zone list. Each is a **context provider**. The CLI runs it, gets an answer, and the answer is baked into the template as a literal — a real `vpc-…` id, a real AMI id, a real string. ## Why the results are cached A CloudFormation template has to contain literal values, and the CDK's contract is that synthesis is a pure function from your code to a template. If lookups ran on every synth, that contract would break in two ways: you would need credentials for the target account every time you built (including in a PR job that has no business holding them), and the template could change underneath you because someone else created a subnet. So the first synth performs the missing lookups and records them in `cdk.context.json`, keyed by provider, account, region and the query arguments. Every later synth uses the cache and makes no AWS call. ```json { "vpc-provider:account=111122223333:filter.vpc-id=vpc-0abc123:region=eu-west-1": { "vpcId": "vpc-0abc123", "availabilityZones": ["eu-west-1a", "eu-west-1b"] } } ``` ## Commit it The file is meant to be in version control. The reasons are the reasons the cache exists: - **Reproducibility.** A given commit synthesizes to a given template on any machine. - **Credential-free builds.** CI can synth, run `cdk diff` against a template, and run policy checks without access to the target account. - **Reviewability.** When a looked-up value changes, it changes in a commit that a human approves, rather than silently between two builds. That last point is the important one and it is the answer to "but it goes stale". Staleness is not an accident of the design; it is the design. You are choosing to change infrastructure inputs deliberately. ## Refreshing an entry When the underlying resource really has changed — the VPC was replaced, a new AMI was published — the cache must be invalidated explicitly: - `cdk context` lists the cached entries with numbers; - `cdk context --reset <key-or-number>` drops one; - `cdk context --clear` drops all of them. Then re-synth with credentials for the right account, review the resulting diff in `cdk.context.json` and in the template, and commit both. The reason to prefer `--reset` over `--clear` is that clearing everything re-queries every provider and produces a large, hard-to-review diff. A common confusion: `cdk.context.json` is the *cache*, while context **values** you set yourself (`cdk.json`'s `context` block, `--context key=value`, `node.tryGetContext`) are inputs. Both live in the same context mechanism, which is why the file sometimes contains feature flags too — those you edit deliberately rather than resetting. ## Synthesis-time versus deploy-time values The alternative to a lookup is to defer the value to deploy time. SSM makes the contrast concrete: `ssm.StringParameter.valueFromLookup` reads the parameter during synthesis and inlines the string, whereas `ssm.StringParameter.valueForStringParameter` emits a CloudFormation dynamic reference that CloudFormation resolves during the deployment. The tradeoff is visibility versus freshness. A synthesis-time value is visible in the template and in `cdk diff`, so a review shows exactly what will be deployed; it goes stale. A deploy-time value is always current; it is opaque to `cdk diff`, and a change to the parameter can alter your infrastructure with no code change at all — which is either the flexibility you wanted or an unreviewed change to production, depending on the parameter. ## Gotchas worth naming Lookups need a stack with a concrete account and region, so an environment-agnostic stack cannot use them at all. If the CLI cannot perform a lookup — no credentials, wrong account — the synth produces obviously fake placeholder values so it can complete, and those templates must never be deployed. And the committed file contains account ids, VPC ids, AZ names and AMI ids, which is usually fine for a private repository but worth a moment's thought before open-sourcing a CDK app.