diff --git a/mkdocs.yml b/mkdocs.yml index 64fca358f..6a6a4a796 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,12 +27,13 @@ nav: - Docker support: - Dockerfile generation: docs/docker/docker-generation.md - Publishing a Docker image: docs/docker/publish-image.md - - Custom Deployment Projects: - - Getting Started: docs/deployment-projects/index.md - - Tutorial: docs/deployment-projects/tutorial.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 + - Tutorials: + - Customizing deployment projects: tutorials/custom-project.md - Troubleshooting Guide: - troubleshooting-guide/index.md - Missing Dependencies: troubleshooting-guide/missing-dependencies.md @@ -56,4 +57,4 @@ theme: markdown_extensions: - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji \ No newline at end of file + emoji_index: !!python/name:materialx.emoji.twemoji diff --git a/site/content/assets/images/cliAfter.png b/site/content/assets/images/cliAfter.png new file mode 100644 index 000000000..365118f38 Binary files /dev/null and b/site/content/assets/images/cliAfter.png differ diff --git a/site/content/assets/images/cliAfterBorder.png b/site/content/assets/images/cliAfterBorder.png new file mode 100644 index 000000000..b2b688377 Binary files /dev/null and b/site/content/assets/images/cliAfterBorder.png differ diff --git a/site/content/assets/images/cliBefore.png b/site/content/assets/images/cliBefore.png new file mode 100644 index 000000000..995b0e320 Binary files /dev/null and b/site/content/assets/images/cliBefore.png differ diff --git a/site/content/assets/images/solutionWithCDKProject.png b/site/content/assets/images/solutionWithCDKProject.png new file mode 100644 index 000000000..6e8626f2d Binary files /dev/null and b/site/content/assets/images/solutionWithCDKProject.png differ diff --git a/site/content/docs/commands/project.md b/site/content/docs/commands/project.md index 0595eb7eb..40165ea6a 100644 --- a/site/content/docs/commands/project.md +++ b/site/content/docs/commands/project.md @@ -9,9 +9,12 @@ ### Description 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 -Creates a deployment project based on the .NET project in the current directory. The new deployment project will be saved to a sibling directory called CustomDeploymentProject. The project display name _"Team custom deployment project"_ will be displayed to users when selecting a publish target when deploying with the custom deployment project. +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" + dotnet aws deployment-project generate --output ../CustomDeploymentProject --project-display-name "Team custom deployment project" diff --git a/site/content/docs/deployment-projects/cdk-project.md b/site/content/docs/deployment-projects/cdk-project.md index 67f96b645..dc9c18ba7 100644 --- a/site/content/docs/deployment-projects/cdk-project.md +++ b/site/content/docs/deployment-projects/cdk-project.md @@ -1,59 +1,22 @@ # CDK Project -A custom deployment project uses a C# Cloud Development Kit (CDK) project to create the AWS infrastructure as a CloudFormation stack based on the settings provided by the user and to deploy your project to that infrastructure. +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. -### CDK Refresher -The following links are useful resources to learn how to write .NET CDK projects. +### What is AWS CDK? -* [.NET CDK Workshop](https://cdkworkshop.com/40-dotnet.html) -* [.NET CDK Reference](https://docs.aws.amazon.com/cdk/api/v2/dotnet/api/index.html) -* [AWS CDK Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/home.html) - -The main concepts to understand about the CDK are the following. - -* Stack - this is the top level container for all of the AWS resources represented as constructs. In deployment projects this type is usually the `AppStack` type in the project. -* Constructs - AWS resources are modeled as constructs. Some constructs are a one-to-one mapping to a single AWS resource. The CDK also has higher level abstractions where a single construct represents a collection of AWS resources that solve a common problem. -* Construct properties - For every construct there is a properties object that is created first, all necessary values are set and then passed into the constructor of a construct. - - -### 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 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. +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. -``` -public static void Main(string[] args) -{ - var app = new App(); +The following links are useful resources to learn more about AWS CDK and how to write .NET CDK projects. - var builder = new ConfigurationBuilder().AddAWSDeployToolConfiguration(app); - var recipeProps = builder.Build().Get>(); - var appStackProps = new DeployToolStackProps(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(new AppStack(app, appStackProps), appStackProps.RecipeProps); - - app.Synth(); -} -``` +* [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**. +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) @@ -80,7 +43,7 @@ internal AppStack(Construct scope, IDeployToolStackProps props) // 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`. @@ -101,8 +64,46 @@ private void CustomizeCDKProps(CustomizePropsEventArgs evnt) } ``` -### Configuration +### 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>(); + var appStackProps = new DeployToolStackProps(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(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. -The settings collected in the deploy tool are passed into the CDK project and then deserialized into the `Configuration` object. If you add new settings to the recipe file you will 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 then you need to create a new type with the child setting ids as properties on the new type. Then add a new property on the `Configuration` type for the 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. \ No newline at end of file diff --git a/site/content/docs/deployment-projects/index.md b/site/content/docs/deployment-projects/index.md index 00cc347e4..838284c90 100644 --- a/site/content/docs/deployment-projects/index.md +++ b/site/content/docs/deployment-projects/index.md @@ -1,45 +1,48 @@ -# Custom Deployment Projects +# Deployment Projects -AWS Deploy Tool comes with multiple recipes that can deploy your .NET application to [several different AWS compute services](../support.md). These built-in recipes let you configure AWS resources related to your application such as IAM roles, virtual private clouds, and load balancers. +### What is a deployment recipe? -But what if your application uses additional AWS resources that are not included in the built-in recipes, such as DynamoDB tables or SQS queues? +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. -You can create a **custom deployment project** to expand one of the built-in recipes to manage additional AWS resources and services. +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). -Once you create a custom deployment project, the AWS Deploy Tool CLI and the AWS Toolkit for Visual Studio will display it alongside the built-in recipes and offer users the same deployment experience. +### What is a deployment project? -![Custom Deployment Project in AWS Toolkit for Visual Studio](../../assets/images/custom-deployment-project.png) -_The recommended publish target is a custom deployment project that manages a DynamoDB table in addition to the ASP.NET Core 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. -### Parts of a custom deployment project +Once you create and customize your deployment project, it will be displayed alongside the built-in recipes as a custom deployment option. -A custom deployment project is comprised of two parts. You can follow the getting start guide on this page or the [tutorial](./tutorial.md) to create these, then refer to the full reference guides below. +** Before:** _The recommended deployment target is a built-in recipe for ASP.NET Core applications._ -* [Recipe file](./recipe-file.md) - a JSON file that drives the user experience in both the deploy tool CLI and AWS Toolkit for Visual Studio. -* [.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 for the deployment project. +![Before](../../assets/images/cliBefore.png) -### Getting started +** After:** _The recommended deployment target is a custom deployment project that manages a DynamoDB table in addition to the ASP.NET Core project._ -To create a custom deployment project, execute the following command in the directory of the .NET project you wish to deploy. +![After](../../assets/images/cliAfterBorder.png) - dotnet aws deployment-project generate --output --project-display-name +### Parts of a deployment project -The `--output` switch sets the directory where the deployment project will be saved. Use the `--project-display-name` switch to customize the name of the custom recipe that will be shown to users when the .NET project is being deployed. +A deployment project consists of two parts. For details, refer to the full reference guides below. -When you run the above command, the tool will display a list of built-in recipes that are compatible with your .NET project. Choose the built-in recipe that is closest to what you wish to deploy. This will be used as the starting point that you can then customize. +* [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. -Select the starting recipe and then a deployment project will be created in the location of the `--output` directory. Now you can begin customizing the deployment project. +### 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. -### Add to source control + dotnet aws deployment-project generate --output --project-display-name -It is important to add the custom deployment project to source control. Redeployments require the custom deployment project to be available to the deployment tooling. If a CloudFormation stack was created from a custom deployment project and that -deployment project has been deleted then you will not be able to redeploy to that CloudFormation stack. +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. -### Searching for custom deployment projects +Now you can begin customizing the deployment project. See our [step-by-step tutorial](../../tutorials/custom-project.md) for a step-by-step instructions. -When the deploy command is initiated AWS Deploy Tool starts from the solution (.sln) of the .NET project being deployed and searches for custom deployment projects anywhere underneath the solution directory. The custom deployment projects are sent through the deployment tooling's recommendation engine to make sure they are compatible with the .NET project being deployed. +### 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. -If the custom deployment project is outside of the solution directory use the `--deployment-project` switch for the `dotnet aws deploy` command to pass in the path of the custom deployment project to use. This is common when sharing custom deployment projects across multiple solutions. diff --git a/site/content/docs/deployment-projects/recipe-file.md b/site/content/docs/deployment-projects/recipe-file.md index e18ac50ad..0cdefc0e0 100644 --- a/site/content/docs/deployment-projects/recipe-file.md +++ b/site/content/docs/deployment-projects/recipe-file.md @@ -1,11 +1,8 @@ -# Deployment project recipe +# Recipe file schema -In the custom deployment project is a JSON file with a `.recipe` extension. This file provides all of the metadata that drives the experience through the AWS Deploy Tool CLI and the AWS Toolkit for Visual Studio. - -The recipe file defines the type of .NET projects the recipe is compatible with and the settings that will be shown to users. - -The full schema for the recipe file can be found [here](https://github.com/aws/aws-dotnet-deploy/blob/main/src/AWS.Deploy.Recipes/RecipeDefinitions/aws-deploy-recipe-schema.json). +Each deployment project has a JSON file with a `.recipe` extension. This recipe file defines the type of .NET projects the recipe is compatible with and the settings that will be shown to users. +Read our [tutorial](../../tutorials/custom-project.md) to see how you can modify this file to drive the custom deployment experience and display custom option settings to the users. The full schema for the recipe file can be found [here](https://github.com/aws/aws-dotnet-deploy/blob/main/src/AWS.Deploy.Recipes/RecipeDefinitions/aws-deploy-recipe-schema.json). ### Top level settings @@ -95,7 +92,7 @@ Here is an example of a rule that checks the project is a web project and target "Condition": { "Value": "Microsoft.NET.Sdk.Web" } - }, + }, { "Type": "MSProperty", "Condition": { @@ -146,24 +143,24 @@ Here is another example that tests if a project contains a docker file. If it do ] ``` -A recipe is considered compatible if no rule ran an effect that set `Include` to false and if the priority is greater then 0. +A recipe is considered compatible if no rule ran an effect that set `Include` to false and if the priority is greater then 0. To simulate an **"or"** set of rules the starting priority in `RecipePriority` can be set to a negative value meaning it is not included by default. Then you can have a series of tests that adjust the priority to a positive amount. That way if any test rule passes it can adjust the priority to a positive number. ### Setting Categories -The `Categories` property is an array of objects that define the categories for the settings. The AWS Toolkit for Visual Studio uses this array to build the list of categories in the UI for fast navigation to a group of settings. +The `Categories` property is an array of objects that define the categories for the settings. The AWS Toolkit for Visual Studio uses this array to build the list of categories in the UI for fast navigation to a group of settings. ![Catagories in AWS Toolkit for Visual Studio](../../assets/images/vs-catagories.png) -A category is defined with the following properties: +A category is defined with the following properties: * **Id** - the unique id within the recipe for the category. * **DisplayName** - the name of the category displayed to users. * **Order** - the order in the toolkit for the category. Categories are display in sorted descending order. -Here is an example of defining a custom category that you could use to categorize additional settings added as application resources. +Here is an example of defining a custom category that you could use to categorize additional settings added as application resources. ``` { @@ -177,7 +174,7 @@ To assign a setting to a category, set the setting's `Category` property of to t ### Option Settings -The settings that are shown to users and allows users to customize the deployment in either the CLI or Visual Studio are defined in the `OptionSettings` array. Settings have the following properties. +The settings that are shown to users and allows users to customize the deployment in either the CLI or Visual Studio are defined in the `OptionSettings` array. Settings have the following properties. * **Id** - the id of the setting. Once projects are deployed with the recipe, this id should not change because the id is saved into the CloudFormation stack's template. * **Name** - the name of the setting shown to users. @@ -296,7 +293,7 @@ Here is an example for a setting used for storing an existing IAM role to use. T "Value": false } ], - + ... } ``` diff --git a/site/content/faq.md b/site/content/faq.md index 9d20270b2..042c389d5 100644 --- a/site/content/faq.md +++ b/site/content/faq.md @@ -20,3 +20,9 @@ The AWS Deploy Tool will show you all compute service options available to depl #### *FAQ: I have an application that has dependency on Windows technology, Can I use the AWS Deploy Tool to deploy it to AWS?* ASP.NET Core applications can be deployed to AWS Elastic Beanstalk picking the "ASP.NET Core App to AWS Elastic Beanstalk on Windows" recommendation. The deployment experience is very similar the "ASP.NET Core App to AWS Elastic Beanstalk on Linux" recommendation with additional settings for configuring the Internet Information Services (IIS) resource path and web site. + +#### *FAQ: Can I deploy my application from Visual Studio?* +Yes, you can deploy your application using the "Publish to AWS" feature in the AWS Toolkit for Visual Studio. This feature exposes the same functionality as the AWS Deploy Tool for .NET CLI. To learn more, go to [Publish to AWS](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/publish-experience.html) in the AWS Toolkit for Visual Studio User Guide. + +#### *FAQ: Can I invoke AWS Deploy Tool from my CI/CD pipeline?* +Yes, you can. To learn more, go to [Integrating with CI/CD](docs/cicd.md) diff --git a/site/content/index.md b/site/content/index.md index 45791c707..135ae235a 100644 --- a/site/content/index.md +++ b/site/content/index.md @@ -1,26 +1,26 @@ -# About the AWS Deploy Tool +# About the AWS Deploy Tool for .NET -** AWS Deploy Tool** is an interactive tooling for the .NET CLI and the AWS Toolkit for Visual Studio that helps deploy .NET applications with minimum AWS knowledge, and with the fewest clicks or commands. It works by analyzing .NET projects and guiding developers to the right AWS service. It then selects the right deployment service, builds and packages your application, and creates the deployment infrastructure. It allows for a quick and easy Proof of concept (POC), smooth graduation to CI/CD, and a gradual ramp up on AWS knowledge. +** AWS Deploy Tool for .NET** is an interactive tooling for the .NET CLI and the AWS Toolkit for Visual Studio that helps deploy .NET applications with minimum AWS knowledge, and with the fewest clicks or commands. -## Key capabilities +### Key capabilities AWS Deploy Tool has the following capabilities: * **Compute recommendations for your application** – Get recommendations about the type of compute best suited for your application based on the application type. * **Dockerfile generation** - The tool will generate a Dockerfile if needed, otherwise an existing Dockerfile will be used. * **Auto packaging and deployment** – The tool builds the deployment artifacts, generates a deployment CDK project, provisions the infrastructure and deploys your application to the chosen AWS compute. -* **Repeatable and shareable deployments** –The tool persists configuration settings and AWS Cloud Development Kit (CDK) project used to deploy your application. You can also version control them and share with other team members for repeatable deployments. -* **Help with learning AWS CDK for .NET!** - Once you are ready to start exploring, the deployment tool will help you gradually learn AWS tools like CDK that are used under the hood. It generates well documented/organized CDK projects that you can easily start modifying to fit your specific use-case. +* **Repeatable and shareable deployments** – You can generate and modify AWS Cloud Development Kit (CDK) deployment projects to fit your specific use case. You can also version control your projects and share them with your team for repeatable deployments. +* **Help with learning AWS CDK for .NET!** - Gradually learn the underlying AWS tools that AWS Deploy Tool for .NET is built on, such as the AWS CDK. -## Availability -### ... in .NET CLI +### Availability +####... in .NET CLI -AWS Deploy tool is available for download as a NuGet package. See [How to install](docs/getting-started/installation.md) section. +AWS Deploy Tool for .NET is available for download as a NuGet package. See [How to install](docs/getting-started/installation.md) section. -### ... in AWS Toolkit for Visual Studio +#### ... in AWS Toolkit for Visual Studio The AWS Toolkit for Visual Studio exposes the same deployment functionality via **Publish to AWS** feature. For information about toolkit versions and using the feature, see [Publish to AWS](https://docs.aws.amazon.com/AWSToolkitVS/latest/UserGuide/publish-experience.html) in the [AWS Toolkit for Visual Studio User Guide](https://docs.aws.amazon.com/AWSToolkitVS/latest/UserGuide/). -## Additional Resources +### Additional Resources * The [aws-dotnet-deploy](https://github.com/aws/aws-dotnet-deploy) GitHub repo. * Blog Post: [Reimagining the AWS .NET deployment experience](http://aws.amazon.com/blogs/developer/reimagining-the-aws-net-deployment-experience/). diff --git a/site/content/docs/deployment-projects/tutorial.md b/site/content/tutorials/custom-project.md similarity index 56% rename from site/content/docs/deployment-projects/tutorial.md rename to site/content/tutorials/custom-project.md index 60645cf6e..b9a889c7c 100644 --- a/site/content/docs/deployment-projects/tutorial.md +++ b/site/content/tutorials/custom-project.md @@ -1,36 +1,72 @@ -# Custom deployment project tutorial +# Adding DynamoDB table to your deployment project -For this tutorial we going to create a custom deployment project to deploy our Acme.WebApp project. This web application uses an AWS DynamoDB table as the backend store. We want to create a custom deployment project that the team can use to deploy the application to Amazon Elastic Container Service (ECS) along with the application's DynamoDB table. +In this tutorial, we will create and customize a deployment project to deploy a web application that uses AWS DynamoDB table as the backend store to Amazon Elastic Container Service (ECS). We will then add the deployment project to the source control and share with the team for future deployments. -***Note: For this tutorial we are not concerned with the logic of the application being deployed. To follow along with this tutorial you can replace Acme.WebApp with any "hello world" web application.*** +Tasks we will accomplish: +1. Create a new web application called Acme.WebApp +2. Generate a deployment project using a built-in recipe. +3. Customize the deployment project's recipe file to allow the user to configure DynamoDB table. +4. Modify the CDK project to add the new DynamoDB setting options. +5. Modify the CDK project to create the DynamoDB table. +6. Pass the DynamoDB table name to the application code using the environment variable so that our application can read to know which table to use. +7. Add the deployment project to source control. +8. Deploy our Acme.WebApp application using custom deployment project. -Tasks we will accomplish: + > **Note:** This tutorial is not concerned with the application logic. You can replace the sample Acme.WebApp used in this tutorial with any other web application.*** -* Create a custom deployment project -* Modify the custom deployment project's recipe file to allow the user to configure what DynamoDB table to use. -* Customize the deployment project's CDK project to create the DynamoDB table and set an environment variable that our application can read to know which table to use. +### Step 1: Create a new web application -### Creating the custom deployment project +In your command prompt, run the following command to create your app: -To create the custom deployment project, navigate to the Acme.WebApp project directory and run the following command. + dotnet new webapp -o Acme.WebApp -f net6.0 - dotnet aws deployment-project generate --output ../Acme.WebApp.DeploymentProject --project-display-name "ASP.NET Core app with DynamoDB" +### Step 2: Generate a deployment project -The AWS Deploy Tool will analyze the Acme.WebApp project and display which built-in recipes can be used as the starting point of the custom deployment project. Since we want to deploy to ECS, pick the option that says "ASP.NET Core App to Amazon ECS using AWS Fargate". +Navigate to the Acme.WebApp project directory and run the following command to generate a deployment project: -Once the starting recipe is picked, `Acme.WebApp.DeploymentProject` is created in a sibling project to the application project. If you are using Visual Studio you might want to add the new `Acme.WebApp.DeploymentProject` project to your solution. + dotnet aws deployment-project generate --output ../Acme.WebApp.DeploymentProject --project-display-name "ASP.NET Core app with DynamoDB" The `--project-display-name` switch above configures the name of the recommendation that is shown in the deploy tool when deploying the application project. +The AWS Deploy Tool will analyze the Acme.WebApp project and display which built-in recipes can be used as the starting point of the custom deployment project. -### Adding DynamoDB settings to the recipe +``` +Recommended Deployment Option +----------------------------- +1: ASP.NET Core App to AWS Elastic Beanstalk on Linux +This ASP.NET Core application will be built and deployed to AWS Elastic Beanstalk on Linux. Recommended if you do not want to deploy your application as a container image. -We want to give our team members who will use the custom deployment project the choice to either select an existing DynamoDB table or create a new table during deployment. To do that we need to add a few new settings to our deployment project's recipe definition. +Additional Deployment Options +------------------------------ +2: ASP.NET Core App to Amazon ECS using Fargate +This ASP.NET Core application will be deployed to Amazon Elastic Container Service (Amazon ECS) with compute power managed by AWS Fargate compute engine. If your project does not contain a Dockerfile, it will be automatically generated. Recommended if you want to deploy your application as a container image on Linux. -In the directory containing the deployment project open the `Acme.WebApp.DeploymentProject.recipe` file in your JSON editor of choice. Find the `OptionSettings` section that contains the settings users can use to configure their project. +3: ASP.NET Core App to AWS App Runner +This ASP.NET Core application will be built as a container image and deployed to AWS App Runner. If your project does not contain a Dockerfile, it will be automatically generated. Recommended if you want to deploy your application as a container image on a fully managed environment. -To get started we are going to create a new "Object" setting called `Backend` to group all of our new settings. The snippet below shows the object-level setting. The options we are about to create will be displayed to the users in the "General" category when configuring their deployment. +4: ASP.NET Core App to Existing AWS Elastic Beanstalk Environment +This ASP.NET Core application will be built and deployed to existing AWS Elastic Beanstalk environment. Recommended if you do not want to deploy your application as a container image. + +Choose deployment option (recommended default: 1) +``` + +Pick the option #2 that says "ASP.NET Core App to Amazon ECS using AWS Fargate". + +`Acme.WebApp.DeploymentProject` is created in a sibling directory to the application project. If you are using Visual Studio, add the new `Acme.WebApp.DeploymentProject` project to your solution. + +![Deployment Project](../assets/images/solutionWithCDKProject.png) + + +### Step 3: Add DynamoDB settings to the recipe file + +To give the team members, who will use our deployment project, the choice to either select an existing DynamoDB table or create a new table during deployment, we will add several new settings to our deployment project's recipe definition. + +Open the `Acme.WebApp.DeploymentProject.recipe` file located in the deployment project directory in your JSON editor of choice. + +Go to the `OptionSettings` section that contains the settings users can use to configure their project. + +Create a new "Object" option setting called `Backend` to group all of our new settings using the snippet below. When users configure their deployment, this option will be displayed in the "General" category. ``` "OptionSettings": [ @@ -55,7 +91,9 @@ To get started we are going to create a new "Object" setting called `Backend` to } ``` -Now we are going to create our child settings. The first is a setting to determine if we should create a new table or not. This setting is a `Bool` type which is defaulted to `true`. As a best practice the `Updatable` setting is set to `false` to protect users from accidentally deleting the table when redeploying in the future. +Now we will create child option settings to configure DynamoDB settings. The first is a setting to determine if we should create a new table or not. This setting is a `Bool` type which is defaulted to `true`. As a best practice the `Updatable` setting is set to `false` to protect users from accidentally deleting the table when redeploying in the future. + +Add the following snippet to the `ChildOptionSettings` of the new `Backend` option we just greated: ``` "ChildOptionSettings": [ @@ -75,8 +113,10 @@ Now we are going to create our child settings. The first is a setting to determi ``` -If the user unchecks the `CreateNewTable` setting we need to give them the choice to select an existing table. This `ExistingTableName` setting is a "String" type that will store the name of an existing DynamoDB table to use as the backend store. +If the user unchecks the `CreateNewTable` setting, we need to give them the choice to select an existing table. This `ExistingTableName` setting is a "String" type that will store the name of an existing DynamoDB table to use as the backend store. + +Add the following snippet to the `ChildOptionSettings` of the new `Backend` option: ``` "ChildOptionSettings": [ @@ -124,7 +164,7 @@ Let us take a deeper dive into the properties for the `ExistingTableName` settin * **DependsOn** - This setting will only be visible if the previous `CreateNewTable` setting is set to `false`. Notice how the `Id` is the full name of the setting including the parent "Object" setting `Backend`. * **Validators** - This attaches validators to make sure that the user-provided name matches the regex for valid table names and that the name meets the required minimum and maximum lengths. Adding validators provides feedback to users when invalid values are provided in either the CLI or Visual Studio. -Here is the full snippet of the `Backend` Object setting with the child settings. +Here is the full snippet of the `Backend` Object option setting with the child settings: ``` { "Id": "Backend", @@ -180,17 +220,14 @@ Here is the full snippet of the `Backend` Object setting with the child settings } ``` -### Customizing the deployment project's CDK project - -Now that users can customize the backend settings when deploying, the CDK project for the custom deployment project needs to be updated to react to the new settings. +### Step 4. Add new setting options to the CDK project -***Note: The .NET CDK projects generated by the deploy tool have the C# feature `Nullable` enabled in the project file. If you do not want this feature enabled edit the csproj file and remove the `Nullable` project from the PropertyGroup.*** +When CDK project is executed, all settings collected from the user are passed and deserialized into the `Configuration` type. Now we need to customize the CDK project to store the new setting options by modifying the `Configuration` type. -#### Deserializing settings +Create a new class called `BackendConfiguration` in the `Configurations` directory. Below is the code for this new type with the properties for `CreateNewTable` and `ExistingTableName`. -When AWS Deploy Tool executes the CDK project it passes all of the settings collected from the user and deserializes them into the `Configuration` type in the CDK project. We need to modify the `Configuration` type to store the new backend settings. + > **Note:** The .NET CDK projects generated by the AWS Deploy Tool have the C# feature `Nullable` enabled in the project file by default. If you do not want this feature enabled, edit the .csproj file and remove the `Nullable` project from the PropertyGroup.*** -Create a new class called `BackendConfiguration` in the `Configurations` directory. Below is the code for this new type with the properties for `CreateNewTable` and `ExistingTableName`. ``` namespace Acme.WebApp.DeploymentProject.Configurations @@ -224,7 +261,7 @@ namespace Acme.WebApp.DeploymentProject.Configurations } ``` -In the `Configuration.cs` file add a new property for our new backend settings. +In the `Configuration.cs` file, add a new property for our new backend settings. ``` namespace Acme.WebApp.DeploymentProject.Configurations @@ -236,11 +273,13 @@ namespace Acme.WebApp.DeploymentProject.Configurations } ``` -Notice that the `Backend` property was added to the partial class that is **not** in the `Generated` directory. In both the `Configuration` and `BackendConfiguration` types the property names match the setting ids used in the recipe file. This is important for the data to be property deserialized. +Notice that the `Backend` property was added to the partial class that is **not** in the `Generated` directory. In both the `Configuration` and `BackendConfiguration` types, the property names match the setting ids used in the recipe file. This is important for the data to be property deserialized. + +### Step 5. Add DynamoDB table to the CDK project -#### CDK Changes + > **Note:** The `AppStack` class is the recommended place to customize the AWS resources. -The `AppStack` class is the recommended place to customize the AWS resources created by the CDK. We will modify the constructor of this class to check if `CreateNewTable` is set to true. If it is we will use the CDK construct to create a table as part of the CloudFormation stack. +Modify the constructor of the `AppStack` class to check if `CreateNewTable` is set to true. Then use the `Amazon.CDK.AWS.DynamoDB` CDK construct to create a table as part of the CloudFormation stack. ``` using Amazon.CDK.AWS.DynamoDB; @@ -276,13 +315,13 @@ namespace Acme.WebApp.DeploymentProject } ``` -In the snippet above the table is created before `Recipe` construct. The `Recipe` construct has all of the AWS resources that are part of the original, built-in ECS recipe that the custom deployment project was created from. +Notice that in the snippet above the table is created before the] `Recipe` construct. The `Recipe` construct has all AWS resources that are part of the original built-in ECS recipe that the deployment project was created from. -Now that we have our table we need to pass the table name into our application code. We are going to do this by setting an environment variable that the application code will read. +### Step 6: Pass the DynamoDB table name to the application code -The `CustomizeCDKProps` method in `AppStack` is a callback method that gets called for each AWS resource about to be created from the `Recipe` construct. Here is where we can set the environment variable. +Now that we have our DynamoDB table, we need to pass the table name into our application code. We will do it by setting an environment variable that the application code will read in the `CustomizeCDKProps` of the `AppStack` class. `CustomizeCDKProps` is a callback method that gets called for each AWS resource about to be created from the `Recipe` construct. -To know which AWS resource is about to be created, compare the `evnt.ResourceLogicalName` property to the public property name on the `Recipe` construct. The built-in recipes are written to make sure the resource logical name is the same as the public property name. In our scenario we are looking to see if the `AppContainerDefinition` is about to be created. +To know which AWS resource is about to be created, compare the `evnt.ResourceLogicalName` property to the public property name on the `Recipe` construct. The built-in recipes are written to make sure the resource logical name is the same as the public property name. In our scenario we are looking to see if the `AppContainerDefinition` is about to be created. When we determine that the callback is for `AppContainerDefinition` then we cast the `evnt.Props` to the corresponding property object for `AppContainerDefinition`, in this case `ContainerDefinitionOptions`. From `ContainerDefinitionOptions` we can set the table name in an environment variable. @@ -290,7 +329,7 @@ When we determine that the callback is for `AppContainerDefinition` then we cast private void CustomizeCDKProps(CustomizePropsEventArgs evnt) { // Example of how to customize the container image definition to include environment variables to the running applications. - // + // if (string.Equals(evnt.ResourceLogicalName, nameof(evnt.Construct.AppContainerDefinition))) { if (evnt.Props is ContainerDefinitionOptions props) @@ -312,9 +351,17 @@ private void CustomizeCDKProps(CustomizePropsEventArgs evnt) } ``` -### Using the deployment project +### Step 6: Add deployment project to the source control + +Check your customized deployment project in to your source control. This is required to re-deploy your application to existing CloudFormation stacks that were created using custom deployment projects. + +### Step 7: Deploy Acme.WebApp application -Custom deployment projects are used through the same deployment workflow as the built-in recipes. For the CLI deploy tool, execute the `dotnet aws deploy` command in the application project directory. The custom deployment project will be displayed as the recommended option. +In your command prompt, run the following command to deploy your application: + + dotnet aws deploy --project-path . + +The custom deployment project will be displayed as the recommended option. ``` Recommended Deployment Option @@ -331,7 +378,7 @@ This ASP.NET Core application will be deployed to Amazon Elastic Container Servi ``` -The settings for the recommendation shows the Backend settings we customized. If we navigate to the backend settings the deploy tool will allow the user to choose between using a new table or picking an existing table. +Select deployment option #1. You can now see Backend settings option we customized. When you navigate to the `Backend` settings, you will be able to choose between using a new table or picking an existing table. ``` ... @@ -352,6 +399,4 @@ Current settings (select number to change its value) ``` -The AWS Toolkit for Visual Studio will also recognize the custom deployment project. The deployment project will show up as the highest recommended option and the user will also be able to choose between creating a new table or choosing from a drop-down list of available tables in the account that is being deployed to. - -The custom deployment project should be checked in to your source control. The deployment project is required for redeployments to existing CloudFormation stacks that were created from the custom deployment project. \ No newline at end of file + > **Note:** The AWS Toolkit for Visual Studio will also recognize the custom deployment project. The deployment project will show up as the highest recommended option and the user will also be able to choose between creating a new table or choosing from a drop-down list of available tables in the account that is being deployed to.