Merge branch 'main' into afd-bug-fixes-march24

CODEOWNERS

@@ -1,2 +1,9 @@
-# The aprl-admins team is responsible for reviewing and merging PRs
+# The aprl-admins team is responsible for reviewing and merging all PRs.
 * @Azure/aprl-admins
+
+# The aprl-networking team is partially responsible for all networking-related PRs.
+/docs/content/services/networking/ @Azure/aprl-admins @Azure/aprl-networking
+
+# The aprl-hpc team is partially responsible for all HPC-related PRs.
+/docs/content/services/specialized-workloads/azure-hpc/ @Azure/aprl-admins @Azure/aprl-hpc
+/docs/content/services/batch/ @Azure/aprl-admins @Azure/aprl-hpc

README.md

@@ -1,5 +1,14 @@
 # Azure Proactive Resiliency Library (APRL)
 
+> [!CAUTION]
+> The APRL repository is scheduled to be migrated to a new repository the week of April 8th.
+> The current APRL repository will be placed in **READ-ONLY** mode from April 8th to April 12th.
+> No new pull requests will be accepted after April 5th.
+>
+> **New Repository:** [https://github.com/Azure/Azure-Proactive-Resiliency-Library-v2](https://github.com/Azure/Azure-Proactive-Resiliency-Library-v2)
+>
+> **[aka.ms/aprl](https://aka.ms/aprl)** will redirect to the new website starting April 15th
+
 [![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/Azure/Azure-Proactive-Resiliency-Library.svg)](http://isitmaintained.com/project/Azure/Azure-Proactive-Resiliency-Library "Average time to resolve an issue")
 [![Percentage of issues still open](http://isitmaintained.com/badge/open/Azure/Azure-Proactive-Resiliency-Library.svg)](http://isitmaintained.com/project/Azure/Azure-Proactive-Resiliency-Library "Percentage of issues still open")
 
@@ -11,13 +20,13 @@ Welcome to the home of the Azure Proactive Resiliency Library (APRL).
 
 This library is built with the intention of being a staging area for guidance and recommendations that can be used by customers, partners and the field in Well-Architected Framework reliability engagements/assessments; with the intent of the guidance and recommendations being promoted, once tested and validated with customers and partners, into the official [Well-Architected Framework documentation](https://aka.ms/waf).
 
-The library also contains supporting [Azure Resource Graph (ARG)](https://learn.microsoft.com/azure/governance/resource-graph/overview) queries, and sometimes [Azure PowerShell](https://learn.microsoft.com/powershell/azure/what-is-azure-powershell) or [Azure CLI](https://learn.microsoft.com/cli/azure/what-is-azure-cli) scripts, that can help customers, partners and the field identify resources that may or may not be compliant with the guidance and recommendations. The intent for these queries, in the long-term, is to make them part of the [Azure Advisor](https://learn.microsoft.com/azure/advisor/advisor-overview) service.
+The library also contains supporting [Azure Resource Graph (ARG)](https://learn.microsoft.com/azure/governance/resource-graph/overview) queries that can help customers, partners and the field identify resources that may or may not be compliant with the guidance and recommendations. The intent for these queries, in the long-term, is to make them part of the [Azure Advisor](https://learn.microsoft.com/azure/advisor/advisor-overview) service.
 
 ## Contributing
 
 > The contribution guide can be found on the GitHub pages site here: [aka.ms/aprl/contribute](https://aka.ms/aprl/contribute)
 
-This project only currently accepts Pull Requests from Microsoft FTEs as of today. However, anyone is welcomed to create issues/features requests on the repo for the team to triage and action.  Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.opensource.microsoft.com](https://cla.opensource.microsoft.com).
+This project only currently accepts Pull Requests from Microsoft FTEs as of today. However, anyone is welcomed to create issues/features requests on the repo for the team to triage and action. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.opensource.microsoft.com](https://cla.opensource.microsoft.com).
 
 When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
 

docs/archetypes/service-bundle/_index.md

@@ -12,10 +12,10 @@ The presented resiliency recommendations in this guidance include {{ replace .Na
 ## Summary of Recommendations
 
 {{< table style="table-striped" >}}
-| Recommendation                                    |  Category                                                               |  Impact         |  State            | ARG Query Available |
-| :------------------------------------------------ | :---------------------------------------------------------------------: | :------:        | :------:          | :-----------------: |
-| [CM-1 - CHANGE ME title](#cm-1---change-me-title) | Compatibility/Compliance/Disaster Recovery/High Availability/Management | High/Medium/Low | Preview/Verified  |         Yes         |
-| [CM-2 - CHANGE ME title](#cm-2---change-me-title) | Monitoring/Networking/Performance/Scalability/Security/Storage          | High/Medium/Low | Preview/Verified  |         No          |
+| Recommendation                                    |                                Category                                 |     Impact      |      State       | ARG Query Available |
+|:--------------------------------------------------|:-----------------------------------------------------------------------:|:---------------:|:----------------:|:-------------------:|
+| [CM-1 - CHANGE ME title](#cm-1---change-me-title) | Compatibility/Compliance/Disaster Recovery/High Availability/Management | High/Medium/Low | Preview/Verified |         Yes         |
+| [CM-2 - CHANGE ME title](#cm-2---change-me-title) |     Monitoring/Networking/Performance/Scalability/Security/Storage      | High/Medium/Low | Preview/Verified |         No          |
 {{< /table >}}
 
 {{< alert style="info" >}}
@@ -41,7 +41,7 @@ FILL ME IN...
 - [CHANGE ME LINK](https://aka.ms)
 - [CHANGE ME LINK](https://aka.ms)
 
-**Resource Graph Query/Scripts**
+**Resource Graph Query**
 
 {{< collapse title="Show/Hide Query/Script" >}}
 
@@ -66,7 +66,7 @@ FILL ME IN...
 - [CHANGE ME LINK](https://aka.ms)
 - [CHANGE ME LINK](https://aka.ms)
 
-**Resource Graph Query/Scripts**
+**Resource Graph Query**
 
 {{< collapse title="Show/Hide Query/Script" >}}
 

docs/content/Privacy/_index.md

@@ -0,0 +1,7 @@
++++
+title = "Privacy"
+description = "This Privacy Policy outlines how we collect and use your data when you interact with this website."
+weight = 4
++++
+
+We partner with Microsoft Clarity to capture how you use and interact with our website through behavioral metrics, heatmaps, and session replay to improve the content and usage of the website. Website usage data is captured using first and third-party cookies and other tracking technologies and is used for site optimization. For more information about how Microsoft collects and uses your data, visit the Microsoft Privacy Statement.

docs/content/_index.md

@@ -4,18 +4,32 @@ description = "Welcome to the home of the Azure Proactive Resiliency Library (AP
 weight = 1
 +++
 
+{{< alert style="danger" >}}
+
+## WEBSITE MAINTENANCE NOTICE
+
+The APRL repository is scheduled to be migrated to a new repository the week of April 8th.
+The current APRL repository will be placed in READ-ONLY mode from April 8th to April 12th.
+No new pull requests will be accepted after April 5th.
+
+### New Repository: [https://github.com/Azure/Azure-Proactive-Resiliency-Library-v2](https://github.com/Azure/Azure-Proactive-Resiliency-Library-v2)
+
+### [aka.ms/aprl](https://aka.ms/aprl) will redirect to the new website starting April 15th
+
+{{< /alert >}}
+
 Welcome to the home of the Azure Proactive Resiliency Library (APRL).
 
 <img src="/Azure-Proactive-Resiliency-Library/media/img/aprl-white.png" width=40%>
 <br><br>
 
 This library is built with the intention of being a staging area for guidance and recommendations that can be used by customers, partners and the field in Well-Architected Framework reliability engagements/assessments; with the intent of the guidance and recommendations being promoted, once tested and validated with customers and partners, into the official [Well-Architected Framework documentation](https://aka.ms/waf).
 
-The library also contains supporting [Azure Resource Graph (ARG)](https://learn.microsoft.com/azure/governance/resource-graph/overview) queries, and sometimes [Azure PowerShell](https://learn.microsoft.com/powershell/azure/what-is-azure-powershell) or [Azure CLI](https://learn.microsoft.com/cli/azure/what-is-azure-cli) scripts, that can help customers, partners and the field identify resources that may or may not be compliant with the guidance and recommendations. The intent for these queries, in the long-term, is to make them part of the [Azure Advisor](https://learn.microsoft.com/azure/advisor/advisor-overview) service.
+The library also contains supporting [Azure Resource Graph (ARG)](https://learn.microsoft.com/azure/governance/resource-graph/overview) queries that can help customers, partners and the field identify resources that may or may not be compliant with the guidance and recommendations. The intent for these queries, in the long-term, is to make them part of the [Azure Advisor](https://learn.microsoft.com/azure/advisor/advisor-overview) service.
 
 ## Get Started
 
-To get started head over to the [Azure Services section]({{< ref "services/_index.md">}}) and then navigate via the appropriate category to find guidance, recommendations alongside supporting Azure Resource Graph queries, Azure PowerShell or Azure CLI scripts to help you discover compliant/non-compliant resources in your environment.
+To get started head over to the [Azure Services section]({{< ref "services/_index.md">}}) and then navigate via the appropriate category to find guidance, recommendations alongside supporting Azure Resource Graph queries to help you discover compliant/non-compliant resources in your environment.
 
 {{< alert style="info" >}}
 
@@ -29,10 +43,10 @@ In APRL you will see a number of terms used, like Preview & Verified. The below
 
 {{< table style="table-striped" >}}
 
-| Term | Definition |
-| ---- | ---------- |
-| Preview Guidance | Guidance that Microsoft FTEs have created based on customer engagements and is in the process of reviewing with the relevant Azure Product Group Engineering Service owners to ensure the content is valid and accurate |
-| Verified Guidance | Guidance has been signed off by Azure Product Group Engineering Service owners following their review |
+| Term              | Definition                                                                                                                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Preview Guidance  | Guidance that Microsoft FTEs have created based on customer engagements and is in the process of reviewing with the relevant Azure Product Group Engineering Service owners to ensure the content is valid and accurate |
+| Verified Guidance | Guidance has been signed off by Azure Product Group Engineering Service owners following their review                                                                                                                   |
 
 {{< /table >}}
 

docs/content/contributing/_index.md

@@ -9,6 +9,23 @@ Looking to contribute to the Azure Proactive Resiliency Library (APRL), well you
 
 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.
@@ -134,18 +151,15 @@ hugo new --kind service-bundle services/compute/virtual-machines
 │       │       │
 │       │       └───code
 │       │           ├───cm-1
-│       │           │       cm-1.azcli
 │       │           │       cm-1.kql
-│       │           │       cm-1.ps1
+│       │           │
 │       │           │
 │       │           └───cm-2
-│       │                   cm-2.azcli
 │       │                   cm-2.kql
-│       │                   cm-2.ps1
 {{< /code >}}
 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, PowerShell, AZCLI scripts in the `code` folder within `virtual-machines`
+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](https://docs.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations). For example, use `vm` for Virtual Machines.
 7. Save, commit and push your changes to your branch and repo
@@ -160,6 +174,23 @@ Don't forget you can see your changes live by running a local copy of the APRL w
 
 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.
+
+  | Recommendation Category | Category Description |
+  |:---:|:---:|
+  | Application Resilience | Ensures software applications remain functional under failures or disruptions. Utilizes fault-tolerance, stateless architecture, and microservices to maintain application health and reduce downtime. |
+  | Automation | Uses automated systems or scripts for routine tasks, backups, and recovery. Minimizes human intervention, thereby reducing errors and speeding up recovery processes. |
+  | Availability | Focuses on ensuring services are accessible and operational. Combines basic mechanisms like backups with advanced techniques like clustering and data replication to achieve near-zero downtime. (Includes High Availability) |
+  | Access & Security | Encompasses identity management, authentication, and security measures for safeguarding systems. Centralizes access control and employs robust security mechanisms like encryption and firewalls. (Includes Identity) |
+  | Governance | Involves policies, procedures, and oversight for IT resource utilization. Ensures adherence to legal, regulatory, and compatibility requirements, while guiding overall system management. (Includes Compliance and Compatibility) |
+  | Disaster Recovery | Involves strategies and technologies to restore systems and data after catastrophic failures. Utilizes off-site backups, recovery sites, and detailed procedures for quick recovery after a disaster. |
+  | System Efficiency | Maintains acceptable service levels under varying conditions. Employs techniques like resource allocation, auto-scaling, and caching to handle changes in load and maintain smooth operation. (Includes Performance and Scalability) |
+  | Monitoring | Involves constant surveillance of system health, performance, and security. Utilizes real-time alerts and analytics to identify and resolve issues quickly, aiding in faster response times. |
+  | Networking | Aims to ensure uninterrupted network service through techniques like failover routing, load balancing, and redundancy. Focuses on maintaining the integrity and availability of network connections. |
+  | Storage | Focuses on the integrity and availability of data storage systems. Employs techniques like RAID, data replication, and backups to safeguard against data loss or corruption. |
+
 ### 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: