feat(cli): write stack outputs to a file (#7020)

feat(cli): write stack outputs to a file

Write stack outputs from deployments into a file. A flag `--outputs-file` can be provided where stack outputs will be written in `json` format.

Supports multi-stack and wild-card deployments where all the generated outputs from deployed stacks will be written to the outputs file.

Closes #1773

packages/aws-cdk/README.md

@@ -158,9 +158,67 @@ Example of overwriting the topic name from a previous deployment.
 $ cdk deploy --parameters "ParametersStack:TopicNameParam=blahagain" --force
 ```
 
-⚠️ Parameters will be applied to all stacks if a stack name is not specified or `*` is provided. Parameters provided to Stacks that do not make use of the parameter will not successfully deploy.
+⚠️ Parameters will be applied to all stacks if a stack name is not specified or `*` is provided.
+Parameters provided to Stacks that do not make use of the parameter will not successfully deploy.
 
-⚠️ Parameters do not propagate to NestedStacks. These must be sent with the constructor. See Nested Stack [documentation](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-cloudformation.NestedStack.html)
+⚠️ Parameters do not propagate to NestedStacks. These must be sent with the constructor.
+See Nested Stack [documentation](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-cloudformation.NestedStack.html)
+
+##### Outputs
+
+Write stack outputs from deployments into a file. When your stack finishes deploying, all stack outputs
+will be written to the output file as JSON.
+
+Usage of output in a CDK stack
+```typescript
+const fn = new lambda.Function(this, "fn", {
+ handler: "index.handler",
+ code: lambda.Code.fromInline(`exports.handler = \${handler.toString()}`),
+ runtime: lambda.Runtime.NODEJS_10_X
+});
+
+new cdk.CfnOutput(this, 'FunctionArn', {
+ value: fn.functionArn,
+});
+```
+
+Specify an outputs file to write to by supplying the `--outputs-file` parameter
+
+```console
+$ cdk deploy --outputs-file outputs.json
+```
+
+When the stack finishes deployment, `outputs.json` would look like this:
+```json
+{
+ "MyStack": {
+ "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
+ }
+}
+```
+
+⚠️ The `key` of the outputs corresponds to the logical ID of the `CfnOutput`.
+Read more about identifiers in the CDK [here](https://docs.aws.amazon.com/cdk/latest/guide/identifiers.html)
+
+If multiple stacks are being deployed or the wild card `*` is used to deploy all stacks, all outputs
+are written to the same output file where each stack artifact ID is a key in the JSON file
+
+
+```console
+$ cdk deploy '*' --outputs-file "/Users/code/myproject/outputs.json"
+```
+
+Example `outputs.json` after deployment of multiple stacks
+```json
+{
+ "MyStack": {
+ "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
+ },
+ "AnotherStack": {
+ "VPCId": "vpc-z0mg270fee16693f"
+ } 
+}
+```
 
 #### `cdk destroy`
 Deletes a stack from it's environment. This will cause the resources in the stack to be destroyed (unless they were

packages/aws-cdk/bin/cdk.ts

@@ -71,6 +71,7 @@ async function parseCommandLineArguments() {
  .option('execute', { type: 'boolean', desc: 'Whether to execute ChangeSet (--no-execute will NOT execute the ChangeSet)', default: true })
  .option('force', { alias: 'f', type: 'boolean', desc: 'Always deploy stack even if templates are identical', default: false })
  .option('parameters', { type: 'array', desc: 'Additional parameters passed to CloudFormation at deploy time (STACK:KEY=VALUE)', nargs: 1, requiresArg: true, default: {} })
+ .option('outputs-file', { type: 'string', alias: 'O', desc: 'Path to file where stack outputs will be written as JSON', requiresArg: true })
  )
  .command('destroy [STACKS..]', 'Destroy the stack(s) named STACKS', yargs => yargs
  .option('exclusively', { type: 'boolean', alias: 'e', desc: 'Only destroy requested stacks, don\'t include dependees' })
@@ -238,7 +239,8 @@ async function initCommandLine() {
  sdk: aws,
  execute: args.execute,
  force: args.force,
- parameters: parameterMap
+ parameters: parameterMap,
+ outputsFile: args.outputsFile
  });
 
  case 'destroy':

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

@@ -100,6 +100,9 @@ export class CdkToolkit {
  }
  }
 
+ const stackOutputs: { [key: string]: any } = { };
+ const outputsFile = options.outputsFile;
+
  for (const stack of stacks) {
  if (stacks.length !== 1) { highlight(stack.displayName); }
  if (!stack.environment) {
@@ -170,6 +173,8 @@ export class CdkToolkit {
 
  if (Object.keys(result.outputs).length > 0) {
  print('\nOutputs:');
+
+ stackOutputs[stack.stackName] = result.outputs;
  }
 
  for (const name of Object.keys(result.outputs)) {
@@ -183,6 +188,17 @@ export class CdkToolkit {
  } catch (e) {
  error('\n ❌ %s failed: %s', colors.bold(stack.displayName), e);
  throw e;
+ } finally {
+ // If an outputs file has been specified, create the file path and write stack outputs to it once.
+ // Outputs are written after all stacks have been deployed. If a stack deployment fails,
+ // all of the outputs from successfully deployed stacks before the failure will still be written.
+ if (outputsFile) {
+ fs.ensureFileSync(outputsFile);
+ fs.writeJson(outputsFile, stackOutputs, {
+ spaces: 2,
+ encoding: 'utf8'
+ });
+ }
  }
  }
  }
@@ -337,6 +353,12 @@ export interface DeployOptions {
  * @default {}
  */
  parameters?: { [name: string]: string | undefined };
+
+ /**
+ * Path to file where stack outputs will be written after a successful deploy as JSON
+ * @default - Outputs are not written to any file
+ */
+ outputsFile?: string;
 }
 
 export interface DestroyOptions {

packages/aws-cdk/test/integ/cli/app/app.js

@@ -61,6 +61,34 @@ class OtherParameterStack extends cdk.Stack {
  }
 }
 
+class OutputsStack extends cdk.Stack {
+ constructor(parent, id, props) {
+ super(parent, id, props);
+
+ const topic = new sns.Topic(this, 'MyOutput', {
+ topicName: 'MyTopic'
+ });
+
+ new cdk.CfnOutput(this, 'TopicName', {
+ value: topic.topicName
+ })
+ }
+}
+
+class AnotherOutputsStack extends cdk.Stack {
+ constructor(parent, id, props) {
+ super(parent, id, props);
+
+ const topic = new sns.Topic(this, 'MyOtherOutput', {
+ topicName: 'MyOtherTopic'
+ });
+
+ new cdk.CfnOutput(this, 'TopicName', {
+ value: topic.topicName
+ });
+ }
+}
+
 class IamStack extends cdk.Stack {
  constructor(parent, id, props) {
  super(parent, id, props);
@@ -208,6 +236,9 @@ new YourStack(app, `${stackPrefix}-test-2`);
 // Deploy wildcard with parameters does ${stackPrefix}-param-test-*
 new ParameterStack(app, `${stackPrefix}-param-test-1`);
 new OtherParameterStack(app, `${stackPrefix}-param-test-2`);
+// Deploy stack with outputs does ${stackPrefix}-outputs-test-*
+new OutputsStack(app, `${stackPrefix}-outputs-test-1`);
+new AnotherOutputsStack(app, `${stackPrefix}-outputs-test-2`);
 // Not included in wildcard
 new IamStack(app, `${stackPrefix}-iam-test`);
 const providing = new ProvidingStack(app, `${stackPrefix}-order-providing`);

packages/aws-cdk/test/integ/cli/cdk-deploy-wildcard-with-outputs-expected.json

@@ -0,0 +1,8 @@
+{
+ "cdk-toolkit-integration-outputs-test-1": {
+ "TopicName": "MyTopic"
+ },
+ "cdk-toolkit-integration-outputs-test-2": {
+ "TopicName": "MyOtherTopic"
+ }
+}

packages/aws-cdk/test/integ/cli/cdk-deploy-with-outputs-expected.json

@@ -0,0 +1,5 @@
+{
+ "cdk-toolkit-integration-outputs-test-1": {
+ "TopicName": "MyTopic"
+ }
+}

packages/aws-cdk/test/integ/cli/common.bash

@@ -93,6 +93,8 @@ function cleanup() {
  cleanup_stack ${STACK_NAME_PREFIX}-test-2
  cleanup_stack ${STACK_NAME_PREFIX}-iam-test
  cleanup_stack ${STACK_NAME_PREFIX}-with-nested-stack
+ cleanup_stack ${STACK_NAME_PREFIX}-outputs-test-1
+ cleanup_stack ${STACK_NAME_PREFIX}-outputs-test-2
 }
 
 function setup() {

packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-outputs.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+set -euo pipefail
+scriptdir=$(cd $(dirname $0) && pwd)
+source ${scriptdir}/common.bash
+# ----------------------------------------------------------
+
+setup
+
+outputs_file=${integ_test_dir}/outputs/outputs.json
+expected_outputs=${scriptdir}/cdk-deploy-wildcard-with-outputs-expected.json
+
+# deploy all outputs stacks
+cdk deploy ${STACK_NAME_PREFIX}-outputs-test-\* --outputs-file ${outputs_file}
+echo "Stacks deployed successfully"
+
+# verify generated outputs file
+generated_outputs_file="$(cat ${outputs_file})"
+expected_outputs_file="$(cat ${expected_outputs})"
+if [[ "${generated_outputs_file}" != "${expected_outputs_file}" ]]; then
+ fail "unexpected outputs. Expected: ${expected_outputs_file} Actual: ${generated_outputs_file}"
+fi 
+
+# destroy
+rm ${outputs_file}
+cdk destroy -f ${STACK_NAME_PREFIX}-outputs-test-1
+cdk destroy -f ${STACK_NAME_PREFIX}-outputs-test-2
+
+echo "✅ success"

packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-outputs.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -euo pipefail
+scriptdir=$(cd $(dirname $0) && pwd)
+source ${scriptdir}/common.bash
+# ----------------------------------------------------------
+
+setup
+
+outputs_file=${integ_test_dir}/outputs/outputs.json
+expected_outputs=${scriptdir}/cdk-deploy-with-outputs-expected.json
+
+cdk deploy -v ${STACK_NAME_PREFIX}-outputs-test-1 --outputs-file ${outputs_file}
+echo "Stack deployed successfully"
+
+# verify generated outputs file
+generated_outputs_file="$(cat ${outputs_file})"
+expected_outputs_file="$(cat ${expected_outputs})"
+if [[ "${generated_outputs_file}" != "${expected_outputs_file}" ]]; then
+ fail "unexpected outputs. Expected: ${expected_outputs_file} Actual: ${generated_outputs_file}"
+fi 
+
+# destroy
+rm ${outputs_file}
+cdk destroy -f ${STACK_NAME_PREFIX}-outputs-test-1
+
+echo "✅ success"

packages/aws-cdk/test/integ/cli/test-cdk-ls.sh

@@ -15,6 +15,8 @@ ${STACK_NAME_PREFIX}-iam-test
 ${STACK_NAME_PREFIX}-lambda
 ${STACK_NAME_PREFIX}-missing-ssm-parameter
 ${STACK_NAME_PREFIX}-order-providing
+${STACK_NAME_PREFIX}-outputs-test-1
+${STACK_NAME_PREFIX}-outputs-test-2
 ${STACK_NAME_PREFIX}-param-test-1
 ${STACK_NAME_PREFIX}-param-test-2
 ${STACK_NAME_PREFIX}-test-1