-
Notifications
You must be signed in to change notification settings - Fork 30
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: add new documentation generator to generate deployment settings…
… file documentation
- Loading branch information
Showing
40 changed files
with
2,222 additions
and
82 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| name: Detect Doc Generator Changes | ||
|
|
||
| on: [pull_request] | ||
|
|
||
| permissions: | ||
| id-token: write | ||
|
|
||
| jobs: | ||
| build: | ||
|
|
||
| runs-on: ubuntu-latest | ||
|
|
||
| steps: | ||
| - name: Configure AWS Credentials | ||
| uses: aws-actions/configure-aws-credentials@v1 | ||
| with: | ||
| role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} | ||
| role-duration-seconds: 7200 | ||
| aws-region: us-west-2 | ||
| - uses: actions/checkout@v2 | ||
| with: | ||
| fetch-depth: '0' | ||
| - name: Setup .NET Core 6.0 | ||
| uses: actions/setup-dotnet@v1 | ||
| with: | ||
| dotnet-version: 6.0.x | ||
| - name: Restore dependencies | ||
| run: dotnet restore | ||
| - name: Build | ||
| run: dotnet build --no-restore | ||
| - name: Run Client Generator | ||
| run: | | ||
| cd ./src/AWS.Deploy.DocGenerator | ||
| dotnet run --project ./AWS.Deploy.DocGenerator.csproj | ||
| - name: Check For Git Untracked Changes | ||
| id: gitcheck | ||
| shell: pwsh | ||
| run: | | ||
| $newFiles=$(git ls-files --others --exclude-standard | wc -l) | ||
| $modifiedFiles=$(git diff --name-only | wc -l) | ||
| "newFiles=$newFiles" >> $env:GITHUB_OUTPUT | ||
| "modifiedFiles=$modifiedFiles" >> $env:GITHUB_OUTPUT | ||
| - name: Fail If New Files Detected | ||
| if: steps.gitcheck.outputs.newFiles != 0 | ||
| run: | | ||
| echo "New files have been generated after running 'AWS.Deploy.DocGenerator'. Make sure to add the new files to your working branch." | ||
| exit 1 | ||
| - name: Fail If Modified Files Detected | ||
| if: steps.gitcheck.outputs.modifiedFiles != 0 | ||
| run: | | ||
| echo "Updated files have been generated after running 'AWS.Deploy.DocGenerator'. Make sure to commit the updated files to your working branch." | ||
| exit 1 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,14 +6,46 @@ on: | |
|
|
||
| # Allow the workflow to be triggered also manually. | ||
| workflow_dispatch: | ||
|
|
||
| permissions: | ||
| id-token: write | ||
| contents: write | ||
|
|
||
| jobs: | ||
| deploy: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Configure AWS Credentials | ||
| uses: aws-actions/configure-aws-credentials@v1 | ||
| with: | ||
| role-to-assume: ${{ secrets.CI_AWS_ROLE_ARN }} | ||
| aws-region: us-west-2 | ||
| - uses: actions/checkout@v2 | ||
| with: | ||
| fetch-depth: '0' | ||
| - uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: 3.x | ||
| - name: Setup .NET Core 6.0 | ||
| uses: actions/setup-dotnet@v1 | ||
| with: | ||
| dotnet-version: 6.0.x | ||
| - run: pip install mkdocs-material==8.2.9 | ||
| - run: pip install mkdocs-awesome-pages-plugin==2.8.0 | ||
| - name: Restore dependencies | ||
| run: dotnet restore | ||
| - name: Build | ||
| run: dotnet build --no-restore | ||
| - name: Run Client Generator | ||
| run: | | ||
| cd ./src/AWS.Deploy.DocGenerator | ||
| dotnet run --project ./AWS.Deploy.DocGenerator.csproj | ||
| - name: Commit and Push next version | ||
| id: commit-push | ||
| run: | | ||
| git config --global user.email "[email protected]" | ||
| git config --global user.name "aws-sdk-dotnet-automation" | ||
| git add site/ | ||
| git commit -m "Update documentation generated by AWS.Deploy.DocGenerator" | ||
| git push | ||
| - run: mkdocs gh-deploy --force | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| # Creating a deployment settings file | ||
|
|
||
| ### What is a deployment settings file | ||
|
|
||
| A deployment settings file allows you to define the deployment settings of your application in a _JSON_ format. This JSON file can be version controlled and plugged into your CI/CD system for future deployments. | ||
|
|
||
| Deployment settings files could be used as a way to automate your deployments or use them in a [CI/CD setting](./cicd.md) where you would define all the settings that you need to apply for your deployment and then use the `--apply` flag on the CLI to link to the deployment setting file. | ||
|
|
||
| By doing this, the AWS .NET deployment tool reads all the settings you have defined and applies them to the deployment. You will need to do a final confirmation to initiate the deployment in the CLI. However, you can bypass the confirmation by making the deployment a silent one. This can be done by adding the `--silent` flag which will turn off any prompts. | ||
|
|
||
| The deployment settings file has the following structure: | ||
|
|
||
| ```json | ||
| { | ||
| "AWSProfile": <AWS_PROFILE>, | ||
| "AWSRegion": <AWS_REGION>, | ||
| "ApplicationName": <APPLICATION_NAME>, | ||
| "RecipeId": <RECIPE_ID>, | ||
| "Settings": <JSON_BLOB> | ||
| } | ||
| ``` | ||
|
|
||
| * _**AWSProfile**_: The name of the AWS profile that will be used during deployment. | ||
|
|
||
| * _**AWSRegion**_: The name of the AWS region where the deployed application is hosted. | ||
|
|
||
| * _**ApplicationName**_: The name that is used to identify your cloud application within AWS. If the application is deployed via AWS CDK, then this name points to the CloudFormation stack. | ||
|
|
||
| * _**RecipeId**_: The recipe identifier that will be used to deploy your application to AWS. | ||
|
|
||
| * _**Settings**_: This is a JSON blob that stores the values of all available settings that can be tweaked to adjust the deployment configuration. This is represented as a _JSON_ object that contains the deployment setting IDs and values as a key/pair configuration. | ||
|
|
||
| *Note:* _**AWSProfile, AWSRegion and ApplicationName**_ are optional and can be overriden by using the appropriate command line switches. This enables users to craft a *deployment settings file* that could be used for multiple AWS profiles and regions. | ||
|
|
||
| An example of overriding _**AWSProfile, AWSRegion and ApplicationName**_ in the CLI: | ||
| ``` | ||
| dotnet aws deploy --application-name WebApp1 --profile default --region us-west-2 | ||
| ``` | ||
|
|
||
| Each recipe has its own set of settings that can be configured. The following pages in this section list the settings for each recipe that can be used to fill in the `Settings` section of the file. | ||
|
|
||
| ### Example of a deployment settings file | ||
|
|
||
| An example of what a deployment settings file would look like: | ||
| ```json | ||
| { | ||
| "AWSProfile": "default", | ||
| "AWSRegion": "us-west-2", | ||
| "ApplicationName": "WebApp1", | ||
| "RecipeId": "AspNetAppEcsFargate", | ||
| "Settings": { | ||
| "ECSCluster": { | ||
| "CreateNew": true, | ||
| "NewClusterName": "WebApp1-Cluster" | ||
| }, | ||
| "ECSServiceName": "WebApp1-service", | ||
| "DesiredCount": 3, | ||
| "ApplicationIAMRole": { | ||
| "CreateNew": true | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| Settings that contain child settings under them are represented as another _JSON_ object similar to the example provided above. | ||
|
|
||
| ### How to create a deployment settings file | ||
|
|
||
| 1. Create a new `JSON` file. | ||
| 2. Add the 3 properties _**AWSProfile, AWSRegion and ApplicationName**_. These are generic and not tied to a specific *Recipe* file. | ||
| > _**AWSProfile**_: The name of the AWS profile that will be used during deployment. | ||
| > _**AWSRegion**_: The name of the AWS region where the deployed application is hosted. | ||
| > _**ApplicationName**_: The name that is used to identify your cloud application within AWS. If the application is deployed via AWS CDK, then this name points to the CloudFormation stack. | ||
| 3. Pick a *Recipe* from the **Deployment Recipes** section in the navigation to use for your deployment. A Recipe defines the .NET application type and the AWS compute to deploy it to. For example [ASP.NET Core App to Amazon ECS using AWS Fargate](./recipes/ASP.NET%20Core%20App%20to%20Amazon%20ECS%20using%20AWS%20Fargate.md). | ||
| 4. Add a _**Settings**_ object to define deployment settings. | ||
| 5. To set the `ECS Service Name`, get the ID from the *Recipe* which is `ECSServiceName`. The value needs to be the same type as the `Type` of setting. `ECS Service Name` has a type `String`, so give it a value `WebApp1-service`. | ||
| 6. To set `ECS Cluster`, the ID is `ECSCluster` and the setting has a type `Object`. The value of `Object` types is another JSON blob representing the setting ID and value of the `Object's children settings`. To set the 2 children settings `Create New ECS Cluster` and `New Cluster Name`, use the IDs `CreateNew` and `NewClusterName` respectively. `Create New ECS Cluster` has a type `Bool` so we can set `true` or `false`, and `New Cluster Name` is a `String`. The deployment settings file will look like this: | ||
| ```json | ||
| { | ||
| "AWSProfile": "default", | ||
| "AWSRegion": "us-west-2", | ||
| "ApplicationName": "WebApp1", | ||
| "RecipeId": "AspNetAppEcsFargate", | ||
| "Settings": { | ||
| "ECSCluster": { | ||
| "CreateNew": true, | ||
| "NewClusterName": "WebApp1-Cluster" | ||
| }, | ||
| "ECSServiceName": "WebApp1-service" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Keep adding more settings by using the *Recipe* you selected as reference and be mindful of the type of setting you are setting. |
Oops, something went wrong.