refactor(core): revisit the Stack API (#2818)

Fixes #2728 

BREAKING CHANGE: multiple changes to the `Stack` API
* **core:** `stack.name` renamed to `stack.stackName`
* **core:** `stack.stackName` will return the concrete stack name. Use `Aws.stackName` to indicate { Ref: "AWS::StackName" }.
* **core:** `stack.account` and `stack.region` will return the concrete account/region only if they are explicitly specified when the stack is defined (under the `env` prop). Otherwise, they will return a token that resolves to the AWS::AccountId and AWS::Region intrinsic references. Use `Context.getDefaultAccount()` and `Context.getDefaultRegion()` to obtain the defaults passed through the toolkit in case those are needed. Use `Token.isUnresolved(v)` to check if you have a concrete or intrinsic.
* **core:** `stack.logicalId` has been removed. Use `stack.getLogicalId()`
* **core:** `stack.env` has been removed, use `stack.account`, `stack.region` and `stack.environment` instead
* **core:** `stack.accountId` renamed to `stack.account` (to allow treating account more abstractly)
* **core:** `AvailabilityZoneProvider` can now be accessed through `Context.getAvailabilityZones()`
* **core:** `SSMParameterProvider` can now be accessed through `Context.getSsmParameter()`
* **core:** `parseArn` is now `Arn.parse`
* **core:** `arnFromComponents` is now `arn.format`
* **core:** `node.lock` and `node.unlock` are now private
* **core:** `stack.requireRegion` and `requireAccountId` have been removed. Use `Token.unresolved(stack.region)` instead
* **core:** `stack.parentApp` have been removed. Use `App.isApp(stack.node.root)` instead.
* **core:** `stack.missingContext` is now private
* **core:** `stack.renameLogical` have been renamed to `stack.renameLogicalId`
* **core:** `IAddressingScheme`, `HashedAddressingScheme` and `LogicalIDs` are now internal. Override `Stack.allocateLogicalId` to customize how logical IDs are allocated to resources.

packages/@aws-cdk/app-delivery/lib/pipeline-deploy-stack-action.ts

@@ -105,7 +105,7 @@ export class PipelineDeployStackAction extends cdk.Construct {
  constructor(scope: cdk.Construct, id: string, props: PipelineDeployStackActionProps) {
  super(scope, id);
 
- if (!cdk.environmentEquals(props.stack.env, cdk.Stack.of(this).env)) {
+ if (props.stack.environment !== cdk.Stack.of(this).environment) {
  // FIXME: Add the necessary to extend to stacks in a different account
  throw new Error(`Cross-environment deployment is not supported`);
  }
@@ -125,8 +125,8 @@ export class PipelineDeployStackAction extends cdk.Construct {
  actionName: 'ChangeSet',
  changeSetName,
  runOrder: createChangeSetRunOrder,
- stackName: props.stack.name,
- templatePath: props.input.atPath(`${props.stack.name}.template.yaml`),
+ stackName: props.stack.stackName,
+ templatePath: props.input.atPath(`${props.stack.stackName}.template.yaml`),
  adminPermissions: props.adminPermissions,
  deploymentRole: props.role,
  capabilities,
@@ -136,7 +136,7 @@ export class PipelineDeployStackAction extends cdk.Construct {
  actionName: 'Execute',
  changeSetName,
  runOrder: executeChangeSetRunOrder,
- stackName: props.stack.name,
+ stackName: props.stack.stackName,
  }));
 
  this.deploymentRole = changeSetAction.deploymentRole;
@@ -160,7 +160,7 @@ export class PipelineDeployStackAction extends cdk.Construct {
  const assets = this.stack.node.metadata.filter(md => md.type === cxapi.ASSET_METADATA);
  if (assets.length > 0) {
  // FIXME: Implement the necessary actions to publish assets
- result.push(`Cannot deploy the stack ${this.stack.name} because it references ${assets.length} asset(s)`);
+ result.push(`Cannot deploy the stack ${this.stack.stackName} because it references ${assets.length} asset(s)`);
  }
  return result;
  }

packages/@aws-cdk/assert/lib/synth-utils.ts

@@ -9,7 +9,7 @@ export class SynthUtils {
  // always synthesize against the root (be it an App or whatever) so all artifacts will be included
  const root = stack.node.root;
  const assembly = ConstructNode.synth(root.node, options);
- return assembly.getStack(stack.name);
+ return assembly.getStack(stack.stackName);
  }
 
  /**

packages/@aws-cdk/assert/test/test.assertions.ts

@@ -210,7 +210,7 @@ function synthesizedStack(fn: (stack: cdk.Stack) => void): cx.CloudFormationStac
  fn(stack);
 
  const assembly = app.synth();
- return assembly.getStack(stack.name);
+ return assembly.getStack(stack.stackName);
 }
 
 interface TestResourceProps extends cdk.CfnResourceProps {

packages/@aws-cdk/assets/test/test.asset.ts

@@ -57,7 +57,7 @@ export = {
  path: dirPath
  });
 
- const synth = app.synth().getStack(stack.name);
+ const synth = app.synth().getStack(stack.stackName);
  const meta = synth.manifest.metadata || {};
  test.ok(meta['/my-stack/MyAsset']);
  test.ok(meta['/my-stack/MyAsset'][0]);
@@ -344,7 +344,7 @@ export = {
 
  // WHEN
  const session = app.synth();
- const artifact = session.getStack(stack.name);
+ const artifact = session.getStack(stack.stackName);
  const metadata = artifact.manifest.metadata || {};
  const md = Object.values(metadata)[0]![0]!.data;
  test.deepEqual(md.path, 'asset.6b84b87243a4a01c592d78e1fd3855c4bfef39328cd0a450cc97e81717fea2a2');

packages/@aws-cdk/aws-apigateway/lib/deployment.ts

@@ -99,7 +99,7 @@ class LatestDeploymentResource extends CfnDeployment {
  constructor(scope: Construct, id: string, props: CfnDeploymentProps) {
  super(scope, id, props);
 
- this.originalLogicalId = Stack.of(this).logicalIds.getLogicalId(this);
+ this.originalLogicalId = Stack.of(this).getLogicalId(this);
  }
 
  /**

packages/@aws-cdk/aws-cloudtrail/lib/index.ts

@@ -136,7 +136,7 @@ export class Trail extends Resource {
  .addServicePrincipal(cloudTrailPrincipal));
 
  s3bucket.addToResourcePolicy(new iam.PolicyStatement()
- .addResource(s3bucket.arnForObjects(`AWSLogs/${Stack.of(this).accountId}/*`))
+ .addResource(s3bucket.arnForObjects(`AWSLogs/${Stack.of(this).account}/*`))
  .addActions("s3:PutObject")
  .addServicePrincipal(cloudTrailPrincipal)
  .setCondition("StringEquals", {'s3:x-amz-acl': "bucket-owner-full-control"}));

packages/@aws-cdk/aws-codepipeline-actions/test/test.pipeline.ts

@@ -7,7 +7,7 @@ import iam = require('@aws-cdk/aws-iam');
 import lambda = require('@aws-cdk/aws-lambda');
 import s3 = require('@aws-cdk/aws-s3');
 import sns = require('@aws-cdk/aws-sns');
-import { App, CfnParameter, ConstructNode, PhysicalName, SecretValue, Stack } from '@aws-cdk/cdk';
+import { App, Aws, CfnParameter, ConstructNode, PhysicalName, SecretValue, Stack } from '@aws-cdk/cdk';
 import { Test } from 'nodeunit';
 import cpactions = require('../lib');
 
@@ -56,7 +56,7 @@ export = {
  const stack = new Stack(undefined, 'StackName');
 
  new codepipeline.Pipeline(stack, 'Pipeline', {
- pipelineName: stack.stackName,
+ pipelineName: Aws.stackName,
  });
 
  expect(stack, true).to(haveResourceLike('AWS::CodePipeline::Pipeline', {
@@ -695,8 +695,8 @@ export = {
 
  const usEast1ScaffoldStack = pipeline.crossRegionScaffolding['us-east-1'];
  test.notEqual(usEast1ScaffoldStack, undefined);
- test.equal(usEast1ScaffoldStack.env.region, 'us-east-1');
- test.equal(usEast1ScaffoldStack.env.account, pipelineAccount);
+ test.equal(usEast1ScaffoldStack.region, 'us-east-1');
+ test.equal(usEast1ScaffoldStack.account, pipelineAccount);
  test.ok(usEast1ScaffoldStack.node.id.indexOf('us-east-1') !== -1,
  `expected '${usEast1ScaffoldStack.node.id}' to contain 'us-east-1'`);
 

packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts

@@ -2,7 +2,7 @@ import events = require('@aws-cdk/aws-events');
 import iam = require('@aws-cdk/aws-iam');
 import kms = require('@aws-cdk/aws-kms');
 import s3 = require('@aws-cdk/aws-s3');
-import { Construct, Lazy, PhysicalName, RemovalPolicy, Resource, Stack } from '@aws-cdk/cdk';
+import { App, Construct, Lazy, PhysicalName, RemovalPolicy, Resource, Stack, Token } from '@aws-cdk/cdk';
 import { Action, IPipeline, IStage } from "./action";
 import { CfnPipeline } from './codepipeline.generated';
 import { Stage } from './stage';
@@ -364,14 +364,21 @@ export class Pipeline extends PipelineBase {
  });
  }
 
+ private requireRegion() {
+ const region = Stack.of(this).region;
+ if (Token.isUnresolved(region)) {
+ throw new Error(`You need to specify an explicit region when using CodePipeline's cross-region support`);
+ }
+ return region;
+ }
+
  private ensureReplicationBucketExistsFor(region?: string) {
  if (!region) {
  return;
  }
 
  // get the region the Pipeline itself is in
- const pipelineRegion = Stack.of(this).requireRegion(
- "You need to specify an explicit region when using CodePipeline's cross-region support");
+ const pipelineRegion = this.requireRegion();
 
  // if we already have an ArtifactStore generated for this region, or it's the Pipeline's region, nothing to do
  if (this.artifactStores[region] || region === pipelineRegion) {
@@ -380,11 +387,14 @@ export class Pipeline extends PipelineBase {
 
  let replicationBucketName = this.crossRegionReplicationBuckets[region];
  if (!replicationBucketName) {
- const pipelineAccount = Stack.of(this).requireAccountId(
- "You need to specify an explicit account when using CodePipeline's cross-region support");
- const app = Stack.of(this).parentApp();
- if (!app) {
- throw new Error(`Pipeline stack which uses cross region actions must be part of an application`);
+ const pipelineAccount = Stack.of(this).account;
+ if (Token.isUnresolved(pipelineAccount)) {
+ throw new Error("You need to specify an explicit account when using CodePipeline's cross-region support");
+ }
+
+ const app = this.node.root;
+ if (!app || !App.isApp(app)) {
+ throw new Error(`Pipeline stack which uses cross region actions must be part of a CDK app`);
  }
  const crossRegionScaffoldStack = new CrossRegionScaffoldStack(this, `cross-region-stack-${pipelineAccount}:${region}`, {
  region,
@@ -421,8 +431,7 @@ export class Pipeline extends PipelineBase {
  const pipelineStack = Stack.of(this);
  const resourceStack = Stack.of(action.resource);
  // check if resource is from a different account
- if (pipelineStack.env.account && resourceStack.env.account &&
- pipelineStack.env.account !== resourceStack.env.account) {
+ if (pipelineStack.environment !== resourceStack.environment) {
  // if it is, the pipeline's bucket must have a KMS key
  if (!this.artifactBucket.encryptionKey) {
  throw new Error('The Pipeline is being used in a cross-account manner, ' +
@@ -434,7 +443,7 @@ export class Pipeline extends PipelineBase {
  // generate a role in the other stack, that the Pipeline will assume for executing this action
  actionRole = new iam.Role(resourceStack,
  `${this.node.uniqueId}-${stage.stageName}-${action.actionName}-ActionRole`, {
- assumedBy: new iam.AccountPrincipal(pipelineStack.env.account),
+ assumedBy: new iam.AccountPrincipal(pipelineStack.account),
  roleName: PhysicalName.auto({ crossEnvironment: true }),
  });
 
@@ -555,7 +564,8 @@ export class Pipeline extends PipelineBase {
 
  // add the Pipeline's artifact store
  const primaryStore = this.renderPrimaryArtifactStore();
- this.artifactStores[Stack.of(this).requireRegion()] = {
+ const primaryRegion = this.requireRegion();
+ this.artifactStores[primaryRegion] = {
  location: primaryStore.location,
  type: primaryStore.type,
  encryptionKey: primaryStore.encryptionKey,

packages/@aws-cdk/aws-ec2/lib/machine-image.ts

@@ -1,4 +1,4 @@
-import { Construct, SSMParameterProvider, Stack } from '@aws-cdk/cdk';
+import { Construct, Context, Stack, Token } from '@aws-cdk/cdk';
 
 /**
  * Interface for classes that can select an appropriate machine image to use
@@ -25,11 +25,7 @@ export class WindowsImage implements IMachineImageSource {
  * Return the image to use in the given context
  */
  public getImage(scope: Construct): MachineImage {
- const ssmProvider = new SSMParameterProvider(scope, {
- parameterName: this.imageParameterName(this.version),
- });
-
- const ami = ssmProvider.parameterValue();
+ const ami = Context.getSsmParameter(scope, this.imageParameterName(this.version));
  return new MachineImage(ami, new WindowsOS());
  }
 
@@ -106,11 +102,7 @@ export class AmazonLinuxImage implements IMachineImageSource {
  ].filter(x => x !== undefined); // Get rid of undefineds
 
  const parameterName = '/aws/service/ami-amazon-linux-latest/' + parts.join('-');
-
- const ssmProvider = new SSMParameterProvider(scope, {
- parameterName,
- });
- const ami = ssmProvider.parameterValue();
+ const ami = Context.getSsmParameter(scope, parameterName);
  return new MachineImage(ami, new LinuxOS());
  }
 }
@@ -188,7 +180,11 @@ export class GenericLinuxImage implements IMachineImageSource {
  }
 
  public getImage(scope: Construct): MachineImage {
- const region = Stack.of(scope).requireRegion('AMI cannot be determined');
+ let region = Stack.of(scope).region;
+ if (Token.isUnresolved(region)) {
+ region = Context.getDefaultRegion(scope);
+ }
+
  const ami = region !== 'test-region' ? this.amiMap[region] : 'ami-12345';
  if (!ami) {
  throw new Error(`Unable to find AMI in AMI map: no AMI specified for region '${region}'`);

packages/@aws-cdk/aws-ec2/lib/vpc.ts

@@ -789,8 +789,7 @@ export class Vpc extends VpcBase {
 
  this.node.applyAspect(new cdk.Tag(NAME_TAG, this.node.path));
 
- this.availabilityZones = new cdk.AvailabilityZoneProvider(this).availabilityZones;
- this.availabilityZones.sort();
+ this.availabilityZones = cdk.Context.getAvailabilityZones(this);
 
  const maxAZs = props.maxAZs !== undefined ? props.maxAZs : 3;
  this.availabilityZones = this.availabilityZones.slice(0, maxAZs);
@@ -946,10 +945,6 @@ export class Vpc extends VpcBase {
  private createSubnets() {
  const remainingSpaceSubnets: SubnetConfiguration[] = [];
 
- // Calculate number of public/private subnets based on number of AZs
- const zones = new cdk.AvailabilityZoneProvider(this).availabilityZones;
- zones.sort();
-
  for (const subnet of this.subnetConfiguration) {
  if (subnet.cidrMask === undefined) {
  remainingSpaceSubnets.push(subnet);

packages/@aws-cdk/aws-ec2/test/test.vpc.ts

@@ -1,5 +1,5 @@
 import { countResources, expect, haveResource, haveResourceLike, isSuperObject } from '@aws-cdk/assert';
-import { AvailabilityZoneProvider, Construct, Stack, Tag } from '@aws-cdk/cdk';
+import { Construct, Context, Stack, Tag } from '@aws-cdk/cdk';
 import { Test } from 'nodeunit';
 import { CfnVPC, DefaultInstanceTenancy, IVpc, SubnetType, Vpc } from '../lib';
 import { exportVpc } from './export-helper';
@@ -63,7 +63,7 @@ export = {
  "contains the correct number of subnets"(test: Test) {
  const stack = getTestStack();
  const vpc = new Vpc(stack, 'TheVPC');
- const zones = new AvailabilityZoneProvider(stack).availabilityZones.length;
+ const zones = Context.getAvailabilityZones(stack).length;
  test.equal(vpc.publicSubnets.length, zones);
  test.equal(vpc.privateSubnets.length, zones);
  test.deepEqual(stack.resolve(vpc.vpcId), { Ref: 'TheVPC92636AB0' });
@@ -109,7 +109,7 @@ export = {
 
  "with no subnets defined, the VPC should have an IGW, and a NAT Gateway per AZ"(test: Test) {
  const stack = getTestStack();
- const zones = new AvailabilityZoneProvider(stack).availabilityZones.length;
+ const zones = Context.getAvailabilityZones(stack).length;
  new Vpc(stack, 'TheVPC', { });
  expect(stack).to(countResources("AWS::EC2::InternetGateway", 1));
  expect(stack).to(countResources("AWS::EC2::NatGateway", zones));
@@ -186,7 +186,7 @@ export = {
  },
  "with custom subnets, the VPC should have the right number of subnets, an IGW, and a NAT Gateway per AZ"(test: Test) {
  const stack = getTestStack();
- const zones = new AvailabilityZoneProvider(stack).availabilityZones.length;
+ const zones = Context.getAvailabilityZones(stack).length;
  new Vpc(stack, 'TheVPC', {
  cidr: '10.0.0.0/21',
  subnetConfiguration: [

packages/@aws-cdk/aws-ecs/lib/cluster.ts

@@ -3,7 +3,7 @@ import cloudwatch = require ('@aws-cdk/aws-cloudwatch');
 import ec2 = require('@aws-cdk/aws-ec2');
 import iam = require('@aws-cdk/aws-iam');
 import cloudmap = require('@aws-cdk/aws-servicediscovery');
-import { Construct, IResource, Resource, SSMParameterProvider, Stack } from '@aws-cdk/cdk';
+import { Construct, Context, IResource, Resource, Stack } from '@aws-cdk/cdk';
 import { InstanceDrainHook } from './drain-hook/instance-drain-hook';
 import { CfnCluster } from './ecs.generated';
 
@@ -268,13 +268,8 @@ export class EcsOptimizedAmi implements ec2.IMachineImageSource {
  * Return the correct image
  */
  public getImage(scope: Construct): ec2.MachineImage {
- const ssmProvider = new SSMParameterProvider(scope, {
- parameterName: this.amiParameterName
- });
-
- const json = ssmProvider.parameterValue("{\"image_id\": \"\"}");
+ const json = Context.getSsmParameter(scope, this.amiParameterName, { defaultValue: "{\"image_id\": \"\"}" });
  const ami = JSON.parse(json).image_id;
-
  return new ec2.MachineImage(ami, new ec2.LinuxOS());
  }
 }

packages/@aws-cdk/aws-elasticloadbalancingv2/lib/alb/application-load-balancer.ts

@@ -2,7 +2,7 @@ import cloudwatch = require('@aws-cdk/aws-cloudwatch');
 import ec2 = require('@aws-cdk/aws-ec2');
 import iam = require('@aws-cdk/aws-iam');
 import s3 = require('@aws-cdk/aws-s3');
-import { Construct, Lazy, Resource, Stack } from '@aws-cdk/cdk';
+import { Construct, Lazy, Resource, Stack, Token } from '@aws-cdk/cdk';
 import { BaseLoadBalancer, BaseLoadBalancerProps, ILoadBalancerV2 } from '../shared/base-load-balancer';
 import { IpAddressType } from '../shared/enums';
 import { ApplicationListener, BaseApplicationListenerProps } from './application-listener';
@@ -86,7 +86,11 @@ export class ApplicationLoadBalancer extends BaseLoadBalancer implements IApplic
  this.setAttribute('access_logs.s3.bucket', bucket.bucketName.toString());
  this.setAttribute('access_logs.s3.prefix', prefix);
 
- const region = Stack.of(this).requireRegion('Enable ELBv2 access logging');
+ const region = Stack.of(this).region;
+ if (Token.isUnresolved(region)) {
+ throw new Error(`Region is required to enable ELBv2 access logging`);
+ }
+
  const account = ELBV2_ACCOUNTS[region];
  if (!account) {
  throw new Error(`Cannot enable access logging; don't know ELBv2 account for region ${region}`);

packages/@aws-cdk/aws-glue/lib/database.ts

@@ -54,7 +54,7 @@ export class Database extends Resource implements IDatabase {
  public databaseArn = databaseArn;
  public databaseName = stack.parseArn(databaseArn).resourceName!;
  public catalogArn = stack.formatArn({ service: 'glue', resource: 'catalog' });
- public catalogId = stack.accountId;
+ public catalogId = stack.account;
  }
 
  return new Import(scope, id);
@@ -95,7 +95,7 @@ export class Database extends Resource implements IDatabase {
  this.locationUri = `s3://${bucket.bucketName}/${props.databaseName}`;
  }
 
- this.catalogId = Stack.of(this).accountId;
+ this.catalogId = Stack.of(this).account;
  const resource = new CfnDatabase(this, 'Resource', {
  catalogId: this.catalogId,
  databaseInput: {

packages/@aws-cdk/aws-iam/lib/principals.ts

@@ -232,7 +232,7 @@ export class FederatedPrincipal extends PrincipalBase {
 
 export class AccountRootPrincipal extends AccountPrincipal {
  constructor() {
- super(new StackDependentToken(stack => stack.accountId).toString());
+ super(new StackDependentToken(stack => stack.account).toString());
  }
 
  public toString() {

packages/@aws-cdk/aws-kms/test/integ.key.ts

@@ -11,7 +11,7 @@ const key = new Key(stack, 'MyKey', { retain: false });
 key.addToResourcePolicy(new PolicyStatement()
  .addAllResources()
  .addAction('kms:encrypt')
- .addAwsPrincipal(stack.accountId));
+ .addAwsPrincipal(stack.account));
 
 key.addAlias('alias/bar');