Merge pull request #71 from Brunoga-MS/main

Update to new release guidance

docs/content/contributing/_index.md

@@ -168,7 +168,7 @@ Below are links to a number of useful resources to have when contributing to AMB
 
 ## 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:
+Run the following commands in your terminal of choice from the directory where your fork of the repo is located:
 
 ```text
 git checkout main

docs/content/patterns/alz/FAQ.md

@@ -5,61 +5,61 @@ weight: 80
 ---
 
 > ## Do I need to have Azure Landing zones deployed for this to work?
-> 
+>
 > No but you will need to be using Azure Management groups and for now our focus is on the resources frequently deployed as part of Azure Landing Zone deployments.
 
 > ## Do I need to deploy to each region that I want to monitor?
-> 
+>
 > No, deploying to multiple regions is not necessary. The definitions and assignments are scoped to a management group and are not region specific.
 
 > ## Do I need to use the thresholds defined as default values in the metric rule alerts?
-> 
+>
 > It's provided as a starting point, we've based the initial thresholds on what we've seen and what Microsoft's documentation recommends. You will need to adjust the thresholds at some point.
 > You will need to observe and if the alert is too chatty, adjust the threshold up; if it's not alerting when there's a problem, adjust the threshold down a bit, (or vice-versa depending on what metric or log error is being used as a monitoring source). Once you have decided upon an appropriate value, if you feel it's fit for more general consumption we would love to hear about it.
 
-> ## Why are the availability alert thresholds lower than 100% in this solution when the product group documention recommends 100%?
-> 
+> ## Why are the availability alert thresholds lower than 100% in this solution when the product group documentation recommends 100%?
+>
 > Setting a threshold of 100% can, on occasion, cause erroneous alerts that generate un-necessary noise. Lowering the threshold slightly below 100% addresses this issue while still providing an alert for a service's availability. If the default threshold isn't aggressive enough we encourage you to adjust it upwards and/or provide us feedback by filing an issue in our GitHub repo [GitHub Issue](https://github.com/Azure/azure-monitor-baseline-alerts/issues).
 
 > ## Do I need to use these metrics or can they be replaced with ones more suited to my environment?
-> 
+>
 > The metric rules we've created are based on recommendations from Microsoft documentation and field experience. How you're using Azure resources may also be different so tailor the alerts to suit your needs. The main goal of this project is to help you have a way to do Azure Monitor alerts at scale, create new rules with your own thresholds. We'd love to hear about your new rules too so feel free to share back.
 
 > ## Can I disable the alerts being deployed for a resource or subscription?
-> 
+>
 > Yes, please refer to the disabling monitoring documentation [Disabling Policies](../Disabling-Policies)
 
 > ## How much does it cost to run the ALZ Baseline solution?
-> 
+>
 > This depends on numerous factors including how many of the alert rules you choose to deploy into your environment, this combined with how many subscriptions inherit the baseline policies and resources deployed within each subscription that match the policy rules triggering an alert rule and action group deployment influence the cost.
-> 
+>
 > The solution is comprised of alert rules. Each alert rule costs ~0.1$/month<sup>1</sup>.
-> 
+>
 > - Alert rules are charged based on evaluations.
 > - Assuming the alert rule had data to evaluate all throughout the month, it'll cost ~0.1$<sup>1</sup>.
 > - If the rule was only evaluating during parts of the month (e.g. because the monitored resource was down and didn't send telemetry), the customer would pay for the prorated amount of time the rule was performing evaluations.
 > - Dynamic Threshold doubles the cost of the alert rule (~0.2$/month in total<sup>1</sup>)
 > - Our solution configures an email address as part of the Action groups deployment (one per subscription) and these are charged at ~2$/month per 1,000 emails<sup>1</sup>.
-> 
+>
 > **Whilst it is not anticipated that the solution will incur significant costs, it is recommended that you assess costs as part of a deployment to a non-production environment to make sure you are clear on the costs incurred for your deployment**
-> 
+>
 > For costings related to your deployment please visit [Pricing - Azure Monitor](https://azure.microsoft.com/en-us/pricing/details/monitor/) and work with your local Microsoft account team to define a rough order of magnitude (RoM) costings
-> 
+>
 > <sup>1</sup> Depending on the region you deploy to their may be a small difference in the associated cost, the costs provided here are based on prices captured as of April 2023
 
 > ## Can I access the Visio diagrams displayed in the documentation?
-> 
+>
 > Yes, the Visio diagrams are available in the [media](https://github.com/Azure/azure-monitor-baseline-alerts/tree/main/docs/content/patterns/alz/media) folder
 
 > ## Can I use AMBA without a GitHub repository
-> 
-> <p>Yes, as long as the ARM templates are publicly accesible. There are several linked templates in this solution which require to be publicly accessible. This is because when the top level ARM template is submitted to Azure Resource Manager, the linked templates are not automatically uploaded and therefore need to pulled in at deploy time from Azure. This means they must be referenced using a URL which can be accessed from Azure (e.g. via a public GitHub repository)</p>
+>
+> <p>Yes, as long as the ARM templates are publicly accessible. There are several linked templates in this solution which require to be publicly accessible. This is because when the top level ARM template is submitted to Azure Resource Manager, the linked templates are not automatically uploaded and therefore need to pulled in at deploy time from Azure. This means they must be referenced using a URL which can be accessed from Azure (e.g. via a public GitHub repository)</p>
 > <p>An alternative is to use Template specs. Instead of maintaining your linked templates at an accessible endpoint, you can create a template spec that packages the main template and its linked templates into a single entity you can deploy. The template spec is a resource in your Azure subscription. It makes it easy to securely share the template with users in your organization. You use Azure role-based access control (Azure RBAC) to grant access to the template spec. This feature is currently in preview.</p>
 >
 > References:
 > - [Template specs](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/linked-templates?tabs=azure-powershell#template-specs)
 > - [ARM Private deployment](https://github.com/Azure/ARM-private-deployment)
 
-> ## Can I deploy a local template by using -TemplateFile 
-> 
+> ## Can I deploy a local template by using -TemplateFile
+>
 > No, it´s not possible to use the -TemplateFile parameter as the ARM template uses linked templates. When referencing a linked template, the value of URI can't be a local file or a file that is only available on your local network. Azure Resource Manager must be able to access the template. This means they must be referenced using a URL which can be accessed from Azure (e.g. via a public GitHub repository)

docs/content/patterns/alz/Update-to-new-Release.md

@@ -0,0 +1,76 @@
+---
+title: Update to a new release
+geekdocCollapseSection: true
+weight: 71
+---
+
+## What is the latest release
+
+The list of enhancement, additions and fixed bugs contained in every release can be seen by navigating to corresponding page linked in the home page of the [azure-monitor-baseline-alerts](https://github.com/Azure/azure-monitor-baseline-alerts) repository.
+
+On the center-right side of the page there's a specific section indicating the latest release. Click on the release number to see the release content.
+
+![Releases](../media/Releases.png)
+
+</br>
+
+## Steps to update to the latest release
+
+This section will guide you through the necessary steps to update the current deployment with the latest enhancements contained in the latest release. Guidance on updating to releases containing breaking changes is not in scope and could eventually be described in a dedicated pages.
+
+{{< hint type=Important >}}
+This scenario only applies to AMBA deployments performed using GitHub. If not using GitHub, please refer to the [Can I use AMBA without a GitHub repository](../FAQ/#can-i-use-amba-without-a-github-repository) scenario documented in the *Frequently Asked Questions* making sure you update the template spec as required.
+{{< /hint >}}
+
+Depending if you used the official code from the official GitHub repository or from a forked one, not all the high-level steps below are required:
+
+1. Sync your fork *(only required if you forked the original repo)*
+2. Update your local copy of the repo *(only required if you cloned your fork on your local hard drive)*
+3. Deploy ***(always required)***
+
+### Sync your fork (only required if you forked the original repo)
+
+Synching a fork means that we're making sure any update made to the main branch in the official repo is replicated over yours. To sync your fork:
+
+1. Open the your GitHub repo page. If you don't remember the URL, consider that it normally looks like `https://github.com/***<YourGitHubId>***/azure-monitor-baseline-alerts`.
+2. You should be redirected to the default page which is **<> Code**. If not, click on the **<> Code** tab.
+
+    ![<> Code](../media/GitHub_Code.png)
+
+3. Click on the **Sync fork** and then select **Update branch**
+
+    ![Update branch](../media/UpdateBranch.png)
+
+4. Refresh the page and make sure to see the description reported in the picture below on the left of the **Contribute** and **Sync fork** buttons
+
+    ![Branch is up to date](../media/BranchUpToDate.png)
+
+</br>
+
+### Update your local copy (only required if you cloned your fork on your local hard drive)
+
+Within the code editor of your choice, make sure you pull the changes from your remote fork. Pulling changes from origin/main is necessary to ensure that the local branch is exactly the same as the remote. In this guide, we will use VSCode.
+
+1. Open VSCode and open the folder containing the cloned repo.
+2. In the bottom-left corner click on the pull icon
+
+    ![Pull icon](../media/PullIcon.png)
+
+3. Confirm or approve the operation if necessary
+
+    ![Confirm pull](../media/ConfirmPull.png)
+
+4. Ensure there are no issues with pulling changes and that the numbers close to the icon in the bottom-left corner are both **0** or not showing at all
+
+    ![Pull request completed](../media/PullCompleted.png)
+
+</br>
+
+### Deploy (always required)
+
+Once you reached this stage, you are ready to deploy the latest release. You can deploy using a method of your choice among the allowed one:
+
+- To deploy with GitHub Actions, please proceed with [Deploy with GitHub Actions](../deploy/Deploy-with-GitHub-Actions)
+- To deploy with Azure DevOps Pipelines, please proceed with [Deploy with Azure Pipelines](../deploy/Deploy-with-Azure-Pipelines)
+- To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../deploy/Deploy-with-Azure-CLI)
+- To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../deploy/Deploy-with-Azure-PowerShell)

docs/content/patterns/alz/Whats-New.md

@@ -4,4 +4,6 @@ geekdocCollapseSection: true
 weight: 10
 ---
 
-For information on what's new please refer to the [Releases page](https://github.com/Azure/azure-monitor-baseline-alerts/releases).
+For information on what's new please refer to the [Releases](https://github.com/Azure/azure-monitor-baseline-alerts/tags) page.
+
+To update your current deployment with the content from the latest release, please refer to the [Update to new release](../Update-to-new-Release) page.