Create Recommendations

This section provides guidance on how to create new recommendations. The following requirements should be followed:

To contribute a new recommendation for an Azure resource, follow these steps:

1. Locate the recommendations.yaml file within the directory corresponding to the Azure resource, Azure WAF design principle, or specialized workload you want to add a recommendation for.

2. Open the recommendations.yaml file and copy the following YAML template:

   - description: Your Recommendation Title Here (less than 100 characters)
     aprlGuid: Generate a Unique GUID using https://guidgenerator.com/online-guid-generator.aspx
     recommendationTypeId: null
     recommendationControl: High Availability/Business Continuity/Disaster Recovery/Scalability/Monitoring and Alerting/Service Upgrade and Retirement/Other Best Practices/Personalized/Governance
     recommendationImpact: Low/Medium/High
     recommendationResourceType: Friendly name to identity resource type
     recommendationMetadataState: Active
     longDescription: |
       Your Long Description Here
       (less than 300 characters)    
     potentialBenefits: Potential Benefits of Implementing the Recommendation (less than 60 characters)
     pgVerified: false
     automationAvailable: false
     tags: null
     learnMoreLink:
       - name: Learn More
         url: "Link URL"
   

3. Customize the placeholders with your recommendation’s specific details. See the Recommendation Structure section for more information on each key-value pair.

4. Once you’ve added your recommendation, save the file.

5. To test your changes, spin up your local hugo server by running the following command within your terminal:

   hugo server --disableFastRender
   

6. Submit your changes by creating a pull request in the repository.

7. That’s all! Your suggestion will be reviewed for potential inclusion in the Azure Proactive Resiliency Library.

8. Questions or need assistance? Don’t hesitate to create a GitHub Issue for support.

If you encounter inconsistencies on the local version of the website that do not reflect your content updates, or errors unrelated to your changes, follow these steps:

1. Press CTRL + C to terminate the Hugo local web server.
2. Restart the Hugo web server by running hugo server --disableFastRender from the root of the repository.

The YAML structure for adding new recommendations consists of several key-value pairs, each providing specific information about the recommendation. Below is a table that describes each key-value pair:

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

When writing a recommendation, consider the following:

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 resource.

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

Not all best practices make good APRL recommendations. If the best practice relates to a particular resource 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 Azure resources 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.