Contributing

Looking to contribute to the Azure Proactive Resiliency Library (APRL), well you have made it to the right place/page 👍

Follow the below instructions, especially the pre-requisites, to get started contributing to the library.

Writing a recommendation

APRL recommendations are intended to enable and accelerate the delivery of Well Architected Reliability Assessments. The purpose of APRL is not to replace existing Azure public documentation and guidance on best practices.

Each recommendation should be actionable for the customer. The customer should be able to place the recommendation in their backlog and the engineer that picks it up should have complete clarity on the change that needs to be made and the specific resources that the change should be made to.

Each recommendation should include a descriptive title, a short guidance section that contains additional detail on the recommendation, links to public documentation that provide additional information related to the recommendation, and a query to identify resources that are not compliant with the recommendation. The title and guidance sections alone should provide sufficient information for a CSA to evaluate a resource.

Recommendations should not require the CSA to spend a lot of time on background reading, they should not be open to interpretation, and they should not be vague. Remember that the CSA delivering the WARA is reviewing a large number of Azure resources in a limited amount of time and is not an expert in every Azure service.

Examples

• Good recommendation: Use a /24 subnet for the service
• Bad recommendation: Size your subnet appropriately

Not all best practices make good APRL recommendations. If the best practice relates to a particular service configuration and can be checked with an ARG query, it probably makes for a good APRL recommendation. If the best practice is more aligned to general architectural concepts that are true for many service or workload types, we very likely already have a recommendation in the APRL WAF section that addresses the topic. If not, consider adding a WAF recommendation to APRL. If neither is the case, APRL may not be the best location for this content.

Context/Background

Before jumping into the pre-requisites and specific section contribution guidance, please familiarize yourself with this context/background on how this library is built to help you contribute going forward.

This site is built using Hugo, a static site generator, that’s source code is stored in the APRL GitHub repo (link in header of this site too) and is hosted on GitHub Pages, via the repo.

The reason for the combination of Hugo & GitHub pages is to allow us to present an easy to navigate and consume library, rather than using a native GitHub repo, which is not easy to consume when there are lots of pages and folders. Also Hugo generates the site in such a way that it is also friendly for mobile consumers.

But I don’t have any skills in Hugo?

That’s okay and you really don’t need them. Hugo just needs you to be able to author markdown (.md) files and it does the rest when it generates the site 👍

Pre-Requisites

Read and follow the below sections to leave you in a “ready state” to contribute to APRL.

A “ready state” means you have a forked copy of the Azure/Azure-Proactive-Resiliency-Library repo cloned to your local machine and open in VS Code.

Run and Access a Local Copy of APRL During Development

When in VS Code you should be able to open a terminal and run the below commands to access a copy of the APRL website from a local web server, provided by Hugo, using the following address http://localhost:1313/Azure-Proactive-Resiliency-Library/:

cd docs
hugo server -D

Software/Applications

To contribute to this project/repo/library you will need the following installed:

• Git
• Visual Studio Code (VS Code)
  • Extensions:
    • editorconfig.editorconfig, streetsidesoftware.code-spell-checker, ms-vsliveshare.vsliveshare, medo64.render-crlf, vscode-icons-team.vscode-icons
    • VS Code will recommend automatically to install these when you open this repo, or a fork of it, in VS Code.
• Hugo Extended

winget Install Commands

To install winget follow the install instructions here.

winget install --id 'Git.Git'
winget install --id 'Microsoft.VisualStudioCode'
winget install --id 'Hugo.Hugo.Extended'

Other requirements

• A GitHub profile/account
• A fork of the Azure/Azure-Proactive-Resiliency-Library repo into your GitHub org/account and cloned locally to your machine
  • Instructions on forking a repo and then cloning it can be found here

Useful Resources

Below are links to a number of useful resources to have when contributing to APRL:

• Ace Documentation Theme (that we use) - Docs
  • Shortcodes - e.g. Code
• Ace Documentation Theme (that we use) - Repo
  • The Example Site, which is the first link above, source code
• Hugo Quick Start
• Hugo Docs
• Markdown Cheat Sheet

Steps to do before contributing anything (after pre-requisites)

Run the following commands in your terminal of choice from the directory where you fork of the repo is located:

git checkout main
git pull
git fetch -p
git fetch -p upstream
git pull upstream main
git push

Doing this will ensure you have the latest changes from the upstream repo and you are ready to now create a new branch from main by running the below commands:

git checkout main
git checkout -b <YOUR-DESIRED-BRANCH-NAME-HERE>

Creating a Service’s Recommendation Page

The is a common task that is likely to be done is adding a new service to which you want to provide recommendations and supporting queries etc. for example Virtual Machines.

For this task we use Hugo’s archetype features which enables you to create a whole directory for a new service with a lot of templated content ready for you to change and use. This can be called by using the following command hugo new --kind service-bundle services/<category>/<service-name

You can see source code of the directory archetype called service-bundle here in the repo.

Steps to follow:

1. In your terminal of choice run the following:
   Copy

   cd docs/
   hugo new --kind service-bundle services/compute/virtual-machines
   

2. You will now see a new folder in content/services/compute called virtual-machines
   Copy

   ├───content
   │   ├───contributing
   │   └───services
   │       ├───ai-ml
   │       ├───compute
   │       │   └───virtual-machines
   │       │       └───code
   │       │           ├───cm-1
   │       │           └───cm-2
   

3. Inside the virtual-machines folder you will see the following files pre-staged
   Copy

   │       │   └───virtual-machines
   │       │       │   _index.md
   │       │       │
   │       │       └───code
   │       │           ├───cm-1
   │       │           │       cm-1.kql
   │       │           │
   │       │           │
   │       │           └───cm-2
   │       │                   cm-2.kql
   

4. Open _index.md in VS Code and make relevant changes
   • You can copy the recommendations labelled CM-1 or CM-2 multiple times to create more recommendations
5. Update Azure Resource Graph queries in the code folder within virtual-machines
   • You will see there is a folder, e.g. cm-1, cm-2, per recommendation to help with file structure organization
6. Ensure you use the correct Azure resource abbreviations provided within our Cloud Adoption Framework (CAF) documentation here. For example, use vm for Virtual Machines.
7. Save, commit and push your changes to your branch and repo
8. Create a create a Pull Request into the main branch of the upstream repo
9. Get it merged

Automation Standards for Recommendations

When creating recommendations for a service, please follow the below standards:

Recommendation categories

Each recommendation should have one and only one associated category from this list below.

Azure Resource Graph (ARG) Queries

1. All ARG queries should have two comments at the top of the query, one comment stating Azure Resource Graph Query and another comment providing a description of the query results returned. For example:

   // Azure Resource Graph Query
   // Provides a list of Azure Container Registry resources that do not have soft delete enabled
   

2. If the ARG query is under development, the query should have a single line stating: // under-development

3. If a recommendation query cannot be returned due to limitations with the data provided within ARG, the query should have a single line stating: // cannot-be-validated-with-arg

4. Queries should only return resources that do not adhere to the APRL recommendation. For example, if the recommendation is to enable soft delete for Azure Container Registries, the associated query should only return Azure Container Registry resources that do not have soft delete enabled.

5. If a ARG query folder has a file with a file type suffixed with .fix, this means that the current query does not work as anticipated and to consider using this as a starting point for fixing the query. Once you have validated that the query is working as anticipated, please remove the file with the .fix suffix.

6. ARG query columns name returned should only include the following:

Updating a Service’s Recommendation Page

This is likely the most common task that will be performed.

All you need to do is just make edits directly to the existing markdown (.md) files, save your changes, commit, stage and push them to your branch and repo. Then create a Pull Request into the main branch of the upstream repo and you are done 👍

Creating a Service Category

For this task we use Hugo’s archetype features which enables you to create a whole directory for a new service with a lot of templated content ready for you to change and use. This can be called by using the following command hugo new --kind category-bundle services/<category>

You can see source code of the directory archetype called category-bundle here in the repo.

Steps to follow:

1. In your terminal of choice run the following:
   Copy

   cd docs/
   hugo new --kind category-bundle services/aaa
   

2. You will now see a new folder in content/services called aaa
   Copy

   ├───content
   │   │   _index.md
   │   │
   │   ├───contributing
   │   │       _index.md
   │   │
   │   └───services
   │       │   _index.md
   │       │
   │       ├───aaa
   │       │       _index.md
   

3. Inside the aaa folder you will see the following file _index.md pre-staged
   Copy

   ├───aaa
   │       │       _index.md
   

4. Open _index.md in VS Code and make relevant changes
5. Save, commit and push your changes to your branch and repo
6. Create a create a Pull Request into the main branch of the upstream repo
7. Get it merged

Top Tips

1. Sometimes the local version of the website may show some inconsistencies that don’t reflect the content you have created.
   • If this happens, simply kill the Hugo local web server by pressing CTRL+C and then restart the Hugo web server by running hugo server -D from the docs/ directory