feat(init-templates): app template comes with hint comments for 'env' (…

…aws#13696)

How the `env` parameter is supposed to be used is still confusing to
a lot of users.

Add uncommentable lines to the init templates showing and describing
the 3 alternatives.

Fixes aws#12321.


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/aws-cdk/lib/init-templates/v1/app/csharp/src/%name.PascalCased%/Program.template.cs

@@ -10,7 +10,35 @@ sealed class Program
         public static void Main(string[] args)
         {
             var app = new App();
-            new %name.PascalCased%Stack(app, "%name.PascalCased%Stack");
+            new %name.PascalCased%Stack(app, "%name.PascalCased%Stack", new StackProps
+            {
+                // If you don't specify 'env', this stack will be environment-agnostic.
+                // Account/Region-dependent features and context lookups will not work,
+                // but a single synthesized template can be deployed anywhere.
+
+                // Uncomment the next block to specialize this stack for the AWS Account
+                // and Region that are implied by the current CLI configuration.
+                /*
+                Env = new Amazon.CDK.Environment
+                {
+                    Account = System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"),
+                    Region = System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION"),
+                }
+                */
+
+                // Uncomment the next block if you know exactly what Account and Region you
+                // want to deploy the stack to.
+                /*
+                Env = new Amazon.CDK.Environment
+                {
+                    Account = "123456789012",
+                    Region = "us-east-1",
+                }
+                */
+
+                // For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html
+            });
+
             app.Synth();
         }
     }

packages/aws-cdk/lib/init-templates/v1/app/java/src/main/java/com/myorg/%name.PascalCased%App.template.java

@@ -1,14 +1,39 @@
 package com.myorg;
 
 import software.amazon.awscdk.core.App;
+import software.amazon.awscdk.core.Environment;
 
 import java.util.Arrays;
 
 public class %name.PascalCased%App {
     public static void main(final String[] args) {
         App app = new App();
 
-        new %name.PascalCased%Stack(app, "%name.PascalCased%Stack");
+        %name.PascalCased%Stack.Builder.create(app, "%name.PascalCased%Stack")
+                // If you don't specify 'env', this stack will be environment-agnostic.
+                // Account/Region-dependent features and context lookups will not work,
+                // but a single synthesized template can be deployed anywhere.
+
+                // Uncomment the next block to specialize this stack for the AWS Account
+                // and Region that are implied by the current CLI configuration.
+                /*
+                .env(Environment.builder()
+                        .account(System.getenv("CDK_DEFAULT_ACCOUNT"))
+                        .region(System.getenv("CDK_DEFAULT_REGION"))
+                        .build())
+                */
+
+                // Uncomment the next block if you know exactly what Account and Region you
+                // want to deploy the stack to.
+                /*
+                .env(Environment.builder()
+                        .account("123456789012")
+                        .region("us-east-1")
+                        .build())
+                */
+
+                // For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html
+                .build();
 
         app.synth();
     }

packages/aws-cdk/lib/init-templates/v1/app/javascript/bin/%name%.template.js

@@ -4,4 +4,18 @@ const cdk = require('@aws-cdk/core');
 const { %name.PascalCased%Stack } = require('../lib/%name%-stack');
 
 const app = new cdk.App();
-new %name.PascalCased%Stack(app, '%name.PascalCased%Stack');
+new %name.PascalCased%Stack(app, '%name.PascalCased%Stack', {
+  /* If you don't specify 'env', this stack will be environment-agnostic.
+   * Account/Region-dependent features and context lookups will not work,
+   * but a single synthesized template can be deployed anywhere. */
+
+  /* Uncomment the next line to specialize this stack for the AWS Account
+   * and Region that are implied by the current CLI configuration. */
+  // env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
+
+  /* Uncomment the next line if you know exactly what Account and Region you
+   * want to deploy the stack to. */
+  // env: { account: '123456789012', region: 'us-east-1' },
+
+  /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
+});

packages/aws-cdk/lib/init-templates/v1/app/python/app.template.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+import os
 
 from aws_cdk import core as cdk
 
@@ -12,6 +13,22 @@
 
 
 app = core.App()
-%name.PascalCased%Stack(app, "%name.PascalCased%Stack")
+%name.PascalCased%Stack(app, "%name.PascalCased%Stack",
+    # If you don't specify 'env', this stack will be environment-agnostic.
+    # Account/Region-dependent features and context lookups will not work,
+    # but a single synthesized template can be deployed anywhere.
+
+    # Uncomment the next line to specialize this stack for the AWS Account
+    # and Region that are implied by the current CLI configuration.
+
+    #env=core.Environment(account=os.getenv('CDK_DEFAULT_ACCOUNT'), region=os.getenv('CDK_DEFAULT_REGION')),
+
+    # Uncomment the next line if you know exactly what Account and Region you
+    # want to deploy the stack to. */
+
+    #env=core.Environment(account='123456789012', region='us-east-1'),
+
+    # For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html
+    )
 
 app.synth()

packages/aws-cdk/lib/init-templates/v1/app/typescript/bin/%name%.template.ts

@@ -4,4 +4,18 @@ import * as cdk from '@aws-cdk/core';
 import { %name.PascalCased%Stack } from '../lib/%name%-stack';
 
 const app = new cdk.App();
-new %name.PascalCased%Stack(app, '%name.PascalCased%Stack');
+new %name.PascalCased%Stack(app, '%name.PascalCased%Stack', {
+  /* If you don't specify 'env', this stack will be environment-agnostic.
+   * Account/Region-dependent features and context lookups will not work,
+   * but a single synthesized template can be deployed anywhere. */
+
+  /* Uncomment the next line to specialize this stack for the AWS Account
+   * and Region that are implied by the current CLI configuration. */
+  // env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
+
+  /* Uncomment the next line if you know exactly what Account and Region you
+   * want to deploy the stack to. */
+  // env: { account: '123456789012', region: 'us-east-1' },
+
+  /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
+});

packages/aws-cdk/lib/init-templates/v2/app/csharp/src/%name.PascalCased%/Program.template.cs

@@ -10,7 +10,34 @@ sealed class Program
         public static void Main(string[] args)
         {
             var app = new App();
-            new %name.PascalCased%Stack(app, "%name.PascalCased%Stack");
+            new %name.PascalCased%Stack(app, "%name.PascalCased%Stack", new StackProps
+            {
+                // If you don't specify 'env', this stack will be environment-agnostic.
+                // Account/Region-dependent features and context lookups will not work,
+                // but a single synthesized template can be deployed anywhere.
+
+                // Uncomment the next block to specialize this stack for the AWS Account
+                // and Region that are implied by the current CLI configuration.
+                /*
+                Env = new Amazon.CDK.Environment
+                {
+                    Account = System.Environment.GetEnvironmentVariable("CDK_DEFAULT_ACCOUNT"),
+                    Region = System.Environment.GetEnvironmentVariable("CDK_DEFAULT_REGION"),
+                }
+                */
+
+                // Uncomment the next block if you know exactly what Account and Region you
+                // want to deploy the stack to.
+                /*
+                Env = new Amazon.CDK.Environment
+                {
+                    Account = "123456789012",
+                    Region = "us-east-1",
+                }
+                */
+
+                // For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html
+            });
             app.Synth();
         }
     }

packages/aws-cdk/lib/init-templates/v2/app/java/src/main/java/com/myorg/%name.PascalCased%App.template.java

@@ -1,14 +1,39 @@
 package com.myorg;
 
 import software.amazon.awscdk.lib.App;
+import software.amazon.awscdk.lib.Environment;
 
 import java.util.Arrays;
 
 public class %name.PascalCased%App {
     public static void main(final String[] args) {
         App app = new App();
 
-        new %name.PascalCased%Stack(app, "%name.PascalCased%Stack");
+        %name.PascalCased%Stack.Builder.create(app, "%name.PascalCased%Stack")
+                // If you don't specify 'env', this stack will be environment-agnostic.
+                // Account/Region-dependent features and context lookups will not work,
+                // but a single synthesized template can be deployed anywhere.
+
+                // Uncomment the next block to specialize this stack for the AWS Account
+                // and Region that are implied by the current CLI configuration.
+                /*
+                .env(Environment.builder()
+                        .account(System.getenv("CDK_DEFAULT_ACCOUNT"))
+                        .region(System.getenv("CDK_DEFAULT_REGION"))
+                        .build())
+                */
+
+                // Uncomment the next block if you know exactly what Account and Region you
+                // want to deploy the stack to.
+                /*
+                .env(Environment.builder()
+                        .account("123456789012")
+                        .region("us-east-1")
+                        .build())
+                */
+
+                // For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html
+                .build();
 
         app.synth();
     }

packages/aws-cdk/lib/init-templates/v2/app/javascript/bin/%name%.template.js

@@ -4,4 +4,18 @@ const cdk = require('aws-cdk-lib');
 const { %name.PascalCased%Stack } = require('../lib/%name%-stack');
 
 const app = new cdk.App();
-new %name.PascalCased%Stack(app, '%name.PascalCased%Stack');
+new %name.PascalCased%Stack(app, '%name.PascalCased%Stack', {
+  /* If you don't specify 'env', this stack will be environment-agnostic.
+   * Account/Region-dependent features and context lookups will not work,
+   * but a single synthesized template can be deployed anywhere. */
+
+  /* Uncomment the next line to specialize this stack for the AWS Account
+   * and Region that are implied by the current CLI configuration. */
+  // env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
+
+  /* Uncomment the next line if you know exactly what Account and Region you
+   * want to deploy the stack to. */
+  // env: { account: '123456789012', region: 'us-east-1' },
+
+  /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
+});

packages/aws-cdk/lib/init-templates/v2/app/python/app.template.py

@@ -1,11 +1,28 @@
 #!/usr/bin/env python3
+import os
 
 import aws_cdk_lib as core
 
 from %name.PythonModule%.%name.PythonModule%_stack import %name.PascalCased%Stack
 
 
 app = core.App()
-%name.PascalCased%Stack(app, "%name.PascalCased%Stack")
+%name.PascalCased%Stack(app, "%name.PascalCased%Stack",
+    # If you don't specify 'env', this stack will be environment-agnostic.
+    # Account/Region-dependent features and context lookups will not work,
+    # but a single synthesized template can be deployed anywhere.
+
+    # Uncomment the next line to specialize this stack for the AWS Account
+    # and Region that are implied by the current CLI configuration.
+
+    #env=core.Environment(account=os.getenv('CDK_DEFAULT_ACCOUNT'), region=os.getenv('CDK_DEFAULT_REGION')),
+
+    # Uncomment the next line if you know exactly what Account and Region you
+    # want to deploy the stack to. */
+
+    #env=core.Environment(account='123456789012', region='us-east-1'),
+
+    # For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html
+    )
 
 app.synth()

packages/aws-cdk/lib/init-templates/v2/app/typescript/bin/%name%.template.ts

@@ -4,4 +4,18 @@ import * as cdk from 'aws-cdk-lib';
 import { %name.PascalCased%Stack } from '../lib/%name%-stack';
 
 const app = new cdk.App();
-new %name.PascalCased%Stack(app, '%name.PascalCased%Stack');
+new %name.PascalCased%Stack(app, '%name.PascalCased%Stack', {
+  /* If you don't specify 'env', this stack will be environment-agnostic.
+   * Account/Region-dependent features and context lookups will not work,
+   * but a single synthesized template can be deployed anywhere. */
+
+  /* Uncomment the next line to specialize this stack for the AWS Account
+   * and Region that are implied by the current CLI configuration. */
+  // env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
+
+  /* Uncomment the next line if you know exactly what Account and Region you
+   * want to deploy the stack to. */
+  // env: { account: '123456789012', region: 'us-east-1' },
+
+  /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
+});