Merge pull request #681 from aws/dev

chore: release 1.1

.github/workflows/doc-builder.yml

@@ -3,7 +3,6 @@ on:
   push:
     branches:
       - main
-      - dev
 
   # Allow the workflow to be triggered also manually.
   workflow_dispatch:

buildtools/ci.template.yml

@@ -15,10 +15,6 @@ Parameters:
     Description: Name of the CodeBuild project.
     Default: "aws-dotnet-deploy-ci"
     Type: String
-  CodeBuildArtifactsBucketName:
-    Description: Name of the buckets where the CodeBuild artifacts will be stored.
-    Default: "aws-dotnet-deploy-codebuild-artifacts"
-    Type: String
   TestRunnerRoleArn:
     Description: Role to assume when running tests.  This role must already exsit.  Role can be a different account.  Example arn:aws:iam:112233445566::role/awsdotnet-deploy-ci-test-runner
     Default: ""
@@ -67,12 +63,6 @@ Resources:
                   - logs:GetLogEvents
                 Resource:
                   - !Sub arn:aws:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/codebuild/${CodeBuildProjectName}:*
-              - Effect: Allow
-                Action:
-                  - s3:GetObject
-                  - s3:GetObjectVersion
-                Resource:
-                  - !Sub "${CodeBuildArtifactsBucket.Arn}/*"
 
   GithubOidc:
     Type: AWS::IAM::OIDCProvider
@@ -105,11 +95,7 @@ Resources:
         Location: !Sub https://github.com/${GitHubOrg}/${GitHubRepositoryName}
         BuildSpec: buildtools/ci.buildspec.yml
       Artifacts:
-        Type: S3
-        Packaging: ZIP
-        Location: !GetAtt CodeBuildArtifactsBucket.Arn
-        OverrideArtifactName: true
-
+        Type: NO_ARTIFACTS
 
   CodeBuildProjectRole:
     Type: AWS::IAM::Role
@@ -150,17 +136,6 @@ Resources:
                 Effect: Allow
                 Resource:
                   - !Sub arn:aws:codebuild:${AWS::Region}:${AWS::AccountId}:report-group/*
-              - Action:
-                - 's3:PutObject'
-                Effect: Allow
-                Resource:
-                  - !Sub "${CodeBuildArtifactsBucket.Arn}/*"
-
-  CodeBuildArtifactsBucket:
-    Type: 'AWS::S3::Bucket'
-    DeletionPolicy: Retain
-    Properties:
-      BucketName: !Ref CodeBuildArtifactsBucketName
 
 Outputs:
   OidcRole:

mkdocs.yml

@@ -18,12 +18,6 @@ nav:
       - Set up custom workspace: docs/getting-started/custom-workspace.md
       - Deploy "Hello World": docs/getting-started/run-tool.md
     -  Support matrix: docs/support.md
-  #  - Supported deployments:
-  #    - Support matrix: docs/aws-computes/matrix.md
-  #    - Amazon ECS: docs/aws-computes/ecs.md
-  #    - AWS Elastic Beanstalk: docs/aws-computes/beanstalk.md
-  #    - AWS App Runner: docs/aws-computes/app-runner.md
-  #    - Amazon S3 and Amazon CloudFront: docs/aws-computes/s3.md
     - Commands:
       - deploy: docs/commands/deploy.md
       - list-deployments: docs/commands/list.md
@@ -33,24 +27,13 @@ nav:
     - Docker support:
       - Dockerfile generation: docs/docker/docker-generation.md
       - Publishing a Docker image: docs/docker/publish-image.md
-    - Deployment recipes: docs/recipe.md
-    - Deployment projects: docs/project.md
-  #    - Generating CDK project: docs/projects/overview.md
-  #    - Customizing CDK project: docs/projects/custom-project.md
+    - Deployment Projects:
+       - Overview: docs/deployment-projects/index.md
+       - Recipe File: docs/deployment-projects/recipe-file.md
+       - CDK Project: docs/deployment-projects/cdk-project.md
     - Integrating with CI/CD: docs/cicd.md
-    #  - Overview: docs/cicd/overview.md
-    #  - Suppress prompts with --silent: docs/cicd/silent.md
-    #  - Deployment settings file: docs/cicd/settings.md
-
-    #- Tutorials:
-    #  - Deploying ASP.NET Core Application: docs/tutorials/deploy-webapp.md
-    #  - Deploying Blazor WebAssembly Application: docs/tutorials/deploy-blazorapp.md
-    #  - Deploying Console Service: docs/tutorials/deploy-console-service.md
-    #  - Deploying Console Task: docs/tutorials/deploy-console-task.md
-    #  - Pushing Image to ECS: docs/tutorials/push-image-ecr.md
-    #  - Automating Deployments: docs/tutorials/automate-deployments.md
-    #  - Listing Deployments: docs/tutorials/list-deployments.md
-    #  - Deleting Deployment: docs/tutorials/delete-deployment.md
+  - Tutorials:
+    - Customizing deployment projects: tutorials/custom-project.md
   - Troubleshooting Guide:
     - troubleshooting-guide/index.md
     - Missing Dependencies: troubleshooting-guide/missing-dependencies.md
@@ -74,4 +57,4 @@ theme:
 
 markdown_extensions:
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_index: !!python/name:materialx.emoji.twemoji

site/content/docs/cicd.md

@@ -14,10 +14,6 @@ To specify the services to deploy and their configurations for your environment,
 
 Storing deployment settings in a JSON file also allows those settings to be version controlled.
 
-This section defines the JSON definitions and syntax that you construct and use a deployment settings file.
-
-TODO
-
 ### Invoking from CI/CD
 
 The `--apply` switch on deploy command allows you to specify a deployment settings file.

site/content/docs/commands/project.md

@@ -7,9 +7,14 @@
     dotnet aws deployment-project generate [-d|--diagnostics] [-s|--silent] [--profile <PROFILE>] [--region <REGION>] [--project-path <PROJECT-PATH>] [--project-display-name <DISPLAY-NAME>]
 
 ### Description
-Generates and saves the deployment CDK project in a user provided directory path without proceeding with a deployment. Allows user to customize the CDK project before deploying the application.
+Generates and saves the [deployment CDK project](../deployment-projects/index.md) in a user provided directory path without proceeding with a deployment. Allows user to customize the CDK project before deploying the application.
+
+* The `--output` switch sets the directory where the deployment project will be saved.
+* The `--project-display-name` switch sets the name that will be shown when the .NET project is being deployed.
 
 ### Examples
-```
-dotnet aws deployment-project generate --region us-west-2
-```
+
+This example creates a deployment project from the .NET project in the current directory. The  deployment project will be saved to a sibling directory called CustomDeploymentProject. The name _"Team custom deployment project"_ will be displayed in the list of the available deployment options.
+
+    dotnet aws deployment-project generate --output ../CustomDeploymentProject --project-display-name "Team custom deployment project"
+

site/content/docs/deployment-projects/cdk-project.md

@@ -0,0 +1,109 @@
+# CDK Project
+
+Each deployment project has a C# Cloud Development Kit (CDK) project. This CDK project is used to create the AWS infrastructure as a CloudFormation stack based on the user settings and to deploy your project to that infrastructure.
+
+Read our [tutorial](../../tutorials/custom-project.md) to see how you can customize this CDK project to add additional infrastructure resources for your deployments.
+
+### What is AWS CDK?
+
+The [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/) is an open-source software development framework to define your cloud application resources using familiar programming languages.
+
+The following links are useful resources to learn more about AWS CDK and how to write .NET CDK projects.
+
+* [AWS CDK Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/home.html)
+* [.NET CDK Workshop](https://cdkworkshop.com/40-dotnet.html)
+* [.NET CDK Reference](https://docs.aws.amazon.com/cdk/api/v2/dotnet/api/index.html)
+
+### Layout of a CDK deployment project
+
+The layout of the generated CDK project puts all the code that was used to create the AWS resources defined in the starting recipe in a directory called **Generated**.
+
+![Catagories in AWS Toolkit for Visual Studio](../../assets/images/deployment-project-file-layout.png)
+
+It is recommended to not modify the code in the `Generated` directory to make it easier to merge future changes from the starting recipe into your custom deployment project. If you do not intend to update your custom deployment project from the original built-in recipe you may modify the code or rearrange the directory layout.
+
+If you choose to not modify the `Generated` code it is recommended to customize the CDK project starting from the `AppStack` class. Here is the constructor of `AppStack`.
+
+```
+internal AppStack(Construct scope, IDeployToolStackProps<Configuration> props)
+    : base(scope, props.StackName, props)
+{
+    _configuration = props.RecipeProps.Settings;
+
+    // Setup callback for generated construct to provide access to customize CDK properties before creating constructs.
+    CDKRecipeCustomizer<Recipe>.CustomizeCDKProps += CustomizeCDKProps;
+
+    // Create custom CDK constructs here that might need to be referenced in the CustomizeCDKProps. For example if
+    // creating a DynamoDB table construct and then later using the CDK construct reference in CustomizeCDKProps to
+    // pass the table name as an environment variable to the container image.
+
+    // Create the recipe defined CDK construct with all of its sub constructs.
+    var generatedRecipe = new Recipe(this, props.RecipeProps);
+
+    // Create additional CDK constructs here. The recipe's constructs can be accessed as properties on
+    // the generatedRecipe variable.
+}
+```
+
+The `var generatedRecipe = new Recipe(this, props.RecipeProps);` line of code creates all of the AWS resources from the `Generated` directory. Your customizations could create new AWS resources via CDK constructs before or after this line. Typically you would create new resources before this line if you want those resources to be connected to the resources defined in the `Recipe` type. If you need to create new resources that are connected to the resources defined in the `Recipe` then create them after this line. The instance of `Recipe` has public properties for all of the resources that were created in the `Recipe`.
+
+In this constructor a callback method called `CustomizeCDKProps` is setup. This callback method is called right before any constructs are created from the `Recipe`. This allows modifying the construct's property object before it is passed into the construct.
+
+The example below shows the `CustomizeCDKProps` callback that checks to see if the resource being created is the Beanstalk Environment. If it is, cast the property object to the appropriate property object and then make whatever customizations are needed.
+
+```
+private void CustomizeCDKProps(CustomizePropsEventArgs<Recipe> evnt)
+{
+    if (string.Equals(evnt.ResourceLogicalName, nameof(evnt.Construct.BeanstalkEnvironment)))
+    {
+        if (evnt.Props is CfnEnvironmentProps props)
+        {
+            Console.WriteLine("Customizing Beanstalk Environment");
+        }
+    }
+}
+```
+
+### Main method in Program.cs
+
+The `Main` method in `Program.cs` for the CDK deployment project must be coded in a certain style to ensure compatibility with the deploy tool. The AWS Deploy Tool relies on .NET's Configuration system to pass along settings from the deploy tool to the CDK project. In the example below the `ConfigurationBuilder().AddAWSDeployToolConfiguration(app)` method reads the settings that were passed into the project from the deploy tool.
+
+With the configuration read from the deploy tool, the CDK environment is set to the account and region the deploy tool was configured with.
+
+The other major difference from normal CDK projects is the call to `CDKRecipeSetup.RegisterStack`. This is required to stamp the CloudFormation stack with the recipe id that created the stack. Future redeployments can only update existing stacks that were created by the original recipe. It also serializes the settings collected from the deploy tool into the metadata for the CloudFormation stack so redeployments can use the previous settings used for deployment.
+
+```
+public static void Main(string[] args)
+{
+    var app = new App();
+
+    var builder = new ConfigurationBuilder().AddAWSDeployToolConfiguration(app);
+    var recipeProps = builder.Build().Get<RecipeProps<Configuration>>();
+    var appStackProps = new DeployToolStackProps<Configuration>(recipeProps)
+    {
+        Env = new Environment
+        {
+            Account = recipeProps.AWSAccountId,
+            Region = recipeProps.AWSRegion
+        }
+    };
+
+    // The RegisterStack method is used to set identifying information on the stack
+    // for the recipe used to deploy the application and preserve the settings used in the recipe
+    // to allow redeployment. The information is stored as CloudFormation tags and metadata inside
+    // the generated CloudFormation template.
+    CDKRecipeSetup.RegisterStack<Configuration>(new AppStack(app, appStackProps), appStackProps.RecipeProps);
+
+    app.Synth();
+}
+```
+
+### Configuration options
+
+The option settings that are defined in the [recipe file](recipe-file.md) are passed into the CDK project and then deserialized into the `Configuration` object.
+
+When you add new settings to the recipe file, you also need to add the `Id` of the new settings to the `Configuration` object. If you added an `Object` setting with a collection of child settings, first create a new type representing that entire `Object`. For reach child setting id, add a property on the new type. Finally, add a new property on `Configuration` for your new type with the property name being the id of the `Object` setting.
+
+The `Configuration` object follows the same `Generated` directory pattern described above. Custom settings should be added to the partial `Configuration.cs` file outside of the `Generated` directory.
+
+

site/content/docs/deployment-projects/index.md

@@ -0,0 +1,48 @@
+# Deployment Projects
+
+### What is a deployment recipe?
+
+The tool provides intelligent deployment recommendations that are tailored to your specific .NET application. The recommendation rules are defined in the `deployment recipes`. These recipes let you configure a pre-defined set of AWS resources related to your application such as IAM roles, virtual private clouds, load balancers, and other.
+
+There is a built-in recipe for [each supported project type](../support.md). All recipe definitions are available [on GitHub](https://github.com/aws/aws-dotnet-deploy/tree/main/src/AWS.Deploy.Recipes/RecipeDefinitions).
+
+### What is a deployment project?
+
+What if your application uses additional AWS resources that are not included in the built-in recipe, such as DynamoDB tables or SQS queues? In this case, you can extend one of the existing recipes and create a custom `deployment project` to manage additional AWS resources and services.
+
+Once you create and customize your deployment project, it will be displayed alongside the built-in recipes as a custom deployment option.
+
+** Before:** _The recommended deployment target is a built-in recipe for ASP.NET Core applications._
+
+![Before](../../assets/images/cliBefore.png)
+
+** After:** _The recommended deployment target is a custom deployment project that manages a DynamoDB table in addition to the ASP.NET Core project._
+
+![After](../../assets/images/cliAfterBorder.png)
+
+### Parts of a deployment project
+
+A deployment project consists of two parts. For details, refer to the full reference guides below.
+
+* [Recipe file](./recipe-file.md) - a  JSON configuration file that drives the deployment experience.
+* [.NET CDK project](./cdk-project.md) - a C# project that uses the [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/) to define the infrastructure that will be created.
+
+### Creating a deployment project
+
+To create a custom deployment project, run this command in the directory of the .NET project you wish to deploy. See [`deployment-project` command](../commands/project.md) for more details.
+
+    dotnet aws deployment-project generate --output <output-directory> --project-display-name <display-name>
+
+The list of built-in recipes that are compatible with your .NET project will be displayed. Select the recipe that you will use to customize, and a deployment project will be created in the `--output` directory.
+
+   > Note: It is important to add your deployment projects to source control. If your deployment project has been deleted, you will not be able to re-deploy your application to the same CloudFormation stack.
+
+Now you can begin customizing the deployment project. See our [step-by-step tutorial](../../tutorials/custom-project.md) for a step-by-step instructions.
+
+### Searching for deployment projects
+
+When you run the `dotnet aws deploy` command, the tool searches for deployment projects anywhere underneath the solution (.sln) directory of project you are deploying. It also ensures that each deployment project iscompatible with the .NET project being deployed.
+
+To point to a deployment project that is outside the solution directory, use the `--deployment-project` switch to pass in the path of the deployment project to use. This is common when sharing deployment projects across multiple solutions.
+
+