cdk synthesize clarification

[gabor-s]

❓ General Issue

The Question

According to the documentation the cdk synthesize command synthesizes and prints the CloudFormation template for the given stack. But in reality it prints the template of the given stack and outputs every stack's template to cdk.out. I don't know if this is a bug or the intended behavior. In the latter case why was it implemented this way? Why does it print to the console and output to the directory at the same time?

Environment

• CDK CLI Version: 1.39.0 (build 5d727c1)
• Module Version:
• OS: Windows 10
• Language: CLI

Other information

[strottos]

I would second the confusion here. I still can't tell for sure if I need to run synth before deploy but it seems that I don't. It is a point of confusion that it would be nice to address on the documentation if possible.

[shivlaks]

@suhaig thanks for letting us know about that. it seems like the documentation needs a bit of a refresh. copy @jerry-aws

cdk synth prints out the given stack. If you have multiple stacks, you should see a message that indicates the stacks that were synthsized.

const app = new cdk.App();
new ExampleStack(app, 'ExampleStack');
new ExampleStack(app, 'MyOtherExamplestack');

cdk synth would render to

Successfully synthesized to some/path/cdk.out
Supply a stack id (ExampleStack, MyOtherExamplestack) to display its template.

The printed output is intended to be human readable (which is why we render it in YAML). The cdk.out folder is the default directory in which the synthesized cloud assembly is stored. It's used during deploy and stores the templates in JSON. We do not expect users to interact directly with the cloud assembly. Learn more about the cloud assembly schema here

@strottos you do not need to run synth ahead of a deploy, the CDK will handle that for you. If a cloud assembly directory does not exist (i.e. cdk.out), it will create one, synthesize the cloud assembly, and then deploy from that assembly.

[ghost]

We could really use more content on the CDK lifecycle in the dev guide.

[gabor-s]

@shivlaks thanks for the clarification. You said that users don't interact directly with cloud assembly. I thought that synth can be used to create a cloud assembly that can be deployed later. For example in a CI system the build pipeline would create the cloud assembly, upload it to some artifact storage system and later the deploy pipeline would deploy it. So what I mean is that users should know that synth is creating a cloud assembly behind the scenes.

[shivlaks]

@suhaig absolutely, you're right. I meant users don't interact directly with the contents in the cloud assembly (i.e. the manifest, the templates, etc). The assembly itself is an artifact and would be used as you've described. hope that clarifies things!

[gabor-s]

Thank you @shivlaks, it's clear now. To summarize: cdk synth will always synthesize all the stacks, but will print the ones you selected. The CLI documentation states that "Synthesizes and prints the CloudFormation template for this stack", so it needs a little update to make things clearer.

[shivlaks]

@suhaig - good catch, I'll update that area of the README today

[SomayaB]

Closing this issue since it seems to have been resolved by #8264. Feel free to reopen.

[johnny-human]

Hello, I am experiencing an issue with my multi-stack app when using a GitHub workflow to deploy stacks and provision dashboards to Grafana. I use an action script that synthesize the stack before it use aws.Cloudformation from the sdk. It works fine when only one stack is defined. Problem is when I want to only synth one stack.

Because this multi stack app has stacks that should be deployed to separate accounts, it seems to run into trouble when synthesizing, as it has to authenticate with proper credentials, and I only have access to one account credentials at one time. I figured out, when it runs npx cdk synth GrafanaStack in the github action, it synthesize both stacks to cdk.out and logs this error:

Error: Command failed: npx cdk synth --outputs-file cdk.out
[Error at /InfluxDBStack] Need to perform AWS calls for account 229944008877, but no credentials have been configured
Found errors

const app = new cdk.App();

new GrafanaStack(app, 'GrafanaStack', {
    env: { account: '227777556644', region: 'eu-central-1' },
    domain: 'example.com',
    subdomain: 'grafana',
    cloudWatchAssumeRoleArn: 'arn:aws:iam::229944008877:role/grafana-role',
});

new InfluxDBStack(app, 'InfluxDBStack', {
    env: { account: '229944008877', region: 'eu-central-1' },
});

It's worth noting that this error doesn't seem to be a problem on some workflow jobs, but it breaks the InfluxDBStack for some reason. I would like to reopen this issue to troubleshoot and resolve this problem.