feat(toolkit): introduce the concept of auto-deployed Stacks.

A Stack that is not auto-deployed is meant to be deployed outside the context of the `cdk deploy` command -
for example, in a CodePipeline.
These Stacks do not appear when running `cdk synth` or `cdk deploy`,
unless you explicitly filter for them.
This is useful when modeling things like Lambda in CodePipeline,
where the main deployment needs to happen in the Pipeline,
but you might want to test things locally before pushing it to the Pipeline.

packages/@aws-cdk/cdk/lib/stack.ts

@@ -22,6 +22,17 @@ export interface StackProps {
    * Optional. If not supplied, the HashedNamingScheme will be used.
    */
   namingScheme?: IAddressingScheme;
+
+  /**
+   * Should the Stack be deployed when running `cdk deploy` without arguments
+   * (and listed when running `cdk synth` without arguments).
+   * Setting this to `false` is useful when you have a Stack in your CDK app
+   * that you don't want to deploy using the CDK toolkit -
+   * for example, because you're planning on deploying it through CodePipeline.
+   *
+   * @default true
+   */
+  autoDeploy?: boolean;
 }
 
 /**
@@ -79,6 +90,17 @@ export class Stack extends Construct {
    */
   public readonly name: string;
 
+  /**
+   * Should the Stack be deployed when running `cdk deploy` without arguments
+   * (and listed when running `cdk synth` without arguments).
+   * Setting this to `false` is useful when you have a Stack in your CDK app
+   * that you don't want to deploy using the CDK toolkit -
+   * for example, because you're planning on deploying it through CodePipeline.
+   *
+   * By default, this is `true`.
+   */
+  public readonly autoDeploy: boolean;
+
   /*
    * Used to determine if this construct is a stack.
    */
@@ -113,6 +135,7 @@ export class Stack extends Construct {
 
     this.logicalIds = new LogicalIDs(props && props.namingScheme ? props.namingScheme : new HashedAddressingScheme());
     this.name = this.node.id;
+    this.autoDeploy = props && props.autoDeploy === false ? false : true;
   }
 
   /**
@@ -455,7 +478,8 @@ export class Stack extends Construct {
       environment: this.environment,
       properties: {
         templateFile: template,
-      }
+      },
+      autoDeploy: this.autoDeploy ? undefined : false,
     };
 
     if (Object.keys(this.parameterValues).length > 0) {

packages/@aws-cdk/cdk/lib/synthesis.ts

@@ -354,6 +354,7 @@ function renderLegacyStacks(artifacts: { [id: string]: cxapi.Artifact }, store:
         environment: { name: artifact.environment.substr('aws://'.length), account: match[1], region: match[2] },
         template,
         metadata: artifact.metadata || {},
+        autoDeploy: artifact.autoDeploy,
       };
 
       if (artifact.dependencies && artifact.dependencies.length > 0) {
@@ -369,4 +370,4 @@ function renderLegacyStacks(artifacts: { [id: string]: cxapi.Artifact }, store:
   }
 
   return stacks;
-}
+}

packages/@aws-cdk/cdk/test/test.synthesis.ts

@@ -87,7 +87,8 @@ export = {
         'one-stack': {
           type: 'aws:cloudformation:stack',
           environment: 'aws://unknown-account/unknown-region',
-          properties: { templateFile: 'one-stack.template.json' }
+          properties: { templateFile: 'one-stack.template.json' },
+          autoDeploy: undefined,
         }
       },
     });

packages/@aws-cdk/cx-api/lib/artifacts.ts

@@ -13,10 +13,11 @@ export interface Artifact {
   dependencies?: string[];
   missing?: { [key: string]: any };
   properties?: { [name: string]: any };
+  autoDeploy?: boolean;
 }
 
 export function validateArtifact(artifcat: Artifact) {
   if (!AWS_ENV_REGEX.test(artifcat.environment)) {
     throw new Error(`Artifact "environment" must conform to ${AWS_ENV_REGEX}: ${artifcat.environment}`);
   }
-}
+}

packages/@aws-cdk/cx-api/lib/cxapi.ts

@@ -81,6 +81,7 @@ export interface SynthesizedStack {
   missing?: { [key: string]: MissingContext };
   metadata: StackMetadata;
   template: any;
+  autoDeploy?: boolean;
 
   /**
    * Other stacks this stack depends on

packages/aws-cdk/lib/api/cxapp/stacks.ts

@@ -87,8 +87,10 @@ export class AppStacks {
     }
 
     if (selectors.length === 0) {
-      debug('Stack name not specified, so defaulting to all available stacks: ' + listStackNames(stacks));
-      return this.applyRenames(stacks);
+      // remove non-auto deployed Stacks
+      const autoDeployedStacks = stacks.filter(s => s.autoDeploy !== false);
+      debug('Stack name not specified, so defaulting to all available stacks: ' + listStackNames(autoDeployedStacks));
+      return this.applyRenames(autoDeployedStacks);
     }
 
     const allStacks = new Map<string, cxapi.SynthesizedStack>();

packages/aws-cdk/test/api/test.stacks.ts

@@ -86,4 +86,86 @@ export = {
 
     test.done();
   },
-};
+
+  async 'does not return non-autoDeployed Stacks when called without any selectors'(test: Test) {
+    // GIVEN
+    const stacks = appStacksWith([
+      {
+        name: 'NotAutoDeployedStack',
+        template: { resource: 'Resource' },
+        environment: { name: 'dev', account: '12345', region: 'here' },
+        metadata: {},
+        autoDeploy: false,
+      },
+    ]);
+
+    // WHEN
+    const synthed = await stacks.selectStacks([], ExtendedStackSelection.None);
+
+    // THEN
+    test.equal(synthed.length, 0);
+
+    test.done();
+  },
+
+  async 'does return non-autoDeployed Stacks when called with selectors matching it'(test: Test) {
+    // GIVEN
+    const stacks = appStacksWith([
+      {
+        name: 'NotAutoDeployedStack',
+        template: { resource: 'Resource' },
+        environment: { name: 'dev', account: '12345', region: 'here' },
+        metadata: {},
+        autoDeploy: false,
+      },
+    ]);
+
+    // WHEN
+    const synthed = await stacks.selectStacks(['NotAutoDeployedStack'], ExtendedStackSelection.None);
+
+    // THEN
+    test.equal(synthed.length, 1);
+
+    test.done();
+  },
+
+  async "does return an non-autoDeployed Stack when it's a dependency of a selected Stack"(test: Test) {
+    // GIVEN
+    const stacks = appStacksWith([
+      {
+        name: 'NotAutoDeployedStack',
+        template: { resource: 'Resource' },
+        environment: { name: 'dev', account: '12345', region: 'here' },
+        metadata: {},
+        autoDeploy: false,
+      },
+      {
+        name: 'AutoDeployedStack',
+        template: { resource: 'Resource' },
+        environment: { name: 'dev', account: '12345', region: 'here' },
+        metadata: {},
+        dependsOn: ['NotAutoDeployedStack'],
+      },
+    ]);
+
+    // WHEN
+    const synthed = await stacks.selectStacks(['AutoDeployedStack'], ExtendedStackSelection.Upstream);
+
+    // THEN
+    test.equal(synthed.length, 2);
+
+    test.done();
+  },
+};
+
+function appStacksWith(stacks: cxapi.SynthesizedStack[]): AppStacks {
+  const response: cxapi.SynthesizeResponse = {
+    version: '1',
+    stacks,
+  };
+  return new AppStacks({
+    configuration: new Configuration(),
+    aws: new SDK(),
+    synthesizer: async () => response,
+  });
+}