diff --git a/site/content/contributing.md b/site/content/contributing.md index 86d800c72..b93e1f9d0 100644 --- a/site/content/contributing.md +++ b/site/content/contributing.md @@ -207,10 +207,11 @@ Material for MkDocs is a theme for MkDocs, a static site generator geared toward ``` pip install mkdocs-material ``` + For, other installation options [see here](https://squidfunk.github.io/mkdocs-material/getting-started/) ### Deploying to a Local Server -MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. +MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. From the root of the project repository, run the following command: ``` diff --git a/site/content/docs/cicd.md b/site/content/docs/cicd.md index 8f4513d5d..94e45b84f 100644 --- a/site/content/docs/cicd.md +++ b/site/content/docs/cicd.md @@ -6,7 +6,9 @@ You can use AWS Deploy Tool when developing your app using any Continuous Deploy To turn off the interactive features, use the `-s (--silent)` switch. This will ensure the tool never prompts for any questions that could block an automated process. - dotnet aws deploy --silent +``` +dotnet aws deploy --silent +``` ### Creating a deployment settings file @@ -38,12 +40,14 @@ Here's an example of a web application with the following directory structure: ┗ MyWebApplication.sln To perform a deployment and also persist the deployment configuration to a JSON file, use the following command: + ``` dotnet aws deploy --project-path MyWebApplication/MyWebApplication/MyWebApplication.csproj --save-settings deploymentsettings.json ``` This will create a JSON file at `MyWebApplication/MyWebApplication/deploymentsettings.json` with the following structure: -``` + +```json { "AWSProfile": "AWSRegion": , @@ -51,8 +55,8 @@ This will create a JSON file at `MyWebApplication/MyWebApplication/deploymentset "RecipeId": "Settings": } - ``` + * _**AWSProfile**_: The name of the AWS profile that was used during deployment. * _**AWSRegion**_: The name of the AWS region where the deployed application is hosted. @@ -89,7 +93,6 @@ dotnet aws deploy --project-path --apply To deploy the application with the above directory structure in CI/CD pipeline without any prompts, use the following command: - dotnet aws deploy --silent --project-path MyWebApplication/MyWebApplication/MyWebApplication.csproj --apply deploymentsettings.json - - - +``` +dotnet aws deploy --silent --project-path MyWebApplication/MyWebApplication/MyWebApplication.csproj --apply deploymentsettings.json +``` diff --git a/site/content/docs/commands/delete.md b/site/content/docs/commands/delete.md index a8b559e23..c5c75e658 100644 --- a/site/content/docs/commands/delete.md +++ b/site/content/docs/commands/delete.md @@ -1,14 +1,19 @@ # delete-deployment command ### Usage - dotnet aws delete-deployment - Tears down the application stack. + +`dotnet aws delete-deployment` - Tears down the application stack. ### Synopsis - dotnet aws delete-deployment [-d|--diagnostics] [-s|--silent] [--profile ] [--region ] [-?|-h|--help] +``` +dotnet aws delete-deployment [-d|--diagnostics] [-s|--silent] [--profile ] [--region ] [-?|-h|--help] +``` ### Description Tears down the application stack. ### Examples - dotnet aws delete-deployment MY_APPLICATION --region us-west-2 +``` +dotnet aws delete-deployment MY_APPLICATION --region us-west-2 +``` diff --git a/site/content/docs/commands/deploy.md b/site/content/docs/commands/deploy.md index 7aaa6ed9d..a8642d7f3 100644 --- a/site/content/docs/commands/deploy.md +++ b/site/content/docs/commands/deploy.md @@ -1,10 +1,15 @@ # deploy command ### Usage - dotnet aws deploy - Inspect, build, and deploy the .NET project to AWS using the chosen AWS compute. + + +`dotnet aws deploy` - Inspect, build, and deploy the .NET project to AWS using the chosen AWS compute. ### Synopsis - dotnet aws deploy [-d|—-diagnostics] [-s|--silent] [--profile ] [--region ] [--project-path ] [[--save-settings|--save-all-settings] ] [--application-name ] [--apply ] [--deployment-project ] [-?|-h|--help] + +``` +dotnet aws deploy [-d|—-diagnostics] [-s|--silent] [--profile ] [--region ] [--project-path ] [[--save-settings|--save-all-settings] ] [--application-name ] [--apply ] [--deployment-project ] [-?|-h|--help] +``` ### Description Inspects the project and recommends AWS compute that is most suited to the type of deployed application. Then builds the project, generates a deployment CDK project to provision the required infrastructure, and deploys the .NET project to AWS using the chosen AWS compute. @@ -13,10 +18,14 @@ Inspects the project and recommends AWS compute that is most suited to the type Deploying HelloWorld - dotnet new web -n HelloWorld -f net6.0 - cd HelloWorld - dotnet aws deploy +``` +dotnet new web -n HelloWorld -f net6.0 +cd HelloWorld +dotnet aws deploy +``` Deploying application to a non-default profile - dotnet aws deploy --profile myCustomProfile --region us-east1 +``` +dotnet aws deploy --profile myCustomProfile --region us-east1 +``` diff --git a/site/content/docs/commands/list.md b/site/content/docs/commands/list.md index ab874dfbc..12e1b06f4 100644 --- a/site/content/docs/commands/list.md +++ b/site/content/docs/commands/list.md @@ -1,15 +1,20 @@ # list-deployments command ### Usage - dotnet aws list-deployments - Lists available cloud applications that were deployed using AWS Deploy Tool + +`dotnet aws list-deployments` - Lists available cloud applications that were deployed using AWS Deploy Tool ### Synopsis - dotnet new list-deployments [-d|--diagnostics] [-s|--silent] [--profile ] [--region ] [-?|-h|--help] + +``` +dotnet new list-deployments [-d|--diagnostics] [-s|--silent] [--profile ] [--region ] [-?|-h|--help] +``` ### Description Lists available cloud applications that were deployed using AWS Deploy Tool. ### Examples - dotnet aws list-deployments --region us-west-2 - +``` +dotnet aws list-deployments --region us-west-2 +``` diff --git a/site/content/docs/commands/project.md b/site/content/docs/commands/project.md index 40165ea6a..ce31c66ee 100644 --- a/site/content/docs/commands/project.md +++ b/site/content/docs/commands/project.md @@ -1,10 +1,14 @@ # deployment-project generate command ### Usage - dotnet aws deployment-project - Generates and saves the deployment CDK project in the user provided location. + +`dotnet aws deployment-project` - Generates and saves the deployment CDK project in the user provided location. ### Synopsis - dotnet aws deployment-project generate [-d|--diagnostics] [-s|--silent] [--profile ] [--region ] [--project-path ] [--project-display-name ] + +``` +dotnet aws deployment-project generate [-d|--diagnostics] [-s|--silent] [--profile ] [--region ] [--project-path ] [--project-display-name ] +``` ### 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. @@ -16,5 +20,6 @@ Generates and saves the [deployment CDK project](../deployment-projects/index.md 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/commands/server-mode.md b/site/content/docs/commands/server-mode.md index 4e763af8b..f68f356e3 100644 --- a/site/content/docs/commands/server-mode.md +++ b/site/content/docs/commands/server-mode.md @@ -1,13 +1,17 @@ # server-mode command ### Usage - dotnet aws server-mode - Launches the tool in a server mode for integrations with IDE, for example Visual Studio. + +`dotnet aws server-mode` - Launches the tool in a server mode for integrations with IDE, for example Visual Studio. ### Synopsis - dotnet aws server-mode [-d|--diagnostics] [-s|--silent] [-?|-h|--help] [--port ] [--parent-pid ] [--unsecure-mode] + +``` +dotnet aws server-mode [-d|--diagnostics] [-s|--silent] [-?|-h|--help] [--port ] [--parent-pid ] [--unsecure-mode] +``` ### Description -Starts the tool in the server mode to provide integration with IDEs, for example Visual Studio. This tool is not intended for the end user usage unless you are writing a custom integration into an IDE. +Starts the tool in the server mode to provide integration with IDEs, for example Visual Studio. This tool is not intended for end user usage unless you are writing a custom integration into an IDE. ### Examples ``` diff --git a/site/content/docs/deployment-projects/cdk-project.md b/site/content/docs/deployment-projects/cdk-project.md index dc9c18ba7..7e7994b4f 100644 --- a/site/content/docs/deployment-projects/cdk-project.md +++ b/site/content/docs/deployment-projects/cdk-project.md @@ -18,13 +18,13 @@ The following links are useful resources to learn more about AWS CDK and how to 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) +![Categories 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`. -``` +```csharp internal AppStack(Construct scope, IDeployToolStackProps props) : base(scope, props.StackName, props) { @@ -45,13 +45,15 @@ internal AppStack(Construct scope, IDeployToolStackProps props) } ``` -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`. +The `var generatedRecipe = new Recipe(this, props.RecipeProps);` statement creates all of the AWS resources specified in the CDK code in the `Generated` directory. Your customizations can create additional custom AWS resources from CDK constructs either before or after this statement. + +If you have custom resources you want to connect to resources generated by the recipe, create your custom resource before the statement. For example, you might want to set an environment variable in a container definition to the name of a custom DynamoDB table. In that scenario, your custom table should be created before the statement. However, if you want to connect a custom resource to a resource created by the recipe, create the custom resource after the statement. An example might be connecting a custom Amazon CloudFront distribution to an Application Load Balancer created in a recipe. Custom resources that have no connection to the resources created by the recipe can be added before, or after, the statement. 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. -``` +```csharp private void CustomizeCDKProps(CustomizePropsEventArgs evnt) { if (string.Equals(evnt.ResourceLogicalName, nameof(evnt.Construct.BeanstalkEnvironment))) @@ -72,7 +74,7 @@ With the configuration read from the deploy tool, the CDK environment is set to 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. -``` +```csharp public static void Main(string[] args) { var app = new App(); @@ -105,5 +107,3 @@ The option settings that are defined in the [recipe file](recipe-file.md) are pa 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. - - diff --git a/site/content/docs/deployment-projects/index.md b/site/content/docs/deployment-projects/index.md index 838284c90..644d30856 100644 --- a/site/content/docs/deployment-projects/index.md +++ b/site/content/docs/deployment-projects/index.md @@ -2,13 +2,13 @@ ### 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. +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 more. 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. +What if your application uses additional AWS resources that are not included in the built-in recipe, such as Amazon DynamoDB tables or Amazon 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. @@ -24,25 +24,25 @@ Once you create and customize your deployment project, it will be displayed alon 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. +* [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 --project-display-name +``` +dotnet aws deployment-project generate --output --project-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. +The list of built-in recipes that are compatible with your .NET project will be displayed. Select the recipe that you want 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. +Now you can begin customizing the deployment project. See our [step-by-step tutorial](../../tutorials/custom-project.md) for 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. +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 is compatible 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. - - diff --git a/site/content/docs/deployment-projects/recipe-file.md b/site/content/docs/deployment-projects/recipe-file.md index 0cdefc0e0..e68ac4cd6 100644 --- a/site/content/docs/deployment-projects/recipe-file.md +++ b/site/content/docs/deployment-projects/recipe-file.md @@ -2,7 +2,7 @@ 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). +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 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 @@ -14,7 +14,7 @@ This is the list of top level properties in the recipe definition. * **Description** - longer description shown when hovering over the recommendation in Visual Studio. * **TargetService** - the main AWS service the application will be deployed to. Visual Studio uses this to provide visual indicators. * **DeploymentType** - for deployment projects this value should always be `CdkProject`. -* **DeploymentBundle** - how the .NET project being deploying should be bundled. Allowed values are `Container` and `DotnetPublishZipFile`. +* **DeploymentBundle** - how the .NET project being deployed should be bundled. Allowed values are `Container` and `DotnetPublishZipFile`. * **DisplayedResources** - the list of resources to display to users at the end of the deployment. * **RecipePriority** - the priority of the recipe in the compatibility list. * **RecommendationRules** - the list of rules to determine the recipe's compatibility with the project being deployed. @@ -24,17 +24,19 @@ This is the list of top level properties in the recipe definition. ### Displayed Resources -The `DisplayedResources` array contains a list of resources that the deployment tooling should display after deployment is complete. This is typically the primary resources for a deployment project like an Elastic Beanstalk Environment or a Load Balancer that allows the user to quickly see their application deployed to AWS. +The `DisplayedResources` array contains a list of resources that the deployment tooling should display after deployment is complete. This is typically the primary resources for a deployment project like an AWS Elastic Beanstalk Environment or a Load Balancer that allows the user to quickly see their application deployed to AWS. -Here is an example for a recipe that wants to the Elastic Beanstalk environment to be displayed after deployment. +Here is an example for a recipe that displays the endpoint of the Elastic Beanstalk environment after deployment. -``` - "DisplayedResources": [ - { - "LogicalId": "RecipeBeanstalkEnvironment83CC12DE", - "Description": "Application Endpoint" - } - ], +```json +... +"DisplayedResources": [ + { + "LogicalId": "RecipeBeanstalkEnvironment83CC12DE", + "Description": "Application Endpoint" + } +], +... ``` `DisplayedResources` objects have the following properties: @@ -52,6 +54,7 @@ The recipe file defines a collection of rules that the deployment tool executes The deploy tool supports a collection of tests that can be run against the .NET project being deployed. Here is an example of a test that checks the version of .NET the project is targeting. ```json +... { "Type": "MSProperty", "Condition": { @@ -62,6 +65,7 @@ The deploy tool supports a collection of tests that can be run against the .NET ] } } +... ``` The `Type` property determines the type of test to run. The `Condition` contains the data needed to evaluate the test, in this case the MSBuild property to check and the allowed values. Each type of test can have a different set of properties for the `Condition`. @@ -73,7 +77,7 @@ The `Type` property determines the type of test to run. The `Condition` contains | MSProjectSdkAttribute | Compares the `Sdk` attribute at the root element of the project file to a given value. |
  • Value - the expected value. For example `Microsoft.NET.Sdk.Web` for web projects.
| | MSProperty | Compares the property in a project file property group. |
  • PropertyName - the property to compare.
  • AllowedValues - an array of possible values for the property.
| | MSPropertyExists | Test to see if a property in a property group exists. |
  • PropertyName - the property test for existence.
| -| FileExists | Tests to see if a file exist. For example checking to see a `Dockerfile` exists. |
  • FileName - the file to test for existence.
| +| FileExists | Tests to see if a file exists. For example checking to see a `Dockerfile` exists. |
  • FileName - the file to test for existence.
| | NuGetPackageReference | Test to see if the project has a `PackageReference` to a NuGet package. |
  • NuGetPackageName - the NuGet package to test if it is being referenced.
| @@ -81,109 +85,114 @@ The `Type` property determines the type of test to run. The `Condition` contains A rules effect defines the behavior of the rule depending on if its test(s) pass or not. Effects can either mark the recipe as not included in the compatible list or adjust the priority for the recipe. -Here is an example of a rule that checks the project is a web project and targets .NET Core 3.1 or .NET 6. If both tests pass the effect's `Pass` property instructs the deployment tooling to include the recipe. If either one of the two tests fail the `Fail` effect is run, removing the recipe from the included compatible list. +Here is an example of a rule that checks if the project is a web project and targets .NET Core 3.1 or .NET 6. If both tests pass the effect's `Pass` property instructs the deployment tooling to include the recipe. If either one of the two tests fail the `Fail` effect is run, removing the recipe from the included compatible list. ```json - "RecommendationRules": [ - { - "Tests": [ - { - "Type": "MSProjectSdkAttribute", - "Condition": { - "Value": "Microsoft.NET.Sdk.Web" - } - }, - { - "Type": "MSProperty", - "Condition": { - "PropertyName": "TargetFramework", - "AllowedValues": [ - "netcoreapp3.1", - "net6.0" - ] - } +... +"RecommendationRules": [ + { + "Tests": [ + { + "Type": "MSProjectSdkAttribute", + "Condition": { + "Value": "Microsoft.NET.Sdk.Web" } - ], - "Effect": { - "Pass": { - "Include": true - }, - "Fail": { - "Include": false + }, + { + "Type": "MSProperty", + "Condition": { + "PropertyName": "TargetFramework", + "AllowedValues": [ + "netcoreapp3.1", + "net6.0" + ] } } + ], + "Effect": { + "Pass": { + "Include": true + }, + "Fail": { + "Include": false + } } - ] + } +] +... ``` -Here is another example that tests if a project contains a docker file. If it does not include a docker file it reduces the priority of the recipe. +Here is another example that tests if a project contains a Dockerfile. If it does not, it reduces the priority of the recipe. ```json - "RecommendationRules": [ - ... - - { - "Tests": [ - { - "Type": "FileExists", - "Condition": { - "FileName": "Dockerfile" - } - } - ], - "Effect": { - "Fail": { - "PriorityAdjustment": -100, - "Include": true - } - } - }, +... +"RecommendationRules": [ + ... - ... - ] + { + "Tests": [ + { + "Type": "FileExists", + "Condition": { + "FileName": "Dockerfile" + } + } + ], + "Effect": { + "Fail": { + "PriorityAdjustment": -100, + "Include": true + } + } + }, + ... +] +... ``` 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. +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. -![Catagories in AWS Toolkit for Visual Studio](../../assets/images/vs-catagories.png) +![Categories in AWS Toolkit for Visual Studio](../../assets/images/vs-catagories.png) 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. +* **Order** - the order in the toolkit UI 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. -``` - { - "Id": "AppResources", - "DisplayName": "Application Resources", - "Order": 15 - } +```json +... +{ + "Id": "AppResources", + "DisplayName": "Application Resources", + "Order": 15 +} +... ``` -To assign a setting to a category, set the setting's `Category` property of to the `Id` of a category. Only top level settings can be assigned a category. Any top level settings that are not assigned a category will be placed in the `General` category. +To assign a setting to a category, set the setting's `Category` property to the `Id` of a category. Only top level settings can be assigned a category. Any top level settings that are not assigned a category will be placed in the `General` category. ### 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 allow them 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. * **Description** - the informational text shown to users for the setting. * **Type** - the data type of the setting. * **DefaultValue** - the default value for the setting. -* **TypeHint** - a hint to the deployment tooling what the meaning of the setting is. +* **TypeHint** - a hint to the deployment tooling what the meaning of the setting's value is. Some examples are an Amazon DynamoDB table name or the name of an Amazon SNS topic. * **TypeHintData** - additional information to pass into the type hint. -* **AdvancedSetting** - a boolean for whether this setting is an advanced use case. If true the setting might not be shown to users unless the request to see all settings. +* **AdvancedSetting** - a boolean for whether this setting is an advanced use case. If true the setting might not be shown to users unless they request to see all settings. * **Updatable** - a boolean that controls whether a setting can be modified during redeployment. It is recommended to set this to `false` for settings where deleting resources once they exist would make the application unavailable. * **AllowedValues** - the list of possible values. * **ValueMapping** - a mapping between values in the `AllowedValues` list to user friendly display names for each allowed value. @@ -213,18 +222,18 @@ Type hints are used to control the user experience in the CLI or Visual Studio. Some type hints require additional configuration which can specified in the `TypeHintData` property. For example if a setting has a type hint of `ExistingIAMRole` the tool should only show roles that can be assumed by the target service. Here is a example of configuring the `ServicePrincipal` for the type hint to filter the list of roles to pick from. -``` - { - "Id": "RoleArn", - "Name": "Existing Role ARN", - "Description": "The ARN of the existing role to use.", - "Type": "String", - "TypeHint": "ExistingIAMRole", - "TypeHintData": { - "ServicePrincipal": "ecs-tasks.amazonaws.com" - }, - - ... +```json +... +{ + "Id": "RoleArn", + "Name": "Existing Role ARN", + "Description": "The ARN of the existing role to use.", + "Type": "String", + "TypeHint": "ExistingIAMRole", + "TypeHintData": { + "ServicePrincipal": "ecs-tasks.amazonaws.com" + }, +... ``` Here is the list of available type hints in the deployment tooling. @@ -232,7 +241,7 @@ Here is the list of available type hints in the deployment tooling. | Type Hint | Type Hint Data | Notes | | --------- | ----------- | ---- | | IAMRole |
  • ServicePrincipal - the service principal the role can be assumed by.
| Set at `Object` level that controls whether to create a new role or select an existing role. | -| ExistingIAMRole |
  • ServicePrincipal - the service principal the role can be assumed by.
| Set at the `String` setting level for storing the existing IAM role arn. | +| ExistingIAMRole |
  • ServicePrincipal - the service principal the role can be assumed by.
| Set at the `String` setting level for storing the existing IAM role ARN. | | ECSCluster | | Set at the `Object` setting level that controls whether to create or select an existing ECS cluster. | | ExistingECSCluster | | Set at the `String` setting level for storing the existing ECS Cluster Name. | | ECSService | | | @@ -266,68 +275,67 @@ Here is the list of available type hints in the deployment tooling. #### DependsOn -The `DependsOn` property is an array of conditions to determine if a setting should be visible based on the values for other setting(s). For example if a user selects the setting to create a new IAM role then the setting for the selecting an existing IAM role should not be displayed. +The `DependsOn` property is an array of conditions to determine if a setting should be visible based on the values for other setting(s). For example if a user selects the setting to create a new IAM role then the setting for selecting an existing IAM role should not be displayed. Each item in the `DependsOn` array has the following properties. -* **Id** - the id of the setting compare. The id should be full id including all parent object id settings. The format is .. +* **Id** - the id of the setting to compare. The id should be the full id including all parent object id settings. The format is .. * **Operation** - the operation to run. Allowed values are `NotEmpty` and `Equals`. If operation is not set then the default is `Equals`. * **Value** - the value to compare when the operation is `Equals`. -Here is an example for a setting used for storing an existing IAM role to use. The value is displayed if the setting `ApplicationIAMRole.CreateNew` is set false. -``` - { - "Id": "RoleArn", - "Name": "Existing Role ARN", - "Description": "The ARN of the existing role to use.", - "Type": "String", - "TypeHint": "ExistingIAMRole", - "TypeHintData": { - "ServicePrincipal": "tasks.apprunner.amazonaws.com" - }, - "AdvancedSetting": false, - "Updatable": true, - "DependsOn": [ - { - "Id": "ApplicationIAMRole.CreateNew", - "Value": false - } - ], - - ... - } +Here is an example for a setting used for storing an existing IAM role to use. The value is displayed if the setting `ApplicationIAMRole.CreateNew` is set `false`. +```json +... +{ + "Id": "RoleArn", + "Name": "Existing Role ARN", + "Description": "The ARN of the existing role to use.", + "Type": "String", + "TypeHint": "ExistingIAMRole", + "TypeHintData": { + "ServicePrincipal": "tasks.apprunner.amazonaws.com" + }, + "AdvancedSetting": false, + "Updatable": true, + "DependsOn": [ + { + "Id": "ApplicationIAMRole.CreateNew", + "Value": false + } + ], + ... +} +... ``` #### Validators -Validators allow telling the user when a setting has an invalid value before starting the deployment. Each setting can have a list of validators specified in the `Validators` array. Validators can do simple checks like making sure string values are of a certain format as well as make AWS service calls to make sure the value of an existing resource exists. +Validators inform the user when a setting has an invalid value before starting the deployment. Each setting can have a list of validators specified in the `Validators` array. Validators can do simple checks like making sure string values are of a certain format, as well as make AWS service calls to make sure the value of an existing resource exists. Here is an example of a validator for a port setting that ensures the value is within the range 0 to 51200. ```json - ... - - { - "Id": "Port", - "Name": "Port", - "Category": "General", - "Description": "The port the container is listening for requests on.", - "Type": "Int", - "DefaultValue": 80, - "AdvancedSetting": false, - "Updatable": true, - "Validators": [ - { - "ValidatorType": "Range", - "Configuration": { - "Min": 0, - "Max": 51200 - } +... +{ + "Id": "Port", + "Name": "Port", + "Category": "General", + "Description": "The port the container is listening for requests on.", + "Type": "Int", + "DefaultValue": 80, + "AdvancedSetting": false, + "Updatable": true, + "Validators": [ + { + "ValidatorType": "Range", + "Configuration": { + "Min": 0, + "Max": 51200 } - ] - } - - ... + } + ] +} +... ``` The `ValidatorType` property determines the type of validator to run. The `Configuration` contains the data needed to evaluate the validator, in this case the min and max values. Each type of validator can have a different set of properties for the `Configuration`. @@ -346,9 +354,7 @@ The `ValidatorType` property determines the type of validator to run. The `Confi | InstanceType | Validates the string value is a valid Linux EC2 instance type. | | | WindowsInstanceType | Validates the string value is a valid Windows EC2 instance type. | | | SubnetsInVpc | Validates the subnets are in the configured VPC. |
  • VpcId - the id of the setting that has the VPC configured for.
  • ValidationFailedMessage - the error message shown if the validator fails.
| -| SecurityGroupsInVpc | Validates the security group are in the configured VPC. |
  • VpcId - the id of the setting that has the VPC configured for.
  • ValidationFailedMessage - the error message shown if the validator fails.
| +| SecurityGroupsInVpc | Validates the security group are in the configured VPC. |
  • VpcId - the id of the setting that contains the VPC configuration.
  • ValidationFailedMessage - the error message shown if the validator fails.
| | Uri | Validates the value is a well-formed URI string. |
  • ValidationFailedMessage - the error message shown if the validator fails.
| | Comparison | Compares this setting with another setting. |
  • SettingId - the setting to compare to.
  • Operation - the comparison operation. Allowed values are `GreaterThan`.
| | VPCSubnetsInDifferentAZs | Validates that the selected VPC must have at least two subnets in two different Availability Zones |
  • ValidationFailedMessage - the error message shown if the validator fails.
| - - diff --git a/site/content/docs/docker/docker-generation.md b/site/content/docs/docker/docker-generation.md index 022ac185a..b188f3651 100644 --- a/site/content/docs/docker/docker-generation.md +++ b/site/content/docs/docker/docker-generation.md @@ -2,7 +2,7 @@ **IF YOUR PROJECT DOES NOT CONTAIN A DOCKERFILE, THE DEPLOYMENT TOOL WILL ATTEMPT TO AUTOMATICALLY GENERATE IT,** otherwise an existing Dockerfile will be used for deployment. -The Dockerfile that deployment tools generates uses Docker's multistage build process. This allows efficient and smaller container images that only contain the bits that are required to run your application. +The Dockerfile the deployment tool generates uses Docker's multistage build process. This allows efficient and smaller container images that only contain the bits that are required to run your application. For a sample web application which has following directory structure: @@ -23,32 +23,38 @@ For a sample web application which has following directory structure: ### Build -Build stage consists of copying the files from the host machine to the container, restoring the dependencies, and building the application. Deployment Tool uses .sln directory as build context and generates file paths relative to the .sln directory. - - FROM mcr.microsoft.com/dotnet/core/aspnet:6.0 AS base - WORKDIR /app - EXPOSE 80 - EXPOSE 443 - WORKDIR /src - COPY ["MyWebApplication/MyWebApplication.csproj", "MyWebApplication/"] - COPY ["MyClassLibrary/MyClassLibrary.csproj", "MyClassLibrary/"] - RUN dotnet restore "MyWebApplication/MyWebApplication.csproj" - COPY . . - WORKDIR "/src/MyWebApplication" - RUN dotnet build "MyWebApplication.csproj" -c Release -o /app/build +Build stage consists of copying the files from the host machine to the container, restoring the dependencies, and building the application. Deployment Tool uses the directory containing the solution file (*.sln) as build context and generates file paths relative to that directory. + +``` +FROM mcr.microsoft.com/dotnet/core/aspnet:6.0 AS base +WORKDIR /app +EXPOSE 80 +EXPOSE 443 +WORKDIR /src +COPY ["MyWebApplication/MyWebApplication.csproj", "MyWebApplication/"] +COPY ["MyClassLibrary/MyClassLibrary.csproj", "MyClassLibrary/"] +RUN dotnet restore "MyWebApplication/MyWebApplication.csproj" +COPY . . +WORKDIR "/src/MyWebApplication" +RUN dotnet build "MyWebApplication.csproj" -c Release -o /app/build +``` ### Publish Publish stage takes the build output and publishes the .NET application to /app/publish directory. - FROM build AS publish - RUN dotnet publish "MyWebApplication.csproj" -c Release -o /app/publish +``` +FROM build AS publish +RUN dotnet publish "MyWebApplication.csproj" -c Release -o /app/publish +``` ### Final Final stage takes the publish output and copies it to the container which uses ASP.NET Core image as a base image. - FROM base AS final - WORKDIR /app - COPY --from=publish /app/publish . - ENTRYPOINT ["dotnet", "MyWebApplication.dll"] +``` +FROM base AS final +WORKDIR /app +COPY --from=publish /app/publish . +ENTRYPOINT ["dotnet", "MyWebApplication.dll"] +``` diff --git a/site/content/docs/getting-started/custom-workspace.md b/site/content/docs/getting-started/custom-workspace.md index be0bdcf94..954133e34 100644 --- a/site/content/docs/getting-started/custom-workspace.md +++ b/site/content/docs/getting-started/custom-workspace.md @@ -1,11 +1,13 @@ +# Set up custom workspace + The default workspace used by AWS.Deploy.Tools is `$USERPROFILE/.aws-dotnet-deploy` on Windows and `$USER/.aws-dotnet-deploy` on Unix based OS. This workspace is used to create the CDK project and any other temporary files used by the tool. -You can override the default workspace by the setting the `AWS_DOTNET_DEPLOYTOOL_WORKSPACE` environment variable. +You can override the default workspace by the setting the `AWS_DOTNET_DEPLOYTOOL_WORKSPACE` environment variable. It must satisfy the following constraints: * It must point to a valid directory that exists on the disk. * The directory path must not have any whitespace characters in it. -**Setting up a custom workspace is optional for most users.** However, on Windows OS, if the `$USERPROFILE` path contains a whitespace character then the deployment will fail. +**Setting up a custom workspace is optional for most users.** However, on Windows OS, if the `$USERPROFILE` path contains a whitespace character then the deployment will fail. In that case, users are required to set up a custom workspace that satisfies the above constraints. \ No newline at end of file diff --git a/site/content/docs/getting-started/installation.md b/site/content/docs/getting-started/installation.md index a09a78da8..ad7d6508a 100644 --- a/site/content/docs/getting-started/installation.md +++ b/site/content/docs/getting-started/installation.md @@ -3,14 +3,18 @@ The following instructions show you how to install, update, and uninstall the deployment tool. #### Install -To install the deployment tool, use the dotnet tool install command: +To install the deployment tool, use the `dotnet tool install` command: - dotnet tool install -g aws.deploy.tools +``` +dotnet tool install -g aws.deploy.tools +``` #### Update -To update to the latest version of the deployment tool, use the dotnet tool update command. +To update to the latest version of the deployment tool, use the `dotnet tool update` command. - dotnet tool update -g aws.deploy.tools +``` +dotnet tool update -g aws.deploy.tools +``` > **Note** > *The deployment tool was initially in a NuGet package called "aws.deploy.cli". If you have this older version of the tool, you'll see a deprecation notice and the version will be 0.40.18 or earlier. Uninstall the older version of the tool and install a new one.* @@ -18,13 +22,19 @@ To update to the latest version of the deployment tool, use the dotnet tool upda #### Uninstall To uninstall it, simply type: - dotnet tool uninstall -g aws.deploy.tools +``` +dotnet tool uninstall -g aws.deploy.tools +``` #### Help Once you install the tool, you can view the list of available commands by typing: - dotnet aws --help +``` +dotnet aws --help +``` -To get help about individual commands like deploy or delete-deployment you can use the --help switch with the commands. For example to get help for the deploy command type: +To get help about individual commands like `deploy` or `delete-deployment` you can use the `--help` switch with the commands. For example to get help for the `deploy` command type: - dotnet aws deploy --help +``` +dotnet aws deploy --help +``` diff --git a/site/content/docs/getting-started/pre-requisites.md b/site/content/docs/getting-started/pre-requisites.md index a2ad65146..7febcf93c 100644 --- a/site/content/docs/getting-started/pre-requisites.md +++ b/site/content/docs/getting-started/pre-requisites.md @@ -3,7 +3,7 @@ To run the AWS Deploy Tool, you need the following pre-requisites set up in your environment: #### AWS Account -* *An AWS account* with a local credential profile configured in the shared AWS config and credentials files. For information on setting up a profile, see our [SDK Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/access-users.html). +* An *AWS account* with a local credential profile configured in the shared AWS config and credentials files. For information on setting up a profile, see our [SDK Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/access-users.html). * The local credential profile can be configured by a variety of tools. For example, the credential profile can be configured with the [AWS Toolkit for Visual Studio](https://docs.aws.amazon.com/toolkit-for-visual-studio/latest/user-guide/credentials.html) or the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html), among others. @@ -14,7 +14,7 @@ To run the AWS Deploy Tool, you need the following pre-requisites set up in your * The .NET CLI is included with the [.NET SDK](https://docs.microsoft.com/en-us/dotnet/core/sdk). For information about how to install or update .NET, see [https://dotnet.microsoft.com/](https://dotnet.microsoft.com/). -* The application you are deploying must be built from .NET Core 3.1 or later (for example, .NET Core 3.1, .NET 5.0, .NET 6.0). To see what version you have, run the following on the command prompt or in a terminal: +* The application you are deploying must be built from .NET Core 3.1 or later (for example, .NET Core 3.1, .NET 5.0, .NET 6.0). To see what version you have, run the following on the command prompt or in a terminal: ``` dotnet --version diff --git a/site/content/docs/getting-started/run-tool.md b/site/content/docs/getting-started/run-tool.md index 8231ac060..bef6e0056 100644 --- a/site/content/docs/getting-started/run-tool.md +++ b/site/content/docs/getting-started/run-tool.md @@ -4,18 +4,26 @@ This article teaches you how to deploy a simple “Hello World!" web application The command for the deployment tool can be expressed in one of two forms. Either form might be used for command examples. - dotnet aws ... - dotnet-aws ... +``` +dotnet aws ... +dotnet-aws ... +``` -#### Step 1: Create ASP.NET Web application +#### Step 1: Create the ASP.NET Web application - dotnet new web -n HelloWorld -f net6.0 +``` +dotnet new web -n HelloWorld -f net6.0 +``` -#### Step 2: cd to the project +#### Step 2: cd to the project folder - cd HelloWorld +``` +cd HelloWorld +``` #### Step 3: Deploy to AWS - dotnet aws deploy --profile default --region us-east-1 +``` +dotnet aws deploy --profile default --region us-east-1 +``` diff --git a/site/content/docs/getting-started/setup-creds.md b/site/content/docs/getting-started/setup-creds.md index dca9c94e7..6a6b36902 100644 --- a/site/content/docs/getting-started/setup-creds.md +++ b/site/content/docs/getting-started/setup-creds.md @@ -1,6 +1,6 @@ # Setting up credentials -AWS.Deploy.Tools, internally uses a variety of different tools and services to host your .NET application on AWS. To run the AWS Deploy Tool, you must configure a credential profile that provides access to the AWS account you wish to deploy to. Your credentials must have permissions for certain services, depending on the tasks that you're trying to perform. +AWS.Deploy.Tools internally uses a variety of different tools and services to host your .NET application on AWS. To run the AWS Deploy Tool, you must configure a credential profile that provides access to the AWS account you wish to deploy to. Your credentials must have permissions for certain services, depending on the tasks that you're trying to perform. ### Recommended policies @@ -12,12 +12,12 @@ The following are some examples of the typical permissions that are required. | --- | --- |--- | |deploy | Deploying to Amazon ECS | AWSCloudFormationFullAccess, AmazonECS_FullAccess, AmazonEC2ContainerRegistryFullAccess, AmazonSSMFullAccess, IAMFullAccess | |deploy | Deploying to AWS App Runner| AWSCloudFormationFullAccess, AWSAppRunnerFullAccess, AmazonEC2ContainerRegistryFullAccess, AmazonSSMFullAccess, IAMFullAccess| -|deploy | Deploying to Elastic Beanstalk (deploy) | AWSCloudFormationFullAccess, AdministratorAccess-AWSElasticBeanstalk, AmazonSSMFullAccess, AmazonS3FullAccess (*required to upload the application bundle*), IAMFullAccess | -|deploy | Hosting WebAssembly Blazor App in S3 & CloudFront | AmazonS3FullAccess, CloudFrontFullAccess, IAMFullAccess, AmazonSSMFullAccess, AWSLambda_FullAccess (*required to copy from CDKBootstrap bucket to S3 bucket*)| -| list-deployments | List CF stacks| AWSCloudFormationReadOnlyAccess | -| delete-deployment | Delete a CF stack | AWSCloudFormationFullAccess + permissions for resources being deleted | +|deploy | Deploying to AWS Elastic Beanstalk (deploy) | AWSCloudFormationFullAccess, AdministratorAccess-AWSElasticBeanstalk, AmazonSSMFullAccess, AmazonS3FullAccess (*required to upload the application bundle*), IAMFullAccess | +|deploy | Hosting WebAssembly Blazor App in Amazon S3 & Amazon CloudFront | AmazonS3FullAccess, CloudFrontFullAccess, IAMFullAccess, AmazonSSMFullAccess, AWSLambda_FullAccess (*required to copy from CDKBootstrap bucket to S3 bucket*)| +| list-deployments | List AWS CloudFormation stacks| AWSCloudFormationReadOnlyAccess | +| delete-deployment | Delete an AWS CloudFormation stack | AWSCloudFormationFullAccess + permissions for resources being deleted | - > Note: If you are creating IAM roles, you need IAMFullAccess otherwise IAMReadOnlyAccess. Note that the first time the CDK bootstrap stack is created it will need IAMFullAccess. + > Note: If you are creating IAM roles, you need IAMFullAccess otherwise IAMReadOnlyAccess. Note that the first time the CDK bootstrap stack is created it will need IAMFullAccess. @@ -30,16 +30,19 @@ In your shared AWS config and credentials files, if the `[default]` profile exis ####... locally * The simplest way to specify region and profile is to provide them as parameters to the tool. - `dotnet aws deploy --profile customProfile --region us-west-2`. - For additional information about command parameters, see [Commands](../../docs/commands/deploy.md) section. +``` +dotnet aws deploy --profile customProfile --region us-west-2 +``` + +For additional information about command parameters, see [Commands](../../docs/commands/deploy.md) section. > **Note** > If you provide only the `--profile` argument, the AWS Region isn't read from the profile that you specify. Instead, the tool reads the Region from the `[default]` profile if one exists, or asks for the desired profile interactively. ####... system-wide -To specify a system-wide profile and region, define the `AWS_PROFILE` and `AWS_REGION` environment variables globally, as appropriate for your operating system. Be sure to reopen command prompts or terminals as necessary. +To specify a system-wide profile and region, define the `AWS_PROFILE` and `AWS_REGION` environment variables globally, as appropriate for your operating system. Be sure to reopen command prompts or terminals as necessary. > **Warning** > If you set the `AWS_PROFILE` environment variable globally for your system, other SDKs, CLIs, and tools will also use that profile. If this behavior is unacceptable, specify a profile for a particular context instead. diff --git a/site/content/docs/support.md b/site/content/docs/support.md index 4b4baaed9..bb26685ea 100644 --- a/site/content/docs/support.md +++ b/site/content/docs/support.md @@ -11,9 +11,9 @@ The table below provides a matrix of supported .NET application types and AWS Co | Amazon S3 & Amazon CloudFront | | | :heavy_check_mark: | -### Amazon ECS using AWS Fargate +### Amazon Elastic Container Service (Amazon ECS) using AWS Fargate -* Supports deployments of .NET applications as a service (e.g. web application or a background processor) or as a scheduled task (e.g. end-of-day process) to Amazon Elastic Container Service (Amazon ECS) with compute power managed by AWS Fargate serverless compute engine. +* Supports deployments of .NET applications as a service (e.g. web application or a background processor) or as a scheduled task (e.g. end-of-day process) to Amazon Elastic Container Service (Amazon ECS) with compute power managed by the AWS Fargate serverless compute engine. * Recommended if you want to deploy a service or a scheduled task as a container image on Linux. > **Note: This compute requires a Dockerfile. IF YOUR PROJECT DOES NOT CONTAIN A DOCKERFILE, THE DEPLOYMENT TOOL WILL ATTEMPT TO AUTOMATICALLY GENERATE IT,** otherwise an existing Dockerfile will be used. diff --git a/site/content/faq.md b/site/content/faq.md index 042c389d5..927cbad04 100644 --- a/site/content/faq.md +++ b/site/content/faq.md @@ -4,21 +4,21 @@ Yes, the AWS Deploy Tool can be used to deploy any cloud-native .NET applications to AWS. A cloud-native .NET application is written in .NET with intent to deploy to Linux, not tied to any Windows specific technology such as Windows registry, IIS or MSMQ, and can be deployed on virtualized compute. It cannot be used to deploy .NET Framework, Desktop, Xamarin, or other applications that do not fit the “cloud-native” criteria. #### *FAQ: How does the AWS Deploy Tool decide what service to choose for deployment?* -It examines .NET project file and project dependencies, and inspects the code for attribution and Dockerfile presence to figure out the application type and the service best suited to run the application. +It examines the .NET project file and project dependencies, and inspects the code for attribution and Dockerfile presence to figure out the application type and the service best suited to run the application. #### *FAQ: How will my application be packaged and deployed?* -Once the AWS compute service is chosen, the deployment tool will package your application binary artifacts in the appropriate format for that service (for example zip file for AWS Elastic Beanstalk) and deploy it using CDK. Once the application is deployed, it will return an endpoint for the application (for example URL for API backend, or SQS queue for messaging app). +Once the AWS compute service is chosen, the deployment tool will package your application binary artifacts in the appropriate format for that service (for example zip file for AWS Elastic Beanstalk) and deploy it using the [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/). Once the application is deployed, it will return an endpoint for the application (for example URL for API backend, or SQS queue for messaging app). -#### *FAQ: How does the AWS Deploy Tool create infrastructure?* +#### *FAQ: How does the AWS Deploy Tool create infrastructure?* It generates a .NET CDK project for the suggested service and uses the .NET CDK binding to build constructs. If you are not ready to learn CDK, it will auto-generate the default .NET CDK project behind the scenes. You can also change or extend the CDK project’s behavior to match your exact needs and then execute the deployment. #### *FAQ: Can I re-deploy my application to a different stack?* -Yes. The AWS Deploy Tool saves your deployment settings, including the environment name (such as the name of the Cloud Formation stack) your application was deployed to. When you re-run “dotnet aws deploy” command, it will detect these previously saved settings, and ask if you want to re-deploy to the same or a different environment. If you choose the latter, it will create a new deployment stack. +Yes. The AWS Deploy Tool saves your deployment settings, including the environment name (such as the name of the AWS CloudFormation stack) your application was deployed to. When you re-run `dotnet aws deploy` command, it will detect these previously saved settings, and ask if you want to re-deploy to the same or a different environment. If you choose the latter, it will create a new deployment stack. #### *FAQ: Can I choose a different AWS service to deploy my application?* -The AWS Deploy Tool will show you all compute service options available to deploy your application, and will recommend a default with information about why it was chosen. The other compute service options will be shown with an explanation of their differences. If the selected compute option does not match your need, you can select a different compute service. +The AWS Deploy Tool will show you all compute service options available to deploy your application, and will recommend a default with information about why it was chosen. The other compute service options will be shown with an explanation of their differences. If the selected compute option does not match your need, you can select a different compute service. -#### *FAQ: I have an application that has dependency on Windows technology, Can I use the AWS Deploy Tool to deploy it to AWS?* +#### *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?* diff --git a/site/content/index.md b/site/content/index.md index 135ae235a..06e6a561d 100644 --- a/site/content/index.md +++ b/site/content/index.md @@ -1,6 +1,6 @@ # About the AWS Deploy Tool for .NET -** 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. +** AWS Deploy Tool for .NET** is an interactive tool 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 @@ -8,7 +8,7 @@ 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. +* **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** – 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. @@ -18,7 +18,7 @@ AWS Deploy Tool has the following capabilities: 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 -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/). +The AWS Toolkit for Visual Studio exposes the same deployment functionality via the **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 diff --git a/site/content/troubleshooting-guide/docker-issues.md b/site/content/troubleshooting-guide/docker-issues.md index f91aa7abe..9882a9c39 100644 --- a/site/content/troubleshooting-guide/docker-issues.md +++ b/site/content/troubleshooting-guide/docker-issues.md @@ -11,12 +11,12 @@ This section of the troubleshooting guide explains how to determine, diagnose, a There are multiple reasons your deployment may fail during the Docker build step. -### **Invalid Dockerfile** +### **Invalid Dockerfile** **Why is this happening**: If there is a syntax error or invalid argument in your Dockerfile, the Docker build command may fail with an error message like this: ``` failed to solve with frontend dockerfile.v0: failed to create LLB definition: -``` +``` **Resolution**: Correct any syntax errors or invalid arguments in your Dockerfile. Consult [Docker's Dockerfile reference](https://docs.docker.com/engine/reference/builder/) for the expected syntax for each instruction. @@ -35,11 +35,11 @@ AWS.Deploy.Tools allows you to specify an alternative Docker execution directory --- ### Missing project dependencies -**Why is this happening**: -The Docker build command may fail during the `RUN dotnet build` instruction if all of your project dependencies are not specified in the Dockerfile. +**Why is this happening**: +The Docker build command may fail during the `RUN dotnet build` instruction if all of your project dependencies are not specified in the Dockerfile. **Resolution**: -Ensure all dependencies from your project and solution files are included in your Dockerfile. A good starting point is to inspect the solution file and add the relevant projects to the Dockerfile. +Ensure all dependencies from your project and solution files are included in your Dockerfile. A good starting point is to inspect the solution file and add the relevant projects to the Dockerfile. If a custom Dockerfile is not initally provided, AWS.Deploy.Tools will generate one if you select a container-based deployment. The generated Dockerfile will include the projects currently defined in your solution file. This Dockerfile is persisted on disk. If you add a new dependency to the solution file in the future, you must manually add a new entry for it in the persisted Dockerfile. @@ -70,7 +70,7 @@ If your container is able to access the internet but the package restore is fail --- ## Failed to push Docker Image -**Why is this happening**: AWS.Deploy.Tools builds the Docker image and pushes it to Amazon Elastic Container Registry (Amazon ECR). +**Why is this happening**: AWS.Deploy.Tools builds the Docker image and pushes it to Amazon Elastic Container Registry (Amazon ECR). If you are missing the required AWS Identity and Access Management (IAM) permissions to perform actions against ECR repositories, the deployment may fail the following error message: @@ -83,4 +83,4 @@ Failed to push Docker Image **Why is this happening** You may see this if your project has project references (.csproj, .vbproj) that are located in a higher folder than the solution file (.sln) that AWS.Deploy.Tools is using to generate a Dockerfile. In this case AWS.Deploy.Tools will not generate a Dockerfile to avoid a large build context that can result in long builds. -**Resolution**: If you would still like to deploy to an [AWS service that requires Docker](../docs/support.md), you must create your own Dockerfile and set an appropriate "Docker Execution Directory" in the deployment options. Alternatively you may choose another deployment target that does not require Docker, such as AWS Elastic Beanstalk. \ No newline at end of file +**Resolution**: If you would still like to deploy to an [AWS service that requires Docker](../docs/support.md), you must create your own Dockerfile and set an appropriate "Docker Execution Directory" in the deployment options. Alternatively you may choose another deployment target that does not require Docker, such as AWS Elastic Beanstalk. diff --git a/site/content/troubleshooting-guide/index.md b/site/content/troubleshooting-guide/index.md index 15abedb52..bf76694f7 100644 --- a/site/content/troubleshooting-guide/index.md +++ b/site/content/troubleshooting-guide/index.md @@ -27,24 +27,25 @@ Recipe configurations target different AWS services and there may be incompatibi Another reason why there are no recommendations generated is if your application's `.csproj` file is using a variable for the `TargetFramework` property. For example: +```xml + + + net5.0 + $(TargetFrameworkVersion) + + +``` - - - net5.0 - $(TargetFrameworkVersion) - - - No recommendations will be generated for the above `.csproj` file. -**This is a bug which we will address**: [GitHub issue](https://github.com/aws/aws-dotnet-deploy/issues/550). +**This is a bug which we will address**: [GitHub issue](https://github.com/aws/aws-dotnet-deploy/issues/550). -Meanwhile, please provide explicit values for the `TargetFramework` property. +Meanwhile, please provide explicit values for the `TargetFramework` property. **Resolution**: If you think that your project is not correctly recognized by our tool and no recommendations are generated, then file a [GitHub issue](https://github.com/aws/aws-dotnet-deploy/issues/new/choose) describing your project and also providing relevant details about your `.csproj` or `.fsproj` file. This will help us understand and narrow down the gaps in our recommendation engine and customer use cases. ## Deployment failures related to JSON configuration file -**Why is this happening**: AWS.Deploy.Tools allows for prompt-less deployments using a JSON configuration file. This workflow can easily be plugged into your CI/CD pipeline for automated deployments. +**Why is this happening**: AWS.Deploy.Tools allows for prompt-less deployments using a JSON configuration file. This workflow can easily be plugged into your CI/CD pipeline for automated deployments. If a deployment failure occurs while using a configuration file, It is possible that the configuration file has the wrong definition or the wrong format. @@ -75,13 +76,13 @@ A common error that is displayed for CDK Bootstrap related deployment failures i ``` The AWS CDK Bootstrap, which is the process of provisioning initial resources for the deployment environment, has failed. Please review the output above for additional details [and check out our troubleshooting guide for the most common failure reasons]. You can learn more about CDK bootstrapping at https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html. ``` -The AWS Deploy Tool for .NET uses [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/home.html) to create the AWS infrastructure needed to deploy your application. The AWS CDK is a framework for defining cloud infrastructure in code and provisioning it through AWS CloudFormation. +The AWS Deploy Tool for .NET uses [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/home.html) to create the AWS infrastructure needed to deploy your application. The AWS CDK is a framework for defining cloud infrastructure in code and provisioning it through AWS CloudFormation. Deploying AWS CDK apps into an AWS environment (a combination of an AWS account and region) requires that you provision resources the AWS CDK needs to perform the deployment. These resources include an Amazon S3 bucket for storing files and IAM roles that grant permissions needed to perform deployments. The process of provisioning these initial resources is called [bootstrapping](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html). The required resources are defined in a AWS CloudFormation stack, called the bootstrap stack, which is usually named `CDKToolkit`. Like any AWS CloudFormation stack, it appears in the AWS CloudFormation console once it has been deployed. -There could be several reasons why you are experiencing this issue. However, the most common ones are related to **Insufficient IAM Permissions** and an **Existing CDK Staging Bucket**. +There could be several reasons why you are experiencing this issue. However, the most common ones are related to **Insufficient IAM Permissions** and an **Existing CDK Staging Bucket**. **Insufficient IAM Permission**: CDKBoostrap failed because your profile does not have sufficient permissions to create the boostrap stack. Check the log - in this case, you should see an error that looks something like this: ``` diff --git a/site/content/troubleshooting-guide/missing-dependencies.md b/site/content/troubleshooting-guide/missing-dependencies.md index 633f14cfb..0b164f6e7 100644 --- a/site/content/troubleshooting-guide/missing-dependencies.md +++ b/site/content/troubleshooting-guide/missing-dependencies.md @@ -4,7 +4,7 @@ This section of the troubleshooting guide explains how to determine, diagnose, a ## Node.js not installed -**Why is this happening**: AWS.Deploy.Tools relies on [AWS Cloud Development Kit](https://aws.amazon.com/cdk/) (CDK) to provision resources for your cloud application. AWS CDK requires Node.js to be installed in your machine. See the [CDK's FAQs](https://aws.amazon.com/cdk/faqs/) for more information about how it uses Node.js. +**Why is this happening**: AWS.Deploy.Tools relies on [AWS Cloud Development Kit](https://aws.amazon.com/cdk/) (CDK) to provision resources for your cloud application. AWS CDK requires Node.js to be installed in your machine. See the [CDK's FAQs](https://aws.amazon.com/cdk/faqs/) for more information about how it uses Node.js. *Minimum required Node.js version >= 14.17.0* @@ -19,7 +19,7 @@ This section of the troubleshooting guide explains how to determine, diagnose, a **Why is this happening**: Non-container based deployments types (such as deployments to AWS Elastic Beanstalk) create a zip file of the artifacts produced by the `dotnet publish` command. The zip command line utility is not installed by default on some **Linux** distributions. If you are deploying using a non-container based option, you may encounter an error saying: -``` +``` We were unable to create a zip archive of the packaged application. Normally this indicates a problem running the \"zip\" utility. Make sure that application is installed and available in your PATH. ``` @@ -29,14 +29,16 @@ We use the Linux zip tool to maintain Linux file permissions. **Resolution**: To install zip on Linux OS, run the following commands depending on your distribution's package management tool. -For distributions using `apt-get`: +For distributions using `apt-get`: ``` sudo apt-get install zip ``` -For distributions using `yum`: + +For distributions using `yum`: ``` sudo yum intall zip ``` + After installation, use the command to verify that zip was installed correctly. ``` zip diff --git a/site/content/tutorials/custom-project.md b/site/content/tutorials/custom-project.md index b9a889c7c..6a99341e3 100644 --- a/site/content/tutorials/custom-project.md +++ b/site/content/tutorials/custom-project.md @@ -1,17 +1,17 @@ -# Adding DynamoDB table to your deployment project +# Adding an Amazon DynamoDB table to your deployment project -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. +In this tutorial, we will create and customize a deployment project to deploy a web application that uses an Amazon 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. Tasks we will accomplish: -1. Create a new web application called Acme.WebApp +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. +3. Customize the deployment project's recipe file to allow the user to configure a 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. +6. Pass the DynamoDB table name to the application code using an environment variable our application reads to know which table to use. 7. Add the deployment project to source control. -8. Deploy our Acme.WebApp application using custom deployment project. +8. Deploy our Acme.WebApp application using the custom deployment project. > **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.*** @@ -19,13 +19,17 @@ Tasks we will accomplish: In your command prompt, run the following command to create your app: - dotnet new webapp -o Acme.WebApp -f net6.0 +``` +dotnet new webapp -o Acme.WebApp -f net6.0 +``` ### Step 2: Generate a deployment project Navigate to the Acme.WebApp project directory and run the following command to generate a deployment project: - dotnet aws deployment-project generate --output ../Acme.WebApp.DeploymentProject --project-display-name "ASP.NET Core app with DynamoDB" +``` +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. @@ -51,7 +55,7 @@ This ASP.NET Core application will be built and deployed to existing AWS Elastic Choose deployment option (recommended default: 1) ``` -Pick the option #2 that says "ASP.NET Core App to Amazon ECS using AWS Fargate". +Pick option #2, "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. @@ -68,168 +72,161 @@ Go to the `OptionSettings` section that contains the settings users can use to c 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. +```json +"OptionSettings": [ + ... + { + "Id": "Backend", + "Name": "Backend", + "Category": "General", + "Description": "Configure the backend store.", + "Type": "Object", + "AdvancedSetting": false, + "Updatable": true, + "ChildOptionSettings": [ + + ] + }, +... +] ``` - "OptionSettings": [ - ... +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 created: +```json +"ChildOptionSettings": [ { - "Id": "Backend", - "Name": "Backend", - "Category": "General", - "Description": "Configure the backend store.", - "Type": "Object", + "Id": "CreateNewTable", + "Name": "Create New DynamoDB Table", + "Description": "Do you want to create a new DynamoDB table for the backend store?", + "Type": "Bool", + "DefaultValue": true, "AdvancedSetting": false, - "Updatable": true, - "ChildOptionSettings": [ - - ] + "Updatable": false }, - - - ... - } -``` - -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": [ - { - "Id": "CreateNewTable", - "Name": "Create New DynamoDB Table", - "Description": "Do you want to create a new DynamoDB table for the backend store?", - "Type": "Bool", - "DefaultValue": true, - "AdvancedSetting": false, - "Updatable": false - }, - - ... - - ] - + ... + ] ``` 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": [ - ... - - { - "Id": "ExistingTableName", - "Name": "Existing DynamoDB Table", - "Description": "Existing DynamoDB table to use as the backend store.", - "Type": "String", - "TypeHint": "DynamoDBTableName", - "DefaultValue": "", - "AdvancedSetting": false, - "Updatable": true, - "DependsOn": [ - { - "Id": "Backend.CreateNewTable", - "Value": false - } - ], - "Validators": [ - { - "ValidatorType": "Regex", - "Configuration": { - "Regex": "[a-zA-Z0-9_.-]+", - "ValidationFailedMessage": "Invalid table name." - } - }, - { - "ValidatorType": "StringLength", - "Configuration": { - "MinLength": 3, - "MaxLength": 255 - } - } - ] +```json +"ChildOptionSettings": [ + ... + { + "Id": "ExistingTableName", + "Name": "Existing DynamoDB Table", + "Description": "Existing DynamoDB table to use as the backend store.", + "Type": "String", + "TypeHint": "DynamoDBTableName", + "DefaultValue": "", + "AdvancedSetting": false, + "Updatable": true, + "DependsOn": [ + { + "Id": "Backend.CreateNewTable", + "Value": false + } + ], + "Validators": [ + { + "ValidatorType": "Regex", + "Configuration": { + "Regex": "[a-zA-Z0-9_.-]+", + "ValidationFailedMessage": "Invalid table name." } - ] + }, + { + "ValidatorType": "StringLength", + "Configuration": { + "MinLength": 3, + "MaxLength": 255 + } + } + ] + } +] ``` Let us take a deeper dive into the properties for the `ExistingTableName` setting. -* **TypeHint** - Set to `DynamoDBTableName` which lets the deployment tool know this String type is for the name of a DynamoDB table. The deploy tool uses this information to show users a list of tables to pick from instead of a text-box. +* **TypeHint** - Set to `DynamoDBTableName` which tells the deployment tool this String type contains the name of a DynamoDB table. The deploy tool uses this information to show users a list of tables to pick from instead of a text-box. * **Updatable** - Since modifying the name of an existing table is not a destructive change, we will allow this field to be updated during redeployments. * **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 option setting with the child settings: -``` + +```json +{ + "Id": "Backend", + "Name": "Backend", + "Category": "General", + "Description": "Configure the backend store.", + "Type": "Object", + "AdvancedSetting": false, + "Updatable": true, + "ChildOptionSettings": [ { - "Id": "Backend", - "Name": "Backend", - "Category": "General", - "Description": "Configure the backend store.", - "Type": "Object", + "Id": "CreateNewTable", + "Name": "Create New DynamoDB Table", + "Description": "Do you want to create a new DynamoDB table for the backend store?", + "Type": "Bool", + "DefaultValue": true, + "AdvancedSetting": false, + "Updatable": false + }, + { + "Id": "ExistingTableName", + "Name": "Existing DynamoDB Table", + "Description": "Existing DynamoDB table to use as the backend store.", + "Type": "String", + "TypeHint": "DynamoDBTableName", + "DefaultValue": "", "AdvancedSetting": false, "Updatable": true, - "ChildOptionSettings": [ + "DependsOn": [ { - "Id": "CreateNewTable", - "Name": "Create New DynamoDB Table", - "Description": "Do you want to create a new DynamoDB table for the backend store?", - "Type": "Bool", - "DefaultValue": true, - "AdvancedSetting": false, - "Updatable": false + "Id": "Backend.CreateNewTable", + "Value": false + } + ], + "Validators": [ + { + "ValidatorType": "Regex", + "Configuration": { + "Regex": "[a-zA-Z0-9_.-]+", + "ValidationFailedMessage": "Invalid table name." + } }, { - "Id": "ExistingTableName", - "Name": "Existing DynamoDB Table", - "Description": "Existing DynamoDB table to use as the backend store.", - "Type": "String", - "TypeHint": "DynamoDBTableName", - "DefaultValue": "", - "AdvancedSetting": false, - "Updatable": true, - "DependsOn": [ - { - "Id": "Backend.CreateNewTable", - "Value": false - } - ], - "Validators": [ - { - "ValidatorType": "Regex", - "Configuration": { - "Regex": "[a-zA-Z0-9_.-]+", - "ValidationFailedMessage": "Invalid table name." - } - }, - { - "ValidatorType": "StringLength", - "Configuration": { - "MinLength": 3, - "MaxLength": 255 - } - } - ] + "ValidatorType": "StringLength", + "Configuration": { + "MinLength": 3, + "MaxLength": 255 + } } ] } + ] +} ``` ### Step 4. Add new setting options to the CDK project -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. +When the 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. 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`. > **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.*** -``` +```csharp namespace Acme.WebApp.DeploymentProject.Configurations { public class BackendConfiguration @@ -263,7 +260,7 @@ namespace Acme.WebApp.DeploymentProject.Configurations In the `Configuration.cs` file, add a new property for our new backend settings. -``` +```csharp namespace Acme.WebApp.DeploymentProject.Configurations { public partial class Configuration @@ -279,9 +276,9 @@ Notice that the `Backend` property was added to the partial class that is **not* > **Note:** The `AppStack` class is the recommended place to customize the AWS resources. -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. +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. -``` +```csharp using Amazon.CDK.AWS.DynamoDB; namespace Acme.WebApp.DeploymentProject @@ -315,17 +312,17 @@ namespace Acme.WebApp.DeploymentProject } ``` -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. +Notice that in the snippet above the table is created before the `Recipe` construct. The `Recipe` construct has all the AWS resources that are part of the original built-in ECS recipe that the deployment project was created from. ### Step 6: Pass the DynamoDB table name to the application code -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. +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` method 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. 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. -``` +```csharp private void CustomizeCDKProps(CustomizePropsEventArgs evnt) { // Example of how to customize the container image definition to include environment variables to the running applications. @@ -351,15 +348,17 @@ private void CustomizeCDKProps(CustomizePropsEventArgs evnt) } ``` -### Step 6: Add deployment project to the source control +### Step 6: Add deployment project to 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. +Check your customized deployment project into your source control repository. 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 In your command prompt, run the following command to deploy your application: - dotnet aws deploy --project-path . +``` +dotnet aws deploy --project-path . +``` The custom deployment project will be displayed as the recommended option.