From 1742167a56071b4d4f31638ffd5283301baceae5 Mon Sep 17 00:00:00 2001 From: Brunoga-MS Date: Thu, 1 Aug 2024 15:57:07 +0200 Subject: [PATCH 01/14] chore: Update ALZ pattern available features documentation --- .../{ => Getting-started}/Alerts-Details.md | 10 +- .../Monitoring-and-Alerting.md | 6 +- .../Policy-Initiatives.md | 32 ++- .../patterns/alz/Getting-started/_index.md | 6 + .../Bring-your-own-Managed-Identity.md | 18 +- .../Bring-your-own-Notifications.md | 18 +- .../{ => HowTo}/Cleaning-up-a-Deployment.md | 2 + .../alz/{ => HowTo}/Disabling-Policies.md | 98 ++++--- .../Log_Search_Alert_Table.md | 0 .../Metrics_Alert_Table.md | 0 .../patterns/alz/{ => HowTo}/Telemetry.md | 2 +- .../Temporarily-disabling-notifications.md | 20 +- .../Threshold-Override.md | 4 +- .../Update_from_release_2023-11-14.md | 4 +- .../Update_from_release_2024-03-01.md | 4 +- .../Update_from_release_2024-04-12.md | 14 +- .../Update_from_release_2024-06-05.md | 8 +- .../{ => HowTo}/UpdateToNewReleases/_index.md | 24 +- .../{Available_features => HowTo}/_index.md | 4 +- .../deploy/Customize-Policy-Assignment.md | 4 +- .../Deploy-only-Service-Health-Alerts.md | 256 +++++++++++------- .../deploy/Deploy-via-Azure-Portal-UI.md | 47 ++-- .../deploy/Deploy-with-Azure-CLI.md | 11 +- .../deploy/Deploy-with-Azure-Pipelines.md | 13 +- .../deploy/Deploy-with-Azure-PowerShell.md | 13 +- .../deploy/Deploy-with-GitHub-Actions.md | 17 +- ...troduction-to-deploying-the-ALZ-Pattern.md | 14 +- .../deploy/PowerShell-ExecutionPolicy.md | 0 .../{ => HowTo}/deploy/Remediate-Policies.md | 6 +- .../patterns/alz/{ => HowTo}/deploy/_index.md | 0 .../deploy/parameterConfiguration.md | 73 +++-- .../patterns/alz/Overview/ALZ-Pattern.md | 99 +++++++ .../patterns/alz/{ => Overview}/Whats-New.md | 20 +- docs/content/patterns/alz/Overview/_index.md | 6 + .../patterns/alz/{ => Resources}/FAQ.md | 4 +- .../alz/{ => Resources}/Known-Issues.md | 14 +- .../Moving-from-preview-to-GA.md | 12 +- .../alz/{ => Resources}/Versioning.md | 2 + docs/content/patterns/alz/Resources/_index.md | 5 + docs/content/patterns/alz/_index.md | 91 ------- .../patterns/alz/media/BYON_Params_3.png | Bin 82635 -> 81259 bytes .../alz/media/NotificationAssets_Params_2.png | Bin 136301 -> 129049 bytes 42 files changed, 589 insertions(+), 392 deletions(-) rename docs/content/patterns/alz/{ => Getting-started}/Alerts-Details.md (94%) rename docs/content/patterns/alz/{ => Getting-started}/Monitoring-and-Alerting.md (98%) rename docs/content/patterns/alz/{ => Getting-started}/Policy-Initiatives.md (93%) create mode 100644 docs/content/patterns/alz/Getting-started/_index.md rename docs/content/patterns/alz/{Available_features => HowTo}/Bring-your-own-Managed-Identity.md (75%) rename docs/content/patterns/alz/{Available_features => HowTo}/Bring-your-own-Notifications.md (60%) rename docs/content/patterns/alz/{ => HowTo}/Cleaning-up-a-Deployment.md (99%) rename docs/content/patterns/alz/{ => HowTo}/Disabling-Policies.md (67%) rename docs/content/patterns/alz/{Available_features => HowTo}/Log_Search_Alert_Table.md (100%) rename docs/content/patterns/alz/{Available_features => HowTo}/Metrics_Alert_Table.md (100%) rename docs/content/patterns/alz/{ => HowTo}/Telemetry.md (99%) rename docs/content/patterns/alz/{ => HowTo}/Temporarily-disabling-notifications.md (78%) rename docs/content/patterns/alz/{Available_features => HowTo}/Threshold-Override.md (98%) rename docs/content/patterns/alz/{ => HowTo}/UpdateToNewReleases/Update_from_release_2023-11-14.md (87%) rename docs/content/patterns/alz/{ => HowTo}/UpdateToNewReleases/Update_from_release_2024-03-01.md (78%) rename docs/content/patterns/alz/{ => HowTo}/UpdateToNewReleases/Update_from_release_2024-04-12.md (79%) rename docs/content/patterns/alz/{ => HowTo}/UpdateToNewReleases/Update_from_release_2024-06-05.md (69%) rename docs/content/patterns/alz/{ => HowTo}/UpdateToNewReleases/_index.md (78%) rename docs/content/patterns/alz/{Available_features => HowTo}/_index.md (84%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Customize-Policy-Assignment.md (89%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Deploy-only-Service-Health-Alerts.md (80%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Deploy-via-Azure-Portal-UI.md (88%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Deploy-with-Azure-CLI.md (81%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Deploy-with-Azure-Pipelines.md (61%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Deploy-with-Azure-PowerShell.md (82%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Deploy-with-GitHub-Actions.md (79%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Introduction-to-deploying-the-ALZ-Pattern.md (93%) rename docs/content/patterns/alz/{ => HowTo}/deploy/PowerShell-ExecutionPolicy.md (100%) rename docs/content/patterns/alz/{ => HowTo}/deploy/Remediate-Policies.md (93%) rename docs/content/patterns/alz/{ => HowTo}/deploy/_index.md (100%) rename docs/content/patterns/alz/{ => HowTo}/deploy/parameterConfiguration.md (89%) create mode 100644 docs/content/patterns/alz/Overview/ALZ-Pattern.md rename docs/content/patterns/alz/{ => Overview}/Whats-New.md (84%) create mode 100644 docs/content/patterns/alz/Overview/_index.md rename docs/content/patterns/alz/{ => Resources}/FAQ.md (99%) rename docs/content/patterns/alz/{ => Resources}/Known-Issues.md (89%) rename docs/content/patterns/alz/{ => Resources}/Moving-from-preview-to-GA.md (91%) rename docs/content/patterns/alz/{ => Resources}/Versioning.md (97%) create mode 100644 docs/content/patterns/alz/Resources/_index.md diff --git a/docs/content/patterns/alz/Alerts-Details.md b/docs/content/patterns/alz/Getting-started/Alerts-Details.md similarity index 94% rename from docs/content/patterns/alz/Alerts-Details.md rename to docs/content/patterns/alz/Getting-started/Alerts-Details.md index a154ecdaf..7f1c55737 100644 --- a/docs/content/patterns/alz/Alerts-Details.md +++ b/docs/content/patterns/alz/Getting-started/Alerts-Details.md @@ -6,20 +6,20 @@ weight: 30 Specific alerts for ALZ can be downloaded by clicking on the Download icon (highlighted in red below) in the top right corner of the AMBA documentation. - ![Alert-Details Download icon](../media/AlertDetailsDownloadReference.png) + ![Alert-Details Download icon](../../media/AlertDetailsDownloadReference.png) The best way to see which policy alert rules are part of the ALZ pattern it is best to go to the [Policy-Initiatives](../Policy-Initiatives) page. The resources, metric alerts and their settings provide you with a starting point to help you address the following monitoring questions: "What should we monitor in Azure?" and "What alert settings should we use?" While they are opinionated settings and they are meant to cover the most common Azure Landing Zone components, we encourage you to adjust these settings to suit your monitoring needs based on how you're using Azure. -If you have suggestions for other resources that should be included please open an Issue on this page providing the Azure resource provider and settings you'd like implemented, we can't promise to implement them all but we will look into it. Or if you'd like to contribute directly, follow the steps on how to contribute [here](../../../contributing/). +If you have suggestions for other resources that should be included please open an Issue on this page providing the Azure resource provider and settings you'd like implemented, we can't promise to implement them all but we will look into it. Or if you'd like to contribute directly, follow the steps in the [Contributor Guide](../../../../contributing). ## Azure Landing Zone Metric Alerts Settings The values shown for Aggregation, Operator, Threshold, WindowSize, Frequency and Severity have been derived from field experience and what customers have implemented themselves; Alerts are based on Microsoft public guidance where available (indicated by a 'Yes' in the Verified column), and on practical application experience where public guidance is not available (indicated by a 'No' in the Verified column). Links to Product Group guidance can be found in the References column and when no guidance is provided we've provided a link to the description of the Metric on learn.microsoft.com. -The Scope column details where we scoped the alerts as described in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern). +The Scope column details where we scoped the alerts as described in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern). Only a small number of the resources support metric alert rules scoped at the subscription level and the metric alerts would only apply to resources deployed within the same region. The Support for Multiple Resources column to show which resources support metric alerts being scoped at the subscription level. For a complete list of which resources support metrics alert rules scoped at the subscription level click [here](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-types#monitor-multiple-resources). @@ -29,7 +29,7 @@ We have tried to make it so that the table doesn't require a lot of side to side {{< alzMetricAlerts >}} -1 See "Why are the availability alert thresholds lower than 100% in this solution when the product group documention recommends 100%?" in the [FAQ](../FAQ) for more details. +1 See "Why are the availability alert thresholds lower than 100% in this solution when the product group documention recommends 100%?" in the [FAQ](../../Resources/FAQ) for more details. ## Azure Landing Zone Activity Log Alerts @@ -68,3 +68,5 @@ Security Alerts and Job Failure alerts are summarized in the "[Using Backup Cent | PolicyName | Component | Category | Scope | Support for Multiple Resources | Verified | References | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------|----------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Deploy RV Backup Health Monitoring Alerts](../../../services/RecoveryServices/vaults/Modify-RSV-BackupHealth-Alert.json) | Microsoft.RecoveryServices/Vaults | Microsoft.RecoveryServices/vaults/monitoringSettings.classicAlertSettings.alertsForCriticalOperations | Resource | No | Y | [Azure Monitor Alerts for Azure Backup](https://learn.microsoft.com/en-us/azure/backup/backup-azure-monitoring-built-in-monitor?tabs=recovery-services-vaults#azure-monitor-alerts-for-azure-backup)
[Move to Azure Monitor Alerts](https://learn.microsoft.com/en-us/azure/backup/move-to-azure-monitor-alerts) | + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Monitoring-and-Alerting.md b/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md similarity index 98% rename from docs/content/patterns/alz/Monitoring-and-Alerting.md rename to docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md index fda251781..51d6d02c5 100644 --- a/docs/content/patterns/alz/Monitoring-and-Alerting.md +++ b/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md @@ -26,7 +26,7 @@ Metric alerts are deployed with resources (in the same resource group) and platf As an example in the context of ALZ, see below for a graphic representation of the flow. -![ALZ alerting](../media/AMBA-focused-rg-alz-monitor-alert-flow.png) +![ALZ alerting](../../media/AMBA-focused-rg-alz-monitor-alert-flow.png) ### ALZ Approach @@ -124,4 +124,6 @@ Azure Backup now provides new and improved alerting capabilities via Azure Monit ### Notifications -While alerts are generated by default and can't be turned off for destructive operations, the notifications are in the control of the user, allowing you to clearly specify which set of email address (or other notification endpoints) you wish to route alerts to. Notifications are configured by an alert processing rule, which will be created by default when deploying AMBA. +While alerts are generated by default and can't be turned off for destructive operations, the notifications are in the control of the user, allowing you to clearly specify which set of email address (or other notification endpoints) you wish to route alerts to. Notifications are configured by an alert processing rule, which will be created by default when deploying AMBA-ALZ pattern. + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Policy-Initiatives.md b/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md similarity index 93% rename from docs/content/patterns/alz/Policy-Initiatives.md rename to docs/content/patterns/alz/Getting-started/Policy-Initiatives.md index 8bbbac3eb..1d3f6696c 100644 --- a/docs/content/patterns/alz/Policy-Initiatives.md +++ b/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md @@ -6,11 +6,11 @@ weight: 40 ## Overview -This document details the ALZ-Monitor Azure policy initiatives leveraged for deploying the ALZ-Monitor baselines. For references on individual alerts/policies, refer to [Alert Details](../Alerts-Details). +This document details the ALZ-Monitor Azure policy initiatives leveraged for deploying the ALZ-Monitor baselines. For references on individual alerts/policies, refer to [Alert Details](../..//Getting-started//Alerts-Details). ## Connectivity initiative -This initiative is intended for assignment of policies relevant to networking components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-connectivity management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for assignment of policies relevant to networking components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-connectivity management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ---------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -67,7 +67,7 @@ This initiative is intended for assignment of policies relevant to networking co ## Management initiative -This initiative is intended for assignment of policies relevant to management components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for assignment of policies relevant to management components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ----------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -80,7 +80,7 @@ This initiative is intended for assignment of policies relevant to management co ## Identity initiative -This initiative is intended for assignment of policies relevant to identity components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-identity management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for assignment of policies relevant to identity components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-identity management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ------------------------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -93,7 +93,7 @@ This initiative is intended for assignment of policies relevant to identity comp ## Key Management initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management Services such as Azure Key Vault, and Managed HSM. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management Services such as Azure Key Vault, and Managed HSM. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -105,7 +105,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management ## Load Balancing initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing Services such as Load Balancer, Application Gateway, Traffic Manager, and Azure Front Door. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing Services such as Load Balancer, Application Gateway, Traffic Manager, and Azure Front Door. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -136,7 +136,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing ## Network Changes initiative -This initiative implements Azure Monitor Baseline Alerts to monitor alterations in Network Routing and Security, such as modifications to Route Tables and the removal of Network Security Groups. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative implements Azure Monitor Baseline Alerts to monitor alterations in Network Routing and Security, such as modifications to Route Tables and the removal of Network Security Groups. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -145,7 +145,7 @@ This initiative implements Azure Monitor Baseline Alerts to monitor alterations ## Recovery Services initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Services such as Azure Backup, and Azure Site Recovery. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Services such as Azure Backup, and Azure Site Recovery. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -153,7 +153,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Servic ## Storage initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Services such as Storage accounts. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Services such as Storage accounts. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -161,7 +161,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Service ## VM initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual Machines. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual Machines. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -179,7 +179,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual M ## Web initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services such as App Services. This initiative is intended for assignment of policies relevant to a landing zone in the ALZ structure. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services such as App Services. This initiative is intended for assignment of policies relevant to a landing zone in the ALZ structure. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -190,7 +190,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services su ## Hybrid VM initiative -This initiative is intended for assignment of policies relevant to Hybrid VM alerts in AMBA-ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern), this will be assigned to the 'alz' intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default policy effect is, refer to the below table. +This initiative is intended for assignment of policies relevant to Hybrid VM alerts in AMBA-ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will be assigned to the 'alz' intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default policy effect is, refer to the below table. | **Policy Display Name** | **Reference ID** | **Path to policy json file** | **Policy default effect** | | ---------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -209,7 +209,7 @@ This initiative is intended for assignment of policies relevant to Hybrid VM ale ## Service Health initiative -This initiative is intended for assignment of policies relevant to service health alerts in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for assignment of policies relevant to service health alerts in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | --------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -222,7 +222,7 @@ This initiative is intended for assignment of policies relevant to service healt ## Notification Assets initiative -This initiative is intended for assignment of policies relevant to notification in AMBA-ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for assignment of policies relevant to notification in AMBA-ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Display Name** | **Reference ID** | **Path to policy json file** | **Policy default effect** | | ------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -231,7 +231,7 @@ This initiative is intended for assignment of policies relevant to notification ## Landing Zone initiative (Deprecated) -This initiative is intended for assignment of policies relevant to a landing zone in the ALZ structure. With the guidance provided in [Introduction to deploying the ALZ Pattern](../deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for assignment of policies relevant to a landing zone in the ALZ structure. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -283,3 +283,5 @@ This initiative is intended for assignment of policies relevant to a landing zon | Deploy App Service Plan Http Queue Length Alert | ALZ_WSFHttpQueueLength | [Deploy-WSF-HttpQueueLength-Alert.json](../../../services/Web/serverFarms/Deploy-WSF-HttpQueueLength-Alert.json) | deployIfNotExists | | Deploy Frontdoor Backend Health Percentage Alert | ALZ_FDBackendHealth | [Deploy-FD-BackendHealth-Alert.json](../../../services/Network/frontDoors/Deploy-FD-BackendHealth-Alert.json) | deployIfNotExists | | Deploy Frontdoor Backend Request Latency Alert | ALZ_FDBackendRequestLatency | [Deploy-FD-BackendRequestLatency-Alert.json](../../../services/Network/frontDoors/Deploy-FD-BackendRequestLatency-Alert.json) | deployIfNotExists | + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Getting-started/_index.md b/docs/content/patterns/alz/Getting-started/_index.md new file mode 100644 index 000000000..34b7e39ea --- /dev/null +++ b/docs/content/patterns/alz/Getting-started/_index.md @@ -0,0 +1,6 @@ +--- +title: Getting started +geekdocCollapseSection: true +weight: 20 +--- + diff --git a/docs/content/patterns/alz/Available_features/Bring-your-own-Managed-Identity.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md similarity index 75% rename from docs/content/patterns/alz/Available_features/Bring-your-own-Managed-Identity.md rename to docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md index 2a41ec11c..ab773a1bd 100644 --- a/docs/content/patterns/alz/Available_features/Bring-your-own-Managed-Identity.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md @@ -4,11 +4,11 @@ geekdocCollapseSection: true weight: 95 --- -# Overview +## Overview -The ***Bring Your Own User Assigned Managed Identity*** (BYO UAMI) feature, available with release [2024-06-05](../../Whats-New#2024-06-05), allows both Greenfield and Brownfield customers to create a new User Assigned Managed Identity (UAMI) during or after the deployment of AMBA-ALZ. It also allows Brownfield customers, who deployed the ALZ pattern when this feature wasn't available, to use any existing one by configuring a couple of parameters. Thanks to this new feature, it's now possible to query Azure Resource Graph (ARG) using the Kusto Query Language. Log-based search alerts can now be enhanced to include ARG queries looking at resource tags. +The ***Bring Your Own User Assigned Managed Identity*** (BYO UAMI) feature, available with release [2024-06-05](../../Overview/Whats-New#2024-06-05), allows both Greenfield and Brownfield customers to create a new User Assigned Managed Identity (UAMI) during or after the deployment of AMBA-ALZ. It also allows Brownfield customers, who deployed the ALZ pattern when this feature wasn't available, to use any existing one by configuring a couple of parameters. Thanks to this new feature, it's now possible to query Azure Resource Graph (ARG) using the Kusto Query Language. Log-based search alerts can now be enhanced to include ARG queries looking at resource tags. -# How this feature works +## How this feature works The BYO UAMI feature works by creating a new UAMI in the management subscription and assigns the ***Monitoring reader*** role on the parent pseudo root Management Group. With this new feature, it's now possible to query Azure Resource Graph (ARG) using the Kusto Query Language and to enhance Log-based search alerts that can now query ARG to look at resource tags or properties. It's enough to enter the necessary parameter values before running the ALZ pattern deployment. @@ -16,7 +16,7 @@ Should Brownfield customers decide to use their own UAMI after the initial deplo Once parameters are set according to your needs, redeploy the AMBA-ALZ pattern and wait for the remediation to happen. You can also start the Policy remediation manually as documented at [Remediate Policies](../deploy/Remediate-Policies). -## Conditional deployment behavior +### Conditional deployment behavior The deployment template has conditions that controls what is being deployed according to the following two scenarios: @@ -51,7 +51,7 @@ Here's a sample extract of the parameter file with the relevant parameter config ![New UAMI deployed by the template](../../media/alz-UAMI-Param-Example-2.png) -## Where is it used +### Where is it used This new feature is used in Log-search based alerts. At the moment of this release, there's one alert using it. The alert is part of the new ***Deploy Azure Monitor Vaseline Alerts for Hybrid VMs*** policySet added to monitor hybrid virtual machine. @@ -61,13 +61,15 @@ This new feature is used in Log-search based alerts. At the moment of this relea We're planning to use this feature more in the future and to include it as part of other alerts. {{< /hint >}} -## Switching between BYO UAMI and new UAMI +### Switching between BYO UAMI and new UAMI -The [conditional deployment behavior](../../Available_features/Bring-your-own-Managed-Identity#conditional-deployment-behavior) discussed earlier, allows brownfield customers to switch from a new created UAMI to an existing one and viceversa. +The [conditional deployment behavior](../Bring-your-own-Managed-Identity#conditional-deployment-behavior) discussed earlier, allows brownfield customers to switch from a new created UAMI to an existing one and viceversa. Should customers decide to switch, it will be enough to: - Change the values in the parameter file to match one of the two scenarios previously discussed - Redeploy the AMBA-ALZ pattern -- Run the remediation for the [Deploy Azure Monitor Baseline Alerts for Hybrid VMs](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-HybridVM-Alerts.json) policy initiative as documented at [Remediate Policies](../../deploy/Remediate-Policies) +- Run the remediation as documented at [Remediate Policies](../deploy/Remediate-Policies) The code will reconfigure the necessary alerts to use either the customer's provided UAMI or the new one created during the deployment. + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Available_features/Bring-your-own-Notifications.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md similarity index 60% rename from docs/content/patterns/alz/Available_features/Bring-your-own-Notifications.md rename to docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md index 426dc5b78..32d1d65e8 100644 --- a/docs/content/patterns/alz/Available_features/Bring-your-own-Notifications.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md @@ -4,21 +4,21 @@ geekdocCollapseSection: true weight: 100 --- -# Overview +## Overview -The ***Bring Your Own Notifications*** (BYON) feature, available with release [2024-04-12](../../Whats-New#2024-04-12), allows brownfield customers to use their existing Action Groups (also known as AGs) and Alert Processing Rule (also known as APR) not forcing the use of notification assets deployed by both the [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) initiative and the [Deploy Service Health Action Group](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/services/Resources/subscriptions/Deploy-ServiceHealth-ActionGroups.json) policy definition present in the ALZ pattern. It also allows Brownfield customer who deployed the ALZ pattern when this feature wasn't available, to switch to it. +The ***Bring Your Own Notifications*** (BYON) feature, available with release [2024-04-12](../../Overview/Whats-New#2024-04-12), allows brownfield customers to use their existing Action Groups (also known as AGs) and Alert Processing Rule (also known as APR) not forcing the use of notification assets deployed by both the [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) initiative and the [Deploy Service Health Action Group](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/services/Resources/subscriptions/Deploy-ServiceHealth-ActionGroups.json) policy definition present in the ALZ pattern. It also allows Brownfield customer who deployed the ALZ pattern when this feature wasn't available, to switch to it. -# How this feature works +## How this feature works The BYON feature works by setting the necessary parameter values before running the ALZ pattern deployment. Customers have the choice to either specify one or more existing AGs and one APR or to enter target values so the AG and the APR will be created using the actions specified in the parameter file (including the option to not specify any value and creating an empty AG). -Should Brownfield customers decide to use their own notification assets, it will be sufficient to enter the _AG resource IDs_ (separated by comma) and the _APR resource ID_ values in the respective parameters ***BYOActionGroup*** and ***BYOAlertProcessingRule***, leaving the ***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId*** and ***ALZFunctionTriggerUrl*** ***with no values***: +Should Brownfield customers decide to use their own notification assets, it will be sufficient to enter the *AG resource IDs* and the *APR resource ID* values in the respective parameters ***BYOActionGroup*** and ***BYOAlertProcessingRule***, leaving the ***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId*** and ***ALZFunctionTriggerUrl*** ***with no values***: - ![policyAssignmentParametersBYON section](../../media/BYON_Params.png) +![policyAssignmentParametersBYON section](../../media/BYON_Params_3.png) -Differently if they decide to use the assets provided by AMBA or if they're Greenfield customers, they'll just leave the ***BYOActionGroup*** and ***BYOAlertProcessingRule*** parameters with no values and populate all the others (***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId*** and ***ALZFunctionTriggerUrl***): +Differently if they decide to use the assets provided by AMBA or if they're Greenfield customers, they'll just leave the ***BYOActionGroup*** and ***BYOAlertProcessingRule*** parameters ***with no values*** and populate all the others (***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId*** and ***ALZFunctionTriggerUrl***): -![policyAssignmentParametersNotificationAssets section](../../media/NotificationAssets_Params.png) +![policyAssignmentParametersNotificationAssets section](../../media/NotificationAssets_Params_2.png) ## Conditional deployment behavior @@ -53,7 +53,7 @@ Here's an example of the parameter file with the relevant sections populated for ## Switching between BYON and Notification Assets -The [conditional deployment behavior](../../Bring-your-own-Notifications#conditional-deployment-behavior) discussed earlier, allows brownfield customers to switch from the initial notification assets scenario (the only one available until release [2024-03-01](../../Whats-New#2024-03-01)) to the new BYON after deployment and viceversa. +The [conditional deployment behavior](../Bring-your-own-Notifications#conditional-deployment-behavior) discussed earlier, allows brownfield customers to switch from the initial notification assets scenario (the only one available until release [2024-03-01](../../Overview/Whats-New#2024-03-01)) to the new BYON after deployment and viceversa. Should customers decide to switch, it will be enough to: @@ -63,3 +63,5 @@ Should customers decide to switch, it will be enough to: - remove notification assets deployed by ALZ patterns using the [**Remove-AMBANotificationAssets.ps1**](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/scripts/Remove-AMBANotificationAssets.ps1) script (_*** only if moving from ALZ notification assets to BYON_) The code will reconfigure the Service Health alerts to use either the customer's action groups to the ALZ pattern notification assets according to the selected case. + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Cleaning-up-a-Deployment.md b/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md similarity index 99% rename from docs/content/patterns/alz/Cleaning-up-a-Deployment.md rename to docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md index 92085a939..87df02d73 100644 --- a/docs/content/patterns/alz/Cleaning-up-a-Deployment.md +++ b/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md @@ -65,3 +65,5 @@ Follow the instructions below to download the cleanup script file. Alternatively ```powershell ./Start-AMBACleanup.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -Force ``` + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Disabling-Policies.md b/docs/content/patterns/alz/HowTo/Disabling-Policies.md similarity index 67% rename from docs/content/patterns/alz/Disabling-Policies.md rename to docs/content/patterns/alz/HowTo/Disabling-Policies.md index 2dad3fd17..1a7e77cbf 100644 --- a/docs/content/patterns/alz/Disabling-Policies.md +++ b/docs/content/patterns/alz/HowTo/Disabling-Policies.md @@ -1,5 +1,5 @@ --- -title: Disabling Policies +title: Disable policies geekdocCollapseSection: true weight: 60 --- @@ -25,24 +25,24 @@ The AlertState parameter is used for both compliance evaluation and configuratio ```json "existenceCondition": { -    "allOf": [ -        { -            "field": "Microsoft.Insights/metricAlerts/criteria.Microsoft-Azure-Monitor-SingleResourceMultipleMetricCriteria.allOf[*].metricNamespace", -            "equals": "Microsoft.Automation/automationAccounts" -        }, -        { -            "field": "Microsoft.Insights/metricAlerts/criteria.Microsoft-Azure-Monitor-SingleResourceMultipleMetricCriteria.allOf[*].metricName", -            "equals": "TotalJob" -        }, -        { -            "field": "Microsoft.Insights/metricalerts/scopes[*]", -            "equals": "[[concat(subscription().id, '/resourceGroups/', resourceGroup().name, '/providers/Microsoft.Automation/automationAccounts/', field('fullName'))]" -        }, -        { -            "field": "Microsoft.Insights/metricAlerts/enabled", -            "equals": "[[parameters('enabled')]" -        } -    ] + "allOf": [ + { + "field": "Microsoft.Insights/metricAlerts/criteria.Microsoft-Azure-Monitor-SingleResourceMultipleMetricCriteria.allOf[*].metricNamespace", + "equals": "Microsoft.Automation/automationAccounts" +   }, + { + "field": "Microsoft.Insights/metricAlerts/criteria.Microsoft-Azure-Monitor-SingleResourceMultipleMetricCriteria.allOf[*].metricName", + "equals": "TotalJob" + }, + { + "field": "Microsoft.Insights/metricalerts/scopes[*]", + "equals": "[[concat(subscription().id, '/resourceGroups/', resourceGroup().name, '/providers/Microsoft.Automation/automationAccounts/', field('fullName'))]" + }, + { + "field": "Microsoft.Insights/metricAlerts/enabled", + "equals": "[[parameters('enabled')]" + } + ] } ``` @@ -53,14 +53,14 @@ If "allOf" evaluates to true, the effect is satisfied and doesn't trigger the de These are the high-level steps that would need to take place: 1. Change the value for the AlertState parameter for the offending policies to false, either via command line or parameter file as described previously. -1. Deploy the policies and assignments as described previously. -1. After deploying and policy evaluation there will be a number of non-compliant policies depending on which alerts were to be disabled. These will then need to be remediated which can be done either through the portal, on a policy-by-policy basis or you can run the script found in [patterns/alz/scripts/Start-AMBARemediation](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBARemediation.ps1) to remediate all ALZ-Monitor policies in scope as defined by management group pre-fix. +2. Deploy the policies and assignments as described previously. +3. After deploying and policy evaluation there will be a number of non-compliant policies depending on which alerts were to be disabled. These will then need to be remediated which can be done either through the portal, on a policy-by-policy basis or you can run the script found in [patterns/alz/scripts/Start-AMBARemediation](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBARemediation.ps1) to remediate all ALZ-Monitor policies in scope as defined by management group pre-fix. Note that the above approach will not delete the alerts objects in Azure, merely disable them. To delete the alerts you will have to do so manually. Also note that while you can engage the PolicyEffect to avoid deploying new alerts, you should not do so until you have successfully remediated the above. Otherwise the policy will be disabled, and you will not be able to turn alerts off via policy until that is changed back. ## PolicyEffect parameter -In general, we evaluate the alert rules on best practices, field experience, customer feedback, type of alert and possible impact. There are situations where disabling the policy makes sense to prevent receiving unnecessary and/ or duplicate alerts/ notifications. For example we deploy an alert rule for VPN Gateway Bandwidth Utilization, in turn we have disabled the alert rules for VPN Gateway Egress and Ingress. +In general, we evaluate the alert rules on best practices, field experience, customer feedback, type of alert and possible impact. There are situations where disabling the policy makes sense to prevent receiving unnecessary and/or duplicate alerts/notifications. For example we deploy an alert rule for VPN Gateway Bandwidth Utilization, in turn we have disabled the alert rules for VPN Gateway Egress and Ingress. The default is intended to provide a well balanced baseline. However you may want to Enable or Disable the creation of certain Alert rules to meet your needs. ### Allowed values @@ -73,34 +73,50 @@ The default is intended to provide a well balanced baseline. However you may wan The PolicyEffect parameter is used for the configuration of the effect of the PolicyDefinition (in the initiatives and the example parameter file the parameter is named combining {resourceType}, {metricName} and PolicyEffect, for example ERCIRQoSDropBitsinPerSecPolicyEffect) . The value of the **PolicyEffect** parameter is passed on to the **effect** parameter which configures the effect of the Policy. ```json - "policyRule": { - "if": { - "allOf": [ - { - "field": "type", - "equals": "Microsoft.Automation/automationAccounts" - }, - { - "field": "[[concat('tags[', parameters('MonitorDisable'), ']')]", - "notEquals": "true" - } - ] +"policyRule": { + "if": { + "allOf": [ + { + "field": "type", + "equals": "Microsoft.Automation/automationAccounts" }, - "then": { - "effect": "[[parameters('effect')]", + { + "field": "[[concat('tags[', parameters('MonitorDisable'), ']')]", + "notEquals": "true" + } + ] + }, + "then": { + "effect": "[[parameters('effect')]", ``` ## MonitorDisable parameter -It´s also possible to exclude certain resources from being monitored. You may not want to monitor pre-production or dev environments. The MonitorDisable parameter contains the tag name and tag value to determine whether a resource should be included. By default, creating the tag MonitorDisable with value "true" will prevent deployment of alert rules on those resources. This can be easily adjusted to use existing tags and tag values. For example you could configure the parameters with the tag name ***Environment*** and tag value of ***Production*** or ***Test*** or ***Sandbox*** or all of them to exclude resources in these environments (see the sample parameter screenshot). +It´s also possible to exclude certain resources from being monitored. You may not want to monitor pre-production or dev environments. The MonitorDisable parameter contains the tag name and tag value to determine whether a resource should be included. By default, creating the tag MonitorDisable with value ___"true"___ will prevent deployment of alert rules on those resources. This can be easily adjusted to use existing tags and tag values. For example you could configure the parameters with the tag name ___Environment___ and tag value of ___Production___ or ___Test___ or ___Sandbox___ or all of them to exclude resources in these environments (see the sample parameter section). -![MonitorDisable* parameters](../media/MonitorDisableParams.png) +```json +. +. +"ALZMonitorDisableTagName": { + "value": "MonitorDisable" +}, +"ALZMonitorDisableTagValues": { + "value": [ + "true", + "Test", + "Dev", + "Sandbox" + ] +}, +. +. +``` This will deploy policy definitions which will only be evaluated and remediated if the tag value(s) are not included in the list you provided. ### How it works -The policyRule only continues if "allOff" is true. Meaning, the deployment will continue as long as the MonitorDisableTagName tag doesn't exist or doesn't hold the any of the values listed in the MonitorDisableTagValues parameter. When the tag holds one of the configured values, the "allOff" will return "false" as *"notIn": "[[parameters('MonitorDisableTagValues')]"* is no longer satisfied, causing the evaluation and hence the remediation to stop. +The policyRule only continues if "allOff" is true. Meaning, the deployment will continue as long as the MonitorDisableTagName tag doesn't exist or doesn't hold the any of the values listed in the MonitorDisableTagValues parameter. When the tag holds one of the configured values, the "allOff" will return "false" as _"notIn": "[[parameters('MonitorDisableTagValues')]"_ is no longer satisfied, causing the evaluation and hence the remediation to stop. ```json "policyRule": { @@ -119,6 +135,8 @@ The policyRule only continues if "allOff" is true. Meaning, the deployment will ``` Given the different resource scope that this method can be applied to, we made it working a little bit different when it comes to log-based alerts. For instance, the virtual machine alerts are scoped to subscription and tagging the subcription would result in disabling all the policies targeted at it. -For this reason, and thanks to the new **Bring Your Own User Assigned Managed Identity (BYO UAMI)*** included in the [2024-06-05](../../Whats-New#2024-06-05) release and to the ability to query Azure resource Graph using Azure Monitor (see [Quickstart: Create alerts with Azure Resource Graph and Log Analytics](https://learn.microsoft.com/en-us/azure/governance/resource-graph/alerts-query-quickstart?tabs=azure-resource-graph)), it is now possible to disable individual alerts for both Azure and hybrid virtual machines after they are created. We got requests to stop alerting fro virtual machines that were off for maintenance and this enhancement came up just in time. +For this reason, and thanks to the new _**Bring Your Own User Assigned Managed Identity (BYO UAMI)**_ included in the [2024-06-05](../../Overview/Whats-New#2024-06-05) release and to the ability to query Azure resource Graph using Azure Monitor (see [Quickstart: Create alerts with Azure Resource Graph and Log Analytics](https://learn.microsoft.com/en-us/azure/governance/resource-graph/alerts-query-quickstart?tabs=azure-resource-graph)), it is now possible to disable individual alerts for both Azure and hybrid virtual machines after they are created. We got requests to stop alerting fro virtual machines that were off for maintenance and this enhancement came up just in time. Should you need to disable the alerts for your virtual machines after they are created, just make sure you tag the relevant resources accordingly. The alert queries have been modified to look at resource properties in [Azure Resource Graph](https://learn.microsoft.com/en-us/azure/governance/resource-graph/overview). If the resource contains the given tag name and tag value, it is made part of an exclusion list, so alerts will not be generated for them. This behavior allows you to dinamically and rapidly exclude the necessary resources from being alerted without the need of deleteing the alert, tag the resource and run the remediation again. + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Available_features/Log_Search_Alert_Table.md b/docs/content/patterns/alz/HowTo/Log_Search_Alert_Table.md similarity index 100% rename from docs/content/patterns/alz/Available_features/Log_Search_Alert_Table.md rename to docs/content/patterns/alz/HowTo/Log_Search_Alert_Table.md diff --git a/docs/content/patterns/alz/Available_features/Metrics_Alert_Table.md b/docs/content/patterns/alz/HowTo/Metrics_Alert_Table.md similarity index 100% rename from docs/content/patterns/alz/Available_features/Metrics_Alert_Table.md rename to docs/content/patterns/alz/HowTo/Metrics_Alert_Table.md diff --git a/docs/content/patterns/alz/Telemetry.md b/docs/content/patterns/alz/HowTo/Telemetry.md similarity index 99% rename from docs/content/patterns/alz/Telemetry.md rename to docs/content/patterns/alz/HowTo/Telemetry.md index fe34c0a7c..2f1e6873d 100644 --- a/docs/content/patterns/alz/Telemetry.md +++ b/docs/content/patterns/alz/HowTo/Telemetry.md @@ -1,5 +1,5 @@ --- -title: Telemetry +title: Disable telemetry tracking geekdocCollapseSection: true weight: 90 --- diff --git a/docs/content/patterns/alz/Temporarily-disabling-notifications.md b/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md similarity index 78% rename from docs/content/patterns/alz/Temporarily-disabling-notifications.md rename to docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md index 4b8aa6883..fa85acb0c 100644 --- a/docs/content/patterns/alz/Temporarily-disabling-notifications.md +++ b/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md @@ -4,7 +4,7 @@ geekdocCollapseSection: true weight: 65 --- -Azure Monitor alerts targeted to a large scope allow for at scale coverage, but reduce the flexibility to disable them for specific resources. There might be several reason to stop the notification of alerts. For instance, customers could have resources that are stopped or disabled due to maintenance or just want to stop the notification during the night shift. To allow this kind of flexibility, as part of the Notification Assets policy initiative, AMBA provides you with an asset to stop the notification for specific resources. +Azure Monitor alerts targeted to a large scope allow for at scale coverage, but reduce the flexibility to disable them for specific resources. There might be several reason to stop the notification of alerts. For instance, customers could have resources that are stopped or disabled due to maintenance or just want to stop the notification during the night shift. To allow this kind of flexibility, as part of the Notification Assets policy initiative, AMBA-ALZ provides you with an asset to stop the notification for specific resources. This asset is made of an alert processing rule (also known as APR) with the following characteristics: @@ -23,15 +23,15 @@ To configure the APR, do the following: 1. In **Monitor --> Alerts**, click on **Alert processing rules** - ![Monitor/Alerts/Alert processing rule](../media/AlertProcessingRules.png) + ![Monitor/Alerts/Alert processing rule](../../media/AlertProcessingRules.png) 2. Click on the ARP named ***apr-AMBA-subscription display name-002*** with rule type **Suppression** - ![Suppression aler processing rule](../media/SuppressionAlertProcessingRule.png) + ![Suppression aler processing rule](../../media/SuppressionAlertProcessingRule.png) 3. Click on ***Edit*** - ![Edit alert processing rule](../media/Edit-AlertProcessingRule.png) + ![Edit alert processing rule](../../media/Edit-AlertProcessingRule.png) 4. In the **Scope** tab, under the filter section, configure the following: @@ -39,14 +39,16 @@ To configure the APR, do the following: - Operator: ***Equals*** - Value: **Enter the resource Id of resources separated by comma with no spaces before, after or between the strings.** - ![Configure filter](../media/Filter-AlertProcessingRule.png) + ![Configure filter](../../media/Filter-AlertProcessingRule.png) - {{< hint type=Important >}} - Each filter can include up to **five** values. Should you need more than **5** resources, add more lines of filter. - {{< /hint >}} + {{< hint type=Important >}} + Each filter can include up to ***5*** values. Should you need more than **5** resources, add more lines of filter. + {{< /hint >}} 5. Click on ***Review + save*** and then ***Save*** -{{< hint type=Note >}} + {{< hint type=Note >}} It is possible to apply other types of filter. For a complete list of allowed scopes and filters, refer to the official [Scope and filters for alert processing rules](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-processing-rules?tabs=portal#scope-and-filters-for-alert-processing-rules) documentation. {{< /hint >}} + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Available_features/Threshold-Override.md b/docs/content/patterns/alz/HowTo/Threshold-Override.md similarity index 98% rename from docs/content/patterns/alz/Available_features/Threshold-Override.md rename to docs/content/patterns/alz/HowTo/Threshold-Override.md index 6cf316a32..2a661cf77 100644 --- a/docs/content/patterns/alz/Available_features/Threshold-Override.md +++ b/docs/content/patterns/alz/HowTo/Threshold-Override.md @@ -1,5 +1,5 @@ --- -title: Alert Threshold Override +title: Override alert thresholds geekdocCollapseSection: true weight: 85 --- @@ -52,3 +52,5 @@ The following table contains the mapping between the alert name and the correspo ### Metric alerts table {{% include "Metrics_Alert_Table.md" %}} + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2023-11-14.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md similarity index 87% rename from docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2023-11-14.md rename to docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md index dd8e2b0bd..f6298c370 100644 --- a/docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2023-11-14.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md @@ -6,7 +6,7 @@ weight: 100 ## Post update actions -Updating from release [2023-11-14](../../Whats-New#2023-11-14) will require running a post update script to remove the old Service Health action group(s) no longer in use. +Updating from release [2023-11-14](../../../Overview/Whats-New#2023-11-14) will require running a post update script to remove the old Service Health action group(s) no longer in use. To run the script, follow the following instructions: @@ -42,3 +42,5 @@ Updating from release [2023-11-14](../../Whats-New#2023-11-14) will require runn ```powershell ./Start-AMBAOldArpCleanup.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -Force ``` + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-03-01.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md similarity index 78% rename from docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-03-01.md rename to docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md index 5e1372f35..51dfca383 100644 --- a/docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-03-01.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md @@ -9,7 +9,7 @@ weight: 99 # Post update actions -Updating from release [2024-03-01](../../Whats-New#2024-03-01) might require running a post update script to remove the notification assets deployed by ALZ pattern ***if and only if*** customer decided to use existing action groups and alert processing rule. In this case, the Service Health alerts will be reconfigured to use the customer' action groups as per the _**B**ring **Y**our **O**wn **N**otifications_ (BYON) feature. +Updating from release [2024-03-01](../../../Overview/Whats-New#2024-03-01) might require running a post update script to remove the notification assets deployed by ALZ pattern ***if and only if*** customer decided to use existing action groups and alert processing rule. In this case, the Service Health alerts will be reconfigured to use the customer' action groups as per the ***B***ring ***Y***our ***O***wn ***N***otifications (BYON) feature. To run the script, complete the following step: @@ -45,3 +45,5 @@ To run the script, complete the following step: ```powershell ./Remove-AMBANotificationAssets.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -Force ``` + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-04-12.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md similarity index 79% rename from docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-04-12.md rename to docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md index 0e54414cc..2fe1e4fa6 100644 --- a/docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-04-12.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md @@ -9,7 +9,7 @@ weight: 98 # Pre update actions -The parameter file structure has changed to accommodate a new feature coming soon. For this reason, updating from release [2024-04-12](../../Whats-New#2024-04-12) requires the alignment of the parameter file structure you have been using so far with the new one coming with the release. +The parameter file structure has changed to accommodate a new feature coming soon. For this reason, updating from release [2024-04-12](../../../Overview/Whats-New#2024-04-12) requires the alignment of the parameter file structure you have been using so far with the new one coming with the release. In particular the new parameter file has the following differences: @@ -21,20 +21,22 @@ In particular the new parameter file has the following differences: 1.1. Enter the UAMI resource ID, leaving the **managementSubscriptionId** blank - ![UAMI resource ID](../../media/alz-BYO-UAMI.png) + ![UAMI resource ID](../../../media/alz-BYO-UAMI.png) 1.2. Configure it with the ***Monitoring Reader*** role on the pseudo root Management Group. 3. ***userAssignedManagedIdentityName***: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **No**, leave the default value or set a different one to specify a different name for the UAMI created during the deployment. The provided default name aligns with the ALZ standard naming convention. - ![UAMI default name](../../media/alz-UAMI-Default-Name.png) + ![UAMI default name](../../../media/alz-UAMI-Default-Name.png) 4. ***managementSubscriptionId***: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **No**, enter the subscription ID of the subscription under the Management management group. The deployment procedure will create the UAMI in this subscription and assign it the ***Monitoring Reader*** role on the pseudo root Management Group - ![Management subscription ID](../../media/alz-ManagementSubscription.png) + ![Management subscription ID](../../../media/alz-ManagementSubscription.png) - ![](../../media/alz-UAMI-Management-SubscriptionID.png) + ![Management subscription ID parameter](../../../media/alz-UAMI-Management-SubscriptionID.png) 2. Changes the previous parameter objects, such as ***policyAssignmentParametersCommon***, ***policyAssignmentParametersBYON*** and ***policyAssignmentParametersNotificationAssets*** into classic parameters using the same name as before. As result, the previous sections of the parameter you'll now look like the following image: - ![New parameter file sample](../../media/alz-New-ParamterFile-Structure.png) + ![New parameter file sample](../../../media/alz-New-ParamterFile-Structure.png) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-06-05.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md similarity index 69% rename from docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-06-05.md rename to docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md index 7f046b64b..29bbd74b4 100644 --- a/docs/content/patterns/alz/UpdateToNewReleases/Update_from_release_2024-06-05.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md @@ -4,16 +4,16 @@ geekdocCollapseSection: true weight: 97 --- {{< hint type=Important >}} -***Updating to release from release [2024-06-05](../../Whats-New#2024-06-05) or from previous releases, contains a breaking change. To perform the update, it's required to remove previously deployed policy definitions, policy set definitions, policy assignments and role assignments. As part of this release we made a script available to clean all the necessary items. ***It's strongly recommended that you test the script thoroughly before running on production environment. It isn't necessary to remove alert definitions that will continue to work in the meantime.*** +***Updating to release from release [2024-06-05](../../../Overview/Whats-New#2024-06-05) or from previous releases, contains a breaking change. To perform the update, it's required to remove previously deployed policy definitions, policy set definitions, policy assignments and role assignments. As part of this release we made a script available to clean all the necessary items. ***It's strongly recommended that you test the script thoroughly before running on production environment. It isn't necessary to remove alert definitions that will continue to work in the meantime.*** {{< /hint >}} # Pre update actions -Before updating to release [2024-06-30](../../Whats-New#2024-06-30), it's required to remove existing policy definitions, policy set definitions, policy assignments and role assignments. This action is required because of a breaking change caused by the redefinition of some parameters, which allows for more flexibility in disabling the policy remediation or, in some cases, the alerts. Unfortunately not all the alerts can be disabled after creation; only log-based alerts can be. Even if disabling the effect of policy was already possible in AMBA-ALZ, with this release we made sure that all the policies will honor both the ***PolicyEffect*** and the ***MonitorDisable*** parameters. +Before updating to release [2024-06-30](../../../Overview/Whats-New#2024-06-30), it's required to remove existing policy definitions, policy set definitions, policy assignments and role assignments. This action is required because of a breaking change caused by the redefinition of some parameters, which allows for more flexibility in disabling the policy remediation or, in some cases, the alerts. Unfortunately not all the alerts can be disabled after creation; only log-based alerts can be. Even if disabling the effect of policy was already possible in AMBA-ALZ, with this release we made sure that all the policies will honor both the ***PolicyEffect*** and the ***MonitorDisable*** parameters. In particular, the *MonitorDisable* feature has been redesigned to allow customer to specify they own existing tag and tag value instead of forcing a hard coded one. Given the ALZ guidance and the best practice of having a consistent tagging definition, it's only allowed to one parameter name fo r the entire deployment. Instead, parameter value can be different. You can specify an array of values assigned to the same parameter. For instance, you have the ```Environment``` tag name consistently applied to several environments, saying ```Production```, ```Test```, ```Sandbox```, and so on and you want to disable alerts for resources, which are in both ```Test``` and ```Sandbox```. Now it's possible by just configuring the parameters for tag name and tag values as reported in the sample screenshot (these are the default values) below: -![MonitorDisable* parameters](../../media/MonitorDisableParams.png) +![MonitorDisable* parameters](../../../media/MonitorDisableParams.png) Complete description of this new/redesigned feature can be found in the [MonitorDisable parameter](../../Disabling-Policies#monitordisable-parameter) paragraph inside the [Disabling Policies](../../Disabling-Policies) page. @@ -53,3 +53,5 @@ To run the script, complete the following steps: ```powershell ./Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -Force ``` + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/UpdateToNewReleases/_index.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/_index.md similarity index 78% rename from docs/content/patterns/alz/UpdateToNewReleases/_index.md rename to docs/content/patterns/alz/HowTo/UpdateToNewReleases/_index.md index 832499bfc..4019688d7 100644 --- a/docs/content/patterns/alz/UpdateToNewReleases/_index.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/_index.md @@ -10,7 +10,7 @@ The list of enhancement, additions and fixed bugs contained in every release can 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) +![Releases](../../media/Releases.png)
@@ -19,7 +19,7 @@ On the center-right side of the page, there's a specific section indicating the 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 page. {{< 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. +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](../../Resources/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: @@ -38,15 +38,15 @@ Synching a fork means that we're making sure any update made to the main branch 1. Open your GitHub repo page. If you don't remember the URL, consider that it normally looks like `https://github.com/******/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) + ![<> Code](../../media/GitHub_Code.png) 3. Click on the **Sync fork** and then select **Update branch** - ![Update branch](../media/UpdateBranch.png) + ![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) + ![Branch is up to date](../../media/BranchUpToDate.png)
@@ -57,28 +57,28 @@ Within the code editor of your choice, make sure you pull the changes from your 1. Open VS Code and open the folder containing the cloned repo. 2. In the bottom-left corner click on the pull icon - ![Pull icon](../media/PullIcon.png) + ![Pull icon](../../media/PullIcon.png) 3. Confirm or approve the operation if necessary - ![Confirm pull](../media/ConfirmPull.png) + ![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) + ![Pull request completed](../../media/PullCompleted.png)
### Check for detailed requirement when updating to a newer release (always required) -Check the content of the page corresponding to the release you are updating from, to see if there's any pre or post deployment action required. For instance, if you're updating from release **2023-11-14**, check the page called ***Updating from release 2023-11-14*** +Check the content of the page corresponding to the release you are updating from, to see if there's any pre or post deployment action required. For instance, if you're updating from release [**2023-11-14**](../../Overview/Whats-New#2023-11-14), check the [Update from release 2023-11-14](../UpdateToNewReleases/Update_from_release_2023-11-14) page. - ![Updating from release](../media/UpdatingFromRelease.png) + ![Updating from release](../../media/UpdatingFromRelease.png) ### Update the parameter file with any new parameter and configuration The parameter may undergo changes in the structure or in the number of parameters that need to be configured. -For this reason, based on what documented in the [What's new](../Whats-New.md) or in the [Releases](https://github.com/Azure/azure-monitor-baseline-alerts/releases) pages. For this reason it mandatory that you check your current parameter file content with the one coming with the release, making sure you with new or refactored parameters. +For this reason, based on what documented in the [What's new](../../Overview/Whats-New) or in the [Releases](https://github.com/Azure/azure-monitor-baseline-alerts/releases) pages. For this reason it mandatory that you check your current parameter file content with the one coming with the release, making sure you with new or refactored parameters. ### Deploy (always required) @@ -92,3 +92,5 @@ Once you reached this stage, you are ready to deploy the latest release. You can ### Start the policy remediation (always required) To remediate non-compliant policies, continue with Policy remediation documented at [Remediate Policies](../deploy/Remediate-Policies) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Available_features/_index.md b/docs/content/patterns/alz/HowTo/_index.md similarity index 84% rename from docs/content/patterns/alz/Available_features/_index.md rename to docs/content/patterns/alz/HowTo/_index.md index 781966701..3d105143d 100644 --- a/docs/content/patterns/alz/Available_features/_index.md +++ b/docs/content/patterns/alz/HowTo/_index.md @@ -1,7 +1,7 @@ --- -title: Available features +title: How to geekdocCollapseSection: true -weight: 50 +weight: 30 --- This section will list all the features available in the ALZ pattern of AMBA. Features appear listed top-bottom in the release date order from newest to oldest. diff --git a/docs/content/patterns/alz/deploy/Customize-Policy-Assignment.md b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md similarity index 89% rename from docs/content/patterns/alz/deploy/Customize-Policy-Assignment.md rename to docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md index 0fd89f9c5..e07c46f1a 100644 --- a/docs/content/patterns/alz/deploy/Customize-Policy-Assignment.md +++ b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md @@ -6,7 +6,7 @@ weight: 20 ## Introduction -As described in [Introduction to deploying AMBA](../Introduction-to-deploying-the-ALZ-Pattern), the policies and initiatives in this repo can be deployed in a default configuration, i.e. with default settings and are intended to be used as such. There may be however, scenarios where you would want to tweak the initiative assignment for individual policies to conform with your monitoring requirements, or potentially wish to deploy alerts in a more phased approach to a brownfield environment. This document lists some of the various scenarios as well as how you would go about making such changes to the assignments. +As described in [Introduction to deploying the ALZ pattern](../Introduction-to-deploying-the-ALZ-Pattern), the policies and initiatives in this repo can be deployed in a default configuration, i.e. with default settings and are intended to be used as such. There may be however, scenarios where you would want to tweak the initiative assignment for individual policies to conform with your monitoring requirements, or potentially wish to deploy alerts in a more phased approach to a brownfield environment. This document lists some of the various scenarios as well as how you would go about making such changes to the assignments. ## Modify initiative assignment @@ -95,3 +95,5 @@ Note that the above parameters specifies the resource group that activity log al - To deploy with Azure DevOps Pipelines, please proceed with [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../Deploy-with-Azure-CLI) - To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/Deploy-only-Service-Health-Alerts.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md similarity index 80% rename from docs/content/patterns/alz/deploy/Deploy-only-Service-Health-Alerts.md rename to docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md index 7deda0aac..2f919e61f 100644 --- a/docs/content/patterns/alz/deploy/Deploy-only-Service-Health-Alerts.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md @@ -5,7 +5,7 @@ weight: 70 --- {{< hint type=Important >}} -Updating from the _**preview**_ version isn't supported. If you deployed the _**preview**_ version, proceed with [Moving from preview to GA](../../Moving-from-preview-to-GA) before continuing. +Updating from the _**preview**_ version isn't supported. If you deployed the _**preview**_ version, proceed with [Moving from preview to GA](../../../Resources/Moving-from-preview-to-GA) before continuing. {{< /hint >}} The following guide describes the steps to use the ALZ pattern to implement Service Health Alerts. When you deploy one Policy Set Definition, like Service Health, you will only need the Policy Definitions required by that Policy Set Definition. You can still choose to deploy all Policy Definitions that are provided in the ALZ Pattern, this is recommended when you want to deploy other Policy Set Definitions in the future. In case you first deploy a subset of the Policy Definitions, you can easily deploy additional definitions at a later stage. This document covers two deployment options: @@ -17,9 +17,9 @@ The following guide describes the steps to use the ALZ pattern to implement Serv In this example we will deploy the Service Health Policy Set Definition via Azure CLI. However, the same principles and steps apply to other Policy Set Definitions and deployment methods as well. {{< /hint >}} -# Quick deployment +## Quick deployment -## 1. Parameter configuration +### 1. Parameter configuration To start, you can either download a copy of the parameter file or clone/fork the repository. @@ -45,7 +45,7 @@ The following changes apply to all scenarios, whether you are aligned or unalign - Change the value of _```ALZLogicappResourceId```_ to the Logic app resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. - Change the value of _```ALZLogicappCallbackUrl```_ to the Logic app callback url of the Logic app you want to use as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. To retrieve the callback url you can either use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/en-us/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic app in the Azure portal, go to _**Logic app designer**_, expand the trigger activity (_When an HTTP request is received_) and copy the value in the URL field using the 2-sheets icon. - ![Get Logic app callback url](../../media/AMBA-LogicAppCallbackUrl.png) + ![Get Logic app callback url](../../../media/AMBA-LogicAppCallbackUrl.png) - Change the value of _```ALZArmRoleId```_ to the Azure Resource Manager Role(s) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no Azure Resource Manager Role notification is required. - Change the value of _```ALZEventHubResourceId```_ to the Event Hubs to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Event Hubs is used. @@ -53,27 +53,37 @@ The following changes apply to all scenarios, whether you are aligned or unalign - Change the value of _```ALZFunctionResourceId```_ to the Function resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. - Change the value of _```ALZFunctionTriggerUrl```_ to the Function App trigger url of the function to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. To retrieve the Function App trigger url with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the menu top menu and copy the value in the URL field using the 2-sheets icon. - ![Get function URL](../../media/AMBA-FunctionAppTriggerUrl.png) + ![Get function URL](../../../media/AMBA-FunctionAppTriggerUrl.png) {{< hint type=note >}} It is possible use multiple email addresses, as well as multiple Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). Should you set multiple entries, make sure they are entered as single string with values separated by comma. Example: - "ALZMonitorActionGroupEmail": { - "value": "action1@contoso.com , action2@contoso.com , action3@contoso.com" - }, + ```json + "ALZMonitorActionGroupEmail": { + "value": [ + "action1@contoso.com", + "action2@contoso.com" + ] + }, + "ALZArmRoleId": { + "value": [ + "8e3af657-a8ff-443c-a75c-2fe8c4bcb635", + "b24988ac-6180-42a0-ab88-20f7382dd24c" + ] + }, + "ALZWebhookServiceUri": { + "value": [ + "https://webookURI1.webook.com", + "http://webookURI2.webook.com" + ] + } + ``` - "ALZArmRoleId": { - "value": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635, b24988ac-6180-42a0-ab88-20f7382dd24c" - }, - - "ALZWebhookServiceUri": { - "value": "https://webhookUri1.webhook.com, http://webhookUri2.webhook.com" - }, {{< /hint >}} - If you would like to disable initiative assignments, you can change the value on one or more of the following parameters; _```enableAMBAConnectivity```_, _```enableAMBAIdentity```_, _```enableAMBALandingZone```_, _```enableAMBAManagement```_, _```enableAMBAServiceHealth```_ to _**"No"**_. -### If you are aligned to ALZ +#### If you are aligned to ALZ - Change the value of _```platformManagementGroup```_ to the management group id for Platform. - Change the value of _```IdentityManagementGroup```_ to the management group id for Identity. @@ -81,7 +91,7 @@ The following changes apply to all scenarios, whether you are aligned or unalign - Change the value of _```connectivityManagementGroup```_ to the management group id for Connectivity. - Change the value of _```LandingZoneManagementGroup```_ to the management group id for Landing Zones. -### If you are unaligned to ALZ +#### If you are unaligned to ALZ - Change the value of _```platformManagementGroup```_ to the management group id for Platform. The same management group id may be repeated. - Change the value of _```IdentityManagementGroup```_ to the management group id for Identity. The same management group id may be repeated. @@ -93,7 +103,7 @@ The following changes apply to all scenarios, whether you are aligned or unalign For ease of deployment and maintenance we have kept the same variables. For example, if you combined Identity, Management and Connectivity into one management group you should configure the variables _```identityManagementGroup```_, _```managementManagementGroup```_ , _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the same management group id. {{< /hint >}} -### If you have a single management group +#### If you have a single management group - Change the value of _```platformManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". - Change the value of _```IdentityManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". @@ -105,68 +115,118 @@ For ease of deployment and maintenance we have kept the same variables. For exam For ease of deployment and maintenance we have kept the same variables. Configure the variables _```enterpriseScaleCompanyPrefix```_, _```identityManagementGroup```_, _```managementManagementGroup```_, _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the pseudo root management group id. {{< /hint >}} -## 2. Example Parameter file +### 2. Example Parameter file The parameter file shown below has been truncated for brevity, compared to the samples included. ```json { - "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "enterpriseScaleCompanyPrefix": { - "value": "contoso" - }, - "platformManagementGroup": { - "value": "contoso-platform" - }, - "IdentityManagementGroup": { - "value": "contoso-identity" - }, - "managementManagementGroup": { - "value": "contoso-management" - }, - "connectivityManagementGroup": { - "value": "contoso-connectivity" - }, - "LandingZoneManagementGroup": { - "value": "contoso-landingzones" - }, - "enableAMBAConnectivity": { - "value": "No" - }, - "enableAMBAIdentity": { - "value": "No" - }, - "enableAMBALandingZone": { - "value": "No" - }, - "enableAMBAManagement": { - "value": "No" - }, - "enableAMBAServiceHealth": { - "value": "Yes" - }, - "policyAssignmentParametersCommon": { - "value": { - "ALZMonitorResourceGroupName": { - "value": "rg-amba-monitoring-001" - }, - "ALZMonitorResourceGroupTags": { - "value": { - "Project": "amba-monitoring" - } - }, - "ALZMonitorResourceGroupLocation": { - "value": "eastus" - } - } - } - } + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "enterpriseScaleCompanyPrefix": { + "value": "contoso" + }, + "platformManagementGroup": { + "value": "contoso-platform" + }, + "IdentityManagementGroup": { + "value": "contoso-identity" + }, + "managementManagementGroup": { + "value": "contoso-management" + }, + "connectivityManagementGroup": { + "value": "contoso-connectivity" + }, + "LandingZoneManagementGroup": { + "value": "contoso-landingzones" + }, + "enableAMBAConnectivity": { + "value": "No" + }, + "enableAMBAIdentity": { + "value": "No" + }, + "enableAMBAManagement": { + "value": "No" + }, + "enableAMBAServiceHealth": { + "value": "Yes" + }, + "enableAMBANotificationAssets": { + "value": "Yes" + }, + "enableAMBAHybridVM": { + "value": "No" + }, + "enableAMBAKeyManagement": { + "value": "No" + }, + "enableAMBALoadBalancing": { + "value": "No" + }, + "enableAMBANetworkChanges": { + "value": "No" + }, + "enableAMBARecoveryServices": { + "value": "No" + }, + "enableAMBAStorage": { + "value": "No" + }, + "enableAMBAVM": { + "value": "No" + }, + "enableAMBAWeb": { + "value": "No" + }, + "telemetryOptOut": { + "value": "No" + }, + "bringYourOwnUserAssignedManagedIdentity": { + "value": "No" + }, + "bringYourOwnUserAssignedManagedIdentityResourceId": { + "value": "" + }, + "userAssignedManagedIdentityName": { + "value": "id-amba-prod-001" + }, + "managementSubscriptionId": { + "value": "" + }, + "ALZMonitorResourceGroupName": { + "value": "rg-amba-monitoring-001" + }, + "ALZMonitorResourceGroupLocation": { + "value": "eastus" + }, + "ALZMonitorResourceGroupTags": { + "value": { + "Project": "amba-monitoring" + } + }, + "ALZMonitorDisableTagName": { + "value": "MonitorDisable" + }, + "ALZMonitorDisableTagValues": { + "value": [ + "true", + "Test", + "Dev", + "Sandbox" + ] + }, + . + . + . + . + } } ``` -## 3. Configuring variables for deployment +### 3. Configuring variables for deployment Open your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), and navigate to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and Policy Set Definitions. @@ -185,7 +245,7 @@ Above-mentioned ```pseudoRootManagementGroup``` variable value, being the so cal The ```location``` variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} -## 4. Deploying AMBA +### 4. Deploying AMBA Using your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), if you closed your previous session, navigate again to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and Policy Set Definitions. @@ -195,9 +255,9 @@ az deployment mg create --template-uri https://raw.githubusercontent.com/Azure/a
-# Custom deployment +## Custom deployment -## 1. Create a copy of policies.bicep +### 1. Create a copy of policies.bicep To create a copy of a Bicep policy file (policies.bicep), you can use standard file copying techniques based on your operating system and programming language of choice. For example, run the following command in PowerShell: @@ -205,31 +265,31 @@ To create a copy of a Bicep policy file (policies.bicep), you can use standard f Copy-Item -Path .\patterns\alz\templates\policies.bicep -Destination .\patterns\alz\templates\policies-sh.bicep ``` -## 2. Edit policies-sh.bicep +### 2. Edit policies-sh.bicep Open the newly created Bicep file in your favorite text editor, such as Visual Studio Code (VS Code). Edit the variables ```loadPolicyDefinitions``` and ```loadPolicySetDefinitions``` in your Bicep file to include only the relevant policy definitions. You should delete or comment out the unnecessary lines. In bicep use ``` // ``` to comment a line. The example below shows the lines you need to keep for the Service Health Policy Set Definition. -**loadPolicyDefinitions variable** +#### loadPolicyDefinitions variable ```bicep { -var loadPolicyDefinitions = { - All: [ - loadTextContent('../../../services/Resources/subscriptions/Deploy-ServiceHealth-ActionGroups.json') - loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ResourceHealth-UnHealthly-Alert.json') - loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ServiceHealth-Health.json') - loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ServiceHealth-Incident.json') - loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ServiceHealth-Maintenance.json') - loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ServiceHealth-Security.json') - ] - AzureCloud: [] - AzureChinaCloud: [] - AzureUSGovernment: [] -} + var loadPolicyDefinitions = { + All: [ + loadTextContent('../../../services/Resources/subscriptions/Deploy-ServiceHealth-ActionGroups.json') + loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ResourceHealth-UnHealthly-Alert.json') + loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ServiceHealth-Health.json') + loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ServiceHealth-Incident.json') + loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ServiceHealth-Maintenance.json') + loadTextContent('../../../services/Resources/subscriptions/Deploy-ActivityLog-ServiceHealth-Security.json') + ] + AzureCloud: [] + AzureChinaCloud: [] + AzureUSGovernment: [] + } } ``` -**loadPolicySetDefinitions variable** +#### loadPolicySetDefinitions variable ```bicep var loadPolicySetDefinitions = { @@ -242,7 +302,7 @@ var loadPolicySetDefinitions = { } ``` -## 3. Build policies-sh.json +### 3. Build policies-sh.json To compile your Bicep file and generate the corresponding JSON ARM template file, you can use the bicep build command. Follow these steps: @@ -254,7 +314,7 @@ bicep build .\patterns\alz\templates\policies-sh.bicep --outfile .\patterns\alz\ Make sure you have the [Bicep CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install) installed and configured in your environment before running this command. {{< /hint >}} -## 4. Configuring variables for deployment +### 4. Configuring variables for deployment Open your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), and navigate to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and Policy Set Definitions. @@ -273,7 +333,7 @@ Above-mentioned ```pseudoRootManagementGroup``` variable value, being the so cal The ```location``` variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} -## 5. Deploy Policy Definitions +### 5. Deploy Policy Definitions To deploy policy definitions to the intermediate management group, run the following command: ```bash @@ -288,8 +348,7 @@ The command doesn't work in Azure Cloud shell. In Azure Cloud Shell run the foll az deployment mg create --name "amba-ServiveHealthOnly" --template-file ./patterns/alz/policyDefinitions/policies-sh.json --location $location --management-group-id $pseudoRootManagementGroup --parameters topLevelManagementGroupPrefix=contoso ``` - -## 6. Assign the Service Health Policy Set Definition +### 6. Assign the Service Health Policy Set Definition Assign a Policy Set Definition by running the following command: ```bash @@ -302,7 +361,8 @@ The final parameter is the ```--parameters``` parameter, which is used to pass a The JSON object contains two parameters: ```topLevelManagementGroupPrefix``` and ```policyAssignmentParameters```. The ```topLevelManagementGroupPrefix``` parameter is used to specify the intermediate root management group, and should _coincide_ with the value of the ```pseudoRootManagementGroup```. The ```policyAssignmentParameters``` parameter is an object that contains the values for the parameters that are used to configure the monitoring resource group. The parameters include the name of the resource group, the tags for the resource group, the location of the resource group, and the email address for the action group associated with the Service Health Policy Set Definition. {{< /hint >}} -  -# Next steps +## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md similarity index 88% rename from docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md rename to docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md index 904f845dd..6924b4474 100644 --- a/docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md @@ -3,17 +3,17 @@ title: Deploy via the Azure Portal (Preview) weight: 30 --- - - +
[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://aka.ms/amba/alz/portal) -## Deployment Settings Blade - -![Deployment Settings Blade](../../media/PortalAccelerator/DeploymentSettings.png) +
+## Deployment Settings Blade +![Deployment Settings Blade](../../../media/PortalAccelerator/DeploymentSettings.png) +
- Change the values on the Deployment Settings blade to the instructions below: - Choose the Management Group where you wish to deploy the policies and the initiatives. This is usually the so called "pseudo root management group", for example, in [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this would be the so called "Intermediate Root Management Group" (directly beneath the "Tenant Root Group"). @@ -28,12 +28,12 @@ weight: 30 - Change the value of _```Resource Group Tags```_ to specify the tags to be added to said resource group. ## Management Groups Settings Blade -- Change the values on the Management Groups Settings blade to the instructions below: -![Management Groups Settings Blade](../../media/PortalAccelerator/MGSettings.png) +- Change the values on the Management Groups Settings blade to the instructions below: + ![Management Groups Settings Blade](../../../media/PortalAccelerator/MGSettings.png) - ### If you are aligned to ALZ +### If you are aligned to ALZ - Choose the value of _```Enterprise Scale Company Management Group```_ to the management group id for Platform. - Choose the value of _```Identity Management Group```_ to the management group id for Identity. @@ -68,16 +68,13 @@ For ease of deployment and maintenance we have kept the same variables. - Change the value of _```Enable AMBA notification assets```_ to _```Yes```_ In this scenario, the deployment will Deploy notification assets for Service Health alerts and wide notifications. - Change the value of _```Enable AMBA Service Health```_ to _```Yes```_ In this scenario, the deployment will assign the Service Health Policy Set Definition. - - ## Notification Settings Blade -![Notification Settings Blade](../../media/PortalAccelerator/NotificationSettings.png) - +![Notification Settings Blade](../../../media/PortalAccelerator/NotificationSettings.png) - {{< hint type=note >}} - While it's technically possible to not add any notification information (no email, no ARM Role, no Logic App, etc.) it is strongly recommended to configure at least one option. - {{< /hint >}} +{{< hint type=note >}} +While it's technically possible to not add any notification information (no email, no ARM Role, no Logic App, etc.) it is strongly recommended to configure at least one option. +{{< /hint >}} - Change values on the Notification Settings Blade blade to the instructions below: - Change the value of _```Bring Your Own Notifications (BYON)```_ to _``` Yes```_ if you wish to use existing Action Groups and Alert Processing Rule. The BYON feature works by setting the necessary parameter values before running the ALZ pattern deployment. Customers have the choice to either specify one or more existing AGs and one APR or to enter target values so the AG and the APR will be created using the actions specified in the parameter file (including the option to not specify any value and creating an empty AG). @@ -87,24 +84,24 @@ For ease of deployment and maintenance we have kept the same variables. - Change the value of _```Logicapp Resource Id```_ to the Logic app resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. - Change the value of _```Logicapp Callback Url```_ to the Logic app callback url of the Logic app you want to use as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. To retrieve the callback url you can either use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/en-us/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic app in the Azure portal, go to _**Logic app designer**_, expand the trigger activity (_When an HTTP request is received_) and copy the value in the URL field using the 2-sheets icon. - ![Get Logic app callback url](../../media/AMBA-LogicAppCallbackUrl.png) + ![Get Logic app callback url](../../../media/AMBA-LogicAppCallbackUrl.png) - Change the value of _```Event Hub Resource Id```_ to the Event Hubs to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Event Hubs is used. - Change the value of _```Function Resource Id```_ to the Function resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. - Change the value of _```Function Trigger Url```_ to the Function App trigger url of the function to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. To retrieve the Function App trigger url with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the menu top menu and copy the value in the URL field using the 2-sheets icon. - ![Get function URL](../../media/AMBA-FunctionAppTriggerUrl.png) + ![Get function URL](../../../media/AMBA-FunctionAppTriggerUrl.png) - {{< hint type=note >}} - It is possible use multiple email addresses, as well as multiple Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). Should you set multiple entries, make sure they are entered as single string with values separated by comma. Example: - - action1@contoso.com , action2@contoso.com , action3@contoso.com - - https://webhookUri1.webhook.com, http://webhookUri2.webhook.com - - {{< /hint >}} + {{< hint type=note >}} + It is possible use multiple email addresses, as well as multiple Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). + Should you set multiple entries, make sure they are entered as single string with values separated by comma. Example: + - action1@contoso.com , action2@contoso.com , action3@contoso.com + - https://webhookUri1.webhook.com, http://webhookUri2.webhook.com + {{< /hint >}} ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/Deploy-with-Azure-CLI.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md similarity index 81% rename from docs/content/patterns/alz/deploy/Deploy-with-Azure-CLI.md rename to docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md index 5a9b8a4e3..54589813d 100644 --- a/docs/content/patterns/alz/deploy/Deploy-with-Azure-CLI.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md @@ -35,10 +35,13 @@ Using your preferred command-line tool (Windows PowerShell, Cmd, Bash or other U {{< hint type=note >}} This should be tested in a safe environment. If you are subsequently looking to deploy to prod environments, consider leveraging the guidance found in [Customize Policy Assignment](../Customize-Policy-Assignment), to deploy and enable alerts in a controlled manner. -If you customized the policies as documented at [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), make sure the run the deployment command using your own repository and branch in the ***--template-uri*** parameter value. Example: +If you customized the policies as documented at [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), make sure the run the deployment command using your own repository and branch in the _*_**--template-uri**_*_ parameter value. Example: + + ```bash + az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main + or branchname***/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" + ``` - az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main - or branchname***/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" {{< /hint >}} ```bash @@ -48,3 +51,5 @@ az deployment mg create --name "amba-GeneralDeployment" --template-uri https://r ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/Deploy-with-Azure-Pipelines.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md similarity index 61% rename from docs/content/patterns/alz/deploy/Deploy-with-Azure-Pipelines.md rename to docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md index 9782407b3..c24251b46 100644 --- a/docs/content/patterns/alz/deploy/Deploy-with-Azure-Pipelines.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md @@ -10,15 +10,16 @@ weight: 50 First configure your Azure DevOps project with a pipeline hosted in GitHub as described [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/github?view=azure-devops&tabs=yaml#access-to-github-repositories). The pipeline should be configured to use the [sample-pipeline.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-pipeline.yml) file. {{< hint type=note >}} -If you customized the policies as documented at [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), make sure to modify the pipeline file to have the **inlineScript** pointing to your own repository and branch. Example: +If you customized the policies as documented at [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), make sure to modify the pipeline file to have the **inlineScript** pointing to your own repository and branch. Example: - inlineScript: | - az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main - or branchname***/patterns/alz/alzArm.json --location $(location) --management-group-id $(ManagementGroupPrefix) --parameters .\patterns\alz\alzArm.param.json + ```ActionScript + inlineScript: | + az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/___YourGithubFork___/azure-monitor-baseline-alerts/___MainOrBranchname___/patterns/alz/alzArm.json --location $(location) --management-group-id $(ManagementGroupPrefix) --parameters .\patterns\alz\alzArm.param.json + ``` {{< /hint >}} -Also in your Azure DevOps project, configure a service connection to your Azure subscription as described [here](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&tabs=yaml). The service connection should target the intermediate root management group for ALZ aligned deployments or the management group where you wish to deploy the policies and the initiatives for ALZ unaligned deployments. +Also in your Azure DevOps project, configure a service connection to your Azure subscription as in the [Connect to Azure by using an Azure Resource Manager service connection](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&tabs=yaml) guide. The service connection should target the intermediate root management group for ALZ aligned deployments or the management group where you wish to deploy the policies and the initiatives for ALZ unaligned deployments. ### Modify variables and run the pipeline @@ -36,3 +37,5 @@ The location variable refers to the deployment location. Deploying to multiple r ## Next steps To remediate non-compliant policies, please continue with [Policy remediation](../Remediate-Policies) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/Deploy-with-Azure-PowerShell.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md similarity index 82% rename from docs/content/patterns/alz/deploy/Deploy-with-Azure-PowerShell.md rename to docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md index 44eb1fabc..eacfabae8 100644 --- a/docs/content/patterns/alz/deploy/Deploy-with-Azure-PowerShell.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md @@ -42,11 +42,14 @@ Using a PowerShell prompt, if you closed your previous session, navigate again t {{< hint type=note >}} This should be tested in a safe environment. If you are later looking to deploy to prod environments, consider using the guidance found in [Customize Policy Assignment](../Customize-Policy-Assignment), to deploy and enable alerts in a controlled manner. -If you customized the policies as documented at [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), make sure the run the deployment command using your own repository and branch in the _***-TemplateUri***_ parameter value. Example: +If you customized the policies as documented at [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), make sure the run the deployment command using your own repository and branch in the _**-TemplateUri**_ parameter value. Example: + + ```PowerShell + New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location + -TemplateUri "https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or branchname***/patterns/alz/alzArm.json" + -TemplateParameterFile ".\patterns\alz\alzArm.param.json" + ``` - New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location - -TemplateUri "https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or branchname***/patterns/alz/alzArm.json" - -TemplateParameterFile ".\patterns\alz\alzArm.param.json" {{< /hint >}} ```powershell @@ -56,3 +59,5 @@ New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupI ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/Deploy-with-GitHub-Actions.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md similarity index 79% rename from docs/content/patterns/alz/deploy/Deploy-with-GitHub-Actions.md rename to docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md index c34f43d4d..4de72c3e8 100644 --- a/docs/content/patterns/alz/deploy/Deploy-with-GitHub-Actions.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md @@ -14,9 +14,10 @@ To deploy through GitHub actions, refer to the [sample-workflow.yml](https://git {{< hint type=note >}} If you customized the policies as documented at [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), make sure to modify the workflow file to have the **run** pointing to your own repository and branch. Example: - run: | - az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or - branchname***/patterns/alz/alzArm.json --location ${{ env.Location }} --management-group-id ${{ env.ManagementGroupPrefix }} --parameters .\patterns\alz\alzArm.param.json + ```ActionScript + run: | + az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/___YourGithubFork___/azure-monitor-baseline-alerts/___MainOrBranchname___/patterns/alz/alzArm.json --location ${{ env.Location }} --management-group-id ${{ env.ManagementGroupPrefix }} --parameters .\patterns\alz\alzArm.param.json + ``` {{< /hint >}} @@ -31,15 +32,15 @@ If you customized the policies as documented at [How to modify individual polici The file name _**must perfectly**_ match the name at line **1** of the sample file. You can eventually replace spaces with **-** {{< /hint >}} - ![Workflow file name](../../media/WorkflowFileName.png) + ![Workflow file name](../../../media/WorkflowFileName.png) - ![Workflow saved](../../media/WorkflowSaved.png) + ![Workflow saved](../../../media/WorkflowSaved.png) More information about workflow is available in the GitHub documentation at [Creating starter workflows for your organization](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) -- Go to GitHub actions and run the action ***Deploy AMBA*** +- Go to GitHub actions and run the action _**Deploy AMBA**_ - ![Deploy AMBA action](../../media/DeployAmbaAction.png) + ![Deploy AMBA action](../../../media/DeployAmbaAction.png) {{< hint type=important >}} Above-mentioned "ManagementGroupPrefix" variable value, being the so called "pseudo root management group id", should _coincide_ with the value of the "parPolicyPseudoRootMgmtGroup" parameter, as set previously within the parameter files. @@ -50,3 +51,5 @@ The location variable refers to the deployment location. Deploying to multiple r ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/Introduction-to-deploying-the-ALZ-Pattern.md b/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md similarity index 93% rename from docs/content/patterns/alz/deploy/Introduction-to-deploying-the-ALZ-Pattern.md rename to docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md index 06f360400..7ce1ef9c8 100644 --- a/docs/content/patterns/alz/deploy/Introduction-to-deploying-the-ALZ-Pattern.md +++ b/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md @@ -22,7 +22,7 @@ Alerts, action groups and alert processing rules are created as follows: ## Prerequisites 1. Microsoft Entra ID Tenant. -2. ALZ Management group hierarchy deployed as described [here](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-areas).* +2. ALZ Management group hierarchy deployed as described in the [Azure landing zone design areas and conceptual architecture](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-areas) Microsoft public documentation. 3. Minimum one subscription, for when deploying alerts through policies. 4. Deployment Identity with `Owner` permission to the pseudo root management group. Owner permission is required to allow the Service Principal Account to create role-based access control assignments. 5. If deploying manually, i.e. via Azure CLI or PowerShell, ensure that you have [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview?tabs=bicep) installed and working, before attempting installation. See here for how to configure for [Azure CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-cli) and here for [PowerShell](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-powershell) @@ -32,7 +32,7 @@ Alerts, action groups and alert processing rules are created as follows: See [here](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) for details on how to register a resource provider should you need to do so. -7. For leveraging the log alerts for Virtual Machines, ensure that VM Insights is enabled for the Virtual Machines to be monitored. For more information on VM Insights deployment, see [here](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-enable-overview) . Note only the performance collection of the VM insights solution is required for the current alerts to deploy. +7. For leveraging the log alerts for virtual machines (both Azure and Azure Arc), ensure that VM Insights is enabled for the virtual machines to be monitored. For more information on VM Insights deployment, see [here](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-enable-overview) . Note only the performance collection of the VM insights solution is required for the current alerts to deploy. {{< hint type=note >}} While it´s recommended to implement the alert policies and initiatives to an ALZ Management Group hierarchy, it is not a technical requirement (avoid Tenant Root Group assignments, to minimize debugging inherited policies at lower-level mangement groups, see [CAF documentation](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups)). These policies and initiatives can be implemented in existing brownfield scenarios that don´t adhere to the ALZ Management Group hierarchy. For example, in hierarchies where there is a single management group, or where the structure does not align to ALZ. At least one management group is required. In case you haven't implemented management groups, we included guidance on how to get started. @@ -62,13 +62,13 @@ The initiatives provided in this repository align with the management group hier The image below is an example of how a management group hierarchy looks like when you follow Azure Landing Zone guidance. Also illustrated in this image is the default recommended assignments of the initiatives. -![ALZ Management group structure](../../media/alz-management-groups.png) +![ALZ Management group structure](../../../media/alz-management-groups.png) The diagram below shows the flow using the orange dash-lines of the policy initiatives and their associated policy definitions. Notice how the Service Health Initiative is assigned at the pseudo root of the management group structure in this case the Contoso management group. This initiative contains the policy that deploys the alert processing rules and action group to each subscription. The other monitoring initiatives are each assigned at specific platform landing zone management groups and workload landing zones. The flows for these are in blue dash-lines. -![Azure Monitor Baseline Alerts policy initiative flows](../../media/azure-monitor-baseline-alerts-policy-initiative-flow.svg) +![Azure Monitor Baseline Alerts policy initiative flows](../../../media/azure-monitor-baseline-alerts-policy-initiative-flow.svg) *Download a [Visio file](../../media/AMBA-Diagrams.vsdx) of this architecture.* @@ -100,7 +100,7 @@ Suppose Identity / Management / Connectivity are combined in one Platform Manage The image below is an example of how the assignments could look like when the management group hierarchy is not aligned with ALZ. -![Management group structure - unaligned](../../media/alz-management-groups-unaligned.png) +![Management group structure - unaligned](../../../media/alz-management-groups-unaligned.png) We recommend that you review the [initiative definitions](https://github.com/Azure/azure-monitor-baseline-alerts/tree/main/patterns/alz/policySetDefinitions) to determine where best to apply the initiatives in your management group hierarchy. @@ -130,7 +130,7 @@ To prevent unnecessary alerts, we recommend keeping development, sandbox, and ot The image below is an example of how the assignments look like when you are using a single management group. -![Management group structure - single](../../media/alz-management-groups-single.png) +![Management group structure - single](../../../media/alz-management-groups-single.png) ## Customizing policy assignments @@ -197,3 +197,5 @@ In some scenarios, it may be necessary to remove everything deployed by the ALZ - To deploy with Azure Pipelines, please proceed with [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../Deploy-with-Azure-CLI) - To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/PowerShell-ExecutionPolicy.md b/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md similarity index 100% rename from docs/content/patterns/alz/deploy/PowerShell-ExecutionPolicy.md rename to docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md diff --git a/docs/content/patterns/alz/deploy/Remediate-Policies.md b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md similarity index 93% rename from docs/content/patterns/alz/deploy/Remediate-Policies.md rename to docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md index c064d637c..7315ad686 100644 --- a/docs/content/patterns/alz/deploy/Remediate-Policies.md +++ b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md @@ -21,7 +21,7 @@ To use the script, do the following: - Set the variables - Run the remediation script - {{% include "PowerShell-ExecutionPolicy.md" %}} + {{% include "./PowerShell-ExecutionPolicy.md" %}} - For example, to remediate **Alerting-Management** initiative, assigned to the **alz-platform-management** Management Group run the following commands: @@ -65,9 +65,11 @@ $LZManagementGroup="The management group id for Landing Zones" .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-Web ``` -Should you need to remediate just one policy definition and not the entire policy initiative, you can run the remediation script targeted at the policy reference id that can be found under [Policy Initiatives](../../Policy-Initiatives). For example, to remediate the ***Deploy AMBA Notification Assets*** policy, run the command below: +Should you need to remediate just one policy definition and not the entire policy initiative, you can run the remediation script targeted at the policy reference id that can be found under the [Policy Initiatives](../../../Getting-started/Policy-Initiatives) page. For example, to remediate the ***Deploy AMBA Notification Assets*** policy, run the command below: ```powershell #Run the following command to initiate remediation of a single policy definition .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName ALZ_AlertProcessing_Rule ``` + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/deploy/_index.md b/docs/content/patterns/alz/HowTo/deploy/_index.md similarity index 100% rename from docs/content/patterns/alz/deploy/_index.md rename to docs/content/patterns/alz/HowTo/deploy/_index.md diff --git a/docs/content/patterns/alz/deploy/parameterConfiguration.md b/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md similarity index 89% rename from docs/content/patterns/alz/deploy/parameterConfiguration.md rename to docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md index e545ac0f3..f63097e48 100644 --- a/docs/content/patterns/alz/deploy/parameterConfiguration.md +++ b/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md @@ -3,7 +3,7 @@ title: Parameter configuration geekdocHidden: true --- {{< hint type=Important >}} -Updating from the _**preview**_ version is not supported. If you deployed the _**preview**_ version, please proceed with [Moving from preview to GA](../../Moving-from-preview-to-GA) before continuing. +Updating from the _**preview**_ version is not supported. If you deployed the _**preview**_ version, please proceed with [Moving from preview to GA](../../../Resources/Moving-from-preview-to-GA) before continuing. {{< /hint >}} ## 1. Parameter configuration @@ -32,7 +32,7 @@ The following changes apply to all scenarios, whether you are aligned or unalign - Change the value of _```ALZLogicappResourceId```_ to the Logic app resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. - Change the value of _```ALZLogicappCallbackUrl```_ to the Logic app callback url of the Logic app you want to use as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. To retrieve the callback url you can either use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/en-us/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic app in the Azure portal, go to _**Logic app designer**_, expand the trigger activity (_When an HTTP request is received_) and copy the value in the URL field using the 2-sheets icon. - ![Get Logic app callback url](../../media/AMBA-LogicAppCallbackUrl.png) + ![Get Logic app callback url](../../../media/AMBA-LogicAppCallbackUrl.png) - Change the value of _```ALZArmRoleId```_ to the Azure Resource Manager Role(s) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no Azure Resource Manager Role notification is required. - Change the value of _```ALZEventHubResourceId```_ to the Event Hubs to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Event Hubs is used. @@ -40,22 +40,32 @@ The following changes apply to all scenarios, whether you are aligned or unalign - Change the value of _```ALZFunctionResourceId```_ to the Function resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. - Change the value of _```ALZFunctionTriggerUrl```_ to the Function App trigger url of the function to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. To retrieve the Function App trigger url with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the menu top menu and copy the value in the URL field using the 2-sheets icon. - ![Get function URL](../../media/AMBA-FunctionAppTriggerUrl.png) + ![Get function URL](../../../media/AMBA-FunctionAppTriggerUrl.png) {{< hint type=note >}} It is possible use multiple email addresses, as well as multiple Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). Should you set multiple entries, make sure they are entered as single string with values separated by comma. Example: - "ALZMonitorActionGroupEmail": { - "value": "action1@contoso.com , action2@contoso.com , action3@contoso.com" - }, - - "ALZArmRoleId": { - "value": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635, b24988ac-6180-42a0-ab88-20f7382dd24c" - }, + ```json + "ALZMonitorActionGroupEmail": { + "value": [ + "action1@contoso.com", + "action2@contoso.com" + ] + }, + "ALZArmRoleId": { + "value": [ + "8e3af657-a8ff-443c-a75c-2fe8c4bcb635", + "b24988ac-6180-42a0-ab88-20f7382dd24c" + ] + }, + "ALZWebhookServiceUri": { + "value": [ + "https://webookURI1.webook.com", + "http://webookURI2.webook.com" + ] + } + ``` - "ALZWebhookServiceUri": { - "value": "https://webhookUri1.webhook.com, http://webhookUri2.webhook.com" - }, {{< /hint >}} - If you would like to disable initiative assignments, you can change the value on one or more of the following parameters; _```enableAMBAConnectivity```_, _```enableAMBAIdentity```_, _```enableAMBALandingZone```_, _```enableAMBAManagement```_, _```enableAMBAServiceHealth```_ to _**"No"**_. @@ -125,9 +135,6 @@ The parameter file shown below has been truncated for brevity, compared to the s "enableAMBAIdentity": { "value": "Yes" }, - "enableAMBALandingZone": { - "value": "Yes" - }, "enableAMBAManagement": { "value": "Yes" }, @@ -140,6 +147,27 @@ The parameter file shown below has been truncated for brevity, compared to the s "enableAMBAHybridVM": { "value": "Yes" }, + "enableAMBAKeyManagement": { + "value": "Yes" + }, + "enableAMBALoadBalancing": { + "value": "Yes" + }, + "enableAMBANetworkChanges": { + "value": "Yes" + }, + "enableAMBARecoveryServices": { + "value": "Yes" + }, + "enableAMBAStorage": { + "value": "Yes" + }, + "enableAMBAVM": { + "value": "Yes" + }, + "enableAMBAWeb": { + "value": "Yes" + }, "telemetryOptOut": { "value": "No" }, @@ -165,7 +193,18 @@ The parameter file shown below has been truncated for brevity, compared to the s "value": { "Project": "amba-monitoring" } - } + }, + "ALZMonitorDisableTagName": { + "value": "MonitorDisable" + }, + "ALZMonitorDisableTagValues": { + "value": [ + "true", + "Test", + "Dev", + "Sandbox" + ] + }, . . . diff --git a/docs/content/patterns/alz/Overview/ALZ-Pattern.md b/docs/content/patterns/alz/Overview/ALZ-Pattern.md new file mode 100644 index 000000000..7577df377 --- /dev/null +++ b/docs/content/patterns/alz/Overview/ALZ-Pattern.md @@ -0,0 +1,99 @@ +--- +title: The ALZ pattern +geekdocCollapseSection: true +weight: 10 +--- + + +## Overview + +One of the most common questions faced when working with customers is, "What should we monitor in Azure?" and "What thresholds should we configure our alerts for?" + +There isn't definitive list of what you should monitor when you deploy something to Azure because "it depends", on what services you're using and how the services are used, which will in turn dictate what you should monitor and what thresholds the metrics you do decide to collect are and what errors you should alert on in logs. + +Microsoft has tried to address this by providing a number of 'insights or solutions' for popular services which pull together all the things you should care about ([Storage Insights](https://learn.microsoft.com/en-us/azure/storage/common/storage-insights-overview), [VM Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-overview), [Container Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/container-insights-overview)); but what about everything else??? + +The purpose of this project is to focus on monitoring for Azure Landing Zone as a common set of Azure resources/services that are configured in a similar way across organizations. We know that every organization is different, as such we also include guidance on how this can be used in custom brownfield scenarios that don´t align with ALZ. This provided us with a starting point on addressing "What should be monitored in Azure?" It also provides an example of how to monitor-at-scale while leveraging Infrastructure-as-code principles. +This project is an opinionated view on what you should monitor for the key components of your Azure Landing Zone within the Platform and Landing Zone scope. i.e: + +- Express Route Circuits +- Express Route Gateways +- Express Route Ports +- Azure Firewalls +- Application Gateways +- Load balancers +- Virtual Networks +- Virtual Network Gateways +- Log Analytics workspaces +- Private DNS zones +- Azure Key Vaults +- Virtual Machine +- Service health + +Monitoring baselines for the above components are proposed to be deployed leveraging Azure Policy and has been bundled into Azure Policy initiatives for ease of deployment and management. In addition to the components mentioned there are also a number of other component alerts included in the repo, but outside any initiatives, or disabled by default. These components are: + +- Storage accounts +- Network security groups +- Azure route tables + +In addition to the component specific alerts mentioned above the repo also contains policies for deploying service health alerts by subscription. + +Alerts are based on Microsoft public guidance where available, and on practical application experience where public guidance is not available. For more details on which alerts are included please refer to [Alert Details](../../Getting-started/Alerts-Details). + +For details on how policies are grouped into initiatives please refer to [Azure Policy Initiatives](../../Getting-started/Policy-Initiatives) + +In addition to the above of course the alerts need to go somewhere. To that end a generic action group and alert processing rule is deployed to every subscription in scope, also via policy. For more details around this, as well as the reasoning behind this approach please refer to [Monitoring and Alerting](../../Getting-started/Monitoring-and-Alerting). + +## 📣Feedback 📣 + +Once you've had an opportunity to deploy the solution we'd love to hear from you! Click [here](https://aka.ms/alz/monitor/feedback) to leave your feedback. + +If you have encountered a problem please file an issue in our GitHub repo [GitHub Issue](https://github.com/Azure/azure-monitor-baseline-alerts/issues). + +## Deployment Guide + +We have a [Deployment Guide](../../Howto/deploy/Introduction-to-deploying-the-ALZ-Pattern) available for guidance on how to consume the contents of this repo. + +## Known Issues + +Please see the [Known Issues](../../Resources/Known-Issues). + +## Frequently Asked Questions + +Please see the [Frequently Asked Questions](../../Resources/FAQ). + +## Contributing + +This project welcomes contributions and suggestions. +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. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +{{< hint type=note >}} +Details on contributing to this repo can be found in the [Contributor Guide](../../../../contributing) +{{< /hint >}} + +## Telemetry + +When you deploy the IP located in this repo, Microsoft can identify the installation of said IP with the deployed Azure resources. Microsoft can correlate these resources used to support the software. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through customer usage attribution. The data is collected and governed by [Microsoft's privacy policies](https://www.microsoft.com/trustcenter). + +If you don't wish to send usage data to Microsoft, or need to understand more about its' use details can be found in the [Disable telemetry tracking](../../Howto/Telemetry) guide. + +## Trademarks + +This project may contain trademarks or logos for projects, products, or services. +Authorized use of Microsoft trademarks or logos is subject to and must follow +[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). +Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. +Any use of third-party trademarks or logos are subject to those third-party's policies. + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Whats-New.md b/docs/content/patterns/alz/Overview/Whats-New.md similarity index 84% rename from docs/content/patterns/alz/Whats-New.md rename to docs/content/patterns/alz/Overview/Whats-New.md index 4d13f6442..432f6a033 100644 --- a/docs/content/patterns/alz/Whats-New.md +++ b/docs/content/patterns/alz/Overview/Whats-New.md @@ -6,13 +6,13 @@ weight: 10 For information on what's new please refer to the [Releases](https://github.com/Azure/azure-monitor-baseline-alerts/releases) page. -To update your current deployment with the content from the latest release, please refer to the [Update to new releases](../UpdateToNewReleases) page. +To update your current deployment with the content from the latest release, please refer to the [Update to new releases](../../HowTo/UpdateToNewReleases) guide. ## 2024-06-05 ### New features -- Added new PIDs for different additional deployment methods. Refer to [Telemetry](../Telemetry) for more information. +- Added new PIDs for different additional deployment methods. Refer to the [Disable telemetry tracking](../../HowTo/Telemetry) guide for more information. - Added new initiative to monitor Azure Arc-enabled Virtual Machines. [Alerting-HybridVM](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/policySetDefinitions/Deploy-HybridVM-Alerts.json) ### Bug fixes @@ -32,9 +32,9 @@ To update your current deployment with the content from the latest release, plea - Updated Existence Condition to detect and remediate configuration drift. The following parameters were added to the Existence Condition of the policies: - Static alerts: EvaluationFrequency, WindowSize, Threshold, Severity, Operator, autoMitigate - Dynamic alerts: alertSensitivity, numberOfEvaluationPeriods, minFailingPeriodsToAlert -- Added a suppression Alert Processing Rule, deployed as part of the notification Assets policy. Refer to [Temporarily disabling notifications](../Temporarily-disabling-notifications) for more details. +- Added a suppression Alert Processing Rule, deployed as part of the notification Assets policy. Refer to the [Temporarily disabling notifications](../../HowTo/Temporarily-disabling-notifications) guide for more details. - Supplying an email address for the Action Group is no longer mandatory. -- Bring your own Action Group and/or Alert Processing Rules. This feature will allow brownfield customers to use existing Action Groups and Alert Processing Rules. Please refer to [Bring Your Own Notifications (BYON)](../Bring-your-own-Notifications) for more details. +- Bring your own Action Group and/or Alert Processing Rules. This feature will allow brownfield customers to use existing Action Groups and Alert Processing Rules. Please refer to the [Bring Your Own Notifications (BYON)](../../HowTo/Bring-your-own-Notifications) guide for more details. ### Bug fixes @@ -70,7 +70,7 @@ To update your current deployment with the content from the latest release, plea ### Documentation updates - Updated [Deploy with GitHub Actions](../deploy/Deploy-with-GitHub-Actions) addressing [Issue #102](https://github.com/Azure/azure-monitor-baseline-alerts/issues/102) -- Updated guidance for AMA in [Monitoring and Alerting](../Monitoring-and-Alerting) documentation +- Updated guidance for AMA in [Monitoring and Alerting](../../Getting-started/Monitoring-and-Alerting) documentation ## 2023-11-14 @@ -92,7 +92,9 @@ To update your current deployment with the content from the latest release, plea ### Documentation updates -- How to modify individual policies - [How to modify individual policies](../deploy/Introduction-to-deploying-the-ALZ-Pattern/#how-to-modify-individual-policies) -- Added guidance to only Server Health alert rules - [Deploy only Service Health Alerts](../deploy/Deploy-only-Service-Health-Alerts) -- New documentation on updating to a new release - [Update to new releases](../UpdateToNewReleases) -- FAQ Updates - [Frequently Asked Questions](../FAQ) +- How to modify individual policies - [How to modify individual policies](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern/#how-to-modify-individual-policies) +- Added guidance to only Server Health alert rules - [Deploy only Service Health Alerts](../../HowTo/deploy/Deploy-only-Service-Health-Alerts) +- New documentation on updating to a new release - [Update to new releases](../../HowTo/UpdateToNewReleases) +- FAQ Updates - [Frequently Asked Questions](../../Resources//FAQ) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Overview/_index.md b/docs/content/patterns/alz/Overview/_index.md new file mode 100644 index 000000000..cb2845032 --- /dev/null +++ b/docs/content/patterns/alz/Overview/_index.md @@ -0,0 +1,6 @@ +--- +title: Overview +geekdocCollapseSection: true +weight: 10 +--- + diff --git a/docs/content/patterns/alz/FAQ.md b/docs/content/patterns/alz/Resources/FAQ.md similarity index 99% rename from docs/content/patterns/alz/FAQ.md rename to docs/content/patterns/alz/Resources/FAQ.md index 6a06d319c..8cf4dd6e0 100644 --- a/docs/content/patterns/alz/FAQ.md +++ b/docs/content/patterns/alz/Resources/FAQ.md @@ -32,7 +32,7 @@ weight: 80 ## Can I disable the alerts being deployed for a resource or subscription? -> Yes, please refer to the disabling monitoring documentation [Disabling Policies](../Disabling-Policies) +> Yes, please refer to the disabling monitoring documentation [Disabling Policies](../../HowTo/Disabling-Policies) ## How much does it cost to run the ALZ Baseline solution? @@ -82,3 +82,5 @@ weight: 80 > - Resource creation will fail > - Action group and/or Alert Processing Rules deployment will fail. Specifically to AMBA we have this one documented in the specific [Failed to deploy action group(s) and/or alert processing rule(s)](../Known-Issues#failed-to-deploy-action-groups-andor-alert-processing-rules) article included in the [Known Issues](../Known-Issues) > - Action group editing will result in Azure portal page error. Specifically to AMBA we have this one documented in the specific [Failed to edit action group(s)](../Known-Issues#failed-to-edit-action-groups) article included in the [Known Issues](../Known-Issues) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Known-Issues.md b/docs/content/patterns/alz/Resources/Known-Issues.md similarity index 89% rename from docs/content/patterns/alz/Known-Issues.md rename to docs/content/patterns/alz/Resources/Known-Issues.md index 62b320fda..ef03d832e 100644 --- a/docs/content/patterns/alz/Known-Issues.md +++ b/docs/content/patterns/alz/Resources/Known-Issues.md @@ -32,7 +32,7 @@ weight: 100 > > ### Resolution > -> For VM Alerts, enable [VM Insights](../Monitoring-and-Alerting#log-alerts). After VM Insights is enabled, run the remediation again. +> For VM Alerts, enable [VM Insights](../../Getting-started/Monitoring-and-Alerting#log-alerts). After VM Insights is enabled, run the remediation again. ## Failed to deploy because of role assignment issue @@ -54,7 +54,7 @@ weight: 100 > ### Resolution > > 1. Navigate to **_Management Groups_** -> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) were AMBA deployment was targeted to +> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) were AMBA-ALZ deployment was targeted to > 3. Select **_Access control (IAM)_** > 4. Under the **_Contributor_** role, select all records named **_Identity not found_** entry and click **_Remove_** > 5. Run the deployment @@ -69,7 +69,7 @@ weight: 100 > > ### Cause > -> A deployment has been performed using one region, for example "uksouth", and when you try to deploy again to the same scope but to a different region you will receive an error. This happens even when a cleanup has been performed (see [Cleaning up a Deployment](../Cleaning-up-a-Deployment) for more details). This is because deployment entries still exist from the previous operation, so a region conflict is detected blocking you to run another deployment using a different region. +> A deployment has been performed using one region, for example "uksouth", and when you try to deploy again to the same scope but to a different region you will receive an error. This happens even when a cleanup has been performed (see [Cleaning up a Deployment](../../HowTo/Cleaning-up-a-Deployment) for more details). This is because deployment entries still exist from the previous operation, so a region conflict is detected blocking you to run another deployment using a different region. > > ### Resolution > @@ -145,13 +145,13 @@ If you deployed AMBA-ALZ just one time, you have 14 deployment instances > > ### Cause > -> The new [Bring Your Own User Assigned Managed Identity (BYO UAMI)](../Bring-your-own-Managed-Identity) allows you to either use an existing User Assigned Managed Identity (UAMI) or to create a new one in the management subscription automatically assigning the Monitoring reader role to it at the parent pseudo root Management Group. If you opted for creating a new UAMI, the management subscription id is needed. +> The new [Bring Your Own User Assigned Managed Identity (BYO UAMI)](../../HowTo/Bring-your-own-Managed-Identity) allows you to either use an existing User Assigned Managed Identity (UAMI) or to create a new one in the management subscription automatically assigning the Monitoring reader role to it at the parent pseudo root Management Group. If you opted for creating a new UAMI, the management subscription id is needed. > > ### Resolution > > Set the parameter for the management subscription id correctly in the parameter file: > -> ![New UAMI deployed by the template](../media/alz-UAMI-Param-Example-2.png) +> ![New UAMI deployed by the template](../../media/alz-UAMI-Param-Example-2.png) ## Failed to deploy action group(s) and/or alert processing rule(s) @@ -184,7 +184,7 @@ If you deployed AMBA-ALZ just one time, you have 14 deployment instances > Editing a previously deployed action group is returning a misleading error in the Azure portal page. > -> ![Api-version required error](../media/api-version_required.png) +> ![Api-version required error](../../media/api-version_required.png) > > ### Error includes > @@ -207,3 +207,5 @@ If you deployed AMBA-ALZ just one time, you have 14 deployment instances > - **_0_** through **_9_** (numbers) > > After the subscription is renamed correctly, remove the existing action groups (those whose name starts with either **_ag-AMBA-_** or **_ag-AMBA-SH-_**) and run the remediation. + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Moving-from-preview-to-GA.md b/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md similarity index 91% rename from docs/content/patterns/alz/Moving-from-preview-to-GA.md rename to docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md index 5ba3ac794..684381952 100644 --- a/docs/content/patterns/alz/Moving-from-preview-to-GA.md +++ b/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md @@ -62,8 +62,10 @@ Follow the instructions below to download the cleanup script file. Alternatively ## Next steps -- To customize policy assignments, please proceed with [Customize Policy Assignment](../deploy/Customize-Policy-Assignment) -- 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) +- To customize policy assignments, please proceed with [Customize Policy Assignment](../../HowTo/deploy/Customize-Policy-Assignment) +- To deploy with GitHub Actions, please proceed with [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions) +- To deploy with Azure DevOps Pipelines, please proceed with [Deploy with Azure Pipelines](../../HowTo/deploy/Deploy-with-Azure-Pipelines) +- To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../../HowTo/deploy/Deploy-with-Azure-CLI) +- To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../../HowTo/deploy/Deploy-with-Azure-PowerShell) + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Versioning.md b/docs/content/patterns/alz/Resources/Versioning.md similarity index 97% rename from docs/content/patterns/alz/Versioning.md rename to docs/content/patterns/alz/Resources/Versioning.md index 9e8b04214..8ac905bff 100644 --- a/docs/content/patterns/alz/Versioning.md +++ b/docs/content/patterns/alz/Resources/Versioning.md @@ -9,3 +9,5 @@ The primary deliverable of this repo is a collection of Azure Policy initiatives While this is sufficient for the purposes of individual policies, to further ease adoption of the policies a new release of the repo as a whole will be made available as one or more policies are updated with breaking changes as per the [Azure Policy versioning guidance](https://github.com/Azure/azure-policy/blob/master/built-in-policies/README.md#versioning). As new versions are released, update guidance will be provided to allow you to update your existing deployments to the new version. + +[Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/_index.md b/docs/content/patterns/alz/Resources/_index.md new file mode 100644 index 000000000..0ef679457 --- /dev/null +++ b/docs/content/patterns/alz/Resources/_index.md @@ -0,0 +1,5 @@ +--- +title: Resources +geekdocCollapseSection: true +weight: 40 +--- diff --git a/docs/content/patterns/alz/_index.md b/docs/content/patterns/alz/_index.md index 8ffcb201c..8f5301106 100644 --- a/docs/content/patterns/alz/_index.md +++ b/docs/content/patterns/alz/_index.md @@ -2,94 +2,3 @@ title: Azure Landing Zones geekdocCollapseSection: true --- - -## Overview - -One of the most common questions faced when working with customers is, "What should we monitor in Azure?" and "What thresholds should we configure our alerts for?" - -There isn't definitive list of what you should monitor when you deploy something to Azure because "it depends", on what services you're using and how the services are used, which will in turn dictate what you should monitor and what thresholds the metrics you do decide to collect are and what errors you should alert on in logs. - -Microsoft has tried to address this by providing a number of 'insights or solutions' for popular services which pull together all the things you should care about ([Storage Insights](https://learn.microsoft.com/en-us/azure/storage/common/storage-insights-overview), [VM Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-overview), [Container Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/container-insights-overview)); but what about everything else??? - -The purpose of this project is to focus on monitoring for Azure Landing Zone as a common set of Azure resources/services that are configured in a similar way across organizations. We know that every organization is different, as such we also include guidance on how this can be used in custom brownfield scenarios that don´t align with ALZ. This provided us with a starting point on addressing "What should be monitored in Azure?" It also provides an example of how to monitor-at-scale while leveraging Infrastructure-as-code principles. -This project is an opinionated view on what you should monitor for the key components of your Azure Landing Zone within the Platform and Landing Zone scope. i.e: - -- Express Route Circuits -- Express Route Gateways -- Express Route Ports -- Azure Firewalls -- Application Gateways -- Load balancers -- Virtual Networks -- Virtual Network Gateways -- Log Analytics workspaces -- Private DNS zones -- Azure Key Vaults -- Virtual Machine -- Service health - -Monitoring baselines for the above components are proposed to be deployed leveraging Azure Policy and has been bundled into Azure Policy initiatives for ease of deployment and management. In addition to the components mentioned there are also a number of other component alerts included in the repo, but outside any initiatives, or disabled by default. These components are: - -- Storage accounts -- Network security groups -- Azure route tables - -In addition to the component specific alerts mentioned above the repo also contains policies for deploying service health alerts by subscription. - -Alerts are based on Microsoft public guidance where available, and on practical application experience where public guidance is not available. For more details on which alerts are included please refer to [Alert Details](../alz/Alerts-Details). - -For details on how policies are grouped into initiatives please refer to [Azure Policy Initiatives](../alz/Policy-Initiatives) - -In addition to the above of course the alerts need to go somewhere. To that end a generic action group and alert processing rule is deployed to every subscription in scope, also via policy. For more details around this, as well as the reasoning behind this approach please refer to [Monitoring and Alerting](../alz/Monitoring-and-Alerting). - -## 📣Feedback 📣 - -Once you've had an opportunity to deploy the solution we'd love to hear from you! Click [here](https://aka.ms/alz/monitor/feedback) to leave your feedback. - -If you have encountered a problem please file an issue in our GitHub repo [GitHub Issue](https://github.com/Azure/azure-monitor-baseline-alerts/issues). - -## Deployment Guide - -We have a [Deployment Guide](../alz/deploy/Introduction-to-deploying-the-ALZ-Pattern) available for guidance on how to consume the contents of this repo. - -## Known Issues - -Please see the [Known Issues](../alz/Known-Issues). - -## Frequently Asked Questions - -Please see the [Frequently Asked Questions](../alz/FAQ). - -## Contributing - -This project welcomes contributions and suggestions. -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. - -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. - -{{< hint type=note >}} -Details on contributing to this repo can be found [here](../../contributing/patterns) -{{< /hint >}} - -## Telemetry - -When you deploy the IP located in this repo, Microsoft can identify the installation of said IP with the deployed Azure resources. Microsoft can correlate these resources used to support the software. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through customer usage attribution. The data is collected and governed by [Microsoft's privacy policies](https://www.microsoft.com/trustcenter). - -If you don't wish to send usage data to Microsoft, or need to understand more about its' use details can be found [here](../alz/Telemetry). - -## Trademarks - -This project may contain trademarks or logos for projects, products, or services. -Authorized use of Microsoft trademarks or logos is subject to and must follow -[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). -Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. -Any use of third-party trademarks or logos are subject to those third-party's policies. diff --git a/docs/content/patterns/alz/media/BYON_Params_3.png b/docs/content/patterns/alz/media/BYON_Params_3.png index ec10588d5dd68e3b041b62b8c8fd7aa8a7a1d0cf..7e5ce51863ce77c3f53e830dbc93f7a9ba311cdb 100644 GIT binary patch literal 81259 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 &C^^PT79Ugg8yhWQ0G&7+j9bKWcd;EZC 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

XY#GXaJ8&r6b`G;5%cZ=-DcCrpb7W8 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 From b96330d4be39eb9c7156a0771841c14f00b8342b Mon Sep 17 00:00:00 2001 From: Brunoga-MS Date: Fri, 30 Aug 2024 14:26:51 +0200 Subject: [PATCH 02/14] moved What's new as first in the Overview group --- docs/content/patterns/alz/Overview/Whats-New.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/patterns/alz/Overview/Whats-New.md b/docs/content/patterns/alz/Overview/Whats-New.md index 432f6a033..6dc259b55 100644 --- a/docs/content/patterns/alz/Overview/Whats-New.md +++ b/docs/content/patterns/alz/Overview/Whats-New.md @@ -1,7 +1,7 @@ --- title: What´s new geekdocCollapseSection: true -weight: 10 +weight: 09 --- For information on what's new please refer to the [Releases](https://github.com/Azure/azure-monitor-baseline-alerts/releases) page. From 38015a4692200aed9b9512fbc325807423db72e7 Mon Sep 17 00:00:00 2001 From: Brunoga-MS Date: Fri, 30 Aug 2024 15:20:02 +0200 Subject: [PATCH 03/14] Adding short AMBA-ALZ description sentence --- docs/content/patterns/alz/Overview/ALZ-Pattern.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/content/patterns/alz/Overview/ALZ-Pattern.md b/docs/content/patterns/alz/Overview/ALZ-Pattern.md index 7577df377..b3dc47885 100644 --- a/docs/content/patterns/alz/Overview/ALZ-Pattern.md +++ b/docs/content/patterns/alz/Overview/ALZ-Pattern.md @@ -7,6 +7,8 @@ weight: 10 ## Overview +AMBA for ALZ is a best practice collection of alerts for resources commonly deployed into Azure landing zones and demonstrates how to deploy alerts at scale using Azure Policy. + One of the most common questions faced when working with customers is, "What should we monitor in Azure?" and "What thresholds should we configure our alerts for?" There isn't definitive list of what you should monitor when you deploy something to Azure because "it depends", on what services you're using and how the services are used, which will in turn dictate what you should monitor and what thresholds the metrics you do decide to collect are and what errors you should alert on in logs. From 63aa3c4db49f8699e0a16d2b202c61d799927f50 Mon Sep 17 00:00:00 2001 From: Brunoga-MS Date: Mon, 2 Sep 2024 12:17:13 +0200 Subject: [PATCH 04/14] chore: Enable suggestion status bar in VS Code editor --- .vscode/settings.json | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..ec8672c04 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "editor.suggest.showStatusBar": true +} From 511f5beac3861964e193e0269a78fa377f070ebe Mon Sep 17 00:00:00 2001 From: Brunoga-MS Date: Mon, 30 Sep 2024 11:41:57 +0200 Subject: [PATCH 05/14] Adding sample of page navigation --- .../deploy/Customize-Policy-Assignment.md | 30 +++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md index 4bef901d1..9e52b3222 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md +++ b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md @@ -3,19 +3,35 @@ title: Customize Policy Assignment geekdocCollapseSection: true weight: 20 --- +## In this page + +[Introduction](./Customize-Policy-Assignment#introduction) +[Modify initiative assignment](./Customize-Policy-Assignment#modify-initiative-assignment) +[- Parameter file](./Customize-Policy-Assignment#parameter-file) +[- Applying changes to the parameter file](./Customize-Policy-Assignment#applying-changes-to-the-parameter-file) +[- Metric alert policy parameters](./Customize-Policy-Assignment#metric-alert-policy-parameters) +[- Activity log, Service health alert and action group policy parameters](./Customize-Policy-Assignment#activity-log-service-health-alert-and-action-group-policy-parameters) +[- Disabling Policies](./Customize-Policy-Assignment#disabling-policies) +[Next steps](./Customize-Policy-Assignment#next-steps) ## Introduction As described in [Introduction to deploying the ALZ pattern](../Introduction-to-deploying-the-ALZ-Pattern), the policies and initiatives in this repo can be deployed in a default configuration, i.e. with default settings and are intended to be used as such. There may be however, scenarios where you would want to tweak the initiative assignment for individual policies to conform with your monitoring requirements, or potentially wish to deploy alerts in a more phased approach to a brownfield environment. This document lists some of the various scenarios as well as how you would go about making such changes to the assignments. +[Back to top of page](.) + ## Modify initiative assignment As an example you may want to change alert thresholds for one or more metric alerts when assigning initiatives. To do so the specific parameters can be specified in a parameter file. For convenience we supply a complete parameter file, containing all the parameters that can be comfigured in each initiative. Note that you are advised to leverage this as a template for creating your own parameter file as the parameters in these files may change over time, which could potentially have undesirable effects on your alert configurations. +[Back to top of page](.) + ### Parameter file - [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-08-30/patterns/alz/alzArm.param.json) +[Back to top of page](.) + ### Applying changes to the parameter file If we want to change the threshold value for Virtual Network Gateway Express Route CPU utilization from 80 (default value) to 90, and Virtual Network Gateway Egress traffic from 1 to 1000, what we would do is include this in a parameter file as shown below. These specific thresholds would then be set in the individual policy assignment, while the remaining values for all other policies would remain at default. Note that the parameter file shown below has been truncated for brevity, compared to the samples included. @@ -61,6 +77,8 @@ The parameter file contains the same default values as listed in our documentati } ``` +[Back to top of page](.) + ### Metric alert policy parameters The following parameters can be changed for metric alert policies, in the initiatives these are prefixed with an appropriate string to indicate the metric in question. @@ -75,6 +93,8 @@ The following parameters can be changed for metric alert policies, in the initia | threshold | Indicates a numerical threshold for when the alert would trigger. Not relevant to all alerts as some are configured with dynamic rather than fixed thresholds | | enabled | Whether the alert is enabled or not | +[Back to top of page](.) + ### Activity log, Service health alert and action group policy parameters The following parameters can be changed for activity log, service health alert and action group policies. @@ -87,10 +107,16 @@ The following parameters can be changed for activity log, service health alert a Note that the above parameters specifies the resource group that activity log alerts are placed in. If the resource group does not exist it gets created. Also the parameter for tags can take several tags, if multiple tags are needed. Tags are only applied at the resource group level. The tags parameter is set to a default value of one tag with the name *environment* and the value *test*, you can add more tags as already mentioned or set it to be an empty value. +[Back to top of page](.) + ### Disabling Policies -- To review the options for disabling policies, please proceed with [Disabling Policies](../../Disabling-Policies) -# Next steps +To review the options for disabling policies, please proceed with [Disabling Policies](../../Disabling-Policies) + +[Back to top of page](.) + +## Next steps + - To deploy with GitHub Actions, please proceed with [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) - To deploy with Azure DevOps Pipelines, please proceed with [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../Deploy-with-Azure-CLI) From 8b90d0113628b143b0aad725edda569660b71ffa Mon Sep 17 00:00:00 2001 From: Brunoga-MS Date: Mon, 30 Sep 2024 11:55:37 +0200 Subject: [PATCH 06/14] fixed menu structure --- .../HowTo/deploy/Customize-Policy-Assignment.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md index 9e52b3222..ee8bd4d7c 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md +++ b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md @@ -5,14 +5,14 @@ weight: 20 --- ## In this page -[Introduction](./Customize-Policy-Assignment#introduction) -[Modify initiative assignment](./Customize-Policy-Assignment#modify-initiative-assignment) -[- Parameter file](./Customize-Policy-Assignment#parameter-file) -[- Applying changes to the parameter file](./Customize-Policy-Assignment#applying-changes-to-the-parameter-file) -[- Metric alert policy parameters](./Customize-Policy-Assignment#metric-alert-policy-parameters) -[- Activity log, Service health alert and action group policy parameters](./Customize-Policy-Assignment#activity-log-service-health-alert-and-action-group-policy-parameters) -[- Disabling Policies](./Customize-Policy-Assignment#disabling-policies) -[Next steps](./Customize-Policy-Assignment#next-steps) +> [Introduction](../Customize-Policy-Assignment#introduction)
+> [Modify initiative assignment](../Customize-Policy-Assignment#modify-initiative-assignment)
+> [- Parameter file](../Customize-Policy-Assignment#parameter-file)
+> [- Applying changes to the parameter file](../Customize-Policy-Assignment#applying-changes-to-the-parameter-file)
+> [- Metric alert policy parameters](../Customize-Policy-Assignment#metric-alert-policy-parameters)
+> [- Activity log, Service health alert and action group policy parameters](../Customize-Policy-Assignment#activity-log-service-health-alert-and-action-group-policy-parameters)
+> [- Disabling Policies](../Customize-Policy-Assignment#disabling-policies)
+> [Next steps](../Customize-Policy-Assignment#next-steps) ## Introduction From 9f73bed764329999a83694d6d9309c7f907f0b89 Mon Sep 17 00:00:00 2001 From: Patrisia Pascan Date: Fri, 8 Nov 2024 14:20:30 +0000 Subject: [PATCH 07/14] Acrolinx and menu updates --- .../alz/Getting-started/Alerts-Details.md | 29 ++- .../Monitoring-and-Alerting.md | 41 ++--- .../alz/Getting-started/Policy-Initiatives.md | 30 ++-- .../HowTo/Bring-your-own-Managed-Identity.md | 45 +++-- .../alz/HowTo/Bring-your-own-Notifications.md | 49 +++--- .../alz/HowTo/Cleaning-up-a-Deployment.md | 35 ++-- .../patterns/alz/HowTo/Disabling-Policies.md | 48 ++--- .../alz/HowTo/Log_Search_Alert_Table.md | 2 +- .../patterns/alz/HowTo/Metrics_Alert_Table.md | 70 ++++---- docs/content/patterns/alz/HowTo/Telemetry.md | 12 +- .../Temporarily-disabling-notifications.md | 22 +-- .../patterns/alz/HowTo/Threshold-Override.md | 19 +- .../Moving-from-preview-to-GA.md | 40 ++--- .../Update_from_release_2023-11-14.md | 19 +- .../Update_from_release_2024-03-01.md | 22 ++- .../Update_from_release_2024-04-12.md | 17 +- .../Update_from_release_2024-06-05.md | 28 ++- .../deploy/Customize-Policy-Assignment.md | 34 ++-- .../Deploy-only-Service-Health-Alerts.md | 8 +- .../deploy/Deploy-via-Azure-Portal-UI.md | 86 ++++----- .../alz/HowTo/deploy/Deploy-with-Azure-CLI.md | 20 +-- .../deploy/Deploy-with-Azure-Pipelines.md | 16 +- .../deploy/Deploy-with-Azure-PowerShell.md | 20 +-- .../deploy/Deploy-with-GitHub-Actions.md | 14 +- ...troduction-to-deploying-the-ALZ-Pattern.md | 130 +++++++------- .../deploy/PowerShell-ExecutionPolicy.md | 6 +- .../alz/HowTo/deploy/Remediate-Policies.md | 37 ++-- .../HowTo/deploy/parameterConfiguration.md | 82 ++++----- .../patterns/alz/Overview/ALZ-Pattern.md | 80 ++++----- .../patterns/alz/Overview/Whats-New.md | 166 +++++++++--------- docs/content/patterns/alz/Resources/FAQ.md | 59 +++---- .../patterns/alz/Resources/Known-Issues.md | 82 +++++---- .../Resources/Moving-from-preview-to-GA.md | 40 ++--- .../patterns/alz/Resources/Versioning.md | 6 +- 34 files changed, 702 insertions(+), 712 deletions(-) diff --git a/docs/content/patterns/alz/Getting-started/Alerts-Details.md b/docs/content/patterns/alz/Getting-started/Alerts-Details.md index 7f1c55737..4c02b1011 100644 --- a/docs/content/patterns/alz/Getting-started/Alerts-Details.md +++ b/docs/content/patterns/alz/Getting-started/Alerts-Details.md @@ -4,38 +4,37 @@ geekdocCollapseSection: true weight: 30 --- -Specific alerts for ALZ can be downloaded by clicking on the Download icon (highlighted in red below) in the top right corner of the AMBA documentation. +Download specific alerts for ALZ by clicking on the Download icon (highlighted in red below) in the top right corner of the page. ![Alert-Details Download icon](../../media/AlertDetailsDownloadReference.png) -The best way to see which policy alert rules are part of the ALZ pattern it is best to go to the [Policy-Initiatives](../Policy-Initiatives) page. +To view which policy alert rules are part of the ALZ pattern, visit the [Policy-Initiatives](../Policy-Initiatives) page. -The resources, metric alerts and their settings provide you with a starting point to help you address the following monitoring questions: -"What should we monitor in Azure?" and "What alert settings should we use?" While they are opinionated settings and they are meant to cover the most common Azure Landing Zone components, we encourage you to adjust these settings to suit your monitoring needs based on how you're using Azure. +The resources, metric alerts, and their configurations serve as an initial guide to help you address key monitoring questions such as "What should we monitor in Azure?" and "What alert settings should we use?". These settings are designed to cover the most common components of an Azure Landing Zone. However, we recommend customising these settings to better align with your specific monitoring requirements and usage of Azure. -If you have suggestions for other resources that should be included please open an Issue on this page providing the Azure resource provider and settings you'd like implemented, we can't promise to implement them all but we will look into it. Or if you'd like to contribute directly, follow the steps in the [Contributor Guide](../../../../contributing). +If you have suggestions for other resources that should be included, open an Issue on this page providing the Azure resource provider and settings you would like implemented. We can not guarantee their implementation but we will carefully consider them. Alternatively, if you would like to contribute directly, follow the steps in the [Contributor Guide](../../../../contributing). ## Azure Landing Zone Metric Alerts Settings -The values shown for Aggregation, Operator, Threshold, WindowSize, Frequency and Severity have been derived from field experience and what customers have implemented themselves; Alerts are based on Microsoft public guidance where available (indicated by a 'Yes' in the Verified column), and on practical application experience where public guidance is not available (indicated by a 'No' in the Verified column). Links to Product Group guidance can be found in the References column and when no guidance is provided we've provided a link to the description of the Metric on learn.microsoft.com. +The values shown for Aggregation, Operator, Threshold, WindowSize, Frequency, and Severity are derived from field experience and customer implementations. Alerts are based on Microsoft public guidance where available (indicated by a 'Yes' in the Verified column) and practical application experience where public guidance is not available (indicated by a 'No' in the Verified column). Links to Product Group guidance are provided in the References column. Where no guidance is available, a link to the description of the Metric on learn.microsoft.com is included. -The Scope column details where we scoped the alerts as described in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern). +The Scope column indicates where we scoped the alerts as described in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern). -Only a small number of the resources support metric alert rules scoped at the subscription level and the metric alerts would only apply to resources deployed within the same region. The Support for Multiple Resources column to show which resources support metric alerts being scoped at the subscription level. For a complete list of which resources support metrics alert rules scoped at the subscription level click [here](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-types#monitor-multiple-resources). +Only a limited number of resources support metric alert rules scoped at the subscription level, and these metric alerts are applicable only to resources deployed within the same region. The Support for Multiple Resources column indicates which resources support metric alerts at the subscription level. For a comprehensive list of resources that support metric alert rules at the subscription level, please click [here](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-types#monitor-multiple-resources). {{< hint type=note >}} -We have tried to make it so that the table doesn't require a lot of side to side scrolling, but it is still a lot of information, we recommended that you click on the specifc alert name which will take you directly to the JSON definition of the alert you're interested in. +We have designed the table to minimize the need for horizontal scrolling, but it still contains a substantial amount of information. We recommend clicking on the specific alert name to directly access the JSON definition of the alert you're interested in. {{< /hint >}} {{< alzMetricAlerts >}} -1 See "Why are the availability alert thresholds lower than 100% in this solution when the product group documention recommends 100%?" in the [FAQ](../../Resources/FAQ) for more details. +1 See "Why are the availability alert thresholds lower than 100% in this solution when the product group document ion recommends 100%?" in the [FAQ](../../Resources/FAQ) for more details. ## Azure Landing Zone Activity Log Alerts ### Azure Landing Zone Activity Log Resource Health -Use the following two sections to quickly know when there's a Service Health issue with an Azure resource, saving you the effort of further troubleshooting and allow you to focus on communicating to your user base and/or use these alerts as part of your business continuity actions (remediations). +Refer to the following two sections to promptly identify any Service Health issues with an Azure resource. This will save you the effort of further troubleshooting and allow you to focus on communicating with your user base or incorporating these alerts into your business continuity actions (remediations). {{< alzActivityLogResourceHealthAlerts >}} @@ -45,15 +44,15 @@ Use the following two sections to quickly know when there's a Service Health iss ### Azure Landing Zone Activity Log Administrative -The following table lists a number of operational Activity Log alerts to alert your team when certain resources have been deleted. +The table below lists several operational Activity Log alerts designed to notify your team when specific resources are deleted. -There isn't any per resource type guidance so what's been provided is some general guidance on alerting on the deletion of specific resources, the list may grow in the future and of course you can create your own following the pattern used for these Activity Log alerts. +While there is no specific guidance per resource type, the provided information offers general advice on alerting for the deletion of particular resources. This list may expand in the future, and you are encouraged to create your own alerts following the pattern used for these Activity Log alerts. {{< alzActivityLogAdministrativeAlerts >}} ## VM Insights Log Alerts -Once VM Insights has been enabled in your environment, the following alert rules can be configured for use via the Baseline Alerts framework. +Once VM Insights has been enabled in your environment, the following alert rules can be configured via the Baseline Alerts framework. N/A: Not applicable, not used in the query or used as a parameter. @@ -61,7 +60,7 @@ N/A: Not applicable, not used in the query or used as a parameter. ## Recovery Vault Alerts -The following policy disables the classic alerts that are available in Azure Backup and enables the Azure Monitor alerts. +The following policy disables the classic alerts available in Azure Backup and enables the Azure Monitor alerts. Security Alerts and Job Failure alerts are summarized in the "[Using Backup Center](https://learn.microsoft.com/en-us/azure/backup/backup-azure-monitoring-built-in-monitor?tabs=recovery-services-vaults#azure-monitor-alerts-for-azure-backup)" documentation. diff --git a/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md b/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md index 51d6d02c5..46be56cd1 100644 --- a/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md +++ b/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md @@ -6,36 +6,36 @@ weight: 20 ## ALZ Monitor Alert Approach -The overall approach for enabling alerts in ALZ is to use Azure Policy to deploy relevant alerts as resources are created, configure action group(s), and then use Alert Processing Rules to activate alerts and connect them to the Action Group. +The overall strategy for enabling alerts in ALZ involves using Azure Policy to deploy relevant alerts as resources are created, configuring action groups, and then using Alert Processing Rules to activate alerts and link them to the action group. -There are two general principles/approaches to enabling alerting in ALZ: +There are two main principles/approaches to enabling alerting in ALZ: ### Centralized -With a **centralized** approach to alerting a central Action Group is used for all alerts, which means a single alerting email (distribution group) address or other configured actions. +In a **centralized** alerting approach, a single Action Group is used for all alerts, which means a unified alerting email (distribution group) address or other configured actions. -Metric alerts are deployed with resources (same resource group) and platform alerts like Service Health / Activity are created in a dedicated resource group, in a subscription typically located in the Management platform management group. A single Alert Action Group in a subscription in the Management platform management group is configured with a central alerting email address, and Alert Processing Rules enabling filters and connecting alerts to the Alert Action Group. +Metric alerts are deployed with resources in the same resource group, while platform alerts like Service Health and Activity are created in a dedicated resource group within a subscription typically located in the Management platform management group. A single Alert Action Group in this subscription is configured with a central alerting email address and Alert Processing Rules in order to enable filters and connect alerts to the Alert Action Group. -As an example in the context of ALZ, a single centralized action group is deployed in the "rg-amba-monitoring-001" resource group in a subscription in the Management platform management group. +For example, in the context of ALZ, a single centralised action group is deployed in the "rg-amba-monitoring-001" resource group within a subscription in the Management platform management group. ### Decentralized -For a **decentralized** approach every subscription has a dedicated Action Group allowing for more granular control of how to direct alert notifications, for example, for connectivity/networking alerts for the platform connectivity subscription, direct the alerts to the network operations team. +In a **decentralized** approach, each subscription has a dedicated Action Group, providing more granular control over how alert notifications are directed. For instance, connectivity/networking alerts for the platform connectivity subscription can be directed to the network operations team. -Metric alerts are deployed with resources (in the same resource group) and platform alerts like Service Health / Activity are created in a dedicated resource group for each subscription. Alert Action Groups are created in each landing zone subscription, allowing each operational area and landing zone subscription to have different alerting email addresses (networking, identity, ops, workloads, etc.) or other supported actions. Alert Processing Rules are created to enable filters and connect alerts to the Action Groups. +Metric alerts are deployed with resources in the same resource group, while platform alerts such as Service Health and Activity are created in a dedicated resource group for each subscription. Alert Action Groups are established in each landing zone subscription, allowing different operational areas and landing zone subscriptions to have distinct alerting email addresses (e.g., networking, identity, operations, workloads) or other supported actions. Alert Processing Rules are created to enable filters and connect alerts to the Action Groups. -As an example in the context of ALZ, see below for a graphic representation of the flow. +For example, in the context of ALZ, a graphic representation of the flow is provided below. ![ALZ alerting](../../media/AMBA-focused-rg-alz-monitor-alert-flow.png) ### ALZ Approach -For ALZ the decentralized approach is followed to allow maximum flexibility in directing alerts. For more information review [What are Azure Monitor Alerts?](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-overview). +In ALZ, a decentralized approach is adopted to provide maximum flexibility in directing alerts. For more information review [What are Azure Monitor Alerts?](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-overview). -- A single Action Group per subscription will be deployed. This allows customers to configure discrete actions per subscription (different email addresses or other supported actions). +- Each subscription will have a single Action Group, allowing customers to configure specific actions per subscription, such as different email addresses or other supported actions. - Alert Processing Rules will target the Action Group in the subscription where the alert originated. -As this is a work in progress, the initial configuration provided by ALZ will configure all Action Groups with the same email distribution group/address through Azure Policy. We may investigate and implement alternative or additional actions in the future (e.g. configure alternate email distribution groups depending on the subscription/service or workload owners/etc.). +As this is a work in progress, the initial configuration provided by ALZ will set up all Action Groups with the same email distribution group/address through Azure Policy. Future updates may include alternative or additional actions, such as configuring different email distribution groups based on the subscription, service, or workload owners. ALZ Alerts, Action Groups and Alert Processing Rules are deployed using Azure Policy defined in the platform native Azure Policy JSON format. @@ -51,11 +51,11 @@ The following policy definition categories will be enabled as part of ALZ deploy ### Resource Metrics -Resource Metric alerts are deployed in the same resource group as the created Azure resource. For example, a resource metric alert for Express Route will be created in the same resource group containing the Express Route Gateway. This is done because these alert types are related to the specific resource id, therefore it makes sense to link the alert to the resource in the same resource group. +Resource Metric alerts are deployed within the same resource group as the associated Azure resource. For instance, a resource metric alert for Express Route will be created in the resource group that contains the Express Route Gateway. This approach is logical because these alert types are tied to the specific resource ID, making it sensible to link the alert to the resource within the same resource group. ### Log Alerts -Log alerts are scoped at the subscription level. For the policies to remediate and deploy, the data which the alert queries for needs to exist in the Log Analytics table. For the virtual machine log alerts the VM insights solution needs to be enabled on the VMs that are targeted. Only the performance collection of the VM insights solution is required for the current alerts to deploy. To enable VM Insights, you need to install the Azure Monitor Agent and optionally the Dependency agent on your supported machines. You can use different methods to install the agents, such as the Azure portal, Azure Policy, Azure Resource Manager templates, PowerShell, or manual install. For more details, please refer to the links below: +Log alerts are scoped at the subscription level. For policies to remediate and deploy, the data queried by the alert must exist in the Log Analytics table. For virtual machine log alerts, the VM insights solution needs to be enabled on the targeted VMs. Only the performance collection of the VM insights solution is required for the current alerts to deploy. To enable VM Insights, you need to install the Azure Monitor Agent and optionally the Dependency agent on your supported machines. Various methods can be used to install the agents, such as the Azure portal, Azure Policy, Azure Resource Manager templates, PowerShell, or manual installation. For more details, please refer to the links below: - [Enable VM Insights overview](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-enable-overview) - [Enable VM insights by using Azure Policy](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-enable-policy) @@ -65,16 +65,17 @@ Log alerts are scoped at the subscription level. For the policies to remediate a [Service health](https://learn.microsoft.com/en-us/azure/service-health/overview) provides a personalized view of the health of the Azure services and regions you're using. Resource health provides information about the health of your individual cloud resources such as a specific virtual machine instance. -Service and resource health events are written into the activity log. This means we can create a sub set of activity log alerts that can alert on health events. We create these alerts scoped to each subscription with four separate alerts for each of the four service health categories: Incident, Planned Maintenance, Security Advisories and Health Advisories. -A resource health alert will be created for any resource that goes into an unavailable or degraded state which can be platform or user initiated. We will ignore if the state is unknown as this can lead to erroneous alerting. +Service and resource health events are recorded in the activity log, allowing us to create a subset of activity log alerts that notify on health events. These alerts are scoped to each subscription and include four separate alerts for each of the service health categories: Incident, Planned Maintenance, Security Advisories, and Health Advisories. + +A resource health alert will be generated for any resource that enters an unavailable or degraded state, whether platform or user-initiated. We will disregard the unknown state to avoid erroneous alerting. ## ALZ Monitor Alert Processing Rules [Alert Processing Rules](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-processing-rules) enable the filtering of alerts and assign alerts to the appropriate action groups based on filter criteria. -As this is currently a work in progress, for ALZ we will implement a single Action Group per subscription, and deploy a single Alert Processing Rule without filters to action alerts via the Action Group. This may be revised in the future. +As this is currently a work in progress, for ALZ we will implement a single Action Group per subscription, and deploy a single Alert Processing Rule without filters to manage alerts via the Action Group. This approach may be revised in the future. -As this is a work in progress, we still need to investigate appropriate filters for Alert Processing Rules for optimal alert processing. +We still need to investigate appropriate filters for Alert Processing Rules for optimal alert processing. Available filters: @@ -90,11 +91,11 @@ Available filters: - Severity - Signal type -As an example, we could implement a filter on Severity (Critical, Error, Warning) only, ignoring (Informational, Verbose). +For instance, we could apply a filter to include only Severity levels of Critical, Error, and Warning, while excluding Informational and Verbose. ## Monitoring Backup (Recovery Services Vaults) -Azure Backup now provides new and improved alerting capabilities via Azure Monitor. The following policy: [Backup Monitor Policy](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/services/RecoveryServices/vaults/Modify-RSV-BackupHealth-Alert.json) configures new and existing recovery services vaults through a modify effect, which disables the classic alerts and enables the new built-in alerts. +Azure Backup now provides new and improved alerting capabilities via Azure Monitor. The following policy: [Backup Monitor Policy](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/services/RecoveryServices/vaults/Modify-RSV-BackupHealth-Alert.json) configures new and existing recovery services vaults through a modify effect, which disables the classic alerts and enables the new built-in ones. ### Modifications @@ -124,6 +125,6 @@ Azure Backup now provides new and improved alerting capabilities via Azure Monit ### Notifications -While alerts are generated by default and can't be turned off for destructive operations, the notifications are in the control of the user, allowing you to clearly specify which set of email address (or other notification endpoints) you wish to route alerts to. Notifications are configured by an alert processing rule, which will be created by default when deploying AMBA-ALZ pattern. +While alerts are generated by default and cannot be disabled for destructive operations, users have control over the notifications. This allows you to specify the email addresses (or other notification endpoints) to which alerts should be routed. Notifications are configured by an alert processing rule, which is created by default when deploying the AMBA-ALZ pattern. [Back to top of page](.) diff --git a/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md b/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md index 1d3f6696c..4d250c3db 100644 --- a/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md +++ b/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md @@ -6,11 +6,11 @@ weight: 40 ## Overview -This document details the ALZ-Monitor Azure policy initiatives leveraged for deploying the ALZ-Monitor baselines. For references on individual alerts/policies, refer to [Alert Details](../..//Getting-started//Alerts-Details). +This document details the ALZ-Monitor Azure policy initiatives used for deploying the ALZ-Monitor baselines. For references on individual alerts/policies, refer to [Alert Details](../..//Getting-started//Alerts-Details). ## Connectivity initiative -This initiative is intended for assignment of policies relevant to networking components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-connectivity management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for relevant policy assignment to networking components in ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-connectivity management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ---------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -67,7 +67,7 @@ This initiative is intended for assignment of policies relevant to networking co ## Management initiative -This initiative is intended for assignment of policies relevant to management components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for relevant policy assignment to management components in ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ----------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -80,7 +80,7 @@ This initiative is intended for assignment of policies relevant to management co ## Identity initiative -This initiative is intended for assignment of policies relevant to identity components in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz-platform-identity management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for relevant policy assignment to identity components in ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-identity management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ------------------------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -93,7 +93,7 @@ This initiative is intended for assignment of policies relevant to identity comp ## Key Management initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management Services such as Azure Key Vault, and Managed HSM. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management Services such as Azure Key Vault, and Managed HSM. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -105,7 +105,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management ## Load Balancing initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing Services such as Load Balancer, Application Gateway, Traffic Manager, and Azure Front Door. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing Services such as Load Balancer, Application Gateway, Traffic Manager, and Azure Front Door. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -136,7 +136,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing ## Network Changes initiative -This initiative implements Azure Monitor Baseline Alerts to monitor alterations in Network Routing and Security, such as modifications to Route Tables and the removal of Network Security Groups. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative implements Azure Monitor Baseline Alerts to monitor alterations in Network Routing and Security, such as modifications to Route Tables and the removal of Network Security Groups. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -145,7 +145,7 @@ This initiative implements Azure Monitor Baseline Alerts to monitor alterations ## Recovery Services initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Services such as Azure Backup, and Azure Site Recovery. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Services such as Azure Backup, and Azure Site Recovery. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -153,7 +153,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Servic ## Storage initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Services such as Storage accounts. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Services such as Storage accounts. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -161,7 +161,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Service ## VM initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual Machines. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual Machines. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -179,7 +179,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual M ## Web initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services such as App Services. This initiative is intended for assignment of policies relevant to a landing zone in the ALZ structure. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services such as App Services. It is intended for relevant policy assignment to a landing zone in the ALZ structure. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -190,7 +190,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services su ## Hybrid VM initiative -This initiative is intended for assignment of policies relevant to Hybrid VM alerts in AMBA-ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will be assigned to the 'alz' intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default policy effect is, refer to the below table. +This initiative is intended for relevant policy assignment to Hybrid VM alerts in AMBA-ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will be assigned to the 'alz' intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Display Name** | **Reference ID** | **Path to policy json file** | **Policy default effect** | | ---------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -209,7 +209,7 @@ This initiative is intended for assignment of policies relevant to Hybrid VM ale ## Service Health initiative -This initiative is intended for assignment of policies relevant to service health alerts in ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for relevant policy assignment service health alerts in ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | --------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -222,7 +222,7 @@ This initiative is intended for assignment of policies relevant to service healt ## Notification Assets initiative -This initiative is intended for assignment of policies relevant to notification in AMBA-ALZ. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for relevant policy assignment to notification in AMBA-ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Display Name** | **Reference ID** | **Path to policy json file** | **Policy default effect** | | ------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -231,7 +231,7 @@ This initiative is intended for assignment of policies relevant to notification ## Landing Zone initiative (Deprecated) -This initiative is intended for assignment of policies relevant to a landing zone in the ALZ structure. With the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on which policies are included in the initiative as well as what the default enablement state of the policy is, refer to the below table. +This initiative is intended for relevant policy assignment to a landing zone in the ALZ structure. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | diff --git a/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md index ab773a1bd..adb07418a 100644 --- a/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md @@ -6,70 +6,69 @@ weight: 95 ## Overview -The ***Bring Your Own User Assigned Managed Identity*** (BYO UAMI) feature, available with release [2024-06-05](../../Overview/Whats-New#2024-06-05), allows both Greenfield and Brownfield customers to create a new User Assigned Managed Identity (UAMI) during or after the deployment of AMBA-ALZ. It also allows Brownfield customers, who deployed the ALZ pattern when this feature wasn't available, to use any existing one by configuring a couple of parameters. Thanks to this new feature, it's now possible to query Azure Resource Graph (ARG) using the Kusto Query Language. Log-based search alerts can now be enhanced to include ARG queries looking at resource tags. +The ***Bring Your Own User Assigned Managed Identity*** (BYO UAMI) feature, introduced in the [2024-06-05 release](../../Overview/Whats-New#2024-06-05), enables both Greenfield and Brownfield customers to create a new User Assigned Managed Identity (UAMI) during or after the deployment of AMBA-ALZ. Additionally, Brownfield customers who deployed the ALZ pattern before this feature was available can now configure existing UAMIs by setting a few parameters. This feature allows querying Azure Resource Graph (ARG) using Kusto Query Language and enhances log-based search alerts to include ARG queries for resource tags. ## How this feature works -The BYO UAMI feature works by creating a new UAMI in the management subscription and assigns the ***Monitoring reader*** role on the parent pseudo root Management Group. With this new feature, it's now possible to query Azure Resource Graph (ARG) using the Kusto Query Language and to enhance Log-based search alerts that can now query ARG to look at resource tags or properties. It's enough to enter the necessary parameter values before running the ALZ pattern deployment. +The BYO UAMI feature creates a new UAMI in the management subscription and assigns the ***Monitoring Reader*** role to the parent pseudo root Management Group. This enables querying Azure Resource Graph (ARG) using Kusto Query Language and enhances log-based search alerts to query ARG for resource tags or properties. To use this feature, enter the necessary parameter values before deploying the ALZ pattern. -Should Brownfield customers decide to use their own UAMI after the initial deployment, it will be sufficient to enter the parameter values for _bringYourOwnUserAssignedManagedIdentity_ and _bringYourOwnUserAssignedManagedIdentityResourceId_, leaving the _userAssignedManagedIdentityName_ parameter at its default and the parameter _managementSubscriptionId_ with no values: +For Brownfield customers wanting to use their own UAMI after initial deployment, set the parameters _bringYourOwnUserAssignedManagedIdentity_ and _bringYourOwnUserAssignedManagedIdentityResourceId_, leaving _userAssignedManagedIdentityName_ at its default and _managementSubscriptionId_ with no values: -Once parameters are set according to your needs, redeploy the AMBA-ALZ pattern and wait for the remediation to happen. You can also start the Policy remediation manually as documented at [Remediate Policies](../deploy/Remediate-Policies). +After setting the parameters, redeploy the AMBA-ALZ pattern and wait for remediation. Manual Policy remediation can also be initiated as documented in [Remediate Policies](../deploy/Remediate-Policies). ### Conditional deployment behavior -The deployment template has conditions that controls what is being deployed according to the following two scenarios: +The deployment template includes conditions that control deployment based on two scenarios: -A. ***Customers want to use existing UAMI.*** In this scenario the deployment will: +A. ***Using an existing UAMI.*** In this scenario, the deployment will: {{< hint type=Important >}} -Before executing the deployment, ensure that the existing UAMI is assigned the ***Monitoring Reader*** role at the pseudo root Management Group. - -It is probable that the UAMI you provide is located within the Management subscription beneath the Platform management group, whereas the Policy Assignment resides at the LandingZones management group. In this case, for the deployIfNotExists policies to have permission to assign the UAMI to the scheduled query rule, the ***Managed Identity Operator*** role must be granted to the system Managed Identity of the Initiative Assignment (```Deploy-AMBA-VM``` for the Virtual machine initiative, ```Deploy-AMBA-HybridVM``` for the Arc-enabled Servers initiative) at the UAMI scope. +Before deployment, ensure the existing UAMI is assigned the ***Monitoring Reader*** role at the pseudo root Management Group. +If the UAMI is within the Management subscription under the Platform management group, and the Policy Assignment is at the LandingZones management group, grant the ***Managed Identity Operator*** role to the system Managed Identity of the Initiative Assignment (```Deploy-AMBA-VM``` for Virtual machine initiative, ```Deploy-AMBA-HybridVM``` for Arc-enabled Servers initiative) at the UAMI scope. {{< /hint >}} - Not deploy any UAMI - Not assign the _Monitoring Reader_ role -- Set the provided existing UAMI as the identity to be used in the necessary alerts +- Use the provided existing UAMI for necessary alerts -Here's a sample extract of the parameter file with the relevant parameter configuration for this scenario: +Sample parameter file configuration for this scenario: ![Customer defined UAMI](../../media/alz-UAMI-Param-Example-1.png) -B. ***Customers does not have an existing UAMI and want AMBA-ALZ to create a new one.*** In this scenario the deployment will: +B. ***Creating a new UAMI.*** In this scenario, the deployment will: {{< hint type=Info >}} -When a new UAMI is created by the deployment template, the ***Monitoring Reader*** role is *is automatically assigned at the pseudo root Management Group level during the deployment*. +When a new UAMI is created by the deployment template, the ***Monitoring Reader*** role is *automatically assigned at the pseudo root Management Group level during deployment*. {{< /hint >}} - Deploy any UAMI - Assign the *Monitoring Reader* role -- Set the provided existing UAMI as the identity to be used in the necessary alerts +- Set the provided UAMI as the identity to be used in the necessary alerts -Here's a sample extract of the parameter file with the relevant parameter configuration for this scenario: +Sample parameter file configuration for this scenario: ![New UAMI deployed by the template](../../media/alz-UAMI-Param-Example-2.png) -### Where is it used +### Usage -This new feature is used in Log-search based alerts. At the moment of this release, there's one alert using it. The alert is part of the new ***Deploy Azure Monitor Vaseline Alerts for Hybrid VMs*** policySet added to monitor hybrid virtual machine. +This feature is currently used in log-search based alerts. As of this release, one alert uses it, part of the ***Deploy Azure Monitor Baseline Alerts for Hybrid VMs*** policySet for monitoring hybrid virtual machines. ![Deploy Azure Monitor Baseline Alerts for Hybrid VMs](../../media/deploy-HybridVM-Alerts.png) {{< hint type=Info >}} -We're planning to use this feature more in the future and to include it as part of other alerts. +Future plans include expanding this feature to other alerts. {{< /hint >}} ### Switching between BYO UAMI and new UAMI -The [conditional deployment behavior](../Bring-your-own-Managed-Identity#conditional-deployment-behavior) discussed earlier, allows brownfield customers to switch from a new created UAMI to an existing one and viceversa. -Should customers decide to switch, it will be enough to: +The [conditional deployment behavior](../Bring-your-own-Managed-Identity#conditional-deployment-behavior) allows Brownfield customers to switch between a newly created UAMI and an existing one. To switch: -- Change the values in the parameter file to match one of the two scenarios previously discussed +- Update the parameter file values to match one of the discussed scenarios - Redeploy the AMBA-ALZ pattern -- Run the remediation as documented at [Remediate Policies](../deploy/Remediate-Policies) +- Run remediation as documented in [Remediate Policies](../deploy/Remediate-Policies) -The code will reconfigure the necessary alerts to use either the customer's provided UAMI or the new one created during the deployment. +The code will reconfigure alerts to use either the provided UAMI or the newly created one. [Back to top of page](.) + diff --git a/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md index 32d1d65e8..602a647e5 100644 --- a/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md @@ -6,62 +6,61 @@ weight: 100 ## Overview -The ***Bring Your Own Notifications*** (BYON) feature, available with release [2024-04-12](../../Overview/Whats-New#2024-04-12), allows brownfield customers to use their existing Action Groups (also known as AGs) and Alert Processing Rule (also known as APR) not forcing the use of notification assets deployed by both the [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) initiative and the [Deploy Service Health Action Group](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/services/Resources/subscriptions/Deploy-ServiceHealth-ActionGroups.json) policy definition present in the ALZ pattern. It also allows Brownfield customer who deployed the ALZ pattern when this feature wasn't available, to switch to it. +The ***Bring Your Own Notifications*** (BYON) feature, introduced in the [2024-04-12](../../Overview/Whats-New#2024-04-12) release, enables brownfield customers to utilize their existing Action Groups (AGs) and Alert Processing Rules (APRs) without mandating the use of notification assets deployed by the [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) initiative or the [Deploy Service Health Action Group](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/services/Resources/subscriptions/Deploy-ServiceHealth-ActionGroups.json) policy definition in the ALZ pattern. This feature also allows brownfield customers who deployed the ALZ pattern before this feature was available to switch to it. ## How this feature works -The BYON feature works by setting the necessary parameter values before running the ALZ pattern deployment. Customers have the choice to either specify one or more existing AGs and one APR or to enter target values so the AG and the APR will be created using the actions specified in the parameter file (including the option to not specify any value and creating an empty AG). +The BYON feature operates by setting the necessary parameter values before deploying the ALZ pattern. Customers can either specify existing AGs and one APR or provide target values to create the AG and APR using the actions specified in the parameter file. If no values are specified, an empty AG will be created. -Should Brownfield customers decide to use their own notification assets, it will be sufficient to enter the *AG resource IDs* and the *APR resource ID* values in the respective parameters ***BYOActionGroup*** and ***BYOAlertProcessingRule***, leaving the ***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId*** and ***ALZFunctionTriggerUrl*** ***with no values***: +For brownfield customers opting to use their own notification assets, they need to enter the *AG resource IDs* and the *APR resource ID* in the parameters ***BYOActionGroup*** and ***BYOAlertProcessingRule***, respectively, while leaving the parameters ***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId***, and ***ALZFunctionTriggerUrl*** empty: ![policyAssignmentParametersBYON section](../../media/BYON_Params_3.png) -Differently if they decide to use the assets provided by AMBA or if they're Greenfield customers, they'll just leave the ***BYOActionGroup*** and ***BYOAlertProcessingRule*** parameters ***with no values*** and populate all the others (***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId*** and ***ALZFunctionTriggerUrl***): +Conversely, if they choose to use the assets provided by AMBA or if they are greenfield customers, they should leave the ***BYOActionGroup*** and ***BYOAlertProcessingRule*** parameters empty and populate the other parameters (***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId***, and ***ALZFunctionTriggerUrl***): ![policyAssignmentParametersNotificationAssets section](../../media/NotificationAssets_Params_2.png) ## Conditional deployment behavior -When running the deployment, the deployment code has conditions that control the deployment behavior according to the following three possible cases: +The deployment code includes conditions that control the deployment behavior based on the following scenarios: -A. ***Use your own AGs with the AMBA APR***. In this scenario, the deployment will: +A. ***Use your own AGs with the AMBA APR***: -- Not deploy the AMBA SH AG -- Deploy the AMBA APR with customer's AGs in it -- Deploy SH alerts pointing to customer's AGs +- Does not deploy the AMBA SH AG +- Deploys the AMBA APR with the customer's AGs +- Deploys SH alerts pointing to the customer's AGs -Here's an example of the parameter file with the relevant sections populated for this scenario: +Example parameter file for this scenario: ![policyAssignmentParametersBYON section](../../media/BYON_Params_2.png) -B. ***Use your own AGs and APR***. In this scenario, the deployment will: +B. ***Use your own AGs and APR***: -- Not deploy any AMBA notification AG or ARP (since it's not physically linked to any alert) assets or AMBA SH AG -- Deploy SH alerts pointing to customer's AGs +- Does not deploy any AMBA notification AG or APR assets or AMBA SH AG +- Deploys SH alerts pointing to the customer's AGs -Here's an example of the parameter file with the relevant sections populated for this scenario: +Example parameter file for this scenario: ![policyAssignmentParametersBYON section](../../media/BYON_Params_3.png) -C. ***Use AMBA notification assets***. In this scenario, the deployment will: +C. ***Use AMBA notification assets***: -- Deploy notification assets for SH alerts and wide notifications. +- Deploys notification assets for SH alerts and wide notifications -Here's an example of the parameter file with the relevant sections populated for this scenario: +Example parameter file for this scenario: ![policyAssignmentParametersNotificationAssets section](../../media/NotificationAssets_Params_2.png) ## Switching between BYON and Notification Assets -The [conditional deployment behavior](../Bring-your-own-Notifications#conditional-deployment-behavior) discussed earlier, allows brownfield customers to switch from the initial notification assets scenario (the only one available until release [2024-03-01](../../Overview/Whats-New#2024-03-01)) to the new BYON after deployment and viceversa. +The [conditional deployment behavior](../Bring-your-own-Notifications#conditional-deployment-behavior) allows brownfield customers to switch from the initial notification assets scenario (available until the [2024-03-01](../../Overview/Whats-New#2024-03-01) release) to the new BYON feature and vice versa. -Should customers decide to switch, it will be enough to: +To switch, customers need to: +- Update the parameter file to match one of the three scenarios discussed +- Redeploy the ALZ pattern +- Run the remediation for both [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) and [Alerting-ServiceHealth](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-ServiceHealth-Alerts.json) policy initiatives +- Remove notification assets deployed by ALZ patterns using the [**Remove-AMBANotificationAssets.ps1**](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/scripts/Remove-AMBANotificationAssets.ps1) script (_*** only if moving from ALZ notification assets to BYON_) -- change the values in the parameter file to match one of the three cases previously discussed -- redeploy the ALZ pattern -- run the remediation for both [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) and [Alerting-ServiceHealth](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-ServiceHealth-Alerts.json) policy initiatives -- remove notification assets deployed by ALZ patterns using the [**Remove-AMBANotificationAssets.ps1**](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/scripts/Remove-AMBANotificationAssets.ps1) script (_*** only if moving from ALZ notification assets to BYON_) - -The code will reconfigure the Service Health alerts to use either the customer's action groups to the ALZ pattern notification assets according to the selected case. +The code will reconfigure the Service Health alerts to use either the customer's action groups or the ALZ pattern notification assets based on the selected scenario. [Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md b/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md index 87df02d73..9f10fcf9b 100644 --- a/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md +++ b/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md @@ -4,7 +4,7 @@ geekdocCollapseSection: true weight: 70 --- -In some scenarios, it may be necessary to remove everything deployed by the AMBA solution. The instructions below detail execution of a PowerShell script to delete all resources deployed, including: +In certain situations, you may need to remove all resources deployed by the AMBA solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all deployed resources, including: - Metric Alerts - Activity Log Alerts @@ -14,37 +14,40 @@ In some scenarios, it may be necessary to remove everything deployed by the AMBA - Policy Set Definitions - Policy Assignment remediation identity role assignments -All resources deployed as part of the initial AMBA deployment and the resources created dynamically by 'deploy if not exist' policies are either tagged, marked in metadata, or in description (depending on what the resource supports) with the value `_deployed_by_amba` or `_deployed_by_amba=True`. This metadata is used to execute the cleanup of deployed resources; _if it has been removed or modified the cleanup script will not include those resources_. +All resources deployed as part of the initial AMBA deployment, as well as those created dynamically by 'deploy if not exist' policies, are tagged, marked in metadata, or described (depending on resource capabilities) with the value `_deployed_by_amba` or `_deployed_by_amba=True`. This metadata is crucial for the cleanup process; if it has been removed or altered, the cleanup script will not target those resources. ## Cleanup Script Execution {{< hint type=Important >}} -It is highly recommended to **thoroughly** test the script before running on production environments. The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. +It is strongly advised to **thoroughly** test the script in a non-production environment before deploying it to production. These sample scripts are not covered by any Microsoft standard support program or service. They are provided "AS IS" without any warranty, express or implied. Microsoft disclaims all implied warranties, including but not limited to, implied warranties of merchantability or fitness for a particular purpose. The user assumes all risks associated with the use or performance of the sample scripts and documentation. Microsoft, its authors, or any contributors to the creation, production, or delivery of the scripts shall not be liable for any damages, including but not limited to, loss of business profits, business interruption, loss of business information, or other financial losses, arising from the use or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. {{< /hint >}} ### Download the script file -Follow the instructions below to download the cleanup script file. Alternatively, clone the repo from GitHub and ensure you are working from the latest version of the file by fetching the latest `main` branch. +To download the cleanup script file, follow these steps. Alternatively, you can clone the repository from GitHub and ensure you are working with the latest version by fetching the latest `main` branch. -1. Navigate AMBA [project in GitHub](https://github.com/Azure/azure-monitor-baseline-alerts) -2. In the folder structure, browse to the `patterns/alz/scripts` directory -3. Open the **Start-AMBACleanup.ps1** script file -4. Click the **Raw** button -5. Save the open file as **Start-AMBACleanup.ps1** +1. Navigate to the [AMBA project on GitHub](https://github.com/Azure/azure-monitor-baseline-alerts). +2. Browse to the `patterns/alz/scripts` directory. +3. Open the **Start-AMBACleanup.ps1** script file. +4. Click the **Raw** button. +5. Save the file as **Start-AMBACleanup.ps1**. ### Executing the Script -1. Open PowerShell -2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph` -3. Change directories to the location of the **Start-AMBACleanup.ps1** script -4. Configure the _**$pseudoRootManagementGroup**_ variable using the command below: +1. Launch PowerShell. +2. Install the **Az.ResourceGraph** module by executing the following command: + ```powershell + Install-Module Az.ResourceGraph + ``` +3. Navigate to the directory containing the **Start-AMBACleanup.ps1** script. +4. Set the _**$pseudoRootManagementGroup**_ variable using the command below: ```powershell - $pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" + $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" ``` -5. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the desired Management Group scope. -6. Execute the script using one of the options below: +5. Sign in to your Azure account using the `Connect-AzAccount` command. Ensure that the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. +6. Run the script with one of the following options: {{% include "PowerShell-ExecutionPolicy.md" %}} diff --git a/docs/content/patterns/alz/HowTo/Disabling-Policies.md b/docs/content/patterns/alz/HowTo/Disabling-Policies.md index 1a7e77cbf..831f8baaa 100644 --- a/docs/content/patterns/alz/HowTo/Disabling-Policies.md +++ b/docs/content/patterns/alz/HowTo/Disabling-Policies.md @@ -4,15 +4,15 @@ geekdocCollapseSection: true weight: 60 --- -The policies in AMBA provide multiple methods to enable or disable the effects of the policy. +The Azure Monitor Baseline Alerts (AMBA) policies offer various methods to enable or disable the effects of the policies. -1. **Parameter: AlertState** - Determines the state of the alert rule. This either deploys an alert rule in a disabled state, or disables an already deployed alert rule at scale trough policy. -2. **Parameter: PolicyEffect** - Determines the effect of a Policy Definition, allowing a Policy to be deployed in a disabled state. -3. **Tag: MonitorDisable** - A tag that determines whether the resource should be evaluated. Allows you to exclude selected resources from monitoring. +1. **Parameter: AlertState** - Configures the state of the alert rule, enabling deployment of alert rules in a disabled state or disabling existing alert rules at scale through policy. +2. **Parameter: PolicyEffect** - Defines the effect of a Policy Definition, allowing the policy to be deployed in a disabled state. +3. **Tag: MonitorDisable** - Specifies whether a resource should be evaluated, enabling exclusion of selected resources from monitoring. ## AlertState parameter -Recognizing that it is not always possible to test alerts in a dev/test environment, we have introduced the AlertState parameter for all metric alerts (in the initiatives and the example parameter file the parameter is named combining {resourceType}, {metricName} and AlertState, for example VnetGwTunnelIngressAlertState). This is to address a scenario where an alert storm occurs and it is necessary to disable one or more alerts deployed via policies through a controlled process. This could be considered for a roll-back process as part of a change request. +In scenarios where it is not feasible to test alerts in a development or test environment, the AlertState parameter has been introduced for all metric alerts. This parameter, named by combining {resourceType}, {metricName}, and AlertState (e.g., VnetGwTunnelIngressAlertState), allows for the controlled disabling of one or more alerts deployed via policies. This feature is particularly useful in situations where an alert storm occurs and a rollback process is necessary as part of a change request. ### Allowed values @@ -21,7 +21,7 @@ Recognizing that it is not always possible to test alerts in a dev/test environm ### How it works -The AlertState parameter is used for both compliance evaluation and configuration of the state of the alert rule. The value of the **AlertState** parameter is passed on to the **enabled** parameter which is part of the existenceCondition of the Policy. +The **AlertState** parameter serves dual purposes: compliance evaluation and configuring the state of the alert rule. The value assigned to the **AlertState** parameter is transferred to the **enabled** parameter, which is a component of the policy's existenceCondition. ```json "existenceCondition": { @@ -46,31 +46,31 @@ The AlertState parameter is used for both compliance evaluation and configuratio } ``` -If "allOf" evaluates to true, the effect is satisfied and doesn't trigger the deployment. If you have implemented the alert rules before and want to disable an alert rule you can change the Alert State to "false", this will cause "allOf" to evaluate as false, which will trigger the deployment that changes the "enabled" property of the alert rule to false. +If "allOf" evaluates to true, the policy effect is satisfied, and the deployment does not proceed. To disable an existing alert rule, set the AlertState parameter to "false". This change causes "allOf" to evaluate as false, triggering the deployment that updates the "enabled" property of the alert rule to false. ### Deployment steps -These are the high-level steps that would need to take place: +These are the high-level steps to disable policies: -1. Change the value for the AlertState parameter for the offending policies to false, either via command line or parameter file as described previously. -2. Deploy the policies and assignments as described previously. -3. After deploying and policy evaluation there will be a number of non-compliant policies depending on which alerts were to be disabled. These will then need to be remediated which can be done either through the portal, on a policy-by-policy basis or you can run the script found in [patterns/alz/scripts/Start-AMBARemediation](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBARemediation.ps1) to remediate all ALZ-Monitor policies in scope as defined by management group pre-fix. +1. Set the AlertState parameter to "false" for the relevant policies, either via command line or parameter file. +2. Deploy the policies and assignments as previously described. +3. After deployment and policy evaluation, identify non-compliant policies based on the alerts to be disabled. Remediate these policies through the portal on a policy-by-policy basis or use the script available at [patterns/alz/scripts/Start-AMBARemediation](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBARemediation.ps1) to remediate all ALZ-Monitor policies in scope as defined by the management group prefix. -Note that the above approach will not delete the alerts objects in Azure, merely disable them. To delete the alerts you will have to do so manually. Also note that while you can engage the PolicyEffect to avoid deploying new alerts, you should not do so until you have successfully remediated the above. Otherwise the policy will be disabled, and you will not be able to turn alerts off via policy until that is changed back. +Note: This approach will disable the alerts but not delete them. To delete alerts, you must do so manually. Ensure successful remediation before engaging the PolicyEffect to avoid deploying new alerts, as disabling the policy will prevent turning off alerts via policy until it is re-enabled. ## PolicyEffect parameter -In general, we evaluate the alert rules on best practices, field experience, customer feedback, type of alert and possible impact. There are situations where disabling the policy makes sense to prevent receiving unnecessary and/or duplicate alerts/notifications. For example we deploy an alert rule for VPN Gateway Bandwidth Utilization, in turn we have disabled the alert rules for VPN Gateway Egress and Ingress. -The default is intended to provide a well balanced baseline. However you may want to Enable or Disable the creation of certain Alert rules to meet your needs. +In practice, alert rules are evaluated based on best practices, field experience, customer feedback, alert type, and potential impact. There are scenarios where disabling a policy is beneficial to avoid unnecessary or duplicate alerts. For instance, while we deploy an alert rule for VPN Gateway Bandwidth Utilization, we have disabled the alert rules for VPN Gateway Egress and Ingress to prevent redundant notifications. +The default settings are designed to offer a balanced baseline, but adjustments may be necessary to better align with your specific requirements. ### Allowed values -- "deployIfNotExists" - Policy will deploy the alert rule if the conditions are met. (Default for most Policies) -- "disabled" - The policy itself will be created but will not create the corresponding Alert rule. +- "deployIfNotExists" - The policy will deploy the alert rule if the specified conditions are met. This is the default setting for most policies. +- "disabled" - The policy will be created, but it will not deploy the corresponding alert rule. ### How it works -The PolicyEffect parameter is used for the configuration of the effect of the PolicyDefinition (in the initiatives and the example parameter file the parameter is named combining {resourceType}, {metricName} and PolicyEffect, for example ERCIRQoSDropBitsinPerSecPolicyEffect) . The value of the **PolicyEffect** parameter is passed on to the **effect** parameter which configures the effect of the Policy. +The **PolicyEffect** parameter configures the effect of the Policy Definition. In the initiatives and example parameter files, this parameter is named by combining {resourceType}, {metricName}, and PolicyEffect (e.g., ERCIRQoSDropBitsinPerSecPolicyEffect). The value assigned to the **PolicyEffect** parameter is transferred to the **effect** parameter, which determines the policy's effect. ```json "policyRule": { @@ -92,7 +92,7 @@ The PolicyEffect parameter is used for the configuration of the effect of the Po ## MonitorDisable parameter -It´s also possible to exclude certain resources from being monitored. You may not want to monitor pre-production or dev environments. The MonitorDisable parameter contains the tag name and tag value to determine whether a resource should be included. By default, creating the tag MonitorDisable with value ___"true"___ will prevent deployment of alert rules on those resources. This can be easily adjusted to use existing tags and tag values. For example you could configure the parameters with the tag name ___Environment___ and tag value of ___Production___ or ___Test___ or ___Sandbox___ or all of them to exclude resources in these environments (see the sample parameter section). +It is also possible to exclude specific resources from monitoring. For instance, you might not want to monitor pre-production or development environments. The **MonitorDisable** parameter includes the tag name and tag value to determine whether a resource should be monitored. By default, creating a tag named **MonitorDisable** with the value **"true"** will prevent the deployment of alert rules on those resources. This can be easily adjusted to use existing tags and tag values. For example, you could configure the parameters with the tag name **Environment** and tag values such as **Production**, **Test**, or **Sandbox** to exclude resources in these environments (refer to the sample parameter section). ```json . @@ -111,12 +111,11 @@ It´s also possible to exclude certain resources from being monitored. You may n . . ``` - -This will deploy policy definitions which will only be evaluated and remediated if the tag value(s) are not included in the list you provided. +This deployment will implement policy definitions that will only be evaluated and remediated if the specified tag values are not present in the provided list. ### How it works -The policyRule only continues if "allOff" is true. Meaning, the deployment will continue as long as the MonitorDisableTagName tag doesn't exist or doesn't hold the any of the values listed in the MonitorDisableTagValues parameter. When the tag holds one of the configured values, the "allOff" will return "false" as _"notIn": "[[parameters('MonitorDisableTagValues')]"_ is no longer satisfied, causing the evaluation and hence the remediation to stop. +The policy rule proceeds only if "allOf" evaluates to true. This means the deployment will continue as long as the tag specified by the MonitorDisableTagName parameter does not exist or does not contain any of the values listed in the MonitorDisableTagValues parameter. If the tag contains one of the specified values, the "allOf" condition will evaluate to false because the _"notIn": "[parameters('MonitorDisableTagValues')]"_ condition is not met, thereby halting the evaluation and remediation process. ```json "policyRule": { @@ -134,9 +133,10 @@ The policyRule only continues if "allOff" is true. Meaning, the deployment will }, ``` -Given the different resource scope that this method can be applied to, we made it working a little bit different when it comes to log-based alerts. For instance, the virtual machine alerts are scoped to subscription and tagging the subcription would result in disabling all the policies targeted at it. -For this reason, and thanks to the new _**Bring Your Own User Assigned Managed Identity (BYO UAMI)**_ included in the [2024-06-05](../../Overview/Whats-New#2024-06-05) release and to the ability to query Azure resource Graph using Azure Monitor (see [Quickstart: Create alerts with Azure Resource Graph and Log Analytics](https://learn.microsoft.com/en-us/azure/governance/resource-graph/alerts-query-quickstart?tabs=azure-resource-graph)), it is now possible to disable individual alerts for both Azure and hybrid virtual machines after they are created. We got requests to stop alerting fro virtual machines that were off for maintenance and this enhancement came up just in time. +Given the varying resource scopes to which this method can be applied, the approach for log-based alerts differs slightly. For example, virtual machine alerts are scoped to the subscription level, and tagging the subscription would disable all targeted policies. + +With the introduction of the _**Bring Your Own User Assigned Managed Identity (BYO UAMI)**_ feature in the [2024-06-05](../../Overview/Whats-New#2024-06-05) release, and the capability to query Azure Resource Graph using Azure Monitor (refer to [Quickstart: Create alerts with Azure Resource Graph and Log Analytics](https://learn.microsoft.com/en-us/azure/governance/resource-graph/alerts-query-quickstart?tabs=azure-resource-graph)), it is now feasible to disable individual alerts for both Azure and hybrid virtual machines post-creation. This enhancement addresses requests to stop alerting for virtual machines that are offline for maintenance, providing a timely solution. -Should you need to disable the alerts for your virtual machines after they are created, just make sure you tag the relevant resources accordingly. The alert queries have been modified to look at resource properties in [Azure Resource Graph](https://learn.microsoft.com/en-us/azure/governance/resource-graph/overview). If the resource contains the given tag name and tag value, it is made part of an exclusion list, so alerts will not be generated for them. This behavior allows you to dinamically and rapidly exclude the necessary resources from being alerted without the need of deleteing the alert, tag the resource and run the remediation again. +To disable alerts for your virtual machines after they are created, ensure that you tag the relevant resources appropriately. The alert queries have been updated to reference resource properties in [Azure Resource Graph](https://learn.microsoft.com/en-us/azure/governance/resource-graph/overview). If a resource contains the specified tag name and tag value, it will be included in an exclusion list, preventing alerts from being generated for those resources. This approach allows for dynamic and rapid exclusion of necessary resources from alerts without needing to delete the alert. Simply tag the resource and run the remediation process again. [Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/Log_Search_Alert_Table.md b/docs/content/patterns/alz/HowTo/Log_Search_Alert_Table.md index 7d20008bf..becf9e469 100644 --- a/docs/content/patterns/alz/HowTo/Log_Search_Alert_Table.md +++ b/docs/content/patterns/alz/HowTo/Log_Search_Alert_Table.md @@ -28,4 +28,4 @@ geekdocHidden: true | Virtual machine | *```subscription().displayName```*-VMHighOSDiskWriteLatencyAlert | _Log search_ | ***\_amba-WriteLatencyMs-OS-threshold-override\_*** | | Virtual machine | *```subscription().displayName```*-VMHighCPUAlert | _Log search_ | ***\_amba-UtilizationPercentage-threshold-override\_*** | | Virtual machine | *```subscription().displayName```*-VMLowMemoryAlert | _Log search_ | ***\_amba-AvailableMemoryPercentage-threshold-override\_*** | -| Log Analytics workspace | *```resourceName```*-DailyCapLimitReachedAlert | _Log search_ | ***Not available since threshold will always be ```0```*** | +| Log Analytics workspace | *```resourceName```*-DailyCapLimitReachedAlert | _Log search_ | ***Not available as threshold will always be ```0```*** | diff --git a/docs/content/patterns/alz/HowTo/Metrics_Alert_Table.md b/docs/content/patterns/alz/HowTo/Metrics_Alert_Table.md index 0af9d5640..72763772b 100644 --- a/docs/content/patterns/alz/HowTo/Metrics_Alert_Table.md +++ b/docs/content/patterns/alz/HowTo/Metrics_Alert_Table.md @@ -8,32 +8,32 @@ geekdocHidden: true | Virtual machine | *```resourceName```*-AvailableMemoryAlert | Metrics | ***\_amba-AvailableMemoryBytes-threshold-override\_*** | | Automation Account | *```resourceName```*-TotalJob | Metrics | ***\_amba-TotalJob-threshold-override\_*** | | Front Door and CDN profile | *```resourceName```*-OriginHealthPercentage | Metrics | ***\_amba-OriginHealthPercentage-threshold-override\_*** | -| Front Door and CDN profile | *```resourceName```*-OriginLatencyAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| Front Door and CDN profile | *```resourceName```*-Percentage4XXAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| Front Door and CDN profile | *```resourceName```*-Percentage5XXAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| Key vault | ActivityKeyVaultDelete | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | +| Front Door and CDN profile | *```resourceName```*-OriginLatencyAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| Front Door and CDN profile | *```resourceName```*-Percentage4XXAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| Front Door and CDN profile | *```resourceName```*-Percentage5XXAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| Key vault | ActivityKeyVaultDelete | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | | Key vault | *```resourceName```*-Availability | Metrics | ***\_amba-Availability-threshold-override\_*** | | Key vault | *```resourceName```*-CapacityAlert | Metrics | ***\_amba-SaturationShoebox-threshold-override\_*** | | Key vault | *```resourceName```*-LatencyAlert | Metrics | ***\_amba-ServiceApiLatency-threshold-override\_*** | -| Key vault | *```resourceName```*-RequestsAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| Azure Key Vault Managed HSM | ActivityManagedHSMDelete | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | +| Key vault | *```resourceName```*-RequestsAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| Azure Key Vault Managed HSM | ActivityManagedHSMDelete | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | | Azure Key Vault Managed HSM | *```resourceName```*-Availability | Metrics | ***\_amba-Availability-threshold-override\_*** | | Azure Key Vault Managed HSM | *```resourceName```*-LatencyAlert | Metrics | ***\_amba-ServiceApiLatency-threshold-override\_*** | -| Application gateway | *```resourceName```*-agApplicationGatewayTotalTime | Metrics | ***Not available since it uses dynamic thresholds*** | -| Application gateway | *```resourceName```*-agBackendLastByteResponseTime | Metrics | ***Not available since it uses dynamic thresholds*** | +| Application gateway | *```resourceName```*-agApplicationGatewayTotalTime | Metrics | ***Not available as it uses dynamic thresholds*** | +| Application gateway | *```resourceName```*-agBackendLastByteResponseTime | Metrics | ***Not available as it uses dynamic thresholds*** | | Application gateway | *```resourceName```*-agCapacityUnits | Metrics | ***\_amba-CapacityUnits-threshold-override\_*** | | Application gateway | *```resourceName```*-agComputeUnits | Metrics | ***\_amba-ComputeUnits-threshold-override\_*** | | Application gateway | *```resourceName```*-agCpuUtilization | Metrics | ***\_amba-CpuUtilization-threshold-override\_*** | -| Application gateway | *```resourceName```*-agFailedRequests | Metrics | ***Not available since it uses dynamic thresholds*** | -| Application gateway | *```resourceName```*-agResponseStatus | Metrics | ***Not available since it uses dynamic thresholds*** | +| Application gateway | *```resourceName```*-agFailedRequests | Metrics | ***Not available as it uses dynamic thresholds*** | +| Application gateway | *```resourceName```*-agResponseStatus | Metrics | ***Not available as it uses dynamic thresholds*** | | Application gateway | *```resourceName```*-agUnhealthyHostCount | Metrics | ***\_amba-UnhealthyHostCount-threshold-override\_*** | -| Firewall | ActivityAzureFirewallDelete | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | +| Firewall | ActivityAzureFirewallDelete | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | | Firewall | *```resourceName```*-FirewallHealth | Metrics | ***\_amba-FirewallHealth-threshold-override\_*** | | Firewall | *```resourceName```*-SNATPortUtilization | Metrics | ***\_amba-SNATPortUtilization-threshold-override\_*** | | ExpressRoute circuit | *```resourceName```*-ArpAvailability | Metrics | ***\_amba-ArpAvailability-threshold-override\_*** | | ExpressRoute circuit | *```resourceName```*-BgpAvailability | Metrics | ***\_amba-BgpAvailability-threshold-override\_*** | -| ExpressRoute circuit | *```resourceName```*-QosDropBitsInPerSecond | Metrics | ***Not available since it uses dynamic thresholds*** | -| ExpressRoute circuit | *```resourceName```*-QosDropBitsOutPerSecond | Metrics | ***Not available since it uses dynamic thresholds*** | +| ExpressRoute circuit | *```resourceName```*-QosDropBitsInPerSecond | Metrics | ***Not available as it uses dynamic thresholds*** | +| ExpressRoute circuit | *```resourceName```*-QosDropBitsOutPerSecond | Metrics | ***Not available as it uses dynamic thresholds*** | | ExpressRoute gateway | *```resourceName```*-GatewayERBitsInAlert | Metrics | ***\_amba-ERGatewayConnectionBitsInPerSecond-threshold-override\_*** | | ExpressRoute gateway | *```resourceName```*-GatewayERBitsOutAlert | Metrics | ***\_amba-ERGatewayConnectionBitsOutPerSecond-threshold-override\_*** | | ExpressRoute gateway | *```resourceName```*-GatewayERCPUAlert | Metrics | ***\_amba-ExpressRouteGatewayCpuUtilization-threshold-override\_*** | @@ -45,12 +45,12 @@ geekdocHidden: true | ExpressRoute port | *```resourceName```*-DirectERTxLightLevelHighAlert | Metrics | ***\_amba-TxLightLevel-High-threshold-override\_*** | | ExpressRoute port | *```resourceName```*-DirectERTxLightLevelLowAlert | Metrics | ***\_amba-TxLightLevel-Low-threshold-override\_*** | | Front Door | *```resourceName```*-BackendHealthPercentage | Metrics | ***\_amba-BackendHealthPercentage-threshold-override\_*** | -| Front Door | *```resourceName```*-BackendRequestLatencyAlert | Metrics | ***Not available since it uses dynamic thresholds*** | +| Front Door | *```resourceName```*-BackendRequestLatencyAlert | Metrics | ***Not available as it uses dynamic thresholds*** | | Load balancer | *```resourceName```*-ALBDataPathAvailability | Metrics | ***\_amba-VipAvailability-threshold-override\_*** | | Load balancer | *```resourceName```*-ALBGlobalBackendAvailability | Metrics | ***\_amba-GlobalBackendAvailability-threshold-override\_*** | | Load balancer | *```resourceName```*-ALBHealthProbeStatus | Metrics | ***\_amba-DipAvailability-threshold-override\_*** | | Load balancer | *```resourceName```*-ALBUsedSNATPorts | Metrics | ***\_amba-UsedSNATPorts-threshold-override\_*** | -| Network security group | ActivityNSGDelete | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | +| Network security group | ActivityNSGDelete | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | | Private DNS zone | *```resourceName```*-CapacityUtilizationAlert | Metrics | ***\_amba-VirtualNetworkLinkCapacityUtilization-threshold-override\_*** | | Private DNS zone | *```resourceName```*-QueryVolumeAlert | Metrics | ***\_amba-QueryVolume-threshold-override\_*** | | Private DNS zone | *```resourceName```*-RecordSet_Capacity_Utilization | Metrics | ***\_amba-RecordSetCapacityUtilization-threshold-override\_*** | @@ -59,37 +59,37 @@ geekdocHidden: true | Public IP address | *```resourceName```*-DDOS_Attack | Metrics | ***\_amba-ifunderddosattack-threshold-override\_*** | | Public IP address | *```resourceName```*-PacketsInDDosAlert | Metrics | ***\_amba-PacketsInDDoS-threshold-override\_*** | | Public IP address | *```resourceName```*-VIPAvailabityAlert | Metrics | ***\_amba-VipAvailability-threshold-override\_*** | -| Route table | ActivityUDRUpdate | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | +| Route table | ActivityUDRUpdate | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | | Traffic Manager profile | *```resourceName```*-EndpointHealthAlert | Metrics | ***\_amba-EndpointHealth-threshold-override\_*** | | Virtual network gateway | *```resourceName```*-TunnelBandwidthAlert | Metrics | ***\_amba-TunnelAverageBandwidth-threshold-override\_*** | | Virtual network gateway | *```resourceName```*-TunnelEgressAlert | Metrics | ***\_amba-TunnelEgressBytes-threshold-override\_*** | -| Virtual network gateway | *```resourceName```*-TunnelEgressPacketDropCountAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| Virtual network gateway | *```resourceName```*-TunnelEgressPacketDropTSMismatchAlert | Metrics | ***Not available since it uses dynamic thresholds*** | +| Virtual network gateway | *```resourceName```*-TunnelEgressPacketDropCountAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| Virtual network gateway | *```resourceName```*-TunnelEgressPacketDropTSMismatchAlert | Metrics | ***Not available as it uses dynamic thresholds*** | | Virtual network gateway | *```resourceName```*-GatewayERBitsAlert | Metrics | ***\_amba-ExpressRouteGatewayBitsPerSecond-threshold-override\_*** | | Virtual network gateway | *```resourceName```*-GatewayERCPUAlert | Metrics | ***\_amba-ExpressRouteGatewayCpuUtilization-threshold-override\_*** | | Virtual network gateway | *```resourceName```*-TunnelIngressAlert | Metrics | ***\_amba-TunnelIngressBytes-threshold-override\_*** | -| Virtual network gateway | *```resourceName```*-TunnelIngressPacketDropCountAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| Virtual network gateway | *```resourceName```*-TunnelIngressPacketDropTSMismatchAlert | Metrics | ***Not available since it uses dynamic thresholds*** | +| Virtual network gateway | *```resourceName```*-TunnelIngressPacketDropCountAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| Virtual network gateway | *```resourceName```*-TunnelIngressPacketDropTSMismatchAlert | Metrics | ***Not available as it uses dynamic thresholds*** | | Virtual network | *```resourceName```*-DDOSAttackAlert | Metrics | ***\_amba-ifunderddosattack-threshold-override\_*** | -| VPN Gateway | ActivityVPNGatewayDelete | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | +| VPN Gateway | ActivityVPNGatewayDelete | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | | VPN Gateway | *```resourceName```*-GatewayBandwidthAlert | Metrics | ***\_amba-tunnelaveragebandwidth-threshold-override\_*** | | VPN Gateway | *```resourceName```*-BGPPeerStatusAlert | Metrics | ***\_amba-bgppeerstatus-threshold-override\_*** | | VPN Gateway | *```resourceName```*-TunnelEgressAlert | Metrics | ***\_amba-tunnelegressbytes-threshold-override\_*** | -| VPN Gateway | *```resourceName```*-TunnelEgressPacketDropCountAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| VPN Gateway | *```resourceName```*-TunnelEgressPacketDropTSMismatchAlert | Metrics | ***Not available since it uses dynamic thresholds*** | +| VPN Gateway | *```resourceName```*-TunnelEgressPacketDropCountAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| VPN Gateway | *```resourceName```*-TunnelEgressPacketDropTSMismatchAlert | Metrics | ***Not available as it uses dynamic thresholds*** | | VPN Gateway | *```resourceName```*-TunnelIngressAlert | Metrics | ***\_amba-tunnelingressbytes-threshold-override\_*** | -| VPN Gateway | *```resourceName```*-TunnelIngressPacketDropCount | Metrics | ***Not available since it uses dynamic thresholds*** | -| VPN Gateway | *```resourceName```*-TunnelIngressPacketDropTSMismatchAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| Log Analytics workspace | ActivityLAWorkspaceDelete | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | -| Log Analytics workspace | ActivityLAWorkspaceRegenKey | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | -| Subscription | ResourceHealthUnhealthyAlert | Resource health | ***Not available since Activity Log based alerts do not have thresholds*** | -| Subscription | ServiceHealthHealth | Service health | ***Not available since Activity Log based alerts do not have thresholds*** | -| Subscription | ServiceHealthIncident | Service health | ***Not available since Activity Log based alerts do not have thresholds*** | -| Subscription | ServiceHealthMaintenance | Service health | ***Not available since Activity Log based alerts do not have thresholds*** | -| Subscription | ServiceSecurityIncident | Service health | ***Not available since Activity Log based alerts do not have thresholds*** | -| Storage account | ActivitySADelete | Activity Log | ***Not available since Activity Log based alerts do not have thresholds*** | +| VPN Gateway | *```resourceName```*-TunnelIngressPacketDropCount | Metrics | ***Not available as it uses dynamic thresholds*** | +| VPN Gateway | *```resourceName```*-TunnelIngressPacketDropTSMismatchAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| Log Analytics workspace | ActivityLAWorkspaceDelete | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | +| Log Analytics workspace | ActivityLAWorkspaceRegenKey | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | +| Subscription | ResourceHealthUnhealthyAlert | Resource health | ***Not available as Activity Log based alerts do not have thresholds*** | +| Subscription | ServiceHealthHealth | Service health | ***Not available as Activity Log based alerts do not have thresholds*** | +| Subscription | ServiceHealthIncident | Service health | ***Not available as Activity Log based alerts do not have thresholds*** | +| Subscription | ServiceHealthMaintenance | Service health | ***Not available as Activity Log based alerts do not have thresholds*** | +| Subscription | ServiceSecurityIncident | Service health | ***Not available as Activity Log based alerts do not have thresholds*** | +| Storage account | ActivitySADelete | Activity Log | ***Not available as Activity Log based alerts do not have thresholds*** | | Storage account | *```resourceName```*-AvailabilityAlert | Metrics | ***\_amba-Availability-threshold-override\_*** | | App Service plan | *```resourceName```*-CpuPercentage | Metrics | ***\_amba-CpuPercentage-threshold-override\_*** | -| App Service plan | *```resourceName```*-DiskQueueLengthAlert | Metrics | ***Not available since it uses dynamic thresholds*** | -| App Service plan | *```resourceName```*-HttpQueueLengthAlert | Metrics | ***Not available since it uses dynamic thresholds*** | +| App Service plan | *```resourceName```*-DiskQueueLengthAlert | Metrics | ***Not available as it uses dynamic thresholds*** | +| App Service plan | *```resourceName```*-HttpQueueLengthAlert | Metrics | ***Not available as it uses dynamic thresholds*** | | App Service plan | *```resourceName```*-MemoryPercentage | Metrics | ***\_amba-MemoryPercentage-threshold-override\_*** | diff --git a/docs/content/patterns/alz/HowTo/Telemetry.md b/docs/content/patterns/alz/HowTo/Telemetry.md index 2f1e6873d..344f50102 100644 --- a/docs/content/patterns/alz/HowTo/Telemetry.md +++ b/docs/content/patterns/alz/HowTo/Telemetry.md @@ -10,13 +10,13 @@ weight: 90 -Microsoft can identify the deployments of the Azure Resource Manager and Bicep templates with the deployed Azure resources. Microsoft can correlate these resources used to support the deployments. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through [customer usage attribution](https://docs.microsoft.com/azure/marketplace/azure-partner-customer-usage-attribution). The data is collected and governed by Microsoft's privacy policies, located at the [trust center](https://www.microsoft.com/trustcenter). +Microsoft can identify deployments of Azure Resource Manager and Bicep templates by correlating them with the deployed Azure resources. This telemetry data helps Microsoft enhance product experiences and manage their services effectively. The telemetry is collected via [customer usage attribution](https://docs.microsoft.com/azure/marketplace/azure-partner-customer-usage-attribution) and is governed by Microsoft's privacy policies, which can be found at the [Microsoft Trust Center](https://www.microsoft.com/trustcenter). -To disable this tracking, we have included a parameter called `telemetryOptOut` to the deployment template in this repo with a simple boolean flag. The default value `No` which **does not** disable the telemetry. If you would like to disable this tracking, then simply set this value to `Yes` and this module will not be included in deployments and **therefore disables** the telemetry tracking. +To disable telemetry tracking, a parameter named `telemetryOptOut` has been added to the deployment template in this repository. This parameter uses a boolean flag, with the default value set to `No`, which means telemetry tracking is **enabled**. To disable telemetry tracking, change the value to `Yes`. This will exclude the module from deployments, effectively **disabling** telemetry tracking. -If you are happy with leaving telemetry tracking enabled, no changes are required. +To keep telemetry tracking enabled, no modifications are necessary. -For example, in the alzArm.json file, you will see the following: +For instance, in the `alzArm.json` file, you will find the following configuration: ```json "telemetryOptOut": { @@ -32,7 +32,7 @@ For example, in the alzArm.json file, you will see the following: } ``` -The default value is `No`, but can be changed to `Yes` in the parameter file. If set to `Yes` the deployment below will be ignored and therefore telemetry will not be tracked. +To disable telemetry tracking, set the `telemetryOptOut` parameter to `Yes` in the parameter file. When this parameter is set to `Yes`, the deployment specified below will be skipped, and telemetry data will not be collected. ```json { @@ -54,7 +54,7 @@ The default value is `No`, but can be changed to `Yes` in the parameter file. If ## Module PID Value Mapping -The following are the unique ID's (also known as PIDs) used in the AMBA deployment +The following are the unique IDs (also known as PIDs) used in the AMBA deployment | Name | PID | Telemetry for | | ------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------- | diff --git a/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md b/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md index fa85acb0c..fa6d306a9 100644 --- a/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md +++ b/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md @@ -4,22 +4,22 @@ geekdocCollapseSection: true weight: 65 --- -Azure Monitor alerts targeted to a large scope allow for at scale coverage, but reduce the flexibility to disable them for specific resources. There might be several reason to stop the notification of alerts. For instance, customers could have resources that are stopped or disabled due to maintenance or just want to stop the notification during the night shift. To allow this kind of flexibility, as part of the Notification Assets policy initiative, AMBA-ALZ provides you with an asset to stop the notification for specific resources. +Azure Monitor alerts configured for a broad scope provide extensive coverage but limit the ability to disable them for specific resources. There are various reasons to halt alert notifications, such as resources being stopped or disabled for maintenance, or the desire to suppress notifications during night shifts. To offer this level of flexibility, the Notification Assets policy initiative includes an asset from AMBA-ALZ that allows you to stop notifications for specific resources. -This asset is made of an alert processing rule (also known as APR) with the following characteristics: +This asset consists of an alert processing rule (APR) with the following characteristics: -- deployed as disabled -- scoped at the subscription level -- suppression rule type -- scheduled to run always +- Initially deployed in a disabled state +- Applied at the subscription level +- Configured as a suppression rule +- Set to run continuously -This APR needs to be configured with the resource ID of the resource(s) for which you want to stop notifications and then enabled every time you need it. +To utilize this APR, configure it with the resource ID(s) of the resources for which you want to suppress notifications. Enable the rule whenever suppression is required. -Once the resource is out of the maintenance period or when you don't need the suppression rule anymore, ***remember*** to remove the resources and disable the rule. +When the maintenance period concludes or the suppression rule is no longer needed, ensure to remove the specified resources and disable the rule. -To know more about how to suppress notifications, see [Suppress notifications during planned maintenance](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-processing-rules?tabs=portal#suppress-notifications-during-planned-maintenance) +For detailed information on how to suppress notifications, refer to the [Suppress notifications during planned maintenance](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-processing-rules?tabs=portal#suppress-notifications-during-planned-maintenance) documentation. -To configure the APR, do the following: +To configure the APR, follow these steps: 1. In **Monitor --> Alerts**, click on **Alert processing rules** @@ -42,7 +42,7 @@ To configure the APR, do the following: ![Configure filter](../../media/Filter-AlertProcessingRule.png) {{< hint type=Important >}} - Each filter can include up to ***5*** values. Should you need more than **5** resources, add more lines of filter. + Each filter can include up to ***5*** values. If you need to specify more than **5** resources, add additional filter lines. {{< /hint >}} 5. Click on ***Review + save*** and then ***Save*** diff --git a/docs/content/patterns/alz/HowTo/Threshold-Override.md b/docs/content/patterns/alz/HowTo/Threshold-Override.md index 2a661cf77..5494e7db5 100644 --- a/docs/content/patterns/alz/HowTo/Threshold-Override.md +++ b/docs/content/patterns/alz/HowTo/Threshold-Override.md @@ -6,40 +6,41 @@ weight: 85 # Overview -The ***Alert Threshold Override*** feature, available with release [2024-09-05](../../Whats-New#2024-09-05), allows both Greenfield and Brownfield customers to override alert threshold for specific resources during or after the deployment of AMBA-ALZ. Thanks to this new feature, it's now possible to use a tag with specific name and value, to override the default alert threshold for specific resources. The new value will be used, only for the tagged resources, in place of the global one coming from the parameter file. +The ***Alert Threshold Override*** feature, introduced in the [2024-09-05 release](../../Whats-New#2024-09-05), enables both Greenfield and Brownfield customers to customize alert thresholds for specific resources during or after the deployment of AMBA-ALZ. This feature allows the use of a tag with a specific name and value to override the default alert threshold for designated resources. The new threshold value will apply exclusively to the tagged resources, replacing the global threshold specified in the parameter file. # How this feature works -This feature is only available for metrics and log-search alerts, since Activity Log based alerts do not use threshold and, as such, cannot benefits from this new enhancement. Using the feature is easy: customers need to create a resource tag with a specific name and assign a value of their choice. Once this release is deployed, tags can be created either before or after the execution of remediation task. However, the feature behavior differs between Metric and Log-search alerts. +This feature is applicable exclusively to metrics and log-search alerts, as Activity Log-based alerts do not utilize thresholds and therefore cannot benefit from this enhancement. To use this feature, customers must create a resource tag with a specific name and assign it a desired value. After deploying this release, tags can be created either before or after the remediation task execution. However, the feature's behavior varies between Metric and Log-search alerts. ## Metrics alerts -For metric alerts, if tags are configured before the remediation tasks execution, corresponding alerts (which are resource-specific) will be created using different thresholds for the same resource type: +If tags are configured before the remediation tasks execution, metric alerts will be created with the specified thresholds for the tagged resources, ensuring that each resource type has the appropriate alert thresholds applied. ![Metric Alerts - Override threshold at work](../../media/MetricAlerts-OverrideThresholdAtWork.png) -If the tags are configured after the remediation task have completed, given the tag being part of the compliance criteria, the resource will be marked as not compliant, as such customers will just need to remediate the corresponding policy initiative(s) as documented at [Remediate Policies](../../deploy/Remediate-Policies) to reconfigure exiting alerts with the new threshold. +If the tags are configured after the remediation tasks have completed, the resource will be marked as non-compliant due to the tag being part of the compliance criteria. Customers will need to remediate the corresponding policy initiative(s) as documented in [Remediate Policies](../../deploy/Remediate-Policies) to reconfigure existing alerts with the new threshold. ## Log-search alerts -Considering the different nature of log-search alerts where resource information is retrieved at query runtime, it does not make any difference if the tags are configured before or after the remediation task execution. The log-search alert query is created with a placeholder containing the threshold passed by the parameter file and with a logic to look at the resource-specific override tag, thanks to the ability to [Correlate data in Azure Data Explorer and Azure Resource Graph with data in a Log Analytics workspace](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/azure-monitor-data-explorer-proxy). If the specific override tag name is present, the query will use the tag value as new threshold, otherwise it will use the default one passed through the parameter file: + +Considering the nature of log-search alerts, where resource information is retrieved at query runtime, it does not matter if the tags are configured before or after the remediation task execution. The log-search alert query is created with a placeholder containing the threshold specified in the parameter file and includes logic to check for the resource-specific override tag. This is made possible by the ability to [correlate data in Azure Data Explorer and Azure Resource Graph with data in a Log Analytics workspace](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/azure-monitor-data-explorer-proxy). If the specific override tag is present, the query will use the tag value as the new threshold; otherwise, it will use the default threshold from the parameter file. ![Log-search Alerts - Override threshold at work](../../media/LogsearchAlerts-OverrideThresholdAtWork.png) ## Which tag does customers need to create -To work correctly, this feature needs to look at specific tag names. Unfortunately it is not possible to allow for more flexibility in tag name in this case. Tag names have been defined, according to the following naming convention: +To ensure proper functionality, this feature requires specific tag names. Flexibility in tag naming is not supported in this case. The tag names must adhere to the following naming convention: {{< hint type=Info >}} -Mapping between resource type friendly name and resource provider namespace (together with the recommended abbreviation) can be found at [Abbreviation recommendations for Azure resources](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations) +For a comprehensive list of resource type friendly names, resource provider namespaces, and recommended abbreviations, refer to [Abbreviation recommendations for Azure resources](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations). {{< /hint >}} ```***_amba--threshold-override_***``` -There might be cases where for the same resource, the same metric is used more than one. In this scenario, we implemented a differentiator value inserted right after the metric name, making the naming convention resampling the following format: +In scenarios where the same metric is used multiple times for the same resource, a differentiator value is implemented immediately after the metric name. This ensures the naming convention follows the format: ```***_amba---threshold-override_***``` -The following table contains the mapping between the alert name and the corresponding tag value to be created: +The following table provides a mapping between alert names and the corresponding tag values that need to be created:
diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md index 93c2a0e7a..39fb5cdc1 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md @@ -3,8 +3,7 @@ title: Moving from preview to GA geekdocCollapseSection: true weight: 101 --- - -When moving from the preview version to GA, it is required to remove everything deployed by the ALZ Monitor solution. The instructions below detail execution of a PowerShell script to delete all resources deployed, including: +When transitioning from the preview version to the General Availability (GA) version, it is necessary to remove all resources deployed by the ALZ Monitor solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all such resources, including: - Metric Alerts - Activity Log Alerts @@ -14,31 +13,31 @@ When moving from the preview version to GA, it is required to remove everything - Policy Set Definitions - Policy Assignment remediation identity role assignments -All resources deployed as part of the initial ALZ Monitor deployment and the resources created dynamically by 'deploy if not exist' policies are either tagged, marked in metadata, or in description (depending on what the resource supports) with the value `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is used to execute the cleanup of deployed resources; _if it has been removed or modified the cleanup script will not include those resources_. +All resources deployed by the initial ALZ Monitor deployment, as well as those created dynamically by 'deploy if not exist' policies, are tagged, marked in metadata, or described (depending on resource capabilities) with `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is crucial for the cleanup script to identify and remove the resources. If this metadata has been altered or removed, the cleanup script will not recognize those resources for deletion. ## Cleanup Script Execution {{< hint type=Important >}} -It is highly recommended to **thoroughly** test the script before running on production environments. The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. +It is strongly advised to **thoroughly** test the script in a non-production environment before deploying it to production. These sample scripts are not covered by any Microsoft standard support program or service. They are provided "AS IS" without any warranty, express or implied. Microsoft disclaims all implied warranties, including but not limited to, implied warranties of merchantability or fitness for a particular purpose. The user assumes all risks associated with the use or performance of the sample scripts and documentation. Microsoft, its authors, or any contributors to the creation, production, or delivery of the scripts shall not be liable for any damages, including but not limited to, loss of business profits, business interruption, loss of business information, or other financial losses, arising from the use or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. {{< /hint >}} ### Download the script file -Follow the instructions below to download the cleanup script file. Alternatively, clone the repo from GitHub and ensure you are working from the latest version of the file by fetching the latest `main` branch. +Follow these steps to download the cleanup script file. Alternatively, you can clone the repository from GitHub and ensure you have the latest version by fetching the `main` branch. -1. Navigate AMBA [project in GitHub](https://github.com/Azure/azure-monitor-baseline-alerts) -2. In the folder structure, browse to the `patterns/alz/scripts` directory -3. Open the **Start-ALZMonitorCleanup.ps1** script file -4. Click the **Raw** button -5. Save the open file as **Start-ALZMonitorCleanup.ps1** +1. Navigate to the [AMBA project on GitHub](https://github.com/Azure/azure-monitor-baseline-alerts). +2. Browse to the `patterns/alz/scripts` directory. +3. Locate and open the **Start-ALZMonitorCleanup.ps1** script file. +4. Click on the **Raw** button to view the raw content of the script. +5. Save the file as **Start-ALZMonitorCleanup.ps1**. ### Executing the Script -1. Open PowerShell -2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph` -3. Change directories to the location of the **Start-ALZMonitorCleanup.ps1** script -4. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the desired Management Group scope. -5. Execute the script using the option below +1. Launch PowerShell. +2. Install the **Az.ResourceGraph** module by running: `Install-Module Az.ResourceGraph`. +3. Navigate to the directory containing the **Start-ALZMonitorCleanup.ps1** script. +4. Sign in to Azure using the `Connect-AzAccount` command. Ensure the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. +5. Execute the script with one of the following options: {{% include "PowerShell-ExecutionPolicy.md" %}} @@ -61,11 +60,10 @@ Follow the instructions below to download the cleanup script file. Alternatively ``` ## Next steps - -- To customize policy assignments, please proceed with [Customize Policy Assignment](../../HowTo/deploy/Customize-Policy-Assignment) -- To deploy with GitHub Actions, please proceed with [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions) -- To deploy with Azure DevOps Pipelines, please proceed with [Deploy with Azure Pipelines](../../HowTo/deploy/Deploy-with-Azure-Pipelines) -- To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../../HowTo/deploy/Deploy-with-Azure-CLI) -- To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../../HowTo/deploy/Deploy-with-Azure-PowerShell) +- For customizing policy assignments, refer to [Customize Policy Assignment](../../HowTo/deploy/Customize-Policy-Assignment). +- For deployment using GitHub Actions, refer to [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions). +- For deployment using Azure DevOps Pipelines, refer to [Deploy with Azure Pipelines](../../HowTo/deploy/Deploy-with-Azure-Pipelines). +- For deployment using Azure CLI, refer to [Deploy with Azure CLI](../../HowTo/deploy/Deploy-with-Azure-CLI). +- For deployment using Azure PowerShell, refer to [Deploy with Azure PowerShell](../../HowTo/deploy/Deploy-with-Azure-PowerShell). [Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md index f6298c370..218f14c04 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md @@ -8,20 +8,21 @@ weight: 100 Updating from release [2023-11-14](../../../Overview/Whats-New#2023-11-14) will require running a post update script to remove the old Service Health action group(s) no longer in use. - To run the script, follow the following instructions: - - 1. Open PowerShell - 2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph` - 3. Change directories to the location of the **Start-AMBAOldArpCleanup.ps1** script - 4. Configure the _**$pseudoRootManagementGroup**_ variable using the following command: +To execute the script, follow these steps: +1. Launch PowerShell. +2. Install the **Az.ResourceGraph** module by executing the following command: + ```powershell + Install-Module Az.ResourceGraph + ``` +3. Navigate to the directory containing the **Start-AMBAOldArpCleanup.ps1** script. +4. Set the _**$pseudoRootManagementGroup**_ variable with the following command: ```powershell $pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" ``` + 1. Sign in to your Azure account using the `Connect-AzAccount` command. Ensure that the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. - 1. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the wanted Management Group scope. - - 2. Execute the script using one of the following options: + 2. Run the script with one of the following options: {{% include "PowerShell-ExecutionPolicy.md" %}} diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md index 51dfca383..c4946dfd2 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md @@ -4,27 +4,25 @@ geekdocCollapseSection: true weight: 99 --- {{< hint type=Important >}} -***No post update action required*** for Greenfield customers or for Brownfield customers that prefer to continue using notification assets deployed by the ALZ pattern code. +***No post update action required*** for Greenfield or Brownfield customers that prefer to continue using notification assets deployed by the ALZ pattern code. {{< /hint >}} # Post update actions -Updating from release [2024-03-01](../../../Overview/Whats-New#2024-03-01) might require running a post update script to remove the notification assets deployed by ALZ pattern ***if and only if*** customer decided to use existing action groups and alert processing rule. In this case, the Service Health alerts will be reconfigured to use the customer' action groups as per the ***B***ring ***Y***our ***O***wn ***N***otifications (BYON) feature. +If you are updating from release [2024-03-01](../../../Overview/Whats-New#2024-03-01), you may need to run a post-update script to remove the notification assets deployed by the ALZ pattern. This is necessary only if you have chosen to use existing action groups and alert processing rules. In such cases, the Service Health alerts will be reconfigured to use your action groups according to the ***Bring Your Own Notifications (BYON)*** feature. -To run the script, complete the following step: - - 1. Open PowerShell - 2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph` (if not present) - 3. Change directories to the location of the **Remove-AMBANotificationAssets.ps1** script - 4. Configure the ***$pseudoRootManagementGroup*** variable using the command below: +To execute the script, follow these steps: +1. Open PowerShell. +2. Install the **Az.ResourceGraph** module if it is not already installed by running: `Install-Module Az.ResourceGraph`. +3. Navigate to the directory containing the **Remove-AMBANotificationAssets.ps1** script. +4. Set the ***$pseudoRootManagementGroup*** variable using the following command: ```powershell - $pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" + $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" ``` + 1. Sign in to your Azure account using the `Connect-AzAccount` command. Ensure that the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. - 1. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the desired Management Group scope. - - 2. Execute the script using one of the options below: + 2. Run the script with one of the following options: {{% include "PowerShell-ExecutionPolicy.md" %}} diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md index 2fe1e4fa6..e60455231 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md @@ -9,15 +9,15 @@ weight: 98 # Pre update actions -The parameter file structure has changed to accommodate a new feature coming soon. For this reason, updating from release [2024-04-12](../../../Overview/Whats-New#2024-04-12) requires the alignment of the parameter file structure you have been using so far with the new one coming with the release. +The parameter file structure has been updated to support an upcoming feature. Therefore, when updating from release [2024-04-12](../../../Overview/Whats-New#2024-04-12), you must align your existing parameter file structure with the new format introduced in this release. -In particular the new parameter file has the following differences: +In particular, the new parameter file includes the following changes: -1. Contains new parameters for using an existing User Assigned Managed Identity or creating a new one during the AMBA-ALZ deployment. It's required by the new hybrid virtual machine alert set. Make sure to review and set the following parameters correctly: +1. Introduces new parameters for utilizing an existing User Assigned Managed Identity (UAMI) or creating a new one during the AMBA-ALZ deployment. These parameters are essential for the new hybrid virtual machine alert set. Ensure to review and configure the following parameters accurately: - 1. ***bringYourOwnUserAssignedManagedIdentity***: set it to **Yes** if you would like to use your own User Assigned Managed Identity (UAMI) or to **No** if you don't have one and would like the deployment of AMBA-ALZ to create one. + 1. ***bringYourOwnUserAssignedManagedIdentity***: Set this parameter to **Yes** if you want to use an existing User Assigned Managed Identity (UAMI). Set it to **No** if you prefer the AMBA-ALZ deployment to create a new UAMI for you. - 2. ***bringYourOwnUserAssignedManagedIdentityResourceId***: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **Yes**: + 2. ***bringYourOwnUserAssignedManagedIdentityResourceId***: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **Yes**, provide the resource ID of your existing UAMI. 1.1. Enter the UAMI resource ID, leaving the **managementSubscriptionId** blank @@ -25,17 +25,18 @@ In particular the new parameter file has the following differences: 1.2. Configure it with the ***Monitoring Reader*** role on the pseudo root Management Group. - 3. ***userAssignedManagedIdentityName***: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **No**, leave the default value or set a different one to specify a different name for the UAMI created during the deployment. The provided default name aligns with the ALZ standard naming convention. + 3. ***userAssignedManagedIdentityName***: If the **bringYourOwnUserAssignedManagedIdentity** parameter is set to **No**, you can either use the default value or specify a custom name for the UAMI that will be created during the deployment. The default name follows the ALZ standard naming convention. ![UAMI default name](../../../media/alz-UAMI-Default-Name.png) - 4. ***managementSubscriptionId***: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **No**, enter the subscription ID of the subscription under the Management management group. The deployment procedure will create the UAMI in this subscription and assign it the ***Monitoring Reader*** role on the pseudo root Management Group + 4. ***managementSubscriptionId***: If the **bringYourOwnUserAssignedManagedIdentity** parameter is set to **No**, provide the subscription ID of the subscription within the Management management group. The deployment process will create the UAMI in this subscription and assign it the ***Monitoring Reader*** role on the pseudo root Management Group. ![Management subscription ID](../../../media/alz-ManagementSubscription.png) ![Management subscription ID parameter](../../../media/alz-UAMI-Management-SubscriptionID.png) -2. Changes the previous parameter objects, such as ***policyAssignmentParametersCommon***, ***policyAssignmentParametersBYON*** and ***policyAssignmentParametersNotificationAssets*** into classic parameters using the same name as before. As result, the previous sections of the parameter you'll now look like the following image: +2. Converts the previous parameter objects, including ***policyAssignmentParametersCommon***, ***policyAssignmentParametersBYON***, and ***policyAssignmentParametersNotificationAssets***, into standard parameters while retaining their original names. Consequently, the corresponding sections of the parameter file will now appear as shown in the following image: + ![New parameter file sample](../../../media/alz-New-ParamterFile-Structure.png) diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md index f120958ea..af9d73c20 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md @@ -4,35 +4,33 @@ geekdocCollapseSection: true weight: 97 --- {{< hint type=Important >}} -***Updating to release from release [2024-06-05](../../../Overview/Whats-New#2024-06-05) or from previous releases, contains a breaking change. To perform the update, it's required to remove previously deployed policy definitions, policy set definitions, policy assignments and role assignments. As part of this release we made a script available to clean all the necessary items. ***It's strongly recommended that you test the script thoroughly before running on production environment. It isn't necessary to remove alert definitions that will continue to work in the meantime.*** +***Updating to release [2024-06-05](../../../Overview/Whats-New#2024-06-05) or from previous releases involves a breaking change. To proceed with the update, you must remove previously deployed policy definitions, policy set definitions, policy assignments, and role assignments. A script is provided to facilitate the removal of these items. ***It is highly recommended to thoroughly test the script in a non-production environment before executing it in production. Alert definitions do not need to be removed as they will continue to function.****** {{< /hint >}} # Pre update actions -Before updating to release [2024-06-30](../../../Overview/Whats-New#2024-06-30), it's required to remove existing policy definitions, policy set definitions, policy assignments and role assignments. This action is required because of a breaking change caused by the redefinition of some parameters, which allows for more flexibility in disabling the policy remediation or, in some cases, the alerts. Unfortunately not all the alerts can be disabled after creation; only log-based alerts can be. Even if disabling the effect of policy was already possible in AMBA-ALZ, with this release we made sure that all the policies will honor both the ***PolicyEffect*** and the ***MonitorDisable*** parameters. +Before updating to release [2024-06-30](../../../Overview/Whats-New#2024-06-30), it is necessary to remove existing policy definitions, policy set definitions, policy assignments, and role assignments. This requirement is due to a breaking change introduced by the redefinition of certain parameters, which now provide greater flexibility in disabling policy remediation or, in some cases, alerts. Note that not all alerts can be disabled post-creation; only log-based alerts can be. While disabling the effect of policies was previously possible in AMBA-ALZ, this release ensures that all policies will respect both the ***PolicyEffect*** and ***MonitorDisable*** parameters. -In particular, the *MonitorDisable* feature has been redesigned to allow customer to specify they own existing tag and tag value instead of forcing a hard coded one. Given the ALZ guidance and the best practice of having a consistent tagging definition, it's only allowed to one parameter name fo r the entire deployment. Instead, parameter value can be different. You can specify an array of values assigned to the same parameter. For instance, you have the ```Environment``` tag name consistently applied to several environments, saying ```Production```, ```Test```, ```Sandbox```, and so on and you want to disable alerts for resources, which are in both ```Test``` and ```Sandbox```. Now it's possible by just configuring the parameters for tag name and tag values as reported in the sample screenshot (these are the default values) below: +The *MonitorDisable* feature has been redesigned to allow customers to specify their own existing tag and tag value instead of using a hard-coded one. Following the ALZ guidance and best practices for consistent tagging definitions, only one parameter name is allowed for the entire deployment. However, the parameter value can vary. You can specify an array of values assigned to the same parameter. For example, if you have the `Environment` tag name consistently applied to several environments such as `Production`, `Test`, `Sandbox`, etc., and you want to disable alerts for resources in both `Test` and `Sandbox`, you can now do so by configuring the parameters for the tag name and tag values as shown in the sample screenshot below (these are the default values): ![MonitorDisable* parameters](../../../media/MonitorDisableParams.png) -Complete description of this new/redesigned feature can be found in the [MonitorDisable parameter](../../Disabling-Policies#monitordisable-parameter) paragraph inside the [Disabling Policies](../../Disabling-Policies) page. +For a detailed description of the new or redesigned feature, refer to the [MonitorDisable parameter](../../Disabling-Policies#monitordisable-parameter) section on the [Disabling Policies](../../Disabling-Policies) page. -Once the policy definitions, policy set definitions, policy assignments and role assignments are removed and the deployment is completed, the execution of [Policy remediation](../../deploy/Remediate-Policies) will ensure that the new alerts will be created accordingly. +After removing the policy definitions, policy set definitions, policy assignments, and role assignments, and completing the deployment, execute the [Policy remediation](../../deploy/Remediate-Policies) to ensure the new alerts are created as expected. -To run the script, complete the following steps: - - 1. Open PowerShell - 2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph` (if not present) - 3. Change directory to `patterns\alz\scripts`, there you find the **Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1** script - 4. Configure the ***$pseudoRootManagementGroup*** variable using the following command: +To execute the script, follow these steps: +1. Open PowerShell. +2. Install the **Az.ResourceGraph** module if it is not already installed by running: `Install-Module Az.ResourceGraph`. +3. Navigate to the `patterns\alz\scripts` directory where the **Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1** script is located. +4. Set the ***$pseudoRootManagementGroup*** variable with the following command: ```powershell - $pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" + $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" ``` + 1. Sign in to Azure using the `Connect-AzAccount` command. Ensure the account has the necessary permissions to remove policy definitions, policy set definitions, policy assignments, and role assignments at the required Management Group scope. - 1. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove policy definitions, policy set definitions, policy assignments and role assignments at the desired Management Group scope. - - 2. Execute the script using one of the following options: + 2. Run the script with one of the following options: {{% include "PowerShell-ExecutionPolicy.md" %}} diff --git a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md index ee8bd4d7c..86d47551d 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md +++ b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md @@ -16,13 +16,13 @@ weight: 20 ## Introduction -As described in [Introduction to deploying the ALZ pattern](../Introduction-to-deploying-the-ALZ-Pattern), the policies and initiatives in this repo can be deployed in a default configuration, i.e. with default settings and are intended to be used as such. There may be however, scenarios where you would want to tweak the initiative assignment for individual policies to conform with your monitoring requirements, or potentially wish to deploy alerts in a more phased approach to a brownfield environment. This document lists some of the various scenarios as well as how you would go about making such changes to the assignments. +The policies and initiatives in this repository can be deployed using their default configurations, as described in [Introduction to deploying the ALZ pattern](../Introduction-to-deploying-the-ALZ-Pattern). These default settings are intended for general use. However, there may be scenarios where you need to adjust the initiative assignment for specific policies to meet your monitoring requirements or to implement alerts gradually in an existing environment. This document outlines various scenarios and provides guidance on how to modify these assignments. [Back to top of page](.) ## Modify initiative assignment -As an example you may want to change alert thresholds for one or more metric alerts when assigning initiatives. To do so the specific parameters can be specified in a parameter file. For convenience we supply a complete parameter file, containing all the parameters that can be comfigured in each initiative. Note that you are advised to leverage this as a template for creating your own parameter file as the parameters in these files may change over time, which could potentially have undesirable effects on your alert configurations. +When assigning initiatives, you may need to adjust alert thresholds for one or more metric alerts. This can be achieved by specifying the relevant parameters in a parameter file. For your convenience, we provide a comprehensive parameter file that includes all configurable parameters for each initiative. It is recommended to use this file as a template to create your own parameter file, as the parameters may change over time, potentially affecting your alert configurations. [Back to top of page](.) @@ -34,10 +34,11 @@ As an example you may want to change alert thresholds for one or more metric ale ### Applying changes to the parameter file -If we want to change the threshold value for Virtual Network Gateway Express Route CPU utilization from 80 (default value) to 90, and Virtual Network Gateway Egress traffic from 1 to 1000, what we would do is include this in a parameter file as shown below. These specific thresholds would then be set in the individual policy assignment, while the remaining values for all other policies would remain at default. Note that the parameter file shown below has been truncated for brevity, compared to the samples included. +To adjust the threshold values for Virtual Network Gateway Express Route CPU utilization from the default value of 80 to 90, and for Virtual Network Gateway Egress traffic from 1 to 1000, you need to include these changes in a parameter file as demonstrated below. These specific thresholds will be applied to the individual policy assignment, while all other policy values will remain at their default settings. Note that the parameter file shown below is truncated for brevity compared to the full samples provided. + {{< hint type=Note >}} -The parameter file contains the same default values as listed in our documentation. However, be aware that the _Policy assignment parameter reference type​_ will change for all parameters when using the template parameter file, even when a value of a parameter wasn't modified it will appear as a _User defined parameter_ after deployment. This occurs because the parameter is explicitly defined in the parameter file. To avoid this, you can create your own parameter files that only includes the parameters that you wish to modify. +The parameter file includes the default values as documented. However, the _Policy assignment parameter reference type_ will change for all parameters when using the template parameter file. Even if a parameter's value remains unmodified, it will be marked as a _User defined parameter_ after deployment because it is explicitly defined in the parameter file. To prevent this, you can create custom parameter files that only include the parameters you wish to modify. {{< /hint >}} ```json @@ -81,13 +82,13 @@ The parameter file contains the same default values as listed in our documentati ### Metric alert policy parameters -The following parameters can be changed for metric alert policies, in the initiatives these are prefixed with an appropriate string to indicate the metric in question. +The following parameters can be modified for metric alert policies. In the initiatives, these parameters are prefixed with a specific string to denote the relevant metric. | **Parameter Name** | **Parameter Description** | |----------|----------| | severity | 0 - 4 indicating alert severity | -| windowSize | Indicating the time windows inside which the alert is evaluating for true/false | -| evaluationFrequency | Indicating how often inside the time window evaluation takes place | +| windowSize | Indicating the time window where the alert performs the true/false evaluation | +| evaluationFrequency | Indicating how often evaluation takes place inside the time window | | effect | Can be either DeployIfNotExists or Disabled (modify is allowed for the recovery services vault alert) | | autoMitigate | Indicates whether the the alert will auto-resolve if the alert condition is no longer true | | threshold | Indicates a numerical threshold for when the alert would trigger. Not relevant to all alerts as some are configured with dynamic rather than fixed thresholds | @@ -101,25 +102,26 @@ The following parameters can be changed for activity log, service health alert a | **Parameter Name** | **Parameter Description** | |----------|----------| -| ALZMonitorResourceGroupName | The name of the resource group to place the alerts in | -| ALZMonitorResourceGroupTags | Any tags than needs to be added to the resource group created | -| ALZMonitorResourceGroupLocation | The location of the resource group to place the alerts in | +| ALZMonitorResourceGroupName | The name of the resource group for the alerts | +| ALZMonitorResourceGroupTags | Any tags than need to be added to the resource group created | +| ALZMonitorResourceGroupLocation | The location of the resource group for the alerts | + -Note that the above parameters specifies the resource group that activity log alerts are placed in. If the resource group does not exist it gets created. Also the parameter for tags can take several tags, if multiple tags are needed. Tags are only applied at the resource group level. The tags parameter is set to a default value of one tag with the name *environment* and the value *test*, you can add more tags as already mentioned or set it to be an empty value. +The parameters mentioned above specify the resource group where activity log alerts will be placed. If the resource group does not exist, it will be created. The `tags` parameter can accept multiple tags if needed, but tags are only applied at the resource group level. By default, the `tags` parameter is set to a single tag with the name *environment* and the value *test*. You can add more tags as required or leave it empty. [Back to top of page](.) ### Disabling Policies -To review the options for disabling policies, please proceed with [Disabling Policies](../../Disabling-Policies) +To review the options for disabling policies, visit [Disabling Policies](../../Disabling-Policies) [Back to top of page](.) ## Next steps -- To deploy with GitHub Actions, please proceed with [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) -- To deploy with Azure DevOps Pipelines, please proceed with [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) -- To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../Deploy-with-Azure-CLI) -- To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) +- To deploy with GitHub Actions, visit [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) +- To deploy with Azure DevOps Pipelines, visit [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) +- To deploy with Azure CLI, visit [Deploy with Azure CLI](../Deploy-with-Azure-CLI) +- To deploy with Azure PowerShell, visit [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) [Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md index 470c54ab7..04febdb06 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md @@ -8,10 +8,10 @@ weight: 70 Updating from the _**preview**_ version isn't supported. If you deployed the _**preview**_ version, proceed with [Moving from preview to GA](../../../Resources/Moving-from-preview-to-GA) before continuing. {{< /hint >}} -The following guide describes the steps to use the ALZ pattern to implement Service Health Alerts. When you deploy one Policy Set Definition, like Service Health, you will only need the Policy Definitions required by that Policy Set Definition. You can still choose to deploy all Policy Definitions that are provided in the ALZ Pattern, this is recommended when you want to deploy other Policy Set Definitions in the future. In case you first deploy a subset of the Policy Definitions, you can easily deploy additional definitions at a later stage. This document covers two deployment options: +This guide describes the steps to use the ALZ pattern to implement Service Health Alerts. When deploying one Policy Set Definition, like Service Health, you will only need the Policy Definitions required by that Policy Set Definition. You can still choose to deploy all Policy Definitions provided in the ALZ Pattern, which is recommended if you plan to deploy other Policy Set Definitions in the future. If you first deploy a subset of the Policy Definitions, you can easily deploy additional definitions later. This document covers two deployment options: -1. [Quick Deployment](../Deploy-only-Service-Health-Alerts/#quick-deployment): Deploys the ALZ Pattern including all Policy Definitions, Policy Set Definitions, however, this assigns only the Service Health Policy Set Definition. -2. [Custom Deployment](../Deploy-only-Service-Health-Alerts/#custom-deployment): Deploys only the Policy Definitions and Policy Set Definition that are needed for the Service Health Alerts. Assigns only the Service Health Policy Set Definition. +1. [Quick Deployment](../Deploy-only-Service-Health-Alerts/#quick-deployment): Deploys the ALZ Pattern including all Policy Definitions and Policy Set Definitions, but assigns only the Service Health Policy Set Definition. +2. [Custom Deployment](../Deploy-only-Service-Health-Alerts/#custom-deployment): Deploys only the Policy Definitions and Policy Set Definition needed for the Service Health Alerts, and assigns only the Service Health Policy Set Definition. {{< hint type=note >}} In this example we will deploy the Service Health Policy Set Definition via Azure CLI. However, the same principles and steps apply to other Policy Set Definitions and deployment methods as well. @@ -27,7 +27,7 @@ To start, you can either download a copy of the parameter file or clone/fork the The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. -- Change the value of the following parameters at the beginning of parameter file according to the instructions below: +- Change the value of the following parameters at the beginning of the parameter file according to the instructions below: {{< hint type=note >}} While it's technically possible to not add any notification information (no email, no ARM Role, no Logic App, etc.) it is strongly recommended to configure at least one option. diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md index 1b7c4e952..a547ee329 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md @@ -22,47 +22,47 @@ weight: 30 ![Deployment Settings Blade](../../media/PortalAccelerator/DeploymentSettings.png) >>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md -- Change the values on the Deployment Settings blade to the instructions below: - - Choose the Management Group where you wish to deploy the policies and the initiatives. This is usually the so called "pseudo root management group", for example, in [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this would be the so called "Intermediate Root Management Group" (directly beneath the "Tenant Root Group"). +- Change the values on the Deployment Settings blade to the following instructions: + - Choose the Management Group where you wish to deploy the policies and the initiatives, usually called the "pseudo root management group". For example, in [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this would be the "Intermediate Root Management Group" (directly beneath the "Tenant Root Group"). - Choose the value of _`Region`_ to specify your Azure location of choice. - Change the value of _`Resource group for baseline alerts`_ to the name of the resource group where the activity logs, resource health alerts, actions groups and alert processing rules will be deployed in. - Choose the value of _`Resource group location`_ to specify the location for said resource group. - Choose the value of _`Bring Your Own User Assigned Managed Identity`_ to specify if you want to bring your own user assigned managed identity for monitoring purpose. - Define the value of _`User Assigned Managed Identity Name`_ to specify the name of the user assigned managed identity for monitoring purpose. - - Choose the value of _`Bring Your Own User Assigned Managed Identity Resource Id`_ to specify the resource id of the user assigned managed identity if you want to bring your own user assigned managed identity for monitoring purpose. - - Choose the value of _`Management Subscription Id`_ to specify the subscription id where the user assigned managed identity will be created. + - Choose the value of _`Bring Your Own User Assigned Managed Identity Resource Id`_ to specify the resource ID of the user assigned managed identity if you want to bring your own user assigned managed identity for monitoring purpose. + - Choose the value of _`Management Subscription Id`_ to specify the subscription ID where the user assigned managed identity will be created. - Choose the value of _`Customer Usage Selection Option`_ Microsoft can identify the deployments of the Azure Resource Manager and Bicep templates with the deployed Azure resources. Microsoft can correlate these resources used to support the deployments. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through customer usage attribution. The data is collected and governed by Microsoft’s privacy policies, located at the trust center. - Change the value of _`Resource Group Tags`_ to specify the tags to be added to said resource group. ## Management Groups Settings Blade -- Change the values on the Management Groups Settings blade to the instructions below: +- Change the values on the Management Groups Settings blade to the following instructions: ![Management Groups Settings Blade](../../../media/PortalAccelerator/MGSettings.png) ### If you are aligned to ALZ <<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md -- Choose the value of _```Enterprise Scale Company Management Group```_ to the management group id for Platform. -- Choose the value of _```Identity Management Group```_ to the management group id for Identity. -- Choose the value of _```Management Management Group```_ to the management group id for Management. -- Choose the value of _```Connectivity Management Group```_ to the management group id for Connectivity. -- Choose the value of _```Landing Zone Management Group```_ to the management group id for Landing Zones. +- Choose the value of _```Enterprise Scale Company Management Group```_ to the management group ID for Platform. +- Choose the value of _```Identity Management Group```_ to the management group ID for Identity. +- Choose the value of _```Management Management Group```_ to the management group ID for Management. +- Choose the value of _```Connectivity Management Group```_ to the management group ID for Connectivity. +- Choose the value of _```Landing Zone Management Group```_ to the management group ID for Landing Zones. ======= -- Choose the value of _`Enterprise Scale Company Management Group`_ to the management group id for Platform. -- Choose the value of _`Identity Management Group`_ to the management group id for Identity. -- Choose the value of _`Management Management Group`_ to the management group id for Management. -- Choose the value of _`Connectivity Management Group`_ to the management group id for Connectivity. -- Choose the value of _`Landing Zone Management Group`_ to the management group id for Landing Zones. +- Choose the value of _`Enterprise Scale Company Management Group`_ to the management group ID for Platform. +- Choose the value of _`Identity Management Group`_ to the management group ID for Identity. +- Choose the value of _`Management Management Group`_ to the management groupID for Management. +- Choose the value of _`Connectivity Management Group`_ to the management group ID for Connectivity. +- Choose the value of _`Landing Zone Management Group`_ to the management group ID for Landing Zones. >>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md ### If you are unaligned to ALZ -- Choose the value of _`Enterprise Scale Company Management Group`_ to the management group id for Platform. The same management group id may be repeated. -- Choose the value of _`Identity Management Group`_ to the management group id for Identity. The same management group id may be repeated. -- Choose the value of _`Management Management Group`_ to the management group id for Management. The same management group id may be repeated. -- Choose the value of _`Connectivity Management Group`_ to the management group id for Connectivity. The same management group id may be repeated. -- Choose the value of _`Landing Zone Management Group`_ to the management group id for Landing Zones. The same management group id may be repeated. +- Choose the value of _`Enterprise Scale Company Management Group`_ to the management group ID for Platform. The same management group ID may be repeated. +- Choose the value of _`Identity Management Group`_ to the management group ID for Identity. The same management group ID may be repeated. +- Choose the value of _`Management Management Group`_ to the management group ID for Management. The same management group ID may be repeated. +- Choose the value of _`Connectivity Management Group`_ to the management group ID for Connectivity. The same management group ID may be repeated. +- Choose the value of _`Landing Zone Management Group`_ to the management group ID for Landing Zones. The same management group ID may be repeated. {{< hint type=note >}} For ease of deployment and maintenance we have kept the same variables. @@ -70,19 +70,19 @@ For ease of deployment and maintenance we have kept the same variables. ### If you have a single management group -- Choose the value of _`Enterprise Scale Company Management Group`_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Choose the value of _`Identity Management Group`_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Choose the value of _`Management Management Group`_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Choose the value of _`Connectivity Management Group`_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Choose the value of _`Landing Zone Management Group`_ to the pseudo root management group id, also called the "Intermediate Root Management Group". +- Choose the value of _`Enterprise Scale Company Management Group`_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". +- Choose the value of _`Identity Management Group`_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". +- Choose the value of _`Management Management Group`_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". +- Choose the value of _`Connectivity Management Group`_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". +- Choose the value of _`Landing Zone Management Group`_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". {{< hint type=note >}} For ease of deployment and maintenance we have kept the same variables. {{< /hint >}} <<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md -- Change the value of _```Enable AMBA notification assets```_ to _```Yes```_ In this scenario, the deployment will Deploy notification assets for Service Health alerts and wide notifications. -- Change the value of _```Enable AMBA Service Health```_ to _```Yes```_ In this scenario, the deployment will assign the Service Health Policy Set Definition. +- Set the value of _`Enable AMBA notification assets`_ to _`Yes`_. This configuration will deploy notification assets for Service Health alerts and broad notifications. +- Set the value of _`Enable AMBA Service Health`_ to _`Yes`_. This setting will assign the Service Health Policy Set Definition during deployment. ======= - Change the value of _`Enable AMBA Hybrid VM`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Arc-enabled Servers. - Change the value of _`Enable AMBA Key Management`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management Services such as Azure Key Vault, and Managed HSM. @@ -92,8 +92,8 @@ For ease of deployment and maintenance we have kept the same variables. - Change the value of _`Enable AMBA Storage`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Services such as Storage accounts. - Change the value of _`Enable AMBA VM`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual Machines. - Change the value of _`Enable AMBA Web`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services such as App Services. -- Change the value of _`Enable AMBA notification assets`_ to _`Yes`_ In this scenario, the deployment will Deploy notification assets for Service Health alerts and wide notifications. -- Change the value of _`Enable AMBA Service Health`_ to _`Yes`_ In this scenario, the deployment will assign the Service Health Policy Set Definition. +- Set the value of _`Enable AMBA notification assets`_ to _`Yes`_. This configuration will deploy notification assets for Service Health alerts and broad notifications. +- Set the value of _`Enable AMBA Service Health`_ to _`Yes`_. This configuration will assign the Service Health Policy Set Definition during deployment. >>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md ## Notification Settings Blade @@ -101,30 +101,30 @@ For ease of deployment and maintenance we have kept the same variables. ![Notification Settings Blade](../../../media/PortalAccelerator/NotificationSettings.png) {{< hint type=note >}} -While it's technically possible to not add any notification information (no email, no ARM Role, no Logic App, etc.) it is strongly recommended to configure at least one option. +While it's technically possible to not add any notification information (email, ARM Role, Logic App, etc.) it is highly recommended to configure at least one option. {{< /hint >}} -- Change values on the Notification Settings Blade blade to the instructions below: +- Change the values on the Notification Settings Blade to the following instructions: - - Change the value of _`Bring Your Own Notifications (BYON)`_ to _` Yes`_ if you wish to use existing Action Groups and Alert Processing Rule. The BYON feature works by setting the necessary parameter values before running the ALZ pattern deployment. Customers have the choice to either specify one or more existing AGs and one APR or to enter target values so the AG and the APR will be created using the actions specified in the parameter file (including the option to not specify any value and creating an empty AG). - - Change the value of _`Email contact for action group notifications`_ to the email address(es) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no email notification is used. - - Change the value of _`Webhook Service Uri`_ to the URI(s) to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Webhook is used. - - Choose the value of _`Arm Role Id`_ to the Azure Resource Manager Role(s) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no Azure Resource Manager Role notification is required. - - Change the value of _`Logicapp Resource Id`_ to the Logic app resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. - - Change the value of _`Logicapp Callback Url`_ to the Logic app callback url of the Logic app you want to use as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. To retrieve the callback url you can either use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/en-us/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic app in the Azure portal, go to _**Logic app designer**_, expand the trigger activity (_When an HTTP request is received_) and copy the value in the URL field using the 2-sheets icon. + - Change the value of _`Bring Your Own Notifications (BYON)`_ to _`Yes`_ if you want to use existing Action Groups and Alert Processing Rules. The BYON feature allows you to set the necessary parameter values before deploying the ALZ pattern. You can either specify one or more existing Action Groups and one Alert Processing Rule, or provide target values so that the Action Group and Alert Processing Rule will be created using the actions specified in the parameter file. You may also leave the values blank, which will result in the creation of an empty Action Group. + - Specify the email address(es) for _`Email contact for action group notifications`_ to receive notifications for alerts, including Service Health alerts. Leave this field blank if email notifications are not required. + - Specify the URI(s) for _`Webhook Service Uri`_ to be used as actions for alerts, including Service Health alerts. Leave this field blank if no Webhook is used. + - Select the Azure Resource Manager Role(s) for _`Arm Role ID`_ to receive notifications for alerts, including Service Health alerts. Leave this field blank if no Azure Resource Manager Role notification is required. + - Specify the Logic app resource ID for _`Logicapp Resource ID`_ to be used as an action for alerts, including Service Health alerts. Leave this field blank if no Logic app is used. + - Update the _`Logicapp Callback Url`_ with the callback URL of the Logic App you intend to use for alert actions (including Service Health alerts). If no Logic App is used, leave this field blank. To obtain the callback URL, you can either use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic App in the Azure portal: go to _**Logic App Designer**_, expand the trigger activity (_When an HTTP request is received_), and copy the URL using the copy icon. ![Get Logic app callback url](../../../media/AMBA-LogicAppCallbackUrl.png) - - Change the value of _`Event Hub Resource Id`_ to the Event Hubs to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Event Hubs is used. - - Change the value of _`Function Resource Id`_ to the Function resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. - - Change the value of _`Function Trigger Url`_ to the Function App trigger url of the function to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. To retrieve the Function App trigger url with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the menu top menu and copy the value in the URL field using the 2-sheets icon. + - Specify the _`Event Hub Resource ID`_ for the Event Hubs to be used as actions for alerts, including Service Health alerts. Leave this field blank if no Event Hubs are used. + - Specify the _`Function Resource ID`_ for the Function App to be used as an action for alerts, including Service Health alerts. Leave this field blank if no Function App is used. + - Update the _`Function Trigger Url`_ with the trigger URL of the Function App to be used as an action for alerts, including Service Health alerts. Leave this field blank if no Function App is used. To obtain the Function App trigger URL with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the top menu, and copy the value in the URL field using the copy icon. ![Get function URL](../../../media/AMBA-FunctionAppTriggerUrl.png) <<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md {{< hint type=note >}} - It is possible use multiple email addresses, as well as multiple Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). - Should you set multiple entries, make sure they are entered as single string with values separated by comma. Example: + It is possible use multiple email addresses, Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). + Should you set multiple entries, ensure that they are entered as a single string with values separated by comma. Example: - action1@contoso.com , action2@contoso.com , action3@contoso.com - https://webhookUri1.webhook.com, http://webhookUri2.webhook.com @@ -132,7 +132,7 @@ While it's technically possible to not add any notification information (no emai ======= {{< hint type=note >}} - It is possible use multiple email addresses, as well as multiple Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). Should you set multiple entries, make sure they are entered as an array. Example: + It is possible use multiple email addresses, Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). Should you set multiple entries, ensure that they are entered as an array. Example: `["action1@contoso.com","action2@contoso.com","action3@contoso.com"]` diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md index 522680762..6024ecbf9 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md @@ -7,35 +7,35 @@ weight: 30 ## 3. Configuring variables for deployment -The following commands apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. +The following commands are applicable to all scenarios, regardless of whether you are aligned with ALZ, unaligned, or managing a single management group. -Open your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), and navigate to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. +Open your preferred command-line tool (Windows PowerShell, Cmd, Bash, or other Unix shells) and navigate to the root directory of the cloned repository. Log in to Azure using an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where the policies and initiatives will be created. Run the following commands: ```bash location="Your Azure location of choice" -pseudoRootManagementGroup="The pseudo root management group id parenting the identity, management and connectivity management groups" +pseudoRootManagementGroup="The pseudo root management group ID parenting the identity, management and connectivity management groups" ``` {{< hint type=Important >}} -When running Azure CLI from PowerShell the variables have to start with a $. +When executing Azure CLI commands from PowerShell, ensure that variables are prefixed with a `$` symbol. -Above-mentioned "pseudoRootManagementGroup" variable value, being the so called "pseudo root management group id", should _coincide_ with the value of the "enterpriseScaleCompanyPrefix" parameter, as set previously within the parameter files. +The `pseudoRootManagementGroup` variable should _match_ the value of the `enterpriseScaleCompanyPrefix` parameter, as defined in the parameter files. -The location variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. +The `location` variable specifies the deployment region. It is not required to deploy to multiple regions as the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} ## 4. Deploying AMBA -The following commands apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. +The following commands are applicable to all scenarios, whether you are aligned with ALZ, unaligned, or managing a single management group. -Using your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), if you closed your previous session, navigate again to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. +Use your preferred command-line tool (Windows PowerShell, Cmd, Bash, or other Unix shells), to navigate to the root directory of the cloned repository. Log in to Azure using an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where the policies and initiatives will be created. {{< hint type=note >}} -This should be tested in a safe environment. If you are subsequently looking to deploy to prod environments, consider leveraging the guidance found in [Customize Policy Assignment](../Customize-Policy-Assignment), to deploy and enable alerts in a controlled manner. +For testing purposes, it is recommended to deploy in a safe environment first. When preparing for a production deployment, refer to the [Customize Policy Assignment](../Customize-Policy-Assignment) guide to deploy and enable alerts in a controlled and secure manner. -If you customized the policies as documented at [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), make sure the run the deployment command using your own repository and branch in the _*_**--template-uri**_*_ parameter value. Example: +If you have customized the policies as described in [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), ensure that you run the deployment command using your own repository and branch in the `--template-uri` parameter. For example: ```bash az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md index c24251b46..e907a4e52 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md @@ -7,10 +7,10 @@ weight: 50 ## 3. Configure and run the pipeline -First configure your Azure DevOps project with a pipeline hosted in GitHub as described [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/github?view=azure-devops&tabs=yaml#access-to-github-repositories). The pipeline should be configured to use the [sample-pipeline.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-pipeline.yml) file. +First, set up your Azure DevOps project to use a pipeline hosted on GitHub by following the instructions [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/github?view=azure-devops&tabs=yaml#access-to-github-repositories). Ensure the pipeline is configured to use the [sample-pipeline.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-pipeline.yml) file. {{< hint type=note >}} -If you customized the policies as documented at [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), make sure to modify the pipeline file to have the **inlineScript** pointing to your own repository and branch. Example: +If you have customized the policies as described in [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), ensure that the **inlineScript** in the pipeline file points to your repository and branch. For example: ```ActionScript inlineScript: | @@ -18,24 +18,24 @@ If you customized the policies as documented at [How to modify individual polici ``` {{< /hint >}} - -Also in your Azure DevOps project, configure a service connection to your Azure subscription as in the [Connect to Azure by using an Azure Resource Manager service connection](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&tabs=yaml) guide. The service connection should target the intermediate root management group for ALZ aligned deployments or the management group where you wish to deploy the policies and the initiatives for ALZ unaligned deployments. +Additionally, in your Azure DevOps project, set up a service connection to your Azure subscription by following the instructions in the [Connect to Azure by using an Azure Resource Manager service connection](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&tabs=yaml) guide. Ensure that the service connection targets the intermediate root management group for ALZ-aligned deployments or the specific management group where you intend to deploy the policies and initiatives for ALZ-unaligned deployments. ### Modify variables and run the pipeline - Modify the following values in [sample-pipeline.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-pipeline.yml): - Change _Location: "norwayeast"_, to your preferred Azure region - Change _ManagementGroupPrefix: "alz"_, to the pseudo root management -- Go to Azure Pipelines and run the pipeline you just created. +- Go to Azure Pipelines and run the pipeline created. {{< hint type=important >}} -Above-mentioned "ManagementGroupPrefix" variable value, being the so called "pseudo root management group id", should _coincide_ with the value of the "parPolicyPseudoRootMgmtGroup" parameter, as set previously within the parameter files. +Ensure that the value of the `ManagementGroupPrefix` variable matches the `parPolicyPseudoRootMgmtGroup` parameter value set in the parameter files. This alignment is crucial for the correct deployment of policies. + -The location variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. +The `Location` variable specifies the deployment region. It is not required to deploy to multiple regions since the policy definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} ## Next steps -To remediate non-compliant policies, please continue with [Policy remediation](../Remediate-Policies) +To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) [Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md index 2ed8737a6..2bbeb8119 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md @@ -7,9 +7,9 @@ weight: 40 ## 3. Configuring variables for deployment -The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. +The following steps apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. -Open a PowerShell prompt, navigate to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. +Open a PowerShell prompt and navigate to the root of the cloned repository. Log in to Azure with an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. Run the following commands: @@ -19,30 +19,30 @@ $pseudoRootManagementGroup = "The pseudo root management group id parenting the ``` {{< hint type=important >}} -Above-mentioned "pseudoRootManagementGroup" variable value, being the so called "pseudo root management group id", should _coincide_ with the value of the "parPolicyPseudoRootMgmtGroup" parameter, as set previously within the parameter files. +The `pseudoRootManagementGroup` variable must _match_ the value of the `parPolicyPseudoRootMgmtGroup` parameter as defined in the parameter files. -The location variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. +The `location` variable specifies the deployment region. It is not required to deploy to multiple regions since the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} ## 4. Deploy the policy definitions, initiatives and policy assignments with default settings {{< hint type=Important >}} -Deploying through PowerShell, requires authentication to Azure and the following modules: +Deploying through PowerShell requires authentication to Azure and the following modules: - Az.Accounts - Az.Resources -Before starting the deployment, make sure you logged in using the Connect-AzAccount PowerShell command and that the modules above are imported. +Before starting the deployment, ensure you logged in using the Connect-AzAccount PowerShell command and that the modules above have been imported. {{< /hint >}} -The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. +The following steps apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. -Using a PowerShell prompt, if you closed your previous session, navigate again to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives and run the command below. +If you have closed your previous session, open a PowerShell prompt and navigate to the root of the cloned repository. Log in to Azure with an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. Then, run the following command: {{< hint type=note >}} -This should be tested in a safe environment. If you are later looking to deploy to prod environments, consider using the guidance found in [Customize Policy Assignment](../Customize-Policy-Assignment), to deploy and enable alerts in a controlled manner. +For testing purposes, it is recommended to deploy in a safe environment first. When preparing for production deployment, refer to the [Customize Policy Assignment](../Customize-Policy-Assignment) guide to deploy and enable alerts in a controlled manner. -If you customized the policies as documented at [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), make sure the run the deployment command using your own repository and branch in the _**-TemplateUri**_ parameter value. Example: +If you have customized the policies as described in [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), ensure that you run the deployment command using your own repository and branch in the _**-TemplateUri**_ parameter. For example: ```PowerShell New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md index 4de72c3e8..9daabb72d 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md @@ -12,7 +12,7 @@ First, configure your OpenID Connect as described [here](https://learn.microsoft To deploy through GitHub actions, refer to the [sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml). {{< hint type=note >}} -If you customized the policies as documented at [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), make sure to modify the workflow file to have the **run** pointing to your own repository and branch. Example: +If you have customized the policies as described in [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), ensure that the workflow file's **run** command points to your specific repository and branch. For example: ```ActionScript run: | @@ -25,27 +25,27 @@ If you customized the policies as documented at [How to modify individual polici - Modify the following values in [amba-sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml): - Change _Location: "norwayeast"_, to your preferred Azure region - - Change _ManagementGroupPrefix: "alz"_, to the pseudo root management group id parenting the identity, management and connectivity management groups + - Change _ManagementGroupPrefix: "alz"_, to the pseudo root management group ID parenting the identity, management and connectivity management groups - Save the customized [amba-sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml) in the _**.github/workflow**_ folder {{< hint type=important >}} - The file name _**must perfectly**_ match the name at line **1** of the sample file. You can eventually replace spaces with **-** + The file name _**must** perfectly match the name at line **1** of the sample file. You may eventually replace spaces with **-** {{< /hint >}} ![Workflow file name](../../../media/WorkflowFileName.png) ![Workflow saved](../../../media/WorkflowSaved.png) - More information about workflow is available in the GitHub documentation at [Creating starter workflows for your organization](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) + For additional details on workflows, refer to the GitHub documentation: [Creating starter workflows for your organization](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) -- Go to GitHub actions and run the action _**Deploy AMBA**_ +- Visit GitHub actions and run the action _**Deploy AMBA**_ ![Deploy AMBA action](../../../media/DeployAmbaAction.png) {{< hint type=important >}} -Above-mentioned "ManagementGroupPrefix" variable value, being the so called "pseudo root management group id", should _coincide_ with the value of the "parPolicyPseudoRootMgmtGroup" parameter, as set previously within the parameter files. +The value of the "ManagementGroupPrefix" variable, referred to as the "pseudo root management group ID," must match the value of the "parPolicyPseudoRootMgmtGroup" parameter set earlier in the parameter files. -The location variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. +The `Location` variable specifies the deployment region. It is not required to deploy to multiple regions since the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} ## Next steps diff --git a/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md b/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md index 7ce1ef9c8..fb5db36c9 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md +++ b/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md @@ -5,44 +5,44 @@ weight: 10 ## Background -This guide describes how to get started with implementing alert policies and initiatives in your environment for testing and validation. In the guide, it is assumed that you will be using GitHub actions or manual deployment to implement policies, initiatives and policy assignments in your environment. +This guide provides instructions on how to begin implementing alert policies and initiatives in your environment for testing and validation. It assumes that you will use GitHub Actions or manual deployment methods to implement policies, initiatives, and policy assignments in your environment. -The repo at present contains code and details for the following: +The repository currently includes code and detailed instructions for the following: -- Policies to automatically create alerts, action groups and alert processing rules for different Azure resource types, centered around a recommended Azure Monitor Baseline for Alerting in a customer´ newly created or existing brownfield ALZ deployment. -- Initiatives grouping said policies into appropriate buckets for ease of policy assignment in alignment with ALZ Platform structure (Networking, Identity and Management). +- Policies to automatically create alerts, action groups, and alert processing rules for various Azure resource types, based on a recommended Azure Monitor Baseline for Alerting in a customer's newly created or existing brownfield ALZ deployment. +- Initiatives that group these policies into appropriate categories for easier policy assignment, aligned with the ALZ Platform structure (Networking, Identity, and Management). -Alerts, action groups and alert processing rules are created as follows: +Alerts, action groups, and alert processing rules are created as follows: -1. All metric alerts are created in the resource group where the resource that is being monitored exists. For example, creating an ER circuit in a resource group covered by the policies will create the corresponding alerts in that same resource group. -2. Activity log alerts are created in a specific resource group (created specifically by and used for this solution) in each subscription, when the subscription is deployed. The resource group name is parameterized, with a default value of rg-amba-monitoring-001. -3. Resource health alerts are created in a specific resource group (created specifically by and used for this solution) in each subscription, when the subscription is deployed. The resource group name is parameterized, with a default value of rg-amba-monitoring-001. -4. Action groups and alert processing rules are created in a specific resource group (created specifically by and used for this solution) in each subscription, when the subscription is deployed. The resource group name is parameterized, with a default value of rg-amba-monitoring-001. +1. Metric alerts are created in the resource group where the monitored resource resides. For instance, if an ER circuit is created in a resource group governed by the policies, the corresponding alerts will be created in that same resource group. +2. Activity log alerts are created in a designated resource group (specifically created and used for this solution) within each subscription upon deployment. The resource group name is parameterized, with a default value of `rg-amba-monitoring-001`. +3. Resource health alerts are created in a designated resource group (specifically created and used for this solution) within each subscription upon deployment. The resource group name is parameterized, with a default value of `rg-amba-monitoring-001`. +4. Action groups and alert processing rules are created in a designated resource group (specifically created and used for this solution) within each subscription upon deployment. The resource group name is parameterized, with a default value of `rg-amba-monitoring-001`. ## Prerequisites -1. Microsoft Entra ID Tenant. -2. ALZ Management group hierarchy deployed as described in the [Azure landing zone design areas and conceptual architecture](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-areas) Microsoft public documentation. -3. Minimum one subscription, for when deploying alerts through policies. -4. Deployment Identity with `Owner` permission to the pseudo root management group. Owner permission is required to allow the Service Principal Account to create role-based access control assignments. -5. If deploying manually, i.e. via Azure CLI or PowerShell, ensure that you have [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview?tabs=bicep) installed and working, before attempting installation. See here for how to configure for [Azure CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-cli) and here for [PowerShell](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-powershell) -6. For the policies to work, the following Azure resource providers, normally registered by default, must be registered on all subscriptions in scope: - - Microsoft.AlertsManagement - - Microsoft.Insights +1. A Microsoft Entra ID Tenant. +2. An ALZ Management group hierarchy deployed as outlined in the [Azure landing zone design areas and conceptual architecture](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-areas) documentation. +3. At least one subscription for deploying alerts through policies. +4. A Deployment Identity with `Owner` permissions to the pseudo root management group. This permission is necessary for the Service Principal Account to create role-based access control assignments. +5. If deploying manually via Azure CLI or PowerShell, ensure [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview?tabs=bicep) is installed and configured. Refer to the configuration guides for [Azure CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-cli) and [PowerShell](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-powershell). +6. The following Azure resource providers must be registered on all subscriptions in scope for the policies to function correctly: + - Microsoft.AlertsManagement + - Microsoft.Insights - See [here](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) for details on how to register a resource provider should you need to do so. + For instructions on registering a resource provider, refer to the [resource provider registration guide](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider). -7. For leveraging the log alerts for virtual machines (both Azure and Azure Arc), ensure that VM Insights is enabled for the virtual machines to be monitored. For more information on VM Insights deployment, see [here](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-enable-overview) . Note only the performance collection of the VM insights solution is required for the current alerts to deploy. +7. To utilize log alerts for virtual machines (both Azure and Azure Arc), ensure that VM Insights is enabled for the virtual machines to be monitored. For more information on deploying VM Insights, refer to the [VM Insights deployment guide](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-enable-overview). Note that only the performance collection aspect of the VM Insights solution is required for the current alerts to function. {{< hint type=note >}} -While it´s recommended to implement the alert policies and initiatives to an ALZ Management Group hierarchy, it is not a technical requirement (avoid Tenant Root Group assignments, to minimize debugging inherited policies at lower-level mangement groups, see [CAF documentation](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups)). These policies and initiatives can be implemented in existing brownfield scenarios that don´t adhere to the ALZ Management Group hierarchy. For example, in hierarchies where there is a single management group, or where the structure does not align to ALZ. At least one management group is required. In case you haven't implemented management groups, we included guidance on how to get started. +While it is recommended to implement the alert policies and initiatives within an ALZ Management Group hierarchy, it is not a strict technical requirement. Avoid assigning policies to the Tenant Root Group to minimize debugging inherited policies at lower-level management groups (refer to the [CAF documentation](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups)). These policies and initiatives can also be applied in existing brownfield scenarios that do not follow the ALZ Management Group hierarchy, such as hierarchies with a single management group or those that do not align with ALZ. At least one management group is required. If management groups have not been implemented, guidance on how to get started is provided. {{< /hint >}} ## Getting started -- Fork this repo to your own GitHub organization, you should not create a direct clone of the repo. Pull requests based off direct clones of the repo will not be allowed. -- Clone the repo from your own GitHub organization to your developer workstation. -- Review your current configuration to determine what scenario applies to you. We have guidance that will help deploy these policies and initiatives whether you are aligned with Azure Landing Zones, or use other management group hierarchy, or you may not be using management groups at all. If you know your type of management group hierarchy, you can skip forward to your preferred deployment method: +- Fork this repository to your own GitHub organization. Do not create a direct clone of the repository, as pull requests from direct clones will not be accepted. +- Clone the repository from your GitHub organization to your local development environment. +- Review your current configuration to identify the applicable scenario. We provide guidance for deploying these policies and initiatives whether you are aligned with Azure Landing Zones, use a different management group hierarchy, or do not use management groups at all. If you already know your management group hierarchy type, proceed to your preferred deployment method: - [Automated deployment with GitHub Actions](../Deploy-with-GitHub-Actions) (recommended method) - [Automated deployment with Azure Pipelines](../Deploy-with-Azure-Pipelines) (recommended method) - [Manual deployment with Azure CLI](../Deploy-with-Azure-CLI) @@ -50,9 +50,9 @@ While it´s recommended to implement the alert policies and initiatives to an AL ### Determining your management group hierarchy -Azure Landing Zones is a concept that provides a set of best practices, patterns, and tools for creating a cloud environment that is secure, Well-Architected, and easy to manage. Management groups are a key component of Azure Landing Zones, as they allow you to organize and manage your subscriptions and resources in a hierarchical structure. By using management groups, you can apply policies and access controls across multiple subscriptions and resources, making it easier to manage and govern your Azure environment. +Azure Landing Zones provide a framework of best practices, patterns, and tools for establishing a secure, Well-Architected, and manageable cloud environment. A crucial element of Azure Landing Zones is the use of management groups, which enable the organization and management of subscriptions and resources in a hierarchical structure. Management groups facilitate the application of policies and access controls across multiple subscriptions and resources, simplifying the governance and management of your Azure environment. -The initiatives provided in this repository align with the management group hierarchy guidelines of Azure Landing Zones. Effectively creating the following assignment mapping between the initiative and the management group: +The initiatives in this repository are designed to align with the management group hierarchy guidelines of Azure Landing Zones. This alignment results in the following assignment mapping between the initiatives and the management groups: - Identity Initiative is assigned to the Identity management group. - Management Initiative is assigned to the Management management group. @@ -60,37 +60,37 @@ The initiatives provided in this repository align with the management group hier - Landing Zone Initiative is assigned to the Landing Zone management group. - Service Health Initiative is assigned to the intermediate (ALZ) root management group. -The image below is an example of how a management group hierarchy looks like when you follow Azure Landing Zone guidance. Also illustrated in this image is the default recommended assignments of the initiatives. +The image below illustrates a management group hierarchy that aligns with Azure Landing Zone guidance. It also shows the default recommended assignments for the initiatives. ![ALZ Management group structure](../../../media/alz-management-groups.png) -The diagram below shows the flow using the orange dash-lines of the policy initiatives and their associated policy definitions. Notice how the Service Health Initiative is assigned at the pseudo root of the management group structure in this case the Contoso management group. This initiative contains the policy that deploys the alert processing rules and action group to each subscription. +The following diagram illustrates the flow of policy initiatives and their associated policy definitions, represented by the orange dash-lines. Note that the Service Health Initiative is assigned at the pseudo root of the management group structure, in this case, the Contoso management group. This initiative includes the policy that deploys the alert processing rules and action group to each subscription. -The other monitoring initiatives are each assigned at specific platform landing zone management groups and workload landing zones. The flows for these are in blue dash-lines. +The other monitoring initiatives are assigned to specific platform landing zone management groups and workload landing zones. These flows are represented by blue dashed lines. ![Azure Monitor Baseline Alerts policy initiative flows](../../../media/azure-monitor-baseline-alerts-policy-initiative-flow.svg) *Download a [Visio file](../../media/AMBA-Diagrams.vsdx) of this architecture.* -If you have this management group hierarchy, you can skip forward to your preferred deployment method: +If your management group hierarchy matches this structure, you can proceed directly to your preferred deployment method: - [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) - [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - [Deploy with Azure CLI](../Deploy-with-Azure-CLI) - [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) -It´s important to understand why we assign initiatives to certain management groups. In the previous example, the assignment mapping was done this way because the associated resources within a subscription below a management group have a specific purpose. For example, below the Connectivity management group you will find a subscription that contains the networking components like Firewalls, Virtual WAN, Hub Networks, etc. Consequently, this is where we assign the connectivity initiative to get relevant alerting on those services. It wouldn't make sense to assign the connectivity initiative to other management groups when there are no relevant networking services deployed. +It is crucial to understand the rationale behind assigning initiatives to specific management groups. In the previous example, the assignment mapping was structured based on the purpose of the associated resources within a subscription under a management group. For instance, the Connectivity management group typically contains subscriptions with networking components such as Firewalls, Virtual WAN, and Hub Networks. Therefore, the connectivity initiative is assigned to this management group to ensure relevant alerting for those services. Assigning the connectivity initiative to other management groups without relevant networking services would not be logical. -We recognize that Azure allows for flexibility and choice, and you may not be aligned with ALZ. For example, you may have: +We understand that Azure offers flexibility and choice, and your environment may not align with the Azure Landing Zone (ALZ) framework. For instance, you might have: -- A management group structure that is not aligned to ALZ. Where you may only have a Platform management group without the sub management groups like Identity/ Management/ Connectivity. +- A management group structure that does not align with ALZ, where you might only have a Platform management group without sub-management groups like Identity, Management, or Connectivity. - No management group structure. {{< hint type=note >}} -If you are looking to align your Azure environment to Azure landing zone, please see [Transition existing Azure environments to the Azure landing zone conceptual architecture](http://aka.ms/alz/brownfield) +If you are looking to align your Azure environment with Azure landing zones, refer to [Transition existing Azure environments to the Azure landing zone conceptual architecture](http://aka.ms/alz/brownfield). {{< /hint >}} -Suppose Identity / Management / Connectivity are combined in one Platform Management Group, the approach could be to assign the three corresponding initiatives to the Platform management group instead. Maybe you have a hierarchy where you organize by geography and/or business units instead of specific landing zones. Assignment mapping: +In scenarios where Identity, Management, and Connectivity are combined into a single Platform Management Group, you can assign the corresponding initiatives to the Platform management group. Alternatively, if your hierarchy is organized by geography or business units instead of specific landing zones, the assignment mapping could be as follows: - Identity Initiative is assigned to the Platform management group. - Management Initiative is assigned to the Platform management group. @@ -98,55 +98,56 @@ Suppose Identity / Management / Connectivity are combined in one Platform Manage - Landing Zone Initiative is assigned to the Geography management group. - Service Health Initiative is assigned to the top-most level(s) in your management group hierarchy. -The image below is an example of how the assignments could look like when the management group hierarchy is not aligned with ALZ. +The following image illustrates an example of how the assignments might appear when the management group hierarchy does not align with Azure Landing Zones (ALZ). + ![Management group structure - unaligned](../../../media/alz-management-groups-unaligned.png) -We recommend that you review the [initiative definitions](https://github.com/Azure/azure-monitor-baseline-alerts/tree/main/patterns/alz/policySetDefinitions) to determine where best to apply the initiatives in your management group hierarchy. +We suggest reviewing the [initiative definitions](https://github.com/Azure/azure-monitor-baseline-alerts/tree/main/patterns/alz/policySetDefinitions) to identify the optimal placement of initiatives within your management group hierarchy. -If you have this management group hierarchy, you can skip forward to your preferred deployment method: +If your management group hierarchy matches this structure, you can proceed directly to your preferred deployment method: - [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) - [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - [Deploy with Azure CLI](../Deploy-with-Azure-CLI) - [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) -If management groups were never configured in your environment, there are some additional steps that need to be implemented. To be able to deploy the policies and initiatives through the guidance and code we provide you need to create at least one management group, and by doing so the tenant root management group is created automatically. We strongly recommend following the [Azure Landing Zones guidance](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups) on management group design. +If management groups have not been configured in your environment, you will need to take additional steps. To deploy the policies and initiatives using the provided guidance and code, you must create at least one management group. This action will automatically create the tenant root management group. We highly recommend following the [Azure Landing Zones guidance](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups) for management group design. -Refer to our [documentation](https://learn.microsoft.com/en-us/azure/governance/management-groups/create-management-group-portal) on how to create management groups. +For detailed instructions on creating management groups, refer to the [official documentation](https://learn.microsoft.com/en-us/azure/governance/management-groups/create-management-group-portal). -If you implemented the recommended management group design, you can skip forward to your preferred deployment method, following the ALZ aligned guidance. +If you have adopted the recommended management group design, you can proceed directly to your preferred deployment method, adhering to the ALZ-aligned guidance. - [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) - [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - [Deploy with Azure CLI](../Deploy-with-Azure-CLI) - [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) -If you implemented a single management group, we recommend moving your production subscriptions into that management group, consult the steps in the [documentation](https://learn.microsoft.com/en-us/azure/governance/management-groups/manage#add-an-existing-subscription-to-a-management-group-in-the-portal) for guidance to add the subscriptions. +If you have implemented a single management group, it is recommended to move your production subscriptions into that management group. For guidance on adding subscriptions, refer to the [official documentation](https://learn.microsoft.com/en-us/azure/governance/management-groups/manage#add-an-existing-subscription-to-a-management-group-in-the-portal). {{< hint type=important >}} -To prevent unnecessary alerts, we recommend keeping development, sandbox, and other non-production subscriptions either in a different management group or below the tenant root group. +To avoid generating unnecessary alerts, it is advisable to place development, sandbox, and other non-production subscriptions in a separate management group or under the tenant root group. {{< /hint >}} -The image below is an example of how the assignments look like when you are using a single management group. +The following image illustrates an example of how the assignments appear when utilizing a single management group. ![Management group structure - single](../../../media/alz-management-groups-single.png) ## Customizing policy assignments -As mentioned previously the above guidance will deploy policies, alerts and action groups with default settings. For details on how to customize policy and in particular initiative assignments please refer to [Customize Policy Assignment](../Customize-Policy-Assignment) +For instructions on customizing policy and initiative assignments, please refer to [Customize Policy Assignment](../Customize-Policy-Assignment). ## Customizing the AMBA policies -Whatever way you may choose to consume the policies we do expect, and want, customers and partners to customize the policies to suit their needs and requirements for their design in their local copies of the policies. +We encourage customers and partners to tailor the policies to meet their specific needs and requirements. Customize the policies in your local copies to align with your design preferences. -For example, if you want to include more thresholds, metrics, activity log alerts or similar, outside of what the parameters allow you to change and customize, then by opening the individual policy or initiative definitions you should be able to read, understand and customize the required lines to meet your requirements easily. +If you need to include additional thresholds, metrics, or activity log alerts beyond what the parameters allow, you can open the individual policy or initiative definitions. By reviewing and understanding the relevant lines, you can easily customize them to meet your specific requirements. -This customized policy can then be deployed into your environment to deliver the desired functionality. +You can then deploy this customized policy into your environment to achieve the desired functionality. ### How to modify individual policies -Policy files are stored in the 'services' folder. The **services** folder contains the baseline alert definitions, guidance, and example deployment scripts. It is grouped by resource category (for example, Compute), and then by resource type (for example, virtualMachines). The example folder structure below highlights the position of individual policy files: +Policy files are located in the `services` directory. This directory contains baseline alert definitions, guidance, and example deployment scripts. The structure is organized by resource category (e.g., Compute) and then by resource type (e.g., virtualMachines). The example folder structure below shows the location of individual policy files: ```plaintext ├── patterns @@ -157,19 +158,19 @@ Policy files are stored in the 'services' folder. The **services** folder contai └── Deploy-VM-DataDiskReadLatency-Alert.json ``` -To modify settings that are not parameterized, follow the steps below: +To modify settings that are not parameterized, follow these steps: -1. Fork the repo. More info on how to fork a repo available on the [Fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) page. -2. Modify existing policies or add new ones based on your need. +1. Fork the repository. For detailed instructions, refer to the [Fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) page. +2. Adjust current policies or introduce new ones as needed. {{< hint type=note >}} - Regardless you're modifying existing policies or adding new ones, you need to update the ***policies.bicep*** file. + Regardless of whether you are modifying existing policies or adding new ones, you must update the ***policies.bicep*** file. {{< /hint >}} -3. Run the following command to update the above mentioned ***policies.bicep*** file: +3. Execute the following command to update the ***policies.bicep*** file: `bicep build .\patterns\alz\templates\policies.bicep --outfile .\patterns\alz\policyDefinitions\policies.json` -4. Commit and sync the changes to your fork. -5. Deploy you local modified copy using the below command: +4. Commit and synchronize the changes to your fork. +5. Execute the following command to deploy your locally modified copy: ```AZ CLI az deployment mg create --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or branchname***/patterns/alz/alzArm.json @@ -178,24 +179,23 @@ To modify settings that are not parameterized, follow the steps below: ## Disabling Monitoring -If you wish to disable monitoring for a resource or for alerts targeted at subscription level such as Activity Log, Service Health, and Resource Health. A "MonitorDisable" tag can be created with a value of "true" at the scope where you wish to disable monitor. This will effectively filter the resource or subscription from the compliance check for the policy. +To disable monitoring for a specific resource or for alerts at the subscription level (such as Activity Log, Service Health, and Resource Health), you can create a tag named `MonitorDisable` with the value `true` at the desired scope. This tag will exclude the resource or subscription from the policy compliance check. {{< hint type=Important >}} -If you believe the changes you have made should be more easily available to be customized by a parameter etc. in the policies, then please raise an [GitHub Issue](https://github.com/Azure/azure-monitor-baseline-alerts/issues) for a 'Feature Request' on the repository. +If you think the changes you have made should be customizable via parameters in the policies, open a [GitHub Issue](https://github.com/Azure/azure-monitor-baseline-alerts/issues) to request this feature. -If you wish to, also feel free to submit a pull request relating to the issue which we can review and work with you to potentially implement the suggestion/feature request. +If you have suggestions or feature requests, consider submitting a pull request. We will review and collaborate with you to potentially implement the proposed changes. {{< /hint >}} ## Cleaning up an AMBA Deployment - -In some scenarios, it may be necessary to remove everything deployed by the ALZ Monitor solution. If you want to clean up all resources deployed, please refer to the instructions on running the [Cleaning up an AMBA Deployment](../../Cleaning-up-a-Deployment). +In certain situations, you may need to remove all resources deployed by the ALZ Monitor solution. For detailed instructions on how to clean up an ALZ Monitor deployment, refer to the [Cleaning up an AMBA Deployment](../../Cleaning-up-a-Deployment) guide. ## Next steps -- To customize policy assignments, please proceed with [Customize Policy Assignment](../Customize-Policy-Assignment) -- To deploy with GitHub Actions, please proceed with [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) -- To deploy with Azure Pipelines, please proceed with [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) -- To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../Deploy-with-Azure-CLI) -- To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) +- For instructions on customizing policy assignments, refer to [Customize Policy Assignment](../Customize-Policy-Assignment). +- For deploying with GitHub Actions, refer to [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions). +- For deploying with Azure Pipelines, refer to [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines). +- For deploying with Azure CLI, refer to [Deploy with Azure CLI](../Deploy-with-Azure-CLI). +- For deploying with Azure PowerShell, refer to [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell). [Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md b/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md index dcc6fd865..0c1cc6bbb 100644 --- a/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md +++ b/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md @@ -4,18 +4,18 @@ geekdocHidden: true --- {{< hint type=Important >}} -Since PowerShell scripts released as part of the ALZ pattern are not digitally signed they might require you to _**temporarily**_ change the execution policy if not already set to _**Unrestricted**_. Before running the script, check the execution policy settings using this command: +To run PowerShell scripts provided in the ALZ pattern, you may need to _**temporarily**_ change the execution policy if it is not set to _**Unrestricted**_. Verify the current execution policy by executing the following command: ```PowerShell Get-ExecutionPolicy ``` -If the result is everything but _**Unrestricted**_, run the following command to change it to **Unrestricted** +If the current execution policy is not set to _**Unrestricted**_, execute the following command to change it to **Unrestricted**: ```PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted ``` -At this point, you should be able to run your scripts with no issues. After you finished, you can set the execution policy back to what it was if you like to do so. +After running your scripts, you may revert the execution policy to its original setting if desired. {{< /hint >}} diff --git a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md index 7315ad686..34ab1fe1b 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md +++ b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md @@ -3,27 +3,28 @@ title: Remediate Policies weight: 80 --- -The policies are all deploy-if-not-exists, by default, meaning that any new deployments will be influenced by them. Therefore, if you are deploying in a green field scenario and will afterwards be deploying any of the covered resource types, including subscriptions, then the policies will take effect and the relevant alert rules, action groups and alert processing rules will be created. -If you are in a brownfield scenario on the other hand, policies will be reporting non-compliance for resources in scope, but to remediate non-compliant resources you will need to initiate remediation. This can be done either through the portal, on a policy-by-policy basis or you can run the *Start-AMBARemediation.ps1* script located in the *.\patterns\alz\scripts* folder to remediate all AMBA policies in scope as defined by management group pre-fix. +The policies are configured as deploy-if-not-exists by default. This means that any new deployments will be affected by these policies. In a greenfield scenario, where you are deploying new resources, including subscriptions, the policies will automatically create the relevant alert rules, action groups, and alert processing rules. + +In a brownfield scenario, the policies will report non-compliance for existing resources within their scope. To remediate these non-compliant resources, you need to initiate remediation. This can be done through the Azure portal on a policy-by-policy basis, or by running the *Start-AMBARemediation.ps1* script located in the *.\patterns\alz\scripts* folder. This script will remediate all AMBA policies in scope as defined by the management group prefix. {{< hint type=Important >}} -This script requires PowerShell 7.0 or higher and the following PowerShell modules: +This script requires PowerShell 7.0 or higher, and the following PowerShell modules: - [Az.Accounts](https://www.powershellgallery.com/packages/Az.Accounts) - [Az.Resources](https://www.powershellgallery.com/packages/Az.Resources) {{< /hint >}} -To use the script, do the following: +To use the script, follow these steps: -- Log on to Azure PowerShell with an account with at least Resource Policy Contributor permissions at the pseudo-root management group level -- Navigate to the root of the cloned repo -- Set the variables -- Run the remediation script +1. Log in to Azure PowerShell with an account that has at least Resource Policy Contributor permissions at the pseudo-root management group level. +2. Navigate to the root directory of the cloned repository. +3. Set the necessary variables. +4. Execute the remediation script. {{% include "./PowerShell-ExecutionPolicy.md" %}} -- For example, to remediate **Alerting-Management** initiative, assigned to the **alz-platform-management** Management Group run the following commands: +- For instance, to remediate the **Alerting-Management** initiative assigned to the **alz-platform-management** Management Group, execute the following commands: ```powershell #Modify the following variables to match your environment @@ -35,18 +36,18 @@ To use the script, do the following: .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $managementManagementGroup -policyName Alerting-Management ``` -- The script will return the output from the REST API calls, which should be a status code 201. If the script fails, check the error message and ensure that the management group name and policy name are correct. -- After running the script, you should be able to see a number of remediation tasks initiated at the alz-platform-management. +- The script will output the results of the REST API calls, typically returning a status code 201. If the script encounters an error, review the error message and verify that the management group name and policy name are correct. +- Upon successful execution of the script, you should observe multiple remediation tasks initiated within the **alz-platform-management** management group. -For convenience, assuming that the management hierarchy is fully aligned to ALZ, below are the commands required to remediate all policies assigned through the guidance provided in this repo: +For convenience, assuming that the management hierarchy is fully aligned with the Azure Landing Zones (ALZ) architecture, the following commands can be used to remediate all policies assigned as per the guidance provided in this repository: ```powershell #Modify the following variables to match your environment -$pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" -$identityManagementGroup = "The management group id for Identity" -$managementManagementGroup = "The management group id for Management" -$connectivityManagementGroup = "The management group id for Connectivity" -$LZManagementGroup="The management group id for Landing Zones" +$pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" +$identityManagementGroup = "The management group ID for Identity" +$managementManagementGroup = "The management group ID for Management" +$connectivityManagementGroup = "The management group ID for Connectivity" +$LZManagementGroup="The management group ID for Landing Zones" ``` ```powershell @@ -65,7 +66,7 @@ $LZManagementGroup="The management group id for Landing Zones" .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-Web ``` -Should you need to remediate just one policy definition and not the entire policy initiative, you can run the remediation script targeted at the policy reference id that can be found under the [Policy Initiatives](../../../Getting-started/Policy-Initiatives) page. For example, to remediate the ***Deploy AMBA Notification Assets*** policy, run the command below: +To remediate a single policy definition instead of the entire policy initiative, use the remediation script with the specific policy reference ID available on the [Policy Initiatives](../../../Getting-started/Policy-Initiatives) page. For example, to remediate the **Deploy AMBA Notification Assets** policy, execute the following command: ```powershell #Run the following command to initiate remediation of a single policy definition diff --git a/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md b/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md index c7eb1ade9..5665f0cf6 100644 --- a/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md +++ b/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md @@ -15,38 +15,39 @@ To start, you can either download a copy of the parameter file or clone/fork the - [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-09-02/patterns/alz/alzArm.param.json) -The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. +The following instructions apply universally, regardless of your alignment with ALZ or if you have a single management group. -- Change the value of the following parameters at the beginning of parameter file according to the instructions below: +- Modify the values of the following parameters at the beginning of the parameter file as per the instructions below: {{< hint type=note >}} - While it's technically possible to not add any notification information (no email, no ARM Role, no Logic App, etc.) it is strongly recommended to configure at least one option. + It is highly recommended to configure at least one notification option (email, ARM Role, Logic App, etc.) to ensure you receive alerts. While it is technically possible to proceed without any notification settings, doing so is not advised. {{< /hint >}} - - Change the value of _```enterpriseScaleCompanyPrefix```_ to the management group where you wish to deploy the policies and the initiatives. This is usually the so called "pseudo root management group", for example, in [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this would be the so called "Intermediate Root Management Group" (directly beneath the "Tenant Root Group"). - - Change the value of _```bringYourownUserAssignedManagedIdentity```_ to **Yes** if you have an existing user assigned managed identity with the ***Monitoring Reader*** role assigned at the pseudo root management group level or leave it to **No** if you would like to create a new one with the proper rights as part of the deployment process. - - Change the value of _```bringYourownUserAssignedManagedIdentityResourceId```_. If you set the _```bringYourownUserAssignedManagedIdentity```_ parameter to **Yes**, insert the resource id of your user assigned managed identity. If you left it with the default value of **No**, leave the value blank. - - Change the value of _```userAssignedManagedIdentityName```_ to a name of your preference. This parameter is used only if the _```bringYourownUserAssignedManagedIdentity```_ has been set to **No**. - - Change the value of _```managementSubscriptionId```_. If you set the _```bringYourownUserAssignedManagedIdentity```_ parameter to **No**, enter the subscriptionId of the management subscription, otherwise leave the default value. - - Change the value of _```ALZMonitorResourceGroupName```_ to the name of the resource group where the activity logs, resource health alerts, actions groups and alert processing rules will be deployed in. - - Change the value of _```ALZMonitorResourceGroupTags```_ to specify the tags to be added to said resource group. - - Change the value of _```ALZMonitorResourceGroupLocation```_ to specify the location for said resource group. - - Change the value of _```ALZMonitorActionGroupEmail```_ to the email address(es) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no email notification is used. - - Change the value of _```ALZLogicappResourceId```_ to the Logic app resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. - - Change the value of _```ALZLogicappCallbackUrl```_ to the Logic app callback url of the Logic app you want to use as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. To retrieve the callback url you can either use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/en-us/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic app in the Azure portal, go to _**Logic app designer**_, expand the trigger activity (_When an HTTP request is received_) and copy the value in the URL field using the 2-sheets icon. + - Set the value of _```enterpriseScaleCompanyPrefix```_ to the management group where you intend to deploy the policies and initiatives. Typically, this is the "pseudo root management group." In [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this refers to the "Intermediate Root Management Group" located directly beneath the "Tenant Root Group." + - Set the _```bringYourownUserAssignedManagedIdentity```_ parameter to **Yes** if you have an existing user-assigned managed identity with the ***Monitoring Reader*** role assigned at the pseudo root management group level. Otherwise, leave it set to **No** to create a new managed identity with the appropriate permissions during the deployment process. + - Update the _```bringYourownUserAssignedManagedIdentityResourceId```_ parameter. If _```bringYourownUserAssignedManagedIdentity```_ is set to **Yes**, provide the resource ID of your user-assigned managed identity. If it is set to **No**, leave this parameter blank. + - Set the _```userAssignedManagedIdentityName```_ parameter to a preferred name. This parameter is only used if _```bringYourownUserAssignedManagedIdentity```_ is set to **No**. + - Update the _```managementSubscriptionId```_ parameter. If _```bringYourownUserAssignedManagedIdentity```_ is set to **No**, provide the subscription ID of the management subscription. Otherwise, leave it blank. + - Set the _```ALZMonitorResourceGroupName```_ parameter to the name of the resource group where activity logs, resource health alerts, action groups, and alert processing rules will be deployed. + - Update the _```ALZMonitorResourceGroupTags```_ parameter to specify the tags to be added to the resource group. + - Set the _```ALZMonitorResourceGroupLocation```_ parameter to specify the location of the resource group. + - Update the _```ALZMonitorActionGroupEmail```_ parameter with the email address(es) for alert notifications (including Service Health alerts). Leave it blank if no email notification is required. + - Set the _```ALZLogicappResourceId```_ parameter to the Logic App resource ID to be used for alert actions (including Service Health alerts). Leave it blank if no Logic App is used. + - Update the _```ALZLogicappCallbackUrl```_ parameter with the callback URL of the Logic App to be used for alert actions (including Service Health alerts). Leave it blank if no Logic App is used. To retrieve the callback URL, use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/en-us/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic App in the Azure portal, go to _**Logic App Designer**_, expand the trigger activity (_When an HTTP request is received_), and copy the URL using the copy icon. ![Get Logic app callback url](../../../media/AMBA-LogicAppCallbackUrl.png) - - Change the value of _```ALZArmRoleId```_ to the Azure Resource Manager Role(s) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no Azure Resource Manager Role notification is required. - - Change the value of _```ALZEventHubResourceId```_ to the Event Hubs to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Event Hubs is used. - - Change the value of _```ALZWebhookServiceUri```_ to the URI(s) to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Webhook is used. - - Change the value of _```ALZFunctionResourceId```_ to the Function resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. - - Change the value of _```ALZFunctionTriggerUrl```_ to the Function App trigger url of the function to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. To retrieve the Function App trigger url with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the menu top menu and copy the value in the URL field using the 2-sheets icon. + - Update the value of `_ALZArmRoleId_` to specify the Azure Resource Manager Role(s) that should receive notifications for the alerts, including Service Health alerts. If no notifications are required for any Azure Resource Manager Role, leave this value blank. + - Update the value of _```ALZEventHubResourceId```_ to specify the Event Hubs that will be used for alert actions, including Service Health alerts. If no Event Hubs are to be used, leave this value blank. + - Update the _```ALZEventHubResourceId```_ parameter with the resource ID of the Event Hubs to be used for alert actions, including Service Health alerts. Leave it blank if no Event Hubs are used. + - Update the _```ALZWebhookServiceUri```_ parameter with the URI(s) of the Webhooks to be used for alert actions, including Service Health alerts. Leave it blank if no Webhooks are used. + - Update the _```ALZFunctionResourceId```_ parameter with the resource ID of the Function App to be used for alert actions, including Service Health alerts. Leave it blank if no Function App is used. + - Update the _```ALZFunctionTriggerUrl```_ parameter with the trigger URL of the Function App to be used for alert actions, including Service Health alerts. Leave it blank if no Function App is used. To retrieve the Function App trigger URL with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the top menu, and copy the value in the URL field using the copy icon. ![Get function URL](../../../media/AMBA-FunctionAppTriggerUrl.png) {{< hint type=note >}} - It is possible use multiple email addresses, as well as multiple Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). Should you set multiple entries, make sure they are entered as single string with values separated by comma. Example: + You can use multiple email addresses, ARM Roles, Webhooks, or Event Hubs (though using multiple Event Hubs is not recommended as per ALZ guidance). If you set multiple entries, ensure they are entered as a single string with values separated by commas. For example: ```json "ALZMonitorActionGroupEmail": { @@ -70,44 +71,43 @@ The following changes apply to all scenarios, whether you are aligned or unalign ``` {{< /hint >}} - -- If you would like to disable initiative assignments, you can change the value on one or more of the following parameters; _```enableAMBAConnectivity```_, _```enableAMBAIdentity```_, _```enableAMBALandingZone```_, _```enableAMBAManagement```_, _```enableAMBAServiceHealth```_ to _**"No"**_. + To disable initiative assignments, set the value of any of the following parameters to **"No"**: _```enableAMBAConnectivity```_, _```enableAMBAIdentity```_, _```enableAMBALandingZone```_, _```enableAMBAManagement```_, or _```enableAMBAServiceHealth```_. ### If you are aligned to ALZ -- Change the value of _```platformManagementGroup```_ to the management group id for Platform. -- Change the value of _```IdentityManagementGroup```_ to the management group id for Identity. -- Change the value of _```managementManagementGroup```_ to the management group id for Management. -- Change the value of _```connectivityManagementGroup```_ to the management group id for Connectivity. -- Change the value of _```LandingZoneManagementGroup```_ to the management group id for Landing Zones. +- Set the _```platformManagementGroup```_ parameter to the management group ID designated for Platform. +- Set the _```IdentityManagementGroup```_ parameter to the management group ID designated for Identity. +- Set the _```managementManagementGroup```_ parameter to the management group ID designated for Management. +- Set the _```connectivityManagementGroup```_ parameter to the management group ID designated for Connectivity. +- Set the _```LandingZoneManagementGroup```_ parameter to the management group ID designated for Landing Zones. ### If you are unaligned to ALZ -- Change the value of _```platformManagementGroup```_ to the management group id for Platform. The same management group id may be repeated. -- Change the value of _```IdentityManagementGroup```_ to the management group id for Identity. The same management group id may be repeated. -- Change the value of _```managementManagementGroup```_ to the management group id for Management. The same management group id may be repeated. -- Change the value of _```connectivityManagementGroup```_ to the management group id for Connectivity. The same management group id may be repeated. -- Change the value of _```LandingZoneManagementGroup```_ to the management group id for Landing Zones. The same management group id may be repeated. +- Set the _```platformManagementGroup```_ parameter to the management group ID designated for Platform. This ID may be used multiple times. +- Set the _```IdentityManagementGroup```_ parameter to the management group ID designated for Identity. This ID may be used multiple times. +- Set the _```managementManagementGroup```_ parameter to the management group ID designated for Management. This ID may be used multiple times. +- Set the _```connectivityManagementGroup```_ parameter to the management group ID designated for Connectivity. This ID may be used multiple times. +- Set the _```LandingZoneManagementGroup```_ parameter to the management group ID designated for Landing Zones. This ID may be used multiple times. {{< hint type=note >}} -For ease of deployment and maintenance we have kept the same variables. For example, if you combined Identity, Management and Connectivity into one management group you should configure the variables _```identityManagementGroup```_, _```managementManagementGroup```_ , _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the same management group id. +For streamlined deployment and maintenance, we have retained the same variable names. For instance, if you have consolidated Identity, Management, and Connectivity into a single management group, configure the variables _```identityManagementGroup```_, _```managementManagementGroup```_, _```connectivityManagementGroup```_, and _```LZManagementGroup```_ with the same management group ID. {{< /hint >}} ### If you have a single management group -- Change the value of _```platformManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```IdentityManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```managementManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```connectivityManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```LandingZoneManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". +- Set the value of _```platformManagementGroup```_ to the pseudo root management group ID, also known as the "Intermediate Root Management Group". +- Set the value of _```IdentityManagementGroup```_ to the pseudo root management group ID, also known as the "Intermediate Root Management Group". +- Set the value of _```managementManagementGroup```_ to the pseudo root management group ID, also known as the "Intermediate Root Management Group". +- Set the value of _```connectivityManagementGroup```_ to the pseudo root management group ID, also known as the "Intermediate Root Management Group". +- Set the value of _```LandingZoneManagementGroup```_ to the pseudo root management group ID, also known as the "Intermediate Root Management Group". {{< hint type=note >}} -For ease of deployment and maintenance we have kept the same variables. Configure the variables _```enterpriseScaleCompanyPrefix```_, _```identityManagementGroup```_, _```managementManagementGroup```_, _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the pseudo root management group id. +For streamlined deployment and maintenance, we have retained the same variable names. Configure the variables _```enterpriseScaleCompanyPrefix```_, _```identityManagementGroup```_, _```managementManagementGroup```_, _```connectivityManagementGroup```_, and _```LZManagementGroup```_ with the pseudo root management group ID. {{< /hint >}} -## 2. Example Parameter file +## 2. Sample Parameter File -The parameter file shown below has been truncated for brevity, compared to the samples included. +The parameter file below is a shortened version for demonstration purposes. Full examples are available in the provided samples. ```json { diff --git a/docs/content/patterns/alz/Overview/ALZ-Pattern.md b/docs/content/patterns/alz/Overview/ALZ-Pattern.md index b3dc47885..0c82f33c5 100644 --- a/docs/content/patterns/alz/Overview/ALZ-Pattern.md +++ b/docs/content/patterns/alz/Overview/ALZ-Pattern.md @@ -1,101 +1,89 @@ --- -title: The ALZ pattern +title: The ALZ Pattern geekdocCollapseSection: true weight: 10 --- - ## Overview -AMBA for ALZ is a best practice collection of alerts for resources commonly deployed into Azure landing zones and demonstrates how to deploy alerts at scale using Azure Policy. +The Azure Monitor Baseline Alerts (AMBA) for Azure Landing Zones (ALZ) is a best practice collection of alerts for resources commonly deployed in Azure landing zones. It demonstrates how to deploy alerts at scale using Azure Policy. + +A frequent question from customers is, "What should we monitor in Azure?" and "What thresholds should we set for our alerts?" -One of the most common questions faced when working with customers is, "What should we monitor in Azure?" and "What thresholds should we configure our alerts for?" +There isn't a definitive list of what to monitor when deploying to Azure because it depends on the services used and their usage patterns. This dictates what to monitor, the metrics to collect, and the errors to alert on. -There isn't definitive list of what you should monitor when you deploy something to Azure because "it depends", on what services you're using and how the services are used, which will in turn dictate what you should monitor and what thresholds the metrics you do decide to collect are and what errors you should alert on in logs. +Microsoft addresses this with various 'insights or solutions' for popular services, such as [Storage Insights](https://learn.microsoft.com/en-us/azure/storage/common/storage-insights-overview), [VM Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-overview), and [Container Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/container-insights-overview). However, this doesn't cover everything. -Microsoft has tried to address this by providing a number of 'insights or solutions' for popular services which pull together all the things you should care about ([Storage Insights](https://learn.microsoft.com/en-us/azure/storage/common/storage-insights-overview), [VM Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-overview), [Container Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/container-insights-overview)); but what about everything else??? +This project focuses on monitoring for Azure Landing Zones, providing a common set of Azure resources/services configured similarly across organizations. It also includes guidance for custom brownfield scenarios that don't align with ALZ. This serves as a starting point for addressing "What should be monitored in Azure?" and demonstrates how to monitor at scale using Infrastructure-as-Code principles. -The purpose of this project is to focus on monitoring for Azure Landing Zone as a common set of Azure resources/services that are configured in a similar way across organizations. We know that every organization is different, as such we also include guidance on how this can be used in custom brownfield scenarios that don´t align with ALZ. This provided us with a starting point on addressing "What should be monitored in Azure?" It also provides an example of how to monitor-at-scale while leveraging Infrastructure-as-code principles. -This project is an opinionated view on what you should monitor for the key components of your Azure Landing Zone within the Platform and Landing Zone scope. i.e: +This project offers an opinionated view on monitoring key components of your Azure Landing Zone within the Platform and Landing Zone scope, including: - Express Route Circuits - Express Route Gateways - Express Route Ports - Azure Firewalls - Application Gateways -- Load balancers +- Load Balancers - Virtual Networks - Virtual Network Gateways -- Log Analytics workspaces -- Private DNS zones +- Log Analytics Workspaces +- Private DNS Zones - Azure Key Vaults -- Virtual Machine -- Service health +- Virtual Machines +- Service Health -Monitoring baselines for the above components are proposed to be deployed leveraging Azure Policy and has been bundled into Azure Policy initiatives for ease of deployment and management. In addition to the components mentioned there are also a number of other component alerts included in the repo, but outside any initiatives, or disabled by default. These components are: +Monitoring baselines for these components are deployed using Azure Policy and bundled into Azure Policy initiatives for ease of deployment and management. Additional component alerts included in the repository, but outside any initiatives or disabled by default, are: -- Storage accounts -- Network security groups -- Azure route tables +- Storage Accounts +- Network Security Groups +- Azure Route Tables -In addition to the component specific alerts mentioned above the repo also contains policies for deploying service health alerts by subscription. +The repository also contains policies for deploying service health alerts by subscription. -Alerts are based on Microsoft public guidance where available, and on practical application experience where public guidance is not available. For more details on which alerts are included please refer to [Alert Details](../../Getting-started/Alerts-Details). +Alerts are based on Microsoft public guidance where available and practical application experience where not. For details on included alerts, refer to [Alert Details](../../Getting-started/Alerts-Details). -For details on how policies are grouped into initiatives please refer to [Azure Policy Initiatives](../../Getting-started/Policy-Initiatives) +For information on how policies are grouped into initiatives, refer to [Azure Policy Initiatives](../../Getting-started/Policy-Initiatives). -In addition to the above of course the alerts need to go somewhere. To that end a generic action group and alert processing rule is deployed to every subscription in scope, also via policy. For more details around this, as well as the reasoning behind this approach please refer to [Monitoring and Alerting](../../Getting-started/Monitoring-and-Alerting). +Alerts need to be directed somewhere. A generic action group and alert processing rule is deployed to every subscription in scope via policy. For more details and the reasoning behind this approach, refer to [Monitoring and Alerting](../../Getting-started/Monitoring-and-Alerting). -## 📣Feedback 📣 +## 📣 Feedback 📣 -Once you've had an opportunity to deploy the solution we'd love to hear from you! Click [here](https://aka.ms/alz/monitor/feedback) to leave your feedback. +We welcome your feedback after deploying the solution. Click [here](https://aka.ms/alz/monitor/feedback) to leave your feedback. -If you have encountered a problem please file an issue in our GitHub repo [GitHub Issue](https://github.com/Azure/azure-monitor-baseline-alerts/issues). +If you encounter a problem, please file an issue in our GitHub repository [GitHub Issue](https://github.com/Azure/azure-monitor-baseline-alerts/issues). ## Deployment Guide -We have a [Deployment Guide](../../Howto/deploy/Introduction-to-deploying-the-ALZ-Pattern) available for guidance on how to consume the contents of this repo. +Refer to our [Deployment Guide](../../Howto/deploy/Introduction-to-deploying-the-ALZ-Pattern) for guidance on consuming the contents of this repository. ## Known Issues -Please see the [Known Issues](../../Resources/Known-Issues). +See the [Known Issues](../../Resources/Known-Issues) section. ## Frequently Asked Questions -Please see the [Frequently Asked Questions](../../Resources/FAQ). +Refer to the [Frequently Asked Questions](../../Resources/FAQ) section. ## Contributing -This project welcomes contributions and suggestions. -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). +We welcome contributions and suggestions. Most contributions require a Contributor License Agreement (CLA) to 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. +When you submit a pull request, a CLA bot will determine if you need to provide a CLA and guide you through the process. You only need to do this once across all repositories using our CLA. -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any questions or comments. {{< hint type=note >}} -Details on contributing to this repo can be found in the [Contributor Guide](../../../../contributing) +Details on contributing to this repository can be found in the [Contributor Guide](../../../../contributing). {{< /hint >}} ## Telemetry -When you deploy the IP located in this repo, Microsoft can identify the installation of said IP with the deployed Azure resources. Microsoft can correlate these resources used to support the software. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through customer usage attribution. The data is collected and governed by [Microsoft's privacy policies](https://www.microsoft.com/trustcenter). +When you deploy the IP located in this repository, Microsoft can identify the installation with the deployed Azure resources. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through customer usage attribution and governed by [Microsoft's privacy policies](https://www.microsoft.com/trustcenter). -If you don't wish to send usage data to Microsoft, or need to understand more about its' use details can be found in the [Disable telemetry tracking](../../Howto/Telemetry) guide. +If you don't wish to send usage data to Microsoft or need more details, refer to the [Disable telemetry tracking](../../Howto/Telemetry) guide. ## Trademarks -This project may contain trademarks or logos for projects, products, or services. -Authorized use of Microsoft trademarks or logos is subject to and must follow -[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). -Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. -Any use of third-party trademarks or logos are subject to those third-party's policies. +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third-party's policies. [Back to top of page](.) diff --git a/docs/content/patterns/alz/Overview/Whats-New.md b/docs/content/patterns/alz/Overview/Whats-New.md index e68a09137..4055f9a4c 100644 --- a/docs/content/patterns/alz/Overview/Whats-New.md +++ b/docs/content/patterns/alz/Overview/Whats-New.md @@ -1,19 +1,21 @@ --- -title: What´s new +title: What's New geekdocCollapseSection: true weight: 09 --- -For information on what's new please refer to the [Releases](https://github.com/Azure/azure-monitor-baseline-alerts/releases) page. +For the latest updates, visit the [Releases](https://github.com/Azure/azure-monitor-baseline-alerts/releases) page. -To update your current deployment with the content from the latest release, please refer to the [Update to new releases](../../HowTo/UpdateToNewReleases) guide. +To update your deployment with the latest release, refer to the [Update to new releases](../../HowTo/UpdateToNewReleases) guide. ## 2024-09-02 -### New features +### New Features + +- **AMBA Portal Accelerator**: Introducing the Azure Monitor Baseline Alerts Accelerator, now in preview! Deploy alerts quickly and confidently through the Azure Portal UI. For detailed instructions, see [Deploy via the Azure Portal (Preview)](../deploy/Deploy-via-Azure-Portal-UI). + +- **Modular Initiatives**: The former Landing Zone Initiative is deprecated. We now offer a modular approach with distinct components. For more details, visit [Policy Initiatives](../Policy-Initiatives). -- **AMBA Portal Accelerator**: We are thrilled to introduce the Azure Monitor Baseline Alerts Accelerator, now available in preview! The new deployment method is accessible directly through the Azure Portal UI, providing a user-friendly interface that guides you through the setup process. This means you can deploy alerts faster and with greater confidence. It simplifies the process of setting up baseline alerts, ensuring that you are promptly notified of critical metrics and log anomalies that could indicate potential issues with your Azure deployments. To begin using the AMBA Portal Accelerator click the Deploy to Azure button below. Please refer to the detailed deployment instructions for further guidance. [Deploy via the Azure Portal (Preview)](../deploy/Deploy-via-Azure-Portal-UI) -- **Modular approach to Initiatives**: Recognizing the limitations of a monolithic approach, we have deprecated the former Landing Zone Initiative. The initiative was becoming too large and impractical. Instead, We have adopted a modular approach by splitting the initiative into the following distinct components. For more details please visit: [Policy Initiatives](../Policy-Initiatives) - Key Management - Load Balancing - Network Changes @@ -21,125 +23,131 @@ To update your current deployment with the content from the latest release, plea - Storage - VM - Web -- **Threshold Override:** Some resources need thresholds different from the baseline set in the Policy Definition. The Alert Threshold Override feature lets both Greenfield and Brownfield customers adjust these thresholds for specific resources, before or after deployment. By using a tag with a specific name and value, you can override the default alert threshold. This custom threshold applies only to the tagged resources, replacing the global parameter value. This feature is available only for metrics and log alerts. Learn more: [Alert Threshold Override](../Available_features/Threshold-Override) -- **Custom tags and values to disable monitoring**: The updated feature lets you specify both a tag name and a list of values. For example, if you have an "Environment" tag with values like "Production," "Development," or "Sandbox," you can deploy alerts only for "Production" resources by disabling monitoring for those tagged as "Development" and "Sandbox." -- Added new alert rule for Azure Key Vault Managed HSM. This has been included in both the Identity and Key Mananagement initiatives. -- Added new Daily Cap threshold alert on a Log Analytics workspace. This alert has been added to the Management initiative. -- Added new Application Insight Throttling alert. Included in the Web initiative. -- Added new ActivityLog Alert for deleting Application Insight. Added to the Web initiative. -- Added the ability to change the Application Gateway dynamic alert sensitivity -- **Deprecated** the Landing Zone Initiative - -### Bug fixes - -- Fixed [[#280](https://github.com/Azure/azure-monitor-baseline-alerts/issues/280)]: AGW Compute Units Alert and AGW Unhealthy Host Count Alert remain non-compliant after successful remediation -- Fixed [[#278](https://github.com/Azure/azure-monitor-baseline-alerts/issues/278)]: Deploy VNetG ExpressRoute CPU Utilization Alert remediation fails -- Fixed [[#284](https://github.com/Azure/azure-monitor-baseline-alerts/issues/284)]: AMBA policy ALZ_ServiceHealth_ActionGroups Missing when remediating AMBA policies -- Fixed [[#253](https://github.com/Azure/azure-monitor-baseline-alerts/issues/253)]: Deploying AMBA, older version used in documentation -- Fixed [[#261](https://github.com/Azure/azure-monitor-baseline-alerts/issues/261)]: displayname VMLowOSDisk(Write/Read)LatencyAlert should be VMHighOSDisk(Write/Read)LatencyAlert -- Fixed [[#260](https://github.com/Azure/azure-monitor-baseline-alerts/issues/260)]: No treshold parameter for ALZ alerts ALZ_WSFMemoryPercentage, ALZ_WSFCPUPercentage. -- Fixed casing in metadata. -- Fixed casing in policies. -- Fixed default values for multiple parameters used in the VM and Hybrid initiatives. - -### Documentation updates - -- Added new policies for ExpressRoute Ports to Connectivity table. [Policy Initiatives](../Policy-Initiatives) -- Documentation update about unsupported/unrecommended Tenant Root Group deployment. [FAQ](../FAQ) -- New guidance for bringing you own Managed Identity. [Bring Your Own User Assigned Managed Identity](../Available_features/Bring-Your-Own-User-Assigned-Managed-Identity) -- Update the Policy Initiatives documentation to include the Policy Reference ID and update the Policy Name column to use the display name of all the policies. [Policy Initiatives](../Policy-Initiatives) + +- **Threshold Override**: Adjust alert thresholds for specific resources using a tag. This feature is available for metrics and log alerts. Learn more: [Alert Threshold Override](../Available_features/Threshold-Override). + +- **Custom Tags to Disable Monitoring**: Specify a tag name and values to disable monitoring for certain resources. + +- New alert rule for Azure Key Vault Managed HSM, included in Identity and Key Management initiatives. +- New Daily Cap threshold alert for Log Analytics workspace, added to the Management initiative. +- New Application Insight Throttling alert, included in the Web initiative. +- New ActivityLog Alert for deleting Application Insight, added to the Web initiative. +- Ability to change Application Gateway dynamic alert sensitivity. + +- **Deprecated** the Landing Zone Initiative. + +### Bug Fixes + +- Fixed [[#280](https://github.com/Azure/azure-monitor-baseline-alerts/issues/280)]: AGW Compute Units Alert and AGW Unhealthy Host Count Alert remain non-compliant after remediation. +- Fixed [[#278](https://github.com/Azure/azure-monitor-baseline-alerts/issues/278)]: Deploy VNetG ExpressRoute CPU Utilization Alert remediation fails. +- Fixed [[#284](https://github.com/Azure/azure-monitor-baseline-alerts/issues/284)]: AMBA policy ALZ_ServiceHealth_ActionGroups missing during remediation. +- Fixed [[#253](https://github.com/Azure/azure-monitor-baseline-alerts/issues/253)]: Older version used in documentation. +- Fixed [[#261](https://github.com/Azure/azure-monitor-baseline-alerts/issues/261)]: Display name VMLowOSDisk(Write/Read)LatencyAlert should be VMHighOSDisk(Write/Read)LatencyAlert. +- Fixed [[#260](https://github.com/Azure/azure-monitor-baseline-alerts/issues/260)]: No threshold parameter for ALZ alerts ALZ_WSFMemoryPercentage, ALZ_WSFCPUPercentage. +- Fixed casing in metadata and policies. +- Fixed default values for multiple parameters in VM and Hybrid initiatives. + +### Documentation Updates + +- Added new policies for ExpressRoute Ports to Connectivity table. [Policy Initiatives](../Policy-Initiatives). +- Updated documentation on unsupported/unrecommended Tenant Root Group deployment. [FAQ](../FAQ). +- New guidance for bringing your own Managed Identity. [Bring Your Own User Assigned Managed Identity](../Available_features/Bring-Your-Own-User-Assigned-Managed-Identity). +- Updated Policy Initiatives documentation to include Policy Reference ID and display names. [Policy Initiatives](../Policy-Initiatives). ### Tools -- **Automation**: New workflow that automates the process of creating ARM templates for Azure Policies/ PolicySets. The workflow is triggered by a pull request event and uses a bicep build to generate the templates. +- **Automation**: New workflow automates ARM template creation for Azure Policies/PolicySets, triggered by pull request events. ## 2024-06-05 -### New features +### New Features -- Added new PIDs for different additional deployment methods. Refer to the [Disable telemetry tracking](../../HowTo/Telemetry) guide for more information. -- Added new initiative to monitor Azure Arc-enabled Virtual Machines. [Alerting-HybridVM](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/policySetDefinitions/Deploy-HybridVM-Alerts.json) +- Added new PIDs for additional deployment methods. See [Disable telemetry tracking](../../HowTo/Telemetry) for more information. +- New initiative to monitor Azure Arc-enabled Virtual Machines. [Alerting-HybridVM](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/policySetDefinitions/Deploy-HybridVM-Alerts.json). -### Bug fixes +### Bug Fixes -- Changes the value of field minFailingPeriodsToAlert and numberOfEvaluationPeriods in the existenceCondition for the above alerts from 2 to 4 to fix the compliance evaluation issue. -- Changes the value of timeAggregation to Average for both Deploy AGW BackendLastByteResponseTime and Deploy AGW ApplicationGatewayTotalTime policy definitions. [Issue #194](https://github.com/Azure/azure-monitor-baseline-alerts/issues/194) -- Fixing case sensitive parameters [Issue #185](https://github.com/Azure/azure-monitor-baseline-alerts/issues/185) +- Changed minFailingPeriodsToAlert and numberOfEvaluationPeriods in existenceCondition from 2 to 4 to fix compliance evaluation. +- Changed timeAggregation to Average for AGW BackendLastByteResponseTime and AGW ApplicationGatewayTotalTime policies. [Issue #194](https://github.com/Azure/azure-monitor-baseline-alerts/issues/194). +- Fixed case-sensitive parameters [Issue #185](https://github.com/Azure/azure-monitor-baseline-alerts/issues/185). -### Documentation updates +### Documentation Updates -- Updated the Deploy only Service Health Alert documentation. Addresses issues with using json-strings in cloud shell. +- Updated Deploy only Service Health Alert documentation for json-strings in cloud shell. ## 2024-04-12 -### New features +### New Features - Updated Existence Condition to detect and remediate configuration drift. The following parameters were added to the Existence Condition of the policies: + - Static alerts: EvaluationFrequency, WindowSize, Threshold, Severity, Operator, autoMitigate + - Dynamic alerts: alertSensitivity, numberOfEvaluationPeriods, minFailingPeriodsToAlert -- Added a suppression Alert Processing Rule, deployed as part of the notification Assets policy. Refer to the [Temporarily disabling notifications](../../HowTo/Temporarily-disabling-notifications) guide for more details. -- Supplying an email address for the Action Group is no longer mandatory. -- Bring your own Action Group and/or Alert Processing Rules. This feature will allow brownfield customers to use existing Action Groups and Alert Processing Rules. Please refer to the [Bring Your Own Notifications (BYON)](../../HowTo/Bring-your-own-Notifications) guide for more details. -### Bug fixes +- Added suppression Alert Processing Rule in notification Assets policy. See [Temporarily disabling notifications](../../HowTo/Temporarily-disabling-notifications) for details. +- Email address for Action Group is no longer mandatory. +- Bring your own Action Group and/or Alert Processing Rules. See [Bring Your Own Notifications (BYON)](../../HowTo/Bring-your-own-Notifications) for details. + +### Bug Fixes -- Fixed operator for `SNATPortUtilization` for Azure Firewall -- Corrected the name for the Deploy Activity Log Storage Account Delete Policy +- Fixed operator for `SNATPortUtilization` for Azure Firewall. +- Corrected name for Deploy Activity Log Storage Account Delete Policy. -### Documentation updates +### Documentation Updates -- Updated deployment documentation to use the latest approved release. -- Updated the Deploy only Service Health Alert documentation. -- Updated the AMBA-ALZ Diagrams to include the new notification assets initiative and Action group options. [AMBA-Diagram](../../media/AMBA-Diagrams.vsdx) +- Updated deployment documentation to use the latest release. +- Updated Deploy only Service Health Alert documentation. +- Updated AMBA-ALZ Diagrams to include new notification assets initiative and Action group options. [AMBA-Diagram](../../media/AMBA-Diagrams.vsdx). ## 2024-03-01 -### New features +### New Features -- The action group has been enhanced to allow more choices for notifications and actions +- Enhanced action group for more notification and action choices: - Email Azure Resource Manager Role - Azure Function - Event Hubs - Logic App - Webhook -- The service health initiative no longer includes the deployment of the Alert Processing Rule policy. Service Health now has its own Action Group. -- Added the [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) initiative, which deploys the Alert Processing Rule and the Action Group used by the Connectivity, Identity, Management and Landing zone initiatives. -- New policy for Policy for Storage Account Deletion. [Issue #76](https://github.com/Azure/azure-monitor-baseline-alerts/issues/76) -- Updating the remediation script to allow for a better experience while remediating the new action group for Service Health +- Service health initiative now has its own Action Group. +- Added [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) initiative. +- New policy for Storage Account Deletion. [Issue #76](https://github.com/Azure/azure-monitor-baseline-alerts/issues/76). +- Updated remediation script for better experience with new action group for Service Health. -### Bug fixes +### Bug Fixes -- Fixed: unable to deploy via pipeline using ubuntu-latest. [Issue #64](https://github.com/Azure/azure-monitor-baseline-alerts/issues/64) -- Fixed the PIP VIP alert existence condition to only check for standard SKU. [Issue #80](https://github.com/Azure/azure-monitor-baseline-alerts/issues/80) +- Fixed: unable to deploy via pipeline using ubuntu-latest. [Issue #64](https://github.com/Azure/azure-monitor-baseline-alerts/issues/64). +- Fixed PIP VIP alert existence condition to check only for standard SKU. [Issue #80](https://github.com/Azure/azure-monitor-baseline-alerts/issues/80). -### Documentation updates +### Documentation Updates -- Updated [Deploy with GitHub Actions](../deploy/Deploy-with-GitHub-Actions) addressing [Issue #102](https://github.com/Azure/azure-monitor-baseline-alerts/issues/102) -- Updated guidance for AMA in [Monitoring and Alerting](../../Getting-started/Monitoring-and-Alerting) documentation +- Updated [Deploy with GitHub Actions](../deploy/Deploy-with-GitHub-Actions) addressing [Issue #102](https://github.com/Azure/azure-monitor-baseline-alerts/issues/102). +- Updated guidance for AMA in [Monitoring and Alerting](../../Getting-started/Monitoring-and-Alerting). ## 2023-11-14 -### New features +### New Features -- The Service Health Policy Set Definition now includes parameters to set the Policy Effect. With this you can choose which Server Health alert rules are deployed. Note that the default value for the parameters is "deployIfNotExists". The parameter file has been updated. -- Added alert rules in the Landing Zone Policy Set Definition. +- Service Health Policy Set Definition now includes parameters to set Policy Effect. Default value is "deployIfNotExists". +- Added alert rules in Landing Zone Policy Set Definition: - Front door (Microsoft.Cdn/profiles) - Front door classic (Microsoft.Network/frontdoors) - Traffic Manager (Microsoft.Network/trafficmanagerprofiles) - App Service (Microsoft.Web/serverfarms) -### Bug fixes +### Bug Fixes -- Update path in sample-workflow [Issue #30](https://github.com/Azure/azure-monitor-baseline-alerts/issues/30) -- Update sample commands in Start-AMBARemediation.ps1 [Pull #49](https://github.com/Azure/azure-monitor-baseline-alerts/pull/49) -- Fixes to Role Assignment cleanup, cleanup script [Issue #42](https://github.com/Azure/azure-monitor-baseline-alerts/issues/42) -- Fixed VSCode template validation error [Issue #43](https://github.com/Azure/azure-monitor-baseline-alerts/issues/43) +- Updated path in sample-workflow [Issue #30](https://github.com/Azure/azure-monitor-baseline-alerts/issues/30). +- Updated sample commands in Start-AMBARemediation.ps1 [Pull #49](https://github.com/Azure/azure-monitor-baseline-alerts/pull/49). +- Fixed Role Assignment cleanup script [Issue #42](https://github.com/Azure/azure-monitor-baseline-alerts/issues/42). +- Fixed VSCode template validation error [Issue #43](https://github.com/Azure/azure-monitor-baseline-alerts/issues/43). -### Documentation updates +### Documentation Updates -- How to modify individual policies - [How to modify individual policies](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern/#how-to-modify-individual-policies) -- Added guidance to only Server Health alert rules - [Deploy only Service Health Alerts](../../HowTo/deploy/Deploy-only-Service-Health-Alerts) -- New documentation on updating to a new release - [Update to new releases](../../HowTo/UpdateToNewReleases) -- FAQ Updates - [Frequently Asked Questions](../../Resources//FAQ) +- How to modify individual policies - [How to modify individual policies](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern/#how-to-modify-individual-policies). +- Added guidance for Server Health alert rules - [Deploy only Service Health Alerts](../../HowTo/deploy/Deploy-only-Service-Health-Alerts). +- New documentation on updating to a new release - [Update to new releases](../../HowTo/UpdateToNewReleases). +- FAQ Updates - [Frequently Asked Questions](../../Resources//FAQ). [Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/FAQ.md b/docs/content/patterns/alz/Resources/FAQ.md index 8cf4dd6e0..4768cff8f 100644 --- a/docs/content/patterns/alz/Resources/FAQ.md +++ b/docs/content/patterns/alz/Resources/FAQ.md @@ -6,59 +6,56 @@ 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. +> No, Azure Landing Zones are not required. However, you must use Azure Management Groups. Currently, our focus is on resources commonly deployed as part of Azure Landing Zone implementations. -## Can I deploy to Tenant Root Group? +## Can I deploy to the Tenant Root Group? -> While it´s recommended to implement the alert policies and initiatives to an ALZ Management Group hierarchy, it is not a technical requirement. However, please avoid Tenant Root Group assignments, to minimize debugging inherited policies at lower-level mangement groups, see [CAF documentation](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups). +> Although it is recommended to implement the alert policies and initiatives within an Azure Landing Zone (ALZ) Management Group hierarchy, it is not a technical requirement. However, avoid assigning policies to the Tenant Root Group to minimize the complexity of debugging inherited policies at lower-level management groups. For more information, refer to the [CAF documentation](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups). ## 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. +> No, deployment to multiple regions is not required. The definitions and assignments are scoped at the management group level and are not specific to any region. ## 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. +> The provided thresholds are intended as a starting point, based on Microsoft's recommendations and field experience. You may need to adjust these thresholds to suit your specific environment. Monitor the alerts and adjust the thresholds accordingly: increase the threshold if the alerts are too frequent, or decrease it if the alerts are not triggering when they should. Once you have determined an appropriate threshold, consider sharing your findings with us for broader use. ## 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). +> Setting a threshold of 100% can sometimes result in false alerts, creating unnecessary noise. By lowering the threshold slightly below 100%, this issue can be mitigated while still ensuring alerts for service availability. If the default threshold is not stringent enough, you are encouraged to adjust it upwards. Additionally, you can provide feedback by filing an issue in our GitHub repository: [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. +> The metric rules provided are based on Microsoft's recommendations and field experience. Your usage of Azure resources may vary, so it is advisable to customize the alerts to meet your specific requirements. The primary objective of this project is to facilitate scalable Azure Monitor alerts. You are encouraged to create new rules with your own thresholds. We welcome feedback on your custom rules, so please share your findings with us. ## Can I disable the alerts being deployed for a resource or subscription? -> Yes, please refer to the disabling monitoring documentation [Disabling Policies](../../HowTo/Disabling-Policies) +> Yes, you can disable the alerts for a specific resource or subscription. For detailed instructions, please refer to the [Disabling Policies](../../HowTo/Disabling-Policies) documentation. ## 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$/month1. +> The cost of running the ALZ Baseline solution varies based on several factors, including the number of alert rules deployed, the number of subscriptions inheriting the baseline policies, and the resources within each subscription that match the policy rules. Each alert rule costs approximately $0.1 per month1. +> - Alert rules are charged based on the number of evaluations. +> - If the alert rule evaluates data continuously throughout the month, the cost is approximately $0.11. +> - If the rule evaluates data intermittently (e.g., due to the monitored resource being down and not sending telemetry), the cost is prorated based on the time the rule was actively evaluating data. +> - Using Dynamic Thresholds doubles the cost of the alert rule, resulting in a total cost of approximately $0.2 per month1. +> - The solution configures an email address as part of the Action Groups deployment (one per subscription), with a charge of approximately $2 per month for every 1,000 emails1. > -> - Alert rules are charged based on evaluations. -> - Assuming the alert rule had data to evaluate all throughout the month, it'll cost ~0.1$1. -> - 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 total1) -> - 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 emails1. +> {{< hint type=Note >}} It is advisable to evaluate the costs in a non-production environment before full deployment to ensure a clear understanding of the potential expenses.{{< /hint >}} > -> {{< hint type=Note >}} 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.{{< /hint >}} -> -> 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 -> -> 1 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 +> For detailed cost estimates related to your deployment, please refer to the [Azure Monitor Pricing](https://azure.microsoft.com/en-us/pricing/details/monitor/) page. Additionally, you can collaborate with your local Microsoft account team to develop a rough order of magnitude (RoM) cost estimate. + +> 1 Note that costs may vary slightly depending on the deployment region. The costs mentioned are based on pricing 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 +> Yes, you can access the Visio diagrams 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 ->

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)

->

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.

+>

Yes, as long as the ARM templates are publicly accessible. This solution includes several linked templates that must be accessible publicly. When the top-level ARM template is submitted to Azure Resource Manager, the linked templates are not automatically uploaded and need to be pulled in at deploy time from Azure. Therefore, they must be referenced using a URL accessible from Azure (e.g., via a public GitHub repository).

+> +>

Alternatively, you can 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 for deployment. The template spec is a resource in your Azure subscription, making it easy to securely share the template with users in your organization. You can use Azure role-based access control (Azure RBAC) to grant access to the template spec. This feature is currently in preview.

> > References: > @@ -67,20 +64,20 @@ weight: 80 ## 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) +> No, using the `-TemplateFile` parameter is not feasible because the ARM template includes linked templates. When referencing a linked template, the URI value cannot be a local file or a file accessible only on your local network. Azure Resource Manager must have access to the template, which requires the templates to be referenced using a URL accessible from Azure (e.g., a public GitHub repository). ## What characters can I use when creating Azure resources or renaming Azure subscriptions? -> Not all the characters can be used when creating an Azure resource or renaming an Azure subscription. A list of supported characters for any resource can be found on the [Naming rules and restrictions for Azure resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) public documentation page. As an example that you can find in the referenced documentation, the alert suppression rules only allow alphanumerics, underscores, and hyphens as valid characters and at the beginning of the same page, alphanumeric is referring to: +> Not all characters are allowed when creating Azure resources or renaming Azure subscriptions. For a comprehensive list of supported characters, refer to the [Naming rules and restrictions for Azure resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) documentation. For example, alert suppression rules permit only alphanumeric characters, underscores, and hyphens. > > - **_a_** through **_z_** (lowercase letters) > - **_A_** through **_Z_** (uppercase letters) > - **_0_** through **_9_** (numbers) > -> Creating an Azure resource or renaming a subscription using unsupported characters can hinder to one or more of the following problem: +> Using unsupported characters when creating an Azure resource or renaming a subscription can lead to the following issues: > -> - Resource creation will fail -> - Action group and/or Alert Processing Rules deployment will fail. Specifically to AMBA we have this one documented in the specific [Failed to deploy action group(s) and/or alert processing rule(s)](../Known-Issues#failed-to-deploy-action-groups-andor-alert-processing-rules) article included in the [Known Issues](../Known-Issues) -> - Action group editing will result in Azure portal page error. Specifically to AMBA we have this one documented in the specific [Failed to edit action group(s)](../Known-Issues#failed-to-edit-action-groups) article included in the [Known Issues](../Known-Issues) +> - Resource creation will fail. +> - Deployment of action groups and/or alert processing rules will fail. For AMBA-specific issues, refer to the [Failed to deploy action group(s) and/or alert processing rule(s)](../Known-Issues#failed-to-deploy-action-groups-andor-alert-processing-rules) section in the [Known Issues](../Known-Issues) documentation. +> - Editing action groups will result in an Azure portal page error. For AMBA-specific issues, refer to the [Failed to edit action group(s)](../Known-Issues#failed-to-edit-action-groups) section in the [Known Issues](../Known-Issues) documentation. [Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/Known-Issues.md b/docs/content/patterns/alz/Resources/Known-Issues.md index ef03d832e..8cab62c18 100644 --- a/docs/content/patterns/alz/Resources/Known-Issues.md +++ b/docs/content/patterns/alz/Resources/Known-Issues.md @@ -8,7 +8,7 @@ weight: 100 > ### Error includes > -> The error can be presented with one of the two following messages: +> The error can be presented with one of the following messages: > > ```TEXT > failed to resolve table or column expression named @@ -49,12 +49,12 @@ weight: 100 > > ### Cause > -> When a role or a role assignment is removed, some orphaned object can still appear, preventing a successful deployment. +> When a role or a role assignment is removed, some orphaned objects can still appear, preventing a successful deployment. > > ### Resolution > > 1. Navigate to **_Management Groups_** -> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) were AMBA-ALZ deployment was targeted to +> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) where the AMBA-ALZ deployment was targeted > 3. Select **_Access control (IAM)_** > 4. Under the **_Contributor_** role, select all records named **_Identity not found_** entry and click **_Remove_** > 5. Run the deployment @@ -69,27 +69,27 @@ weight: 100 > > ### Cause > -> A deployment has been performed using one region, for example "uksouth", and when you try to deploy again to the same scope but to a different region you will receive an error. This happens even when a cleanup has been performed (see [Cleaning up a Deployment](../../HowTo/Cleaning-up-a-Deployment) for more details). This is because deployment entries still exist from the previous operation, so a region conflict is detected blocking you to run another deployment using a different region. -> +> When attempting to deploy to a different region, such as "uksouth", after a previous deployment in another region, an error may occur. This issue persists even after performing a cleanup (refer to [Cleaning up a Deployment](../../HowTo/Cleaning-up-a-Deployment) for more details). The error arises because deployment entries from the previous operation still exist, causing a region conflict that prevents the new deployment. + > ### Resolution > -> Situation 1: You are trying to deploy to a region different from the one used in previous deployment. Deploying to the same scope in a different region is not necessary. The definitions and assignments are scoped to a management group and are not region-specific. No action is required. -> -> Situation 2: You cleaned up a previous implementation and want to deploy again to a different region. To resolve this issue, follow the steps below: -> +> Situation 1: You are attempting to deploy to a different region than the one used in a previous deployment. It is not necessary to deploy to the same scope in a different region, as the definitions and assignments are scoped to a management group and are not region-specific. No further action is required. + +> Situation 2: You have cleaned up a previous deployment and now wish to deploy to a different region. Follow these steps to resolve the issue: + > 1. Navigate to **_Management Groups_** -> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) were AMBA deployment was targeted to +> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) where the AMBA deployment was targeted > 3. Click **_Deployment_** > 4. Select all the deployment instances related to AMBA and click **_Delete_**. > -> {{< hint type=Note >}} To recognize the deployment names belonging to AMBA, select those deployments whose names start with: +> {{< hint type=Note >}} To recognize the deployment names belonging to AMBA, select those whose names start with: -1. amba- -2. pid- -3. alzArm -4. ambaPreparingToLaunch +> 1. amba- +> 2. pid- +> 3. alzArm +> 4. ambaPreparingToLaunch -If you deployed AMBA just one time, you have 14 deployment instances +If you've only deployed AMBA once, you have 14 deployment instances. {{< /hint >}} @@ -107,22 +107,22 @@ If you deployed AMBA just one time, you have 14 deployment instances > > ### Resolution > -> To resolve this issue, follow the steps below: +> To resolve this issue, follow these steps: > > 1. Navigate to **_Management Groups_** -> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) were AMBA deployment was targeted to +> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) where AMBA deployment was targeted > 3. Click **_Deployment_** -> 4. Select all the deployments that could be deleted (example: instances of previous deployment related to AMBA) and click **_Delete_** +> 4. Select all the deployments that could be deleted (example: instances of previous deployments related to AMBA) and click **_Delete_** > 5. Run the deployment > -> {{< hint type=Note >}} To recognize the deployment names belonging to AMBA, select those deployments whose names start with: +> {{< hint type=Note >}} To recognize the deployment names belonging to AMBA, select those whose names start with: -1. amba- -2. pid- -3. alzArm -4. ambaPreparingToLaunch +> 1. amba- +> 2. pid- +> 3. alzArm +> 4. ambaPreparingToLaunch -If you deployed AMBA-ALZ just one time, you have 14 deployment instances +If you've only deployed AMBA once, you have 14 deployment instances. {{< /hint >}} @@ -130,7 +130,7 @@ If you deployed AMBA-ALZ just one time, you have 14 deployment instances > ### Error includes > -> The error can be presented with one of the two following messages: +> The error can be presented with one of the following messages: > > ```JSON > { @@ -145,20 +145,18 @@ If you deployed AMBA-ALZ just one time, you have 14 deployment instances > > ### Cause > -> The new [Bring Your Own User Assigned Managed Identity (BYO UAMI)](../../HowTo/Bring-your-own-Managed-Identity) allows you to either use an existing User Assigned Managed Identity (UAMI) or to create a new one in the management subscription automatically assigning the Monitoring reader role to it at the parent pseudo root Management Group. If you opted for creating a new UAMI, the management subscription id is needed. -> +> The new [Bring Your Own User Assigned Managed Identity (BYO UAMI)](../../HowTo/Bring-your-own-Managed-Identity) feature allows you to either use an existing User Assigned Managed Identity (UAMI) or create a new one within the management subscription. This process automatically assigns the Monitoring Reader role to the UAMI at the parent pseudo root Management Group. If a new UAMI is created, ensure the management subscription ID is correctly specified. > ### Resolution > -> Set the parameter for the management subscription id correctly in the parameter file: -> +> Ensure that the management subscription ID is accurately specified in the parameter file: > ![New UAMI deployed by the template](../../media/alz-UAMI-Param-Example-2.png) ## Failed to deploy action group(s) and/or alert processing rule(s) -> The following remediation tasks are failing for one or more resource when the subscription name is used as part of the resource name and contains invalid characters: +> The following remediation tasks fail when the subscription name, used as part of the resource name, contains invalid characters: > -> - Deploy AMBA Notification Assets -> - Deploy AMBA Notification Suppression Asset +> - Deployment of AMBA Notification Assets +> - Deployment of AMBA Notification Suppression Assets > > ### Error includes > @@ -168,27 +166,27 @@ If you deployed AMBA-ALZ just one time, you have 14 deployment instances > > ### Cause > -> When action group(s) and alert processing rule(s) are deployed, they get the subscription name as part of their display name. If the subscription in which they are about to be deployed contains invalid characters in the name, this will make the remediation task failing with a the misleading error reported above. -> +> When action groups and alert processing rules are deployed, the subscription name is included in their display names. If the subscription name contains invalid characters, the deployment will fail, resulting in the misleading error mentioned above. + > ### Resolution > -> Rename the subscription to avoid invalid characters. A list of supported characters for any resource can be found on the [Naming rules and restrictions for Azure resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) public documentation page. As an example that you can find in the referenced documentation, the alert suppression rules only allow alphanumerics, underscores, and hyphens as valid characters and at the beginning of the same page, alphanumeric is referring to: +> Rename the subscription to exclude invalid characters. Refer to the [Naming rules and restrictions for Azure resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) for a list of supported characters. For instance, alert suppression rules only permit alphanumeric characters, underscores, and hyphens. Specifically, alphanumeric characters include: > > - **_a_** through **_z_** (lowercase letters) > - **_A_** through **_Z_** (uppercase letters) > - **_0_** through **_9_** (numbers) > -> After the subscription is renamed correctly, run the remediation +> After renaming the subscription correctly, rerun the remediation. ## Failed to edit action group(s) -> Editing a previously deployed action group is returning a misleading error in the Azure portal page. +> Editing a previously deployed action group is returning a misleading error in the Azure portal. > > ![Api-version required error](../../media/api-version_required.png) > > ### Error includes > -> The error message appearing in the Azure portal includes the following message: +> The error includes the following message: > > ```TEXT > The api-version query parameter (?api-version=) is required for all requests. (Code: MissingApiVersionParameter) @@ -196,16 +194,16 @@ If you deployed AMBA-ALZ just one time, you have 14 deployment instances > > ### Cause > -> Action group are deployed using a name which contain the subscription name. If the subscription name contains characters which are not considered valid for the resource, editing the action group will fail. +> Action groups are deployed with names that include the subscription name. If the subscription name contains invalid characters, editing the action group will fail. > > ### Resolution > -> Rename the subscription to avoid invalid characters. A list of supported characters for any resource can be found on the [Naming rules and restrictions for Azure resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) public documentation page. As an example that you can find in the referenced documentation, the alert suppression rules only allow alphanumerics, underscores, and hyphens as valid characters and at the beginning of the same page, alphanumeric is referring to: +> Rename the subscription to exclude invalid characters. Refer to the [Naming rules and restrictions for Azure resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) for a list of supported characters. For instance, alert suppression rules only permit alphanumeric characters, underscores, and hyphens. Specifically, alphanumeric characters include: > > - **_a_** through **_z_** (lowercase letters) > - **_A_** through **_Z_** (uppercase letters) > - **_0_** through **_9_** (numbers) > -> After the subscription is renamed correctly, remove the existing action groups (those whose name starts with either **_ag-AMBA-_** or **_ag-AMBA-SH-_**) and run the remediation. +> Once the subscription has been renamed to exclude invalid characters, delete the existing action groups (those with names starting with **_ag-AMBA-_** or **_ag-AMBA-SH-_**) and rerun the remediation process. [Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md b/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md index 93c2a0e7a..39fb5cdc1 100644 --- a/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md +++ b/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md @@ -3,8 +3,7 @@ title: Moving from preview to GA geekdocCollapseSection: true weight: 101 --- - -When moving from the preview version to GA, it is required to remove everything deployed by the ALZ Monitor solution. The instructions below detail execution of a PowerShell script to delete all resources deployed, including: +When transitioning from the preview version to the General Availability (GA) version, it is necessary to remove all resources deployed by the ALZ Monitor solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all such resources, including: - Metric Alerts - Activity Log Alerts @@ -14,31 +13,31 @@ When moving from the preview version to GA, it is required to remove everything - Policy Set Definitions - Policy Assignment remediation identity role assignments -All resources deployed as part of the initial ALZ Monitor deployment and the resources created dynamically by 'deploy if not exist' policies are either tagged, marked in metadata, or in description (depending on what the resource supports) with the value `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is used to execute the cleanup of deployed resources; _if it has been removed or modified the cleanup script will not include those resources_. +All resources deployed by the initial ALZ Monitor deployment, as well as those created dynamically by 'deploy if not exist' policies, are tagged, marked in metadata, or described (depending on resource capabilities) with `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is crucial for the cleanup script to identify and remove the resources. If this metadata has been altered or removed, the cleanup script will not recognize those resources for deletion. ## Cleanup Script Execution {{< hint type=Important >}} -It is highly recommended to **thoroughly** test the script before running on production environments. The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. +It is strongly advised to **thoroughly** test the script in a non-production environment before deploying it to production. These sample scripts are not covered by any Microsoft standard support program or service. They are provided "AS IS" without any warranty, express or implied. Microsoft disclaims all implied warranties, including but not limited to, implied warranties of merchantability or fitness for a particular purpose. The user assumes all risks associated with the use or performance of the sample scripts and documentation. Microsoft, its authors, or any contributors to the creation, production, or delivery of the scripts shall not be liable for any damages, including but not limited to, loss of business profits, business interruption, loss of business information, or other financial losses, arising from the use or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. {{< /hint >}} ### Download the script file -Follow the instructions below to download the cleanup script file. Alternatively, clone the repo from GitHub and ensure you are working from the latest version of the file by fetching the latest `main` branch. +Follow these steps to download the cleanup script file. Alternatively, you can clone the repository from GitHub and ensure you have the latest version by fetching the `main` branch. -1. Navigate AMBA [project in GitHub](https://github.com/Azure/azure-monitor-baseline-alerts) -2. In the folder structure, browse to the `patterns/alz/scripts` directory -3. Open the **Start-ALZMonitorCleanup.ps1** script file -4. Click the **Raw** button -5. Save the open file as **Start-ALZMonitorCleanup.ps1** +1. Navigate to the [AMBA project on GitHub](https://github.com/Azure/azure-monitor-baseline-alerts). +2. Browse to the `patterns/alz/scripts` directory. +3. Locate and open the **Start-ALZMonitorCleanup.ps1** script file. +4. Click on the **Raw** button to view the raw content of the script. +5. Save the file as **Start-ALZMonitorCleanup.ps1**. ### Executing the Script -1. Open PowerShell -2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph` -3. Change directories to the location of the **Start-ALZMonitorCleanup.ps1** script -4. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the desired Management Group scope. -5. Execute the script using the option below +1. Launch PowerShell. +2. Install the **Az.ResourceGraph** module by running: `Install-Module Az.ResourceGraph`. +3. Navigate to the directory containing the **Start-ALZMonitorCleanup.ps1** script. +4. Sign in to Azure using the `Connect-AzAccount` command. Ensure the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. +5. Execute the script with one of the following options: {{% include "PowerShell-ExecutionPolicy.md" %}} @@ -61,11 +60,10 @@ Follow the instructions below to download the cleanup script file. Alternatively ``` ## Next steps - -- To customize policy assignments, please proceed with [Customize Policy Assignment](../../HowTo/deploy/Customize-Policy-Assignment) -- To deploy with GitHub Actions, please proceed with [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions) -- To deploy with Azure DevOps Pipelines, please proceed with [Deploy with Azure Pipelines](../../HowTo/deploy/Deploy-with-Azure-Pipelines) -- To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../../HowTo/deploy/Deploy-with-Azure-CLI) -- To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../../HowTo/deploy/Deploy-with-Azure-PowerShell) +- For customizing policy assignments, refer to [Customize Policy Assignment](../../HowTo/deploy/Customize-Policy-Assignment). +- For deployment using GitHub Actions, refer to [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions). +- For deployment using Azure DevOps Pipelines, refer to [Deploy with Azure Pipelines](../../HowTo/deploy/Deploy-with-Azure-Pipelines). +- For deployment using Azure CLI, refer to [Deploy with Azure CLI](../../HowTo/deploy/Deploy-with-Azure-CLI). +- For deployment using Azure PowerShell, refer to [Deploy with Azure PowerShell](../../HowTo/deploy/Deploy-with-Azure-PowerShell). [Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/Versioning.md b/docs/content/patterns/alz/Resources/Versioning.md index 8ac905bff..1416e840a 100644 --- a/docs/content/patterns/alz/Resources/Versioning.md +++ b/docs/content/patterns/alz/Resources/Versioning.md @@ -4,10 +4,10 @@ geekdocCollapseSection: true weight: 110 --- -The primary deliverable of this repo is a collection of Azure Policy initiatives and associated Azure Policy definitions, and as such is versioned in a manner consistent with the [Azure Policy versioning guidance](https://github.com/Azure/azure-policy/blob/master/built-in-policies/README.md#versioning). +The main output of this repository is a set of Azure Policy initiatives and corresponding Azure Policy definitions. These are versioned in alignment with the [Azure Policy versioning guidance](https://github.com/Azure/azure-policy/blob/master/built-in-policies/README.md#versioning). -While this is sufficient for the purposes of individual policies, to further ease adoption of the policies a new release of the repo as a whole will be made available as one or more policies are updated with breaking changes as per the [Azure Policy versioning guidance](https://github.com/Azure/azure-policy/blob/master/built-in-policies/README.md#versioning). +To facilitate the adoption of policies, a new release of the repository will be issued whenever one or more policies are updated with breaking changes, in accordance with the [Azure Policy versioning guidance](https://github.com/Azure/azure-policy/blob/master/built-in-policies/README.md#versioning). -As new versions are released, update guidance will be provided to allow you to update your existing deployments to the new version. +Guidance for updating existing deployments to new versions will be provided with each release. [Back to top of page](.) From 8a98b8e66d9b9450c1d201d12067a00321aa2c44 Mon Sep 17 00:00:00 2001 From: Brunoga-MS Date: Sat, 9 Nov 2024 17:19:13 +0100 Subject: [PATCH 08/14] Aligned Pat' version with Main --- .../Available_features/Threshold-Override.md | 54 ----- .../patterns/alz/Cleaning-up-a-Deployment.md | 0 .../patterns/alz/Disabling-Policies.md | 125 ----------- .../alz/Getting-started/Alerts-Details.md | 20 +- .../Monitoring-and-Alerting.md | 29 ++- .../alz/Getting-started/Policy-Initiatives.md | 32 ++- .../HowTo/Bring-your-own-Managed-Identity.md | 3 - .../alz/HowTo/Bring-your-own-Notifications.md | 5 +- .../alz/HowTo/Cleaning-up-a-Deployment.md | 52 +++-- .../patterns/alz/HowTo/Disabling-Policies.md | 5 +- .../Temporarily-disabling-notifications.md | 2 - .../patterns/alz/HowTo/Threshold-Override.md | 14 +- .../Moving-from-preview-to-GA.md | 6 +- .../Update_from_release_2023-11-14.md | 0 .../Update_from_release_2024-03-01.md | 47 ----- .../Update_from_release_2024-04-12.md | 43 ---- .../Update_from_release_2024-06-05.md | 49 ----- .../Update_to_release_2024-03-01.md | 21 +- .../Update_to_release_2024-04-12.md | 26 +-- .../Update_to_release_2024-06-05.md | 33 ++- .../Update_to_release_2024-09-02.md | 39 ++-- .../Update_to_release_2024-11-01.md | 13 ++ .../deploy/Customize-Policy-Assignment.md | 34 +-- .../Deploy-only-Service-Health-Alerts.md | 7 +- .../deploy/Deploy-via-Azure-Portal-UI.md | 52 +---- .../alz/HowTo/deploy/Deploy-with-Azure-CLI.md | 6 +- .../deploy/Deploy-with-Azure-Pipelines.md | 3 +- .../deploy/Deploy-with-Azure-PowerShell.md | 4 +- .../deploy/Deploy-with-GitHub-Actions.md | 4 +- ...troduction-to-deploying-the-ALZ-Pattern.md | 22 +- .../alz/HowTo/deploy/Remediate-Policies.md | 6 +- .../HowTo/deploy/parameterConfiguration.md | 17 +- .../patterns/alz/Overview/ALZ-Pattern.md | 14 +- .../patterns/alz/Overview/Whats-New.md | 50 ++++- docs/content/patterns/alz/Resources/FAQ.md | 6 +- .../patterns/alz/Resources/Known-Issues.md | 32 +-- .../Resources/Moving-from-preview-to-GA.md | 69 ------ .../patterns/alz/Resources/Versioning.md | 2 - docs/content/patterns/alz/Whats-New.md | 178 ---------------- .../alz/deploy/Deploy-with-Azure-CLI.md | 50 ----- .../deploy/Deploy-with-Azure-PowerShell.md | 58 ----- ...troduction-to-deploying-the-ALZ-Pattern.md | 199 ------------------ .../patterns/alz/deploy/Remediate-Policies.md | 73 ------- .../alz/deploy/parameterConfiguration.md | 172 --------------- 44 files changed, 271 insertions(+), 1405 deletions(-) delete mode 100644 docs/content/patterns/alz/Available_features/Threshold-Override.md delete mode 100644 docs/content/patterns/alz/Cleaning-up-a-Deployment.md delete mode 100644 docs/content/patterns/alz/Disabling-Policies.md delete mode 100644 docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md delete mode 100644 docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md delete mode 100644 docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md delete mode 100644 docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md create mode 100644 docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-11-01.md delete mode 100644 docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md delete mode 100644 docs/content/patterns/alz/Whats-New.md delete mode 100644 docs/content/patterns/alz/deploy/Deploy-with-Azure-CLI.md delete mode 100644 docs/content/patterns/alz/deploy/Deploy-with-Azure-PowerShell.md delete mode 100644 docs/content/patterns/alz/deploy/Introduction-to-deploying-the-ALZ-Pattern.md delete mode 100644 docs/content/patterns/alz/deploy/Remediate-Policies.md delete mode 100644 docs/content/patterns/alz/deploy/parameterConfiguration.md diff --git a/docs/content/patterns/alz/Available_features/Threshold-Override.md b/docs/content/patterns/alz/Available_features/Threshold-Override.md deleted file mode 100644 index 6cf316a32..000000000 --- a/docs/content/patterns/alz/Available_features/Threshold-Override.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Alert Threshold Override -geekdocCollapseSection: true -weight: 85 ---- - -# Overview - -The ***Alert Threshold Override*** feature, available with release [2024-09-05](../../Whats-New#2024-09-05), allows both Greenfield and Brownfield customers to override alert threshold for specific resources during or after the deployment of AMBA-ALZ. Thanks to this new feature, it's now possible to use a tag with specific name and value, to override the default alert threshold for specific resources. The new value will be used, only for the tagged resources, in place of the global one coming from the parameter file. - -# How this feature works - -This feature is only available for metrics and log-search alerts, since Activity Log based alerts do not use threshold and, as such, cannot benefits from this new enhancement. Using the feature is easy: customers need to create a resource tag with a specific name and assign a value of their choice. Once this release is deployed, tags can be created either before or after the execution of remediation task. However, the feature behavior differs between Metric and Log-search alerts. - -## Metrics alerts - -For metric alerts, if tags are configured before the remediation tasks execution, corresponding alerts (which are resource-specific) will be created using different thresholds for the same resource type: - -![Metric Alerts - Override threshold at work](../../media/MetricAlerts-OverrideThresholdAtWork.png) - -If the tags are configured after the remediation task have completed, given the tag being part of the compliance criteria, the resource will be marked as not compliant, as such customers will just need to remediate the corresponding policy initiative(s) as documented at [Remediate Policies](../../deploy/Remediate-Policies) to reconfigure exiting alerts with the new threshold. - -## Log-search alerts -Considering the different nature of log-search alerts where resource information is retrieved at query runtime, it does not make any difference if the tags are configured before or after the remediation task execution. The log-search alert query is created with a placeholder containing the threshold passed by the parameter file and with a logic to look at the resource-specific override tag, thanks to the ability to [Correlate data in Azure Data Explorer and Azure Resource Graph with data in a Log Analytics workspace](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/azure-monitor-data-explorer-proxy). If the specific override tag name is present, the query will use the tag value as new threshold, otherwise it will use the default one passed through the parameter file: - -![Log-search Alerts - Override threshold at work](../../media/LogsearchAlerts-OverrideThresholdAtWork.png) - -## Which tag does customers need to create - -To work correctly, this feature needs to look at specific tag names. Unfortunately it is not possible to allow for more flexibility in tag name in this case. Tag names have been defined, according to the following naming convention: - -{{< hint type=Info >}} -Mapping between resource type friendly name and resource provider namespace (together with the recommended abbreviation) can be found at [Abbreviation recommendations for Azure resources](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations) -{{< /hint >}} - -```***_amba--threshold-override_***``` - -There might be cases where for the same resource, the same metric is used more than one. In this scenario, we implemented a differentiator value inserted right after the metric name, making the naming convention resampling the following format: - -```***_amba---threshold-override_***``` - -The following table contains the mapping between the alert name and the corresponding tag value to be created: - -
- -### Log-search alerts table - -{{% include "Log_Search_Alert_Table.md" %}} - -
- -### Metric alerts table - -{{% include "Metrics_Alert_Table.md" %}} diff --git a/docs/content/patterns/alz/Cleaning-up-a-Deployment.md b/docs/content/patterns/alz/Cleaning-up-a-Deployment.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/content/patterns/alz/Disabling-Policies.md b/docs/content/patterns/alz/Disabling-Policies.md deleted file mode 100644 index b6a0039f3..000000000 --- a/docs/content/patterns/alz/Disabling-Policies.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Disabling Policies -geekdocCollapseSection: true -weight: 60 ---- - -The policies included in AMBA-ALZ provide multiple methods to enable or disable the effects of the policy. - -1. **Parameter: AlertState** - Determines the state of the alert rule. This either deploys an alert rule in a disabled state, or disables an already deployed alert rule at scale trough policy. -2. **Parameter: PolicyEffect** - Determines the effect of a Policy Definition, allowing a Policy to be deployed in a disabled state. -3. **Tag: MonitorDisable** - A tag that determines whether the resource should be evaluated. Allows you to exclude selected resources from monitoring. - -## AlertState parameter - -Recognizing that it is not always possible to test alerts in a dev/test environment, we have introduced the AlertState parameter for all metric alerts (in the initiatives and the example parameter file the parameter is named combining {resourceType}, {metricName} and AlertState, for example VnetGwTunnelIngressAlertState). This is to address a scenario where an alert storm occurs and it is necessary to disable one or more alerts deployed via policies through a controlled process. This could be considered for a roll-back process as part of a change request. - -### Allowed values - -- "true" - Alert rule will be enabled. (Default) -- "false" - Alert rule will be disabled. - -### How it works - -The AlertState parameter is used for both compliance evaluation and configuration of the state of the alert rule. The value of the **AlertState** parameter is passed on to the **enabled** parameter which is part of the existenceCondition of the Policy. - -```json -"existenceCondition": { -    "allOf": [ -        { -            "field": "Microsoft.Insights/metricAlerts/criteria.Microsoft-Azure-Monitor-SingleResourceMultipleMetricCriteria.allOf[*].metricNamespace", -            "equals": "Microsoft.Automation/automationAccounts" -        }, -        { -            "field": "Microsoft.Insights/metricAlerts/criteria.Microsoft-Azure-Monitor-SingleResourceMultipleMetricCriteria.allOf[*].metricName", -            "equals": "TotalJob" -        }, -        { -            "field": "Microsoft.Insights/metricalerts/scopes[*]", -            "equals": "[[concat(subscription().id, '/resourceGroups/', resourceGroup().name, '/providers/Microsoft.Automation/automationAccounts/', field('fullName'))]" -        }, -        { -            "field": "Microsoft.Insights/metricAlerts/enabled", -            "equals": "[[parameters('enabled')]" -        } -    ] -} -``` - -If "allOf" evaluates to true, the effect is satisfied and does not trigger the deployment. If you have implemented the alert rules before and want to disable an alert rule you can change the Alert State to "false", this will cause "allOf" to evaluate as false, which will trigger the deployment that changes the "enabled" property of the alert rule to false. - -### Deployment steps - -These are the high-level steps that would need to take place: - -1. Change the value for the AlertState parameter for the offending policies to false, either via command line or parameter file as described previously. -2. Deploy the policies and assignments as described previously. -3. Once the deployment is completed successfully and the policy evaluation is finished, there will be many non-compliant policies and resources depending on which alerts were to be disabled. These non-compliant resources need to be remediated which can be done either through the portal, on a policy-by-policy basis or you can run the script found in [patterns/alz/scripts/Start-AMBARemediation](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBARemediation.ps1) to remediate all ALZ-Monitor policies in scope as defined by management group pre-fix. - -Note that the preceding approach will not delete the alerts objects in Azure, merely disable them. To delete the alerts, you will have to do so manually. Also note that while you can engage the PolicyEffect to avoid deploying new alerts, you should not do so until you have successfully remediated what was mentioned earlier. Otherwise the policy will be disabled, and you will not be able to turn off alerts via policy until that is changed back. - -## PolicyEffect parameter - -In general, we evaluate the alert rules on best practices, field experience, customer feedback, type of alert and possible impact. There are situations where disabling the policy makes sense to prevent receiving unnecessary and/ or duplicate alerts/ notifications. For example we deploy an alert rule for VPN Gateway Bandwidth Utilization, in turn we have disabled the alert rules for VPN Gateway Egress and Ingress. -The default is intended to provide a well-balanced baseline. However you may want to Enable or Disable the creation of certain Alert rules to meet your needs. - -### Allowed values - -- "deployIfNotExists" - Policy will deploy the alert rule if the conditions are met. (Default for most Policies) -- "disabled" - The policy itself will be created but will not create the corresponding Alert rule. - -### How it works - -The PolicyEffect parameter is used for the configuration of the effect of the PolicyDefinition (in the initiatives and the example parameter file the parameter is named combining {resourceType}, {metricName} and PolicyEffect, for example ERCIRQoSDropBitsinPerSecPolicyEffect). The value of the **PolicyEffect** parameter is passed on to the **effect** parameter which configures the effect of the Policy. - -```json - "policyRule": { - "if": { - "allOf": [ - { - "field": "type", - "equals": "Microsoft.Automation/automationAccounts" - }, - { - "field": "[[concat('tags[', parameters('MonitorDisable'), ']')]", - "notEquals": "true" - } - ] - }, - "then": { - "effect": "[[parameters('effect')]", -``` - -## MonitorDisable parameter - -It´s also possible to exclude certain resources from being monitored. You may not want to monitor pre-production or dev environments. The MonitorDisable parameter contains the tag name and tag value to determine whether a resource should be included. By default, creating the tag MonitorDisable with value "true" will prevent deployment of alert rules on those resources. This can be easily adjusted to use existing tags and tag values. For example you could configure the parameters with the tag name ***Environment*** and tag value of ***Production*** or ***Test*** or ***Sandbox*** or all of them to exclude resources in these environments (see the sample parameter screenshot). - -![MonitorDisable* parameters](../media/MonitorDisableParams.png) - -This will deploy policy definitions which will only be evaluated and remediated if the tag value(s) are not included in the list you provided. - -### How it works - -The policyRule only continues if "allOff" is true. Meaning, the deployment will continue as long as the MonitorDisableTagName tag does not exist or does not hold any of the values listed in the MonitorDisableTagValues parameter. When the tag holds one of the configured values, the "allOff" will return "false" as *"notIn": "[[parameters('MonitorDisableTagValues')]"* is no longer satisfied, causing the evaluation and hence the remediation to stop. - -```json - "policyRule": { - "if": { - "allOf": [ - { - "field": "type", - "equals": "Microsoft.Automation/automationAccounts" - }, - { - "field": "[[concat('tags[', parameters('MonitorDisableTagName'), ']')]", - "notIn": "[[parameters('MonitorDisableTagValues')]" - } - ] - }, -``` - -Given the different resource scope that this method can be applied to, we made it working slightly different when it comes to log-based alerts. For instance, the virtual machine alerts are scoped to subscription and tagging the subscription would result in disabling all the policies targeted at it. -For this reason, and thanks to the new **Bring Your Own User Assigned Managed Identity (BYO UAMI)*** included in the [2024-06-05](../../Whats-New#2024-06-05) release and to the ability to query Azure resource Graph using Azure Monitor (see [Quickstart: Create alerts with Azure Resource Graph and Log Analytics](https://learn.microsoft.com/en-us/azure/governance/resource-graph/alerts-query-quickstart?tabs=azure-resource-graph)), it is now possible to disable individual alerts for both Azure and hybrid virtual machines after they are created. We got requests to stop alerting from virtual machines that were off for maintenance and this enhancement came up just in time. - -Should you need to disable the alerts for your virtual machines after they are created, just make sure you tag the relevant resources accordingly. The alert queries have been modified to look at resource properties in [Azure Resource Graph](https://learn.microsoft.com/en-us/azure/governance/resource-graph/overview). If the resource contains the given tag name and tag value, it is made part of an exclusion list, so alerts will not be generated for them. This behavior allows you to dynamically and rapidly exclude the necessary resources from being alerted without the need of deleting the alert, tag the resource and run the remediation again. - diff --git a/docs/content/patterns/alz/Getting-started/Alerts-Details.md b/docs/content/patterns/alz/Getting-started/Alerts-Details.md index 4c02b1011..5c41b987d 100644 --- a/docs/content/patterns/alz/Getting-started/Alerts-Details.md +++ b/docs/content/patterns/alz/Getting-started/Alerts-Details.md @@ -4,21 +4,21 @@ geekdocCollapseSection: true weight: 30 --- -Download specific alerts for ALZ by clicking on the Download icon (highlighted in red below) in the top right corner of the page. +Download specific alerts for AMBA-ALZ pattern by clicking on the Download icon (highlighted in red below) in the top right corner of the page. ![Alert-Details Download icon](../../media/AlertDetailsDownloadReference.png) -To view which policy alert rules are part of the ALZ pattern, visit the [Policy-Initiatives](../Policy-Initiatives) page. +To view which policy alert rules are part of the AMBA-ALZ pattern, visit the [Policy-Initiatives](../Policy-Initiatives) page. The resources, metric alerts, and their configurations serve as an initial guide to help you address key monitoring questions such as "What should we monitor in Azure?" and "What alert settings should we use?". These settings are designed to cover the most common components of an Azure Landing Zone. However, we recommend customising these settings to better align with your specific monitoring requirements and usage of Azure. If you have suggestions for other resources that should be included, open an Issue on this page providing the Azure resource provider and settings you would like implemented. We can not guarantee their implementation but we will carefully consider them. Alternatively, if you would like to contribute directly, follow the steps in the [Contributor Guide](../../../../contributing). -## Azure Landing Zone Metric Alerts Settings +## AMBA-ALZ pattern Metric Alerts Settings The values shown for Aggregation, Operator, Threshold, WindowSize, Frequency, and Severity are derived from field experience and customer implementations. Alerts are based on Microsoft public guidance where available (indicated by a 'Yes' in the Verified column) and practical application experience where public guidance is not available (indicated by a 'No' in the Verified column). Links to Product Group guidance are provided in the References column. Where no guidance is available, a link to the description of the Metric on learn.microsoft.com is included. -The Scope column indicates where we scoped the alerts as described in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern). +The Scope column indicates where we scoped the alerts as described in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern). Only a limited number of resources support metric alert rules scoped at the subscription level, and these metric alerts are applicable only to resources deployed within the same region. The Support for Multiple Resources column indicates which resources support metric alerts at the subscription level. For a comprehensive list of resources that support metric alert rules at the subscription level, please click [here](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-types#monitor-multiple-resources). @@ -28,21 +28,21 @@ We have designed the table to minimize the need for horizontal scrolling, but it {{< alzMetricAlerts >}} -1 See "Why are the availability alert thresholds lower than 100% in this solution when the product group document ion recommends 100%?" in the [FAQ](../../Resources/FAQ) for more details. +1 See "Why are the availability alert thresholds lower than 100% in this solution when the product group documentaion recommends 100%?" in the [FAQ](../../Resources/FAQ) for more details. -## Azure Landing Zone Activity Log Alerts +## AMBA-ALZ pattern Activity Log Alerts -### Azure Landing Zone Activity Log Resource Health +### Activity Log Resource Health Refer to the following two sections to promptly identify any Service Health issues with an Azure resource. This will save you the effort of further troubleshooting and allow you to focus on communicating with your user base or incorporating these alerts into your business continuity actions (remediations). {{< alzActivityLogResourceHealthAlerts >}} -### Azure Landing Zone Service Health Alerts +### Service Health Alerts {{< alzActivityLogServiceHealthAlerts >}} -### Azure Landing Zone Activity Log Administrative +### Activity Log Administrative The table below lists several operational Activity Log alerts designed to notify your team when specific resources are deleted. @@ -67,5 +67,3 @@ Security Alerts and Job Failure alerts are summarized in the "[Using Backup Cent | PolicyName | Component | Category | Scope | Support for Multiple Resources | Verified | References | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------|----------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Deploy RV Backup Health Monitoring Alerts](../../../services/RecoveryServices/vaults/Modify-RSV-BackupHealth-Alert.json) | Microsoft.RecoveryServices/Vaults | Microsoft.RecoveryServices/vaults/monitoringSettings.classicAlertSettings.alertsForCriticalOperations | Resource | No | Y | [Azure Monitor Alerts for Azure Backup](https://learn.microsoft.com/en-us/azure/backup/backup-azure-monitoring-built-in-monitor?tabs=recovery-services-vaults#azure-monitor-alerts-for-azure-backup)
[Move to Azure Monitor Alerts](https://learn.microsoft.com/en-us/azure/backup/move-to-azure-monitor-alerts) | - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md b/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md index 46be56cd1..e4950437b 100644 --- a/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md +++ b/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md @@ -4,11 +4,11 @@ geekdocCollapseSection: true weight: 20 --- -## ALZ Monitor Alert Approach +## AMBA-ALZ Monitor Alert Approach -The overall strategy for enabling alerts in ALZ involves using Azure Policy to deploy relevant alerts as resources are created, configuring action groups, and then using Alert Processing Rules to activate alerts and link them to the action group. +The overall strategy for enabling alerts in AMBA-ALZ pattern involves using Azure Policy to deploy relevant alerts as resources are created, configuring action groups, and then using Alert Processing Rules to activate alerts and link them to the action group. -There are two main principles/approaches to enabling alerting in ALZ: +There are two main principles/approaches to enabling alerting in AMBA-ALZ pattern : ### Centralized @@ -16,7 +16,7 @@ In a **centralized** alerting approach, a single Action Group is used for all al Metric alerts are deployed with resources in the same resource group, while platform alerts like Service Health and Activity are created in a dedicated resource group within a subscription typically located in the Management platform management group. A single Alert Action Group in this subscription is configured with a central alerting email address and Alert Processing Rules in order to enable filters and connect alerts to the Alert Action Group. -For example, in the context of ALZ, a single centralised action group is deployed in the "rg-amba-monitoring-001" resource group within a subscription in the Management platform management group. +For example, in the context of AMBA-ALZ pattern, a single centralised action group is deployed in the "rg-amba-monitoring-001" resource group within a subscription in the Management platform management group. ### Decentralized @@ -24,24 +24,24 @@ In a **decentralized** approach, each subscription has a dedicated Action Group, Metric alerts are deployed with resources in the same resource group, while platform alerts such as Service Health and Activity are created in a dedicated resource group for each subscription. Alert Action Groups are established in each landing zone subscription, allowing different operational areas and landing zone subscriptions to have distinct alerting email addresses (e.g., networking, identity, operations, workloads) or other supported actions. Alert Processing Rules are created to enable filters and connect alerts to the Action Groups. -For example, in the context of ALZ, a graphic representation of the flow is provided below. +For example, in the context of AMBA-ALZ pattern , a graphic representation of the flow is provided below. ![ALZ alerting](../../media/AMBA-focused-rg-alz-monitor-alert-flow.png) -### ALZ Approach +### AMBA-ALZ Approach -In ALZ, a decentralized approach is adopted to provide maximum flexibility in directing alerts. For more information review [What are Azure Monitor Alerts?](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-overview). +In AMBA-ALZ pattern, a decentralized approach is adopted to provide maximum flexibility in directing alerts. For more information review [What are Azure Monitor Alerts?](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-overview). - Each subscription will have a single Action Group, allowing customers to configure specific actions per subscription, such as different email addresses or other supported actions. - Alert Processing Rules will target the Action Group in the subscription where the alert originated. -As this is a work in progress, the initial configuration provided by ALZ will set up all Action Groups with the same email distribution group/address through Azure Policy. Future updates may include alternative or additional actions, such as configuring different email distribution groups based on the subscription, service, or workload owners. +As this is a work in progress, the initial configuration provided by AMBA-ALZ will set up all Action Groups with the same email distribution group/address through Azure Policy. Future updates may include alternative or additional actions, such as configuring different email distribution groups based on the subscription, service, or workload owners. -ALZ Alerts, Action Groups and Alert Processing Rules are deployed using Azure Policy defined in the platform native Azure Policy JSON format. +AMBA-ALZ Alerts, Action Groups and Alert Processing Rules are deployed using Azure Policy defined in the platform native Azure Policy JSON format. -## ALZ Monitor Alert Policy Definitions +## AMBA-ALZ Pattern Monitor Alert Policy Definitions -The following policy definition categories will be enabled as part of ALZ deployments for the hubs and landing zones defined by Azure landing zone: +The following policy definition categories will be enabled as part of AMBA-ALZ deployments for the hubs and landing zones defined by Azure landing zone: - Resource Metrics; See [here](../Alerts-Details#azure-landing-zone-metric-alerts-settings) for details on which resource metrics are included. - Service and Resource Health; See [here](../Alerts-Details#azure-landing-zone-activity-log-resource-health) for details on which alerts are included. @@ -67,13 +67,14 @@ Log alerts are scoped at the subscription level. For policies to remediate and d Service and resource health events are recorded in the activity log, allowing us to create a subset of activity log alerts that notify on health events. These alerts are scoped to each subscription and include four separate alerts for each of the service health categories: Incident, Planned Maintenance, Security Advisories, and Health Advisories. + A resource health alert will be generated for any resource that enters an unavailable or degraded state, whether platform or user-initiated. We will disregard the unknown state to avoid erroneous alerting. -## ALZ Monitor Alert Processing Rules +## AMBA-ALZ Monitor Alert Processing Rules [Alert Processing Rules](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-processing-rules) enable the filtering of alerts and assign alerts to the appropriate action groups based on filter criteria. -As this is currently a work in progress, for ALZ we will implement a single Action Group per subscription, and deploy a single Alert Processing Rule without filters to manage alerts via the Action Group. This approach may be revised in the future. +As this is currently a work in progress, for AMBA-ALZ we will implement a single Action Group per subscription, and deploy a single Alert Processing Rule without filters to manage alerts via the Action Group. This approach may be revised in the future. We still need to investigate appropriate filters for Alert Processing Rules for optimal alert processing. @@ -126,5 +127,3 @@ Azure Backup now provides new and improved alerting capabilities via Azure Monit ### Notifications While alerts are generated by default and cannot be disabled for destructive operations, users have control over the notifications. This allows you to specify the email addresses (or other notification endpoints) to which alerts should be routed. Notifications are configured by an alert processing rule, which is created by default when deploying the AMBA-ALZ pattern. - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md b/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md index 4d250c3db..2fc36fa30 100644 --- a/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md +++ b/docs/content/patterns/alz/Getting-started/Policy-Initiatives.md @@ -6,11 +6,11 @@ weight: 40 ## Overview -This document details the ALZ-Monitor Azure policy initiatives used for deploying the ALZ-Monitor baselines. For references on individual alerts/policies, refer to [Alert Details](../..//Getting-started//Alerts-Details). +This document details the AMBA-ALZ pattern Azure policy initiatives used for deploying the AMBA-ALZ baselines. For references on individual alerts/policies, refer to [Alert Details](../..//Getting-started//Alerts-Details). ## Connectivity initiative -This initiative is intended for relevant policy assignment to networking components in ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-connectivity management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative is intended for relevant policy assignment to networking components in ALZ. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-connectivity management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ---------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -67,7 +67,7 @@ This initiative is intended for relevant policy assignment to networking compone ## Management initiative -This initiative is intended for relevant policy assignment to management components in ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative is intended for relevant policy assignment to management components in AMBA-ALZ. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ----------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -80,7 +80,7 @@ This initiative is intended for relevant policy assignment to management compone ## Identity initiative -This initiative is intended for relevant policy assignment to identity components in ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-identity management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative is intended for relevant policy assignment to identity components in ALZ. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign policies to the alz-platform-identity management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | ------------------------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -93,7 +93,7 @@ This initiative is intended for relevant policy assignment to identity component ## Key Management initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management Services such as Azure Key Vault, and Managed HSM. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management Services such as Azure Key Vault, and Managed HSM. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -105,7 +105,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management ## Load Balancing initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing Services such as Load Balancer, Application Gateway, Traffic Manager, and Azure Front Door. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing Services such as Load Balancer, Application Gateway, Traffic Manager, and Azure Front Door. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -136,7 +136,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing ## Network Changes initiative -This initiative implements Azure Monitor Baseline Alerts to monitor alterations in Network Routing and Security, such as modifications to Route Tables and the removal of Network Security Groups. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative implements Azure Monitor Baseline Alerts to monitor alterations in Network Routing and Security, such as modifications to Route Tables and the removal of Network Security Groups. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -145,7 +145,7 @@ This initiative implements Azure Monitor Baseline Alerts to monitor alterations ## Recovery Services initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Services such as Azure Backup, and Azure Site Recovery. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Services such as Azure Backup, and Azure Site Recovery. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -153,7 +153,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Recovery Servic ## Storage initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Services such as Storage accounts. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Services such as Storage accounts. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -161,7 +161,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Service ## VM initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual Machines. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual Machines. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -179,7 +179,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual M ## Web initiative -This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services such as App Services. It is intended for relevant policy assignment to a landing zone in the ALZ structure. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services such as App Services. It is intended for relevant policy assignment to a landing zone in the ALZ structure. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -190,7 +190,7 @@ This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services su ## Hybrid VM initiative -This initiative is intended for relevant policy assignment to Hybrid VM alerts in AMBA-ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will be assigned to the 'alz' intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative is intended for relevant policy assignment to Hybrid VM alerts in AMBA-ALZ. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will be assigned to the 'alz' intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Display Name** | **Reference ID** | **Path to policy json file** | **Policy default effect** | | ---------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -209,7 +209,7 @@ This initiative is intended for relevant policy assignment to Hybrid VM alerts i ## Service Health initiative -This initiative is intended for relevant policy assignment service health alerts in ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative is intended for relevant policy assignment service health alerts in ALZ. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy json file** | **Policy default effect** | | --------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | @@ -222,7 +222,7 @@ This initiative is intended for relevant policy assignment service health alerts ## Notification Assets initiative -This initiative is intended for relevant policy assignment to notification in AMBA-ALZ. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative is intended for relevant policy assignment to notification in AMBA-ALZ. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern), this will assign to the alz intermediate root management group structure in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Display Name** | **Reference ID** | **Path to policy json file** | **Policy default effect** | | ------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -231,7 +231,7 @@ This initiative is intended for relevant policy assignment to notification in AM ## Landing Zone initiative (Deprecated) -This initiative is intended for relevant policy assignment to a landing zone in the ALZ structure. Using the guidance provided in [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. +This initiative is intended for relevant policy assignment to a landing zone in the ALZ structure. Using the guidance provided in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) this will be assigned to the Landing Zones management group in the ALZ reference architecture. For details on the initiative policies and their default enablement state, refer to the table below. | **Policy Name** | **Policy Reference ID** | **Path to policy .json file** | **Policy default effect** | | ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | @@ -283,5 +283,3 @@ This initiative is intended for relevant policy assignment to a landing zone in | Deploy App Service Plan Http Queue Length Alert | ALZ_WSFHttpQueueLength | [Deploy-WSF-HttpQueueLength-Alert.json](../../../services/Web/serverFarms/Deploy-WSF-HttpQueueLength-Alert.json) | deployIfNotExists | | Deploy Frontdoor Backend Health Percentage Alert | ALZ_FDBackendHealth | [Deploy-FD-BackendHealth-Alert.json](../../../services/Network/frontDoors/Deploy-FD-BackendHealth-Alert.json) | deployIfNotExists | | Deploy Frontdoor Backend Request Latency Alert | ALZ_FDBackendRequestLatency | [Deploy-FD-BackendRequestLatency-Alert.json](../../../services/Network/frontDoors/Deploy-FD-BackendRequestLatency-Alert.json) | deployIfNotExists | - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md index adb07418a..6664dd858 100644 --- a/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md @@ -69,6 +69,3 @@ The [conditional deployment behavior](../Bring-your-own-Managed-Identity#conditi - Run remediation as documented in [Remediate Policies](../deploy/Remediate-Policies) The code will reconfigure alerts to use either the provided UAMI or the newly created one. - -[Back to top of page](.) - diff --git a/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md index 602a647e5..1987871f0 100644 --- a/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md @@ -16,7 +16,7 @@ For brownfield customers opting to use their own notification assets, they need ![policyAssignmentParametersBYON section](../../media/BYON_Params_3.png) -Conversely, if they choose to use the assets provided by AMBA or if they are greenfield customers, they should leave the ***BYOActionGroup*** and ***BYOAlertProcessingRule*** parameters empty and populate the other parameters (***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId***, and ***ALZFunctionTriggerUrl***): +Conversely, if they choose to use the assets provided by AMBA-ALZ or if they are greenfield customers, they should leave the ***BYOActionGroup*** and ***BYOAlertProcessingRule*** parameters empty and populate the other parameters (***ALZMonitorActionGroupEmail***, ***ALZLogicappResourceId***, ***ALZLogicappCallbackUrl***, ***ALZArmRoleId***, ***ALZEventHubResourceId***, ***ALZWebhookServiceUri***, ***ALZFunctionResourceId***, and ***ALZFunctionTriggerUrl***): ![policyAssignmentParametersNotificationAssets section](../../media/NotificationAssets_Params_2.png) @@ -56,11 +56,10 @@ Example parameter file for this scenario: The [conditional deployment behavior](../Bring-your-own-Notifications#conditional-deployment-behavior) allows brownfield customers to switch from the initial notification assets scenario (available until the [2024-03-01](../../Overview/Whats-New#2024-03-01) release) to the new BYON feature and vice versa. To switch, customers need to: + - Update the parameter file to match one of the three scenarios discussed - Redeploy the ALZ pattern - Run the remediation for both [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) and [Alerting-ServiceHealth](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-ServiceHealth-Alerts.json) policy initiatives - Remove notification assets deployed by ALZ patterns using the [**Remove-AMBANotificationAssets.ps1**](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/scripts/Remove-AMBANotificationAssets.ps1) script (_*** only if moving from ALZ notification assets to BYON_) The code will reconfigure the Service Health alerts to use either the customer's action groups or the ALZ pattern notification assets based on the selected scenario. - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md b/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md index 9f10fcf9b..c2947b5ef 100644 --- a/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md +++ b/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md @@ -1,18 +1,19 @@ --- -title: Cleaning up a Deployment +title: Clean-up AMBA-ALZ Deployment geekdocCollapseSection: true weight: 70 --- -In certain situations, you may need to remove all resources deployed by the AMBA solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all deployed resources, including: +In certain situations, you may need to remove all resources deployed by the AMBA-ALZ solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all deployed resources, including: - Metric Alerts - Activity Log Alerts -- Resource Groups (created for to contain alert resources) - Policy Assignments - Policy Definitions - Policy Set Definitions - Policy Assignment remediation identity role assignments +- Action Groups +- Alert Processing Rules All resources deployed as part of the initial AMBA deployment, as well as those created dynamically by 'deploy if not exist' policies, are tagged, marked in metadata, or described (depending on resource capabilities) with the value `_deployed_by_amba` or `_deployed_by_amba=True`. This metadata is crucial for the cleanup process; if it has been removed or altered, the cleanup script will not target those resources. @@ -28,18 +29,19 @@ To download the cleanup script file, follow these steps. Alternatively, you can 1. Navigate to the [AMBA project on GitHub](https://github.com/Azure/azure-monitor-baseline-alerts). 2. Browse to the `patterns/alz/scripts` directory. -3. Open the **Start-AMBACleanup.ps1** script file. +3. Open the **Start-AMBA-ALZ-Maintenance.ps1** script file. 4. Click the **Raw** button. -5. Save the file as **Start-AMBACleanup.ps1**. +5. Save the file as **Start-AMBA-ALZ-Maintenance.ps1**. ### Executing the Script 1. Launch PowerShell. -2. Install the **Az.ResourceGraph** module by executing the following command: - ```powershell - Install-Module Az.ResourceGraph - ``` -3. Navigate to the directory containing the **Start-AMBACleanup.ps1** script. +2. Ensure the following modules are installed: + 1. **Az.Accounts**: if not installed, use the `Install-Module Az.Accounts` to install it + 2. **Az.Resources**: if not installed, use the `Install-Module Az.Resources` to install it + 3. **Az.ResourceGraph**: if not installed, use the `Install-Module Az.ResourceGraph` to install it + 4. **Az.ManagedServiceIdentity**: if not installed, use the `Install-Module Az.ManagedServiceIdentity` to install it +3. Navigate to the directory containing the **Start-ALZ-Maintenance.ps1** script. 4. Set the _**$pseudoRootManagementGroup**_ variable using the command below: ```powershell @@ -51,22 +53,26 @@ To download the cleanup script file, follow these steps. Alternatively, you can {{% include "PowerShell-ExecutionPolicy.md" %}} - **Generate a list of the resource IDs which would be deleted by this script:** + **Get full help on script usage help:** + + ```powershell + Get-help ./Start-AMBA-ALZ-Maintenance.ps1 + ``` - ```powershell - ./Start-AMBACleanup.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -ReportOnly - ``` + **Show output of what would happen if deletes executed:** - **Show output of what would happen if deletes executed:** + ```powershell + ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz -WhatIf + ``` - ```powershell - ./Start-AMBACleanup.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -WhatIf - ``` + **Execute the script asking for confirmation before deleting the resources deployed by AMBA-ALZ:** - **Delete all resources deployed by the ALZ-Monitor IaC without prompting for confirmation:** + ```powershell + ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz + ``` - ```powershell - ./Start-AMBACleanup.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -Force - ``` + **Execute the script without asking for confirmation before deleting the resources deployed by AMBA-ALZ.** -[Back to top of page](.) + ```powershell + ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz -Confirm:$false + ``` diff --git a/docs/content/patterns/alz/HowTo/Disabling-Policies.md b/docs/content/patterns/alz/HowTo/Disabling-Policies.md index 831f8baaa..06f55bc92 100644 --- a/docs/content/patterns/alz/HowTo/Disabling-Policies.md +++ b/docs/content/patterns/alz/HowTo/Disabling-Policies.md @@ -4,7 +4,7 @@ geekdocCollapseSection: true weight: 60 --- -The Azure Monitor Baseline Alerts (AMBA) policies offer various methods to enable or disable the effects of the policies. +The AMBA-ALZ pattern offers various methods to enable or disable the effects of the policies. 1. **Parameter: AlertState** - Configures the state of the alert rule, enabling deployment of alert rules in a disabled state or disabling existing alert rules at scale through policy. 2. **Parameter: PolicyEffect** - Defines the effect of a Policy Definition, allowing the policy to be deployed in a disabled state. @@ -111,6 +111,7 @@ It is also possible to exclude specific resources from monitoring. For instance, . . ``` + This deployment will implement policy definitions that will only be evaluated and remediated if the specified tag values are not present in the provided list. ### How it works @@ -138,5 +139,3 @@ Given the varying resource scopes to which this method can be applied, the appro With the introduction of the _**Bring Your Own User Assigned Managed Identity (BYO UAMI)**_ feature in the [2024-06-05](../../Overview/Whats-New#2024-06-05) release, and the capability to query Azure Resource Graph using Azure Monitor (refer to [Quickstart: Create alerts with Azure Resource Graph and Log Analytics](https://learn.microsoft.com/en-us/azure/governance/resource-graph/alerts-query-quickstart?tabs=azure-resource-graph)), it is now feasible to disable individual alerts for both Azure and hybrid virtual machines post-creation. This enhancement addresses requests to stop alerting for virtual machines that are offline for maintenance, providing a timely solution. To disable alerts for your virtual machines after they are created, ensure that you tag the relevant resources appropriately. The alert queries have been updated to reference resource properties in [Azure Resource Graph](https://learn.microsoft.com/en-us/azure/governance/resource-graph/overview). If a resource contains the specified tag name and tag value, it will be included in an exclusion list, preventing alerts from being generated for those resources. This approach allows for dynamic and rapid exclusion of necessary resources from alerts without needing to delete the alert. Simply tag the resource and run the remediation process again. - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md b/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md index fa6d306a9..3656b4189 100644 --- a/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md +++ b/docs/content/patterns/alz/HowTo/Temporarily-disabling-notifications.md @@ -50,5 +50,3 @@ To configure the APR, follow these steps: {{< hint type=Note >}} It is possible to apply other types of filter. For a complete list of allowed scopes and filters, refer to the official [Scope and filters for alert processing rules](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-processing-rules?tabs=portal#scope-and-filters-for-alert-processing-rules) documentation. {{< /hint >}} - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/Threshold-Override.md b/docs/content/patterns/alz/HowTo/Threshold-Override.md index 5494e7db5..be18cefbd 100644 --- a/docs/content/patterns/alz/HowTo/Threshold-Override.md +++ b/docs/content/patterns/alz/HowTo/Threshold-Override.md @@ -4,11 +4,11 @@ geekdocCollapseSection: true weight: 85 --- -# Overview +## Overview The ***Alert Threshold Override*** feature, introduced in the [2024-09-05 release](../../Whats-New#2024-09-05), enables both Greenfield and Brownfield customers to customize alert thresholds for specific resources during or after the deployment of AMBA-ALZ. This feature allows the use of a tag with a specific name and value to override the default alert threshold for designated resources. The new threshold value will apply exclusively to the tagged resources, replacing the global threshold specified in the parameter file. -# How this feature works +## How this feature works This feature is applicable exclusively to metrics and log-search alerts, as Activity Log-based alerts do not utilize thresholds and therefore cannot benefit from this enhancement. To use this feature, customers must create a resource tag with a specific name and assign it a desired value. After deploying this release, tags can be created either before or after the remediation task execution. However, the feature's behavior varies between Metric and Log-search alerts. @@ -28,17 +28,17 @@ Considering the nature of log-search alerts, where resource information is retri ## Which tag does customers need to create -To ensure proper functionality, this feature requires specific tag names. Flexibility in tag naming is not supported in this case. The tag names must adhere to the following naming convention: - {{< hint type=Info >}} For a comprehensive list of resource type friendly names, resource provider namespaces, and recommended abbreviations, refer to [Abbreviation recommendations for Azure resources](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations). {{< /hint >}} -```***_amba--threshold-override_***``` +To ensure proper functionality, this feature requires specific tag names. Flexibility in tag naming is not supported in this case. The tag names must adhere to the following naming convention: + +```***_amba--threshold-Override_***``` In scenarios where the same metric is used multiple times for the same resource, a differentiator value is implemented immediately after the metric name. This ensures the naming convention follows the format: -```***_amba---threshold-override_***``` +```***_amba---threshold-Override_***``` The following table provides a mapping between alert names and the corresponding tag values that need to be created: @@ -53,5 +53,3 @@ The following table provides a mapping between alert names and the corresponding ### Metric alerts table {{% include "Metrics_Alert_Table.md" %}} - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md index 39fb5cdc1..5b6979d53 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md @@ -7,11 +7,12 @@ When transitioning from the preview version to the General Availability (GA) ver - Metric Alerts - Activity Log Alerts -- Resource Groups (created for to contain alert resources) - Policy Assignments - Policy Definitions - Policy Set Definitions - Policy Assignment remediation identity role assignments +- Action Groups +- Alert Processing Rules All resources deployed by the initial ALZ Monitor deployment, as well as those created dynamically by 'deploy if not exist' policies, are tagged, marked in metadata, or described (depending on resource capabilities) with `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is crucial for the cleanup script to identify and remove the resources. If this metadata has been altered or removed, the cleanup script will not recognize those resources for deletion. @@ -60,10 +61,9 @@ Follow these steps to download the cleanup script file. Alternatively, you can c ``` ## Next steps + - For customizing policy assignments, refer to [Customize Policy Assignment](../../HowTo/deploy/Customize-Policy-Assignment). - For deployment using GitHub Actions, refer to [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions). - For deployment using Azure DevOps Pipelines, refer to [Deploy with Azure Pipelines](../../HowTo/deploy/Deploy-with-Azure-Pipelines). - For deployment using Azure CLI, refer to [Deploy with Azure CLI](../../HowTo/deploy/Deploy-with-Azure-CLI). - For deployment using Azure PowerShell, refer to [Deploy with Azure PowerShell](../../HowTo/deploy/Deploy-with-Azure-PowerShell). - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2023-11-14.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md deleted file mode 100644 index c4946dfd2..000000000 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-03-01.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Updating from release 2024-03-01 -geekdocCollapseSection: true -weight: 99 ---- -{{< hint type=Important >}} -***No post update action required*** for Greenfield or Brownfield customers that prefer to continue using notification assets deployed by the ALZ pattern code. -{{< /hint >}} - -# Post update actions - -If you are updating from release [2024-03-01](../../../Overview/Whats-New#2024-03-01), you may need to run a post-update script to remove the notification assets deployed by the ALZ pattern. This is necessary only if you have chosen to use existing action groups and alert processing rules. In such cases, the Service Health alerts will be reconfigured to use your action groups according to the ***Bring Your Own Notifications (BYON)*** feature. - -To execute the script, follow these steps: -1. Open PowerShell. -2. Install the **Az.ResourceGraph** module if it is not already installed by running: `Install-Module Az.ResourceGraph`. -3. Navigate to the directory containing the **Remove-AMBANotificationAssets.ps1** script. -4. Set the ***$pseudoRootManagementGroup*** variable using the following command: - - ```powershell - $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" - ``` - 1. Sign in to your Azure account using the `Connect-AzAccount` command. Ensure that the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. - - 2. Run the script with one of the following options: - - {{% include "PowerShell-ExecutionPolicy.md" %}} - - **Generate a list of the resource IDs which would be deleted by this script:** - - ```powershell - ./Remove-AMBANotificationAssets.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -ReportOnly - ``` - - **Show output of what would happen if deletes executed:** - - ```powershell - ./Remove-AMBANotificationAssets.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -WhatIf - ``` - - **Delete notification asset resources deployed by the ALZ pattern without prompting for confirmation:** - - ```powershell - ./Remove-AMBANotificationAssets.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -Force - ``` - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md deleted file mode 100644 index e60455231..000000000 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-04-12.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Updating from release 2024-04-12 -geekdocCollapseSection: true -weight: 98 ---- -{{< hint type=Important >}} -***The parameter file structure has changed to accommodate a new feature coming soon.*** -{{< /hint >}} - -# Pre update actions - -The parameter file structure has been updated to support an upcoming feature. Therefore, when updating from release [2024-04-12](../../../Overview/Whats-New#2024-04-12), you must align your existing parameter file structure with the new format introduced in this release. - -In particular, the new parameter file includes the following changes: - -1. Introduces new parameters for utilizing an existing User Assigned Managed Identity (UAMI) or creating a new one during the AMBA-ALZ deployment. These parameters are essential for the new hybrid virtual machine alert set. Ensure to review and configure the following parameters accurately: - - 1. ***bringYourOwnUserAssignedManagedIdentity***: Set this parameter to **Yes** if you want to use an existing User Assigned Managed Identity (UAMI). Set it to **No** if you prefer the AMBA-ALZ deployment to create a new UAMI for you. - - 2. ***bringYourOwnUserAssignedManagedIdentityResourceId***: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **Yes**, provide the resource ID of your existing UAMI. - - 1.1. Enter the UAMI resource ID, leaving the **managementSubscriptionId** blank - - ![UAMI resource ID](../../../media/alz-BYO-UAMI.png) - - 1.2. Configure it with the ***Monitoring Reader*** role on the pseudo root Management Group. - - 3. ***userAssignedManagedIdentityName***: If the **bringYourOwnUserAssignedManagedIdentity** parameter is set to **No**, you can either use the default value or specify a custom name for the UAMI that will be created during the deployment. The default name follows the ALZ standard naming convention. - - ![UAMI default name](../../../media/alz-UAMI-Default-Name.png) - - 4. ***managementSubscriptionId***: If the **bringYourOwnUserAssignedManagedIdentity** parameter is set to **No**, provide the subscription ID of the subscription within the Management management group. The deployment process will create the UAMI in this subscription and assign it the ***Monitoring Reader*** role on the pseudo root Management Group. - - ![Management subscription ID](../../../media/alz-ManagementSubscription.png) - - ![Management subscription ID parameter](../../../media/alz-UAMI-Management-SubscriptionID.png) - -2. Converts the previous parameter objects, including ***policyAssignmentParametersCommon***, ***policyAssignmentParametersBYON***, and ***policyAssignmentParametersNotificationAssets***, into standard parameters while retaining their original names. Consequently, the corresponding sections of the parameter file will now appear as shown in the following image: - - - ![New parameter file sample](../../../media/alz-New-ParamterFile-Structure.png) - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md deleted file mode 100644 index af9d73c20..000000000 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_from_release_2024-06-05.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Updating from release 2024-06-05 -geekdocCollapseSection: true -weight: 97 ---- -{{< hint type=Important >}} -***Updating to release [2024-06-05](../../../Overview/Whats-New#2024-06-05) or from previous releases involves a breaking change. To proceed with the update, you must remove previously deployed policy definitions, policy set definitions, policy assignments, and role assignments. A script is provided to facilitate the removal of these items. ***It is highly recommended to thoroughly test the script in a non-production environment before executing it in production. Alert definitions do not need to be removed as they will continue to function.****** -{{< /hint >}} - -# Pre update actions - -Before updating to release [2024-06-30](../../../Overview/Whats-New#2024-06-30), it is necessary to remove existing policy definitions, policy set definitions, policy assignments, and role assignments. This requirement is due to a breaking change introduced by the redefinition of certain parameters, which now provide greater flexibility in disabling policy remediation or, in some cases, alerts. Note that not all alerts can be disabled post-creation; only log-based alerts can be. While disabling the effect of policies was previously possible in AMBA-ALZ, this release ensures that all policies will respect both the ***PolicyEffect*** and ***MonitorDisable*** parameters. - -The *MonitorDisable* feature has been redesigned to allow customers to specify their own existing tag and tag value instead of using a hard-coded one. Following the ALZ guidance and best practices for consistent tagging definitions, only one parameter name is allowed for the entire deployment. However, the parameter value can vary. You can specify an array of values assigned to the same parameter. For example, if you have the `Environment` tag name consistently applied to several environments such as `Production`, `Test`, `Sandbox`, etc., and you want to disable alerts for resources in both `Test` and `Sandbox`, you can now do so by configuring the parameters for the tag name and tag values as shown in the sample screenshot below (these are the default values): - -![MonitorDisable* parameters](../../../media/MonitorDisableParams.png) - -For a detailed description of the new or redesigned feature, refer to the [MonitorDisable parameter](../../Disabling-Policies#monitordisable-parameter) section on the [Disabling Policies](../../Disabling-Policies) page. - -After removing the policy definitions, policy set definitions, policy assignments, and role assignments, and completing the deployment, execute the [Policy remediation](../../deploy/Remediate-Policies) to ensure the new alerts are created as expected. - -To execute the script, follow these steps: -1. Open PowerShell. -2. Install the **Az.ResourceGraph** module if it is not already installed by running: `Install-Module Az.ResourceGraph`. -3. Navigate to the `patterns\alz\scripts` directory where the **Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1** script is located. -4. Set the ***$pseudoRootManagementGroup*** variable with the following command: - - ```powershell - $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" - ``` - 1. Sign in to Azure using the `Connect-AzAccount` command. Ensure the account has the necessary permissions to remove policy definitions, policy set definitions, policy assignments, and role assignments at the required Management Group scope. - - 2. Run the script with one of the following options: - - {{% include "PowerShell-ExecutionPolicy.md" %}} - - **Generate a list of policy definitions, policy set definitions, policy assignments and role assignments resources which would be deleted by this script:** - - ```powershell - ./Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -ReportOnly - ``` - - **Delete policy definitions, policy set definitions, policy assignments and role assignments resources deployed by the AMBA-ALZ pattern without prompting for confirmation:** - - ```powershell - ./Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -Force - ``` - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-03-01.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-03-01.md index 36d7e7038..4cb072f0a 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-03-01.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-03-01.md @@ -10,25 +10,32 @@ Complete the activities documented in the [Steps to update to the latest release ## Post update actions -Updating to release [2024-03-01](../../Whats-New#2024-03-01) will require running a post update script to remove the old Service Health action group(s) no longer in use. +Updating to release [2024-03-01](../../../Whats-New#2024-03-01) will require running a post update script to remove the old Service Health action group(s) no longer in use. To execute the script, follow these steps: -1. Open PowerShell. -2. Install the **Az.ResourceGraph** module if it is not already installed by running: `Install-Module Az.ResourceGraph`. -3. Navigate to the directory containing the **Remove-AMBANotificationAssets.ps1** script. -4. Set the ***$pseudoRootManagementGroup*** variable using the following command: +1. Launch PowerShell. +2. Install the **Az.ResourceGraph** module by executing the following command: ```powershell - $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" + Install-Module Az.ResourceGraph + ``` + +3. Navigate to the directory containing the **Start-AMBAOldArpCleanup.ps1** script. + +4. Set the _**$pseudoRootManagementGroup**_ variable with the following command: + + ```powershell + $pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" ``` 5. Sign in to your Azure account using the `Connect-AzAccount` command. Ensure that the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. + 6. Run the script with one of the following options: {{% include "PowerShell-ExecutionPolicy.md" %}} -**Get full help on script usage help:** + **Get full help on script usage help:** ```powershell Get-help ./Start-AMBA-ALZ-Maintenance.ps1 diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-04-12.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-04-12.md index c8f8091a6..0827d0f37 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-04-12.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-04-12.md @@ -14,26 +14,26 @@ Complete the activities documented in the [Steps to update to the latest release ## Post update actions -Updating to release [2024-04-12](../../Whats-New#2024-04-12) might require running a post update script to remove the notification assets deployed by ALZ pattern **_if and only if_** customer decided to use existing action groups and alert processing rule. In this case, the Service Health alerts will be reconfigured to use the customer' action groups as per the _**B**ring **Y**our **O**wn **N**otifications_ (BYON) feature. +If you are updating to release [2024-04-12](../../../Overview/Whats-New#2024-04-12), you may need to run a post-update script to remove the notification assets deployed by the ALZ pattern. This is necessary only if you have chosen to use existing action groups and alert processing rules. In such cases, the Service Health alerts will be reconfigured to use your action groups according to the ***Bring Your Own Notifications (BYON)*** feature. -To run the script, complete the following step: +To execute the script, follow these steps: -1. Open PowerShell -2. Install the **Az.ResourceGraph** module: `Install-Module Az.ResourceGraph` (if not present) -3. Change directories to the location of the **Remove-AMBANotificationAssets.ps1** script -4. Configure the **_$pseudoRootManagementGroup_** variable using the command below: +1. Open PowerShell. +2. Install the **Az.ResourceGraph** module if it is not already installed by running: `Install-Module Az.ResourceGraph`. +3. Navigate to the directory containing the **Remove-AMBANotificationAssets.ps1** script. +4. Set the ***$pseudoRootManagementGroup*** variable using the following command: - ```powershell - $pseudoRootManagementGroup = "The pseudo root management group id parenting the Platform and Landing Zones management groups" - ``` + ```powershell + $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" + ``` -5. Sign in to the Azure with the `Connect-AzAccount` command. The account you sign in as needs to have permissions to remove Policy Assignments, Policy Definitions, and resources at the desired Management Group scope. +5. Sign in to your Azure account using the `Connect-AzAccount` command. Ensure that the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. -6. Execute the script using one of the options below: +6. Run the script with one of the following options: - {{% include "PowerShell-ExecutionPolicy.md" %}} + {{% include "PowerShell-ExecutionPolicy.md" %}} - **Show output of what would happen if deletes executed:** + **Show output of what would happen if deletes executed:** ```powershell ./Remove-AMBANotificationAssets.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -WhatIf diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-06-05.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-06-05.md index 85018666d..ca0852af8 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-06-05.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-06-05.md @@ -5,40 +5,39 @@ weight: 98 --- {{< hint type=Important >}} -**_The parameter file structure has changed to accommodate a new feature coming soon._** +***The parameter file structure has changed to accommodate a new feature coming soon.*** {{< /hint >}} -## Pre update actions +# Pre update actions -The parameter file structure has changed to accommodate a new feature coming soon. For this reason, updating from release [2024-06-05](../../Whats-New#2024-06-05) requires the alignment of the parameter file structure you have been using so far with the new one coming with the release. +The parameter file structure has been updated to support an upcoming feature. Therefore, when updating from release [2024-06-05](../../../Overview/Whats-New#2024-06-05), you must align your existing parameter file structure with the new format introduced in this release. +In particular, the new parameter file includes the following changes: -In particular the new parameter file has the following differences: +1. Introduces new parameters for utilizing an existing User Assigned Managed Identity (UAMI) or creating a new one during the AMBA-ALZ deployment. These parameters are essential for the new hybrid virtual machine alert set. Ensure to review and configure the following parameters accurately: -1. Contains new parameters for using an existing User Assigned Managed Identity or creating a new one during the AMBA-ALZ deployment. It's required by the new hybrid virtual machine alert set. Make sure to review and set the following parameters correctly: + 1. ***bringYourOwnUserAssignedManagedIdentity***: Set this parameter to **Yes** if you want to use an existing User Assigned Managed Identity (UAMI). Set it to **No** if you prefer the AMBA-ALZ deployment to create a new UAMI for you. - 1. **_bringYourOwnUserAssignedManagedIdentity_**: set it to **Yes** if you would like to use your own User Assigned Managed Identity (UAMI) or to **No** if you don't have one and would like the deployment of AMBA-ALZ to create one. - - 2. **_bringYourOwnUserAssignedManagedIdentityResourceId_**: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **Yes**: + 2. ***bringYourOwnUserAssignedManagedIdentityResourceId***: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **Yes**, provide the resource ID of your existing UAMI. 1.1. Enter the UAMI resource ID, leaving the **managementSubscriptionId** blank - ![UAMI resource ID](../../media/alz-BYO-UAMI.png) + ![UAMI resource ID](../../../media/alz-BYO-UAMI.png) - 1.2. Configure it with the **_Monitoring Reader_** role on the pseudo root Management Group. + 1.2. Configure it with the ***Monitoring Reader*** role on the pseudo root Management Group. - 3. **_userAssignedManagedIdentityName_**: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **No**, leave the default value or set a different one to specify a different name for the UAMI created during the deployment. The provided default name aligns with the ALZ standard naming convention. + 3. ***userAssignedManagedIdentityName***: If the **bringYourOwnUserAssignedManagedIdentity** parameter is set to **No**, you can either use the default value or specify a custom name for the UAMI that will be created during the deployment. The default name follows the ALZ standard naming convention. - ![UAMI default name](../../media/alz-UAMI-Default-Name.png) + ![UAMI default name](../../../media/alz-UAMI-Default-Name.png) - 4. **_managementSubscriptionId_**: If you set the **bringYourOwnUserAssignedManagedIdentity** parameter to **No**, enter the subscription ID of the subscription under the Management management group. The deployment procedure will create the UAMI in this subscription and assign it the **_Monitoring Reader_** role on the pseudo root Management Group + 4. ***managementSubscriptionId***: If the **bringYourOwnUserAssignedManagedIdentity** parameter is set to **No**, provide the subscription ID of the subscription within the Management management group. The deployment process will create the UAMI in this subscription and assign it the ***Monitoring Reader*** role on the pseudo root Management Group. - ![Management subscription ID](../../media/alz-ManagementSubscription.png) + ![Management subscription ID](../../../media/alz-ManagementSubscription.png) - ![](../../media/alz-UAMI-Management-SubscriptionID.png) + ![Management subscription ID parameter](../../../media/alz-UAMI-Management-SubscriptionID.png) -2. Changes the previous parameter objects, such as **_policyAssignmentParametersCommon_**, **_policyAssignmentParametersBYON_** and **_policyAssignmentParametersNotificationAssets_** into classic parameters using the same name as before. As result, the previous sections of the parameter you'll now look like the following image: +2. Converts the previous parameter objects, including ***policyAssignmentParametersCommon***, ***policyAssignmentParametersBYON***, and ***policyAssignmentParametersNotificationAssets***, into standard parameters while retaining their original names. Consequently, the corresponding sections of the parameter file will now appear as shown in the following image: - ![New parameter file sample](../../media/alz-New-ParamterFile-Structure.png) + ![New parameter file sample](../../../media/alz-New-ParamterFile-Structure.png) ## Update diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-09-02.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-09-02.md index 2c5837293..905a2bbb2 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-09-02.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-09-02.md @@ -5,40 +5,39 @@ weight: 97 --- {{< hint type=Important >}} -**_Updating to release [2024-09-02](../../Whats-New#2024-09-02) from previous releases, contains a breaking change. To perform the update, it's required to remove previously deployed policy definitions, policy set definitions, policy assignments and role assignments. It isn't necessary to remove alert definitions that will continue to work in the meantime._** +***Updating to release [2024-09-02](../../../Overview/Whats-New#2024-09-02) from previous releases involves a breaking change. To proceed with the update, you must remove previously deployed policy definitions, policy set definitions, policy assignments, and role assignments. A script is provided to facilitate the removal of these items. ***It is highly recommended to thoroughly test the script in a non-production environment before executing it in production. Alert definitions do not need to be removed as they will continue to function.****** {{< /hint >}} ## Pre update actions -Before updating to release [2024-09-02](../../Whats-New#2024-09-02), it's required to remove existing policy definitions, policy set definitions, policy assignments and role assignments. This action is required because of a breaking change caused by the redefinition of some parameters, which allows for more flexibility in disabling the policy remediation or, in some cases, the alerts. Unfortunately not all the alerts can be disabled after creation; only log-based alerts can be. Even if disabling the effect of policy was already possible in AMBA-ALZ, with this release we made sure that all the policies will honor both the **_PolicyEffect_** and the **_MonitorDisable_** parameters. +Before updating to release [2024-09-02](../../../Overview/Whats-New#2024-09-02), it is necessary to remove existing policy definitions, policy set definitions, policy assignments, and role assignments. This requirement is due to a breaking change introduced by the redefinition of certain parameters, which now provide greater flexibility in disabling policy remediation or, in some cases, alerts. Note that not all alerts can be disabled post-creation; only log-based alerts can be. While disabling the effect of policies was previously possible in AMBA-ALZ, this release ensures that all policies will respect both the ***PolicyEffect*** and ***MonitorDisable*** parameters. -In particular, the _MonitorDisable_ feature has been redesigned to allow customer to specify they own existing tag and tag value instead of forcing a hard coded one. Given the ALZ guidance and the best practice of having a consistent tagging definition, it's only allowed to one parameter name fo r the entire deployment. Instead, parameter value can be different. You can specify an array of values assigned to the same parameter. For instance, you have the `Environment` tag name consistently applied to several environments, saying `Production`, `Test`, `Sandbox`, and so on, and you want to disable alerts for resources, which are in both `Test` and `Sandbox`. Now it's possible by just configuring the parameters for tag name and tag values as reported in the sample screenshot (these are the default values) below: +The *MonitorDisable* feature has been redesigned to allow customers to specify their own existing tag and tag value instead of using a hard-coded one. Following the ALZ guidance and best practices for consistent tagging definitions, only one parameter name is allowed for the entire deployment. However, the parameter value can vary. You can specify an array of values assigned to the same parameter. For example, if you have the `Environment` tag name consistently applied to several environments such as `Production`, `Test`, `Sandbox`, etc., and you want to disable alerts for resources in both `Test` and `Sandbox`, you can now do so by configuring the parameters for the tag name and tag values as shown in the sample screenshot below (these are the default values): -![MonitorDisable* parameters](../../media/MonitorDisableParams.png) +![MonitorDisable* parameters](../../../media/MonitorDisableParams.png) -Complete description of this new/redesigned feature can be found in the [MonitorDisable parameter](../../Disabling-Policies#monitordisable-parameter) paragraph inside the [Disabling Policies](../../Disabling-Policies) page. +For a detailed description of the new or redesigned feature, refer to the [MonitorDisable parameter](../../Disabling-Policies#monitordisable-parameter) section on the [Disabling Policies](../../Disabling-Policies) page. -Once the policy definitions, policy set definitions, policy assignments and role assignments are removed and the deployment is completed, the execution of [Policy remediation](../../deploy/Remediate-Policies) will ensure that the new alerts will be created accordingly. +After removing the policy definitions, policy set definitions, policy assignments, and role assignments, and completing the deployment, execute the [Policy remediation](../../deploy/Remediate-Policies) to ensure the new alerts are created as expected. -To run the script, complete the following steps: +To execute the script, follow these steps: -1. Open PowerShell -2. Make sure the following modules are installed: - 1. **Az.Accounts**: if not installed, use the `Install-Module Az.Accounts` to install it - 2. **Az.Resources**: if not installed, use the `Install-Module Az.Resources` to install it -3. Change directory to the location of the **Start-AMBA-ALZ-Maintenance.ps1** script -4. Configure the **_$pseudoRootManagementGroup_** variable using the following command: +1. Open PowerShell. +2. Install the **Az.ResourceGraph** module if it is not already installed by running: `Install-Module Az.ResourceGraph`. +3. Navigate to the `patterns\alz\scripts` directory where the **Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1** script is located. +4. Set the ***$pseudoRootManagementGroup*** variable with the following command: - ```powershell - $pseudoRootManagementGroup = "The pseudo root management group id parenting the Platform and Landing Zones management groups" - ``` + ```powershell + $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" + ``` + +5. Sign in to Azure using the `Connect-AzAccount` command. Ensure the account has the necessary permissions to remove policy definitions, policy set definitions, policy assignments, and role assignments at the required Management Group scope. -5. Sign in to Azure with the `Connect-AzAccount` command. The account you sign in with needs to have permissions to all the aforementioned resources (Policy Assignments, Policy Definitions, and other resources) at the desired Management Group scope. -6. Execute the script using one of the following options: +6. Run the script with one of the following options: - {{% include "PowerShell-ExecutionPolicy.md" %}} + {{% include "PowerShell-ExecutionPolicy.md" %}} - **Get full help on script usage help:** + **Get full help on script usage help:** ```powershell Get-help ./Start-AMBA-ALZ-Maintenance.ps1 diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-11-01.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-11-01.md new file mode 100644 index 000000000..be8af3a68 --- /dev/null +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Update_to_release_2024-11-01.md @@ -0,0 +1,13 @@ +--- +title: Updating to release 2024-11-01 +geekdocCollapseSection: true +weight: 96 +--- + +{{< hint type=Info >}} +**_No pre-update or post-update actions_** are required. +{{< /hint >}} + +## Update + +Complete the activities documented in the [Steps to update to the latest release](.._index#steps-to-update-to-the-latest-release) page. diff --git a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md index 86d47551d..cf8c46da7 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md +++ b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md @@ -3,40 +3,26 @@ title: Customize Policy Assignment geekdocCollapseSection: true weight: 20 --- -## In this page - -> [Introduction](../Customize-Policy-Assignment#introduction)
-> [Modify initiative assignment](../Customize-Policy-Assignment#modify-initiative-assignment)
-> [- Parameter file](../Customize-Policy-Assignment#parameter-file)
-> [- Applying changes to the parameter file](../Customize-Policy-Assignment#applying-changes-to-the-parameter-file)
-> [- Metric alert policy parameters](../Customize-Policy-Assignment#metric-alert-policy-parameters)
-> [- Activity log, Service health alert and action group policy parameters](../Customize-Policy-Assignment#activity-log-service-health-alert-and-action-group-policy-parameters)
-> [- Disabling Policies](../Customize-Policy-Assignment#disabling-policies)
-> [Next steps](../Customize-Policy-Assignment#next-steps) ## Introduction -The policies and initiatives in this repository can be deployed using their default configurations, as described in [Introduction to deploying the ALZ pattern](../Introduction-to-deploying-the-ALZ-Pattern). These default settings are intended for general use. However, there may be scenarios where you need to adjust the initiative assignment for specific policies to meet your monitoring requirements or to implement alerts gradually in an existing environment. This document outlines various scenarios and provides guidance on how to modify these assignments. - -[Back to top of page](.) +The policies and initiatives in this repository can be deployed using their default configurations, as described in [Introduction to deploying the AMBA-ALZ pattern](../Introduction-to-deploying-the-ALZ-Pattern). These default settings are intended for general use. However, there may be scenarios where you need to adjust the initiative assignment for specific policies to meet your monitoring requirements or to implement alerts gradually in an existing environment. This document outlines various scenarios and provides guidance on how to modify these assignments. ## Modify initiative assignment When assigning initiatives, you may need to adjust alert thresholds for one or more metric alerts. This can be achieved by specifying the relevant parameters in a parameter file. For your convenience, we provide a comprehensive parameter file that includes all configurable parameters for each initiative. It is recommended to use this file as a template to create your own parameter file, as the parameters may change over time, potentially affecting your alert configurations. -[Back to top of page](.) - ### Parameter file -- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-08-30/patterns/alz/alzArm.param.json) +We provide you with 2 versions of the parameter file: -[Back to top of page](.) +1. [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-11-01/patterns/alz/alzArm.param.json) aligned to the latest release +2. [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/alzArm.param.json) aligned to the main branch ### Applying changes to the parameter file To adjust the threshold values for Virtual Network Gateway Express Route CPU utilization from the default value of 80 to 90, and for Virtual Network Gateway Egress traffic from 1 to 1000, you need to include these changes in a parameter file as demonstrated below. These specific thresholds will be applied to the individual policy assignment, while all other policy values will remain at their default settings. Note that the parameter file shown below is truncated for brevity compared to the full samples provided. - {{< hint type=Note >}} The parameter file includes the default values as documented. However, the _Policy assignment parameter reference type_ will change for all parameters when using the template parameter file. Even if a parameter's value remains unmodified, it will be marked as a _User defined parameter_ after deployment because it is explicitly defined in the parameter file. To prevent this, you can create custom parameter files that only include the parameters you wish to modify. {{< /hint >}} @@ -78,8 +64,6 @@ The parameter file includes the default values as documented. However, the _Poli } ``` -[Back to top of page](.) - ### Metric alert policy parameters The following parameters can be modified for metric alert policies. In the initiatives, these parameters are prefixed with a specific string to denote the relevant metric. @@ -94,8 +78,6 @@ The following parameters can be modified for metric alert policies. In the initi | threshold | Indicates a numerical threshold for when the alert would trigger. Not relevant to all alerts as some are configured with dynamic rather than fixed thresholds | | enabled | Whether the alert is enabled or not | -[Back to top of page](.) - ### Activity log, Service health alert and action group policy parameters The following parameters can be changed for activity log, service health alert and action group policies. @@ -106,22 +88,16 @@ The following parameters can be changed for activity log, service health alert a | ALZMonitorResourceGroupTags | Any tags than need to be added to the resource group created | | ALZMonitorResourceGroupLocation | The location of the resource group for the alerts | - The parameters mentioned above specify the resource group where activity log alerts will be placed. If the resource group does not exist, it will be created. The `tags` parameter can accept multiple tags if needed, but tags are only applied at the resource group level. By default, the `tags` parameter is set to a single tag with the name *environment* and the value *test*. You can add more tags as required or leave it empty. -[Back to top of page](.) - ### Disabling Policies To review the options for disabling policies, visit [Disabling Policies](../../Disabling-Policies) -[Back to top of page](.) - ## Next steps +- To deploy using Azure Portal UI, visit [Deploy via the Azure Portal (Preview)](../Deploy-via-Azure-Portal-UI) - To deploy with GitHub Actions, visit [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) - To deploy with Azure DevOps Pipelines, visit [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - To deploy with Azure CLI, visit [Deploy with Azure CLI](../Deploy-with-Azure-CLI) - To deploy with Azure PowerShell, visit [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md index d2c25aba0..8035c1d81 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md @@ -66,6 +66,7 @@ The following changes apply to all scenarios, whether you are aligned or unalign "action2@contoso.com" ] }, + "ALZArmRoleId": { "value": [ "8e3af657-a8ff-443c-a75c-2fe8c4bcb635", @@ -246,7 +247,7 @@ Above-mentioned ```pseudoRootManagementGroup``` variable value, being the so cal The ```location``` variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} -### 4. Deploying AMBA +### 4. Deploying AMBA-ALZ Using your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), if you closed your previous session, navigate again to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and Policy Set Definitions. @@ -335,6 +336,7 @@ The ```location``` variable refers to the deployment location. Deploying to mult {{< /hint >}} ### 5. Deploy Policy Definitions + To deploy policy definitions to the intermediate management group, run the following command: ```bash @@ -350,6 +352,7 @@ az deployment mg create --name "amba-ServiveHealthOnly" --template-file ./patter ``` ### 6. Assign the Service Health Policy Set Definition + Assign a Policy Set Definition by running the following command: ```bash @@ -365,5 +368,3 @@ The JSON object contains two parameters: ```topLevelManagementGroupPrefix``` and ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md index a547ee329..bead24ed9 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md @@ -3,24 +3,15 @@ title: Deploy via the Azure Portal (Preview) weight: 30 --- -<<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md -
- -======= ->>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://aka.ms/amba/alz/portal)
## Deployment Settings Blade -<<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md ![Deployment Settings Blade](../../../media/PortalAccelerator/DeploymentSettings.png)
-======= -![Deployment Settings Blade](../../media/PortalAccelerator/DeploymentSettings.png) ->>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md - Change the values on the Deployment Settings blade to the following instructions: - Choose the Management Group where you wish to deploy the policies and the initiatives, usually called the "pseudo root management group". For example, in [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this would be the "Intermediate Root Management Group" (directly beneath the "Tenant Root Group"). @@ -42,19 +33,11 @@ weight: 30 ### If you are aligned to ALZ -<<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md - Choose the value of _```Enterprise Scale Company Management Group```_ to the management group ID for Platform. - Choose the value of _```Identity Management Group```_ to the management group ID for Identity. - Choose the value of _```Management Management Group```_ to the management group ID for Management. - Choose the value of _```Connectivity Management Group```_ to the management group ID for Connectivity. - Choose the value of _```Landing Zone Management Group```_ to the management group ID for Landing Zones. -======= -- Choose the value of _`Enterprise Scale Company Management Group`_ to the management group ID for Platform. -- Choose the value of _`Identity Management Group`_ to the management group ID for Identity. -- Choose the value of _`Management Management Group`_ to the management groupID for Management. -- Choose the value of _`Connectivity Management Group`_ to the management group ID for Connectivity. -- Choose the value of _`Landing Zone Management Group`_ to the management group ID for Landing Zones. ->>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md ### If you are unaligned to ALZ @@ -80,10 +63,8 @@ For ease of deployment and maintenance we have kept the same variables. For ease of deployment and maintenance we have kept the same variables. {{< /hint >}} -<<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md -- Set the value of _`Enable AMBA notification assets`_ to _`Yes`_. This configuration will deploy notification assets for Service Health alerts and broad notifications. -- Set the value of _`Enable AMBA Service Health`_ to _`Yes`_. This setting will assign the Service Health Policy Set Definition during deployment. -======= +- Set the value of _`Enable AMBA notification assets`_ to _`Yes`_. This configuration will deploy notification assets broad notifications. +- Set the value of _`Enable AMBA Service Health`_ to _`Yes`_. This setting will assign the Service Health Policy Set Definition during deployment and deploy action groups for Service Health alerts notifications. - Change the value of _`Enable AMBA Hybrid VM`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Arc-enabled Servers. - Change the value of _`Enable AMBA Key Management`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Key Management Services such as Azure Key Vault, and Managed HSM. - Change the value of _`Enable AMBA Load Balancing`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Load Balancing Services such as Load Balancer, Application Gateway, Traffic Manager, and Azure Front Door. @@ -92,9 +73,6 @@ For ease of deployment and maintenance we have kept the same variables. - Change the value of _`Enable AMBA Storage`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Storage Services such as Storage accounts. - Change the value of _`Enable AMBA VM`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Azure Virtual Machines. - Change the value of _`Enable AMBA Web`_ to _`Yes`_ This initiative deploys Azure Monitor Baseline Alerts to monitor Web Services such as App Services. -- Set the value of _`Enable AMBA notification assets`_ to _`Yes`_. This configuration will deploy notification assets for Service Health alerts and broad notifications. -- Set the value of _`Enable AMBA Service Health`_ to _`Yes`_. This configuration will assign the Service Health Policy Set Definition during deployment. ->>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md ## Notification Settings Blade @@ -121,28 +99,20 @@ While it's technically possible to not add any notification information (email, ![Get function URL](../../../media/AMBA-FunctionAppTriggerUrl.png) -<<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/Deploy-via-Azure-Portal-UI.md {{< hint type=note >}} It is possible use multiple email addresses, Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). - Should you set multiple entries, ensure that they are entered as a single string with values separated by comma. Example: + Should you set multiple entries, ensure that they are entered in the proper format which is: + - Array format for: + - Email addresses. Example: ["action1@contoso.com" , "action2@contoso.com" , "action3@contoso.com"] + - Azure roles. Example: ["8e3af657-a8ff-443c-a75c-2fe8c4bcb635", "b24988ac-6180-42a0-ab88-20f7382dd24c"] + - Event Hubs. Example: [] + - Webhooks. Example: ["https://br1.br2.com","http://br2.br1.com"] + - Single stringfor: + - Logic Apps + - Functions - - action1@contoso.com , action2@contoso.com , action3@contoso.com - - https://webhookUri1.webhook.com, http://webhookUri2.webhook.com {{< /hint >}} -======= - {{< hint type=note >}} - It is possible use multiple email addresses, Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). Should you set multiple entries, ensure that they are entered as an array. Example: - - `["action1@contoso.com","action2@contoso.com","action3@contoso.com"]` - - `["https://webhookUri1.webhook.com","http://webhookUri2.webhook.com"]` - - {{< /hint >}} - ->>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/Deploy-via-Azure-Portal-UI.md ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md index 6024ecbf9..3445eca92 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md @@ -26,7 +26,7 @@ The `pseudoRootManagementGroup` variable should _match_ the value of the `enterp The `location` variable specifies the deployment region. It is not required to deploy to multiple regions as the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} -## 4. Deploying AMBA +## 4. Deploying AMBA-ALZ The following commands are applicable to all scenarios, whether you are aligned with ALZ, unaligned, or managing a single management group. @@ -45,11 +45,9 @@ If you have customized the policies as described in [How to modify individual po {{< /hint >}} ```bash -az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/2024-09-02/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" +az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/2024-11-01/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" ``` ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md index e907a4e52..789ed226f 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md @@ -18,6 +18,7 @@ If you have customized the policies as described in [How to modify individual po ``` {{< /hint >}} + Additionally, in your Azure DevOps project, set up a service connection to your Azure subscription by following the instructions in the [Connect to Azure by using an Azure Resource Manager service connection](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&tabs=yaml) guide. Ensure that the service connection targets the intermediate root management group for ALZ-aligned deployments or the specific management group where you intend to deploy the policies and initiatives for ALZ-unaligned deployments. ### Modify variables and run the pipeline @@ -37,5 +38,3 @@ The `Location` variable specifies the deployment region. It is not required to d ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md index 2bbeb8119..cbaeee0eb 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md @@ -53,11 +53,9 @@ If you have customized the policies as described in [How to modify individual po {{< /hint >}} ```powershell -New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location -TemplateUri "https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/2024-09-02/patterns/alz/alzArm.json" -TemplateParameterFile ".\patterns\alz\alzArm.param.json" +New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location -TemplateUri "https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/2024-11-01/patterns/alz/alzArm.json" -TemplateParameterFile ".\patterns\alz\alzArm.param.json" ``` ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md index 9daabb72d..fa850da99 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md @@ -29,7 +29,7 @@ If you have customized the policies as described in [How to modify individual po - Save the customized [amba-sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml) in the _**.github/workflow**_ folder {{< hint type=important >}} - The file name _**must** perfectly match the name at line **1** of the sample file. You may eventually replace spaces with **-** + The file name _**must** perfectly_ match the name at line **1** of the sample file. You may eventually replace spaces with **-** {{< /hint >}} ![Workflow file name](../../../media/WorkflowFileName.png) @@ -51,5 +51,3 @@ The `Location` variable specifies the deployment region. It is not required to d ## Next steps To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md b/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md index fb5db36c9..1ce867a1e 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md +++ b/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md @@ -1,5 +1,5 @@ --- -title: Introduction to deploying the ALZ Pattern +title: Introduction to deploying the AMBA-ALZ Pattern weight: 10 --- @@ -27,8 +27,8 @@ Alerts, action groups, and alert processing rules are created as follows: 4. A Deployment Identity with `Owner` permissions to the pseudo root management group. This permission is necessary for the Service Principal Account to create role-based access control assignments. 5. If deploying manually via Azure CLI or PowerShell, ensure [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview?tabs=bicep) is installed and configured. Refer to the configuration guides for [Azure CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-cli) and [PowerShell](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-powershell). 6. The following Azure resource providers must be registered on all subscriptions in scope for the policies to function correctly: - - Microsoft.AlertsManagement - - Microsoft.Insights + - Microsoft.AlertsManagement + - Microsoft.Insights For instructions on registering a resource provider, refer to the [resource provider registration guide](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider). @@ -43,6 +43,8 @@ While it is recommended to implement the alert policies and initiatives within a - Fork this repository to your own GitHub organization. Do not create a direct clone of the repository, as pull requests from direct clones will not be accepted. - Clone the repository from your GitHub organization to your local development environment. - Review your current configuration to identify the applicable scenario. We provide guidance for deploying these policies and initiatives whether you are aligned with Azure Landing Zones, use a different management group hierarchy, or do not use management groups at all. If you already know your management group hierarchy type, proceed to your preferred deployment method: + + - [Deploy via the Azure Portal (Preview)](../Deploy-via-Azure-Portal-UI) (recommended method) - [Automated deployment with GitHub Actions](../Deploy-with-GitHub-Actions) (recommended method) - [Automated deployment with Azure Pipelines](../Deploy-with-Azure-Pipelines) (recommended method) - [Manual deployment with Azure CLI](../Deploy-with-Azure-CLI) @@ -74,6 +76,7 @@ The other monitoring initiatives are assigned to specific platform landing zone If your management group hierarchy matches this structure, you can proceed directly to your preferred deployment method: +- [Deploy via the Azure Portal (Preview)](../Deploy-via-Azure-Portal-UI) - [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) - [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - [Deploy with Azure CLI](../Deploy-with-Azure-CLI) @@ -100,13 +103,13 @@ In scenarios where Identity, Management, and Connectivity are combined into a si The following image illustrates an example of how the assignments might appear when the management group hierarchy does not align with Azure Landing Zones (ALZ). - ![Management group structure - unaligned](../../../media/alz-management-groups-unaligned.png) We suggest reviewing the [initiative definitions](https://github.com/Azure/azure-monitor-baseline-alerts/tree/main/patterns/alz/policySetDefinitions) to identify the optimal placement of initiatives within your management group hierarchy. If your management group hierarchy matches this structure, you can proceed directly to your preferred deployment method: +- [Deploy via the Azure Portal (Preview)](../Deploy-via-Azure-Portal-UI) - [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) - [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - [Deploy with Azure CLI](../Deploy-with-Azure-CLI) @@ -118,6 +121,7 @@ For detailed instructions on creating management groups, refer to the [official If you have adopted the recommended management group design, you can proceed directly to your preferred deployment method, adhering to the ALZ-aligned guidance. +- [Deploy via the Azure Portal (Preview)](../Deploy-via-Azure-Portal-UI) - [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) - [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) - [Deploy with Azure CLI](../Deploy-with-Azure-CLI) @@ -137,7 +141,7 @@ The following image illustrates an example of how the assignments appear when ut For instructions on customizing policy and initiative assignments, please refer to [Customize Policy Assignment](../Customize-Policy-Assignment). -## Customizing the AMBA policies +## Customizing the AMBA-ALZ policies We encourage customers and partners to tailor the policies to meet their specific needs and requirements. Customize the policies in your local copies to align with your design preferences. @@ -187,15 +191,15 @@ If you think the changes you have made should be customizable via parameters in If you have suggestions or feature requests, consider submitting a pull request. We will review and collaborate with you to potentially implement the proposed changes. {{< /hint >}} -## Cleaning up an AMBA Deployment -In certain situations, you may need to remove all resources deployed by the ALZ Monitor solution. For detailed instructions on how to clean up an ALZ Monitor deployment, refer to the [Cleaning up an AMBA Deployment](../../Cleaning-up-a-Deployment) guide. +## Cleaning up an AMBA-ALZ Deployment + +In certain situations, you may need to remove all resources deployed by the AMBA-ALZ solution. For detailed instructions on how to clean up an AMBA-ALZ deployment, refer to the [Cleaning up an AMBA-ALZ Deployment](../../Cleaning-up-a-Deployment) guide. ## Next steps - For instructions on customizing policy assignments, refer to [Customize Policy Assignment](../Customize-Policy-Assignment). +- For deploying using Azure Portal UI, refer to [Deploy via the Azure Portal (Preview)](../Deploy-via-Azure-Portal-UI). - For deploying with GitHub Actions, refer to [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions). - For deploying with Azure Pipelines, refer to [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines). - For deploying with Azure CLI, refer to [Deploy with Azure CLI](../Deploy-with-Azure-CLI). - For deploying with Azure PowerShell, refer to [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell). - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md index 34ab1fe1b..b8ceb1c9f 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md +++ b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md @@ -5,7 +5,7 @@ weight: 80 The policies are configured as deploy-if-not-exists by default. This means that any new deployments will be affected by these policies. In a greenfield scenario, where you are deploying new resources, including subscriptions, the policies will automatically create the relevant alert rules, action groups, and alert processing rules. -In a brownfield scenario, the policies will report non-compliance for existing resources within their scope. To remediate these non-compliant resources, you need to initiate remediation. This can be done through the Azure portal on a policy-by-policy basis, or by running the *Start-AMBARemediation.ps1* script located in the *.\patterns\alz\scripts* folder. This script will remediate all AMBA policies in scope as defined by the management group prefix. +In a brownfield scenario, the policies will report non-compliance for existing resources within their scope. To remediate these non-compliant resources, you need to initiate remediation. This can be done through the Azure portal on a policy-by-policy basis, or by running the *Start-AMBARemediation.ps1* script located in the *.\patterns\alz\scripts* folder. This script will remediate all AMBA-ALZ policies in scope as defined by the management group prefix. {{< hint type=Important >}} This script requires PowerShell 7.0 or higher, and the following PowerShell modules: @@ -60,6 +60,8 @@ $LZManagementGroup="The management group ID for Landing Zones" .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-KeyManagement .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-LoadBalancing .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-NetworkChanges +.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-RecoveryServices + .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-HybridVM .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-Storage .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-VM @@ -72,5 +74,3 @@ To remediate a single policy definition instead of the entire policy initiative, #Run the following command to initiate remediation of a single policy definition .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName ALZ_AlertProcessing_Rule ``` - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md b/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md index 5665f0cf6..69d6369b7 100644 --- a/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md +++ b/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md @@ -2,18 +2,17 @@ title: Parameter configuration geekdocHidden: true --- -<<<<<<< HEAD:docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md + {{< hint type=Important >}} Updating from the _**preview**_ version is not supported. If you deployed the _**preview**_ version, please proceed with [Moving from preview to GA](../../../Resources/Moving-from-preview-to-GA) before continuing. {{< /hint >}} -======= ->>>>>>> 50e64f12830f19892cc6e813b50d9577e20035e7:docs/content/patterns/alz/deploy/parameterConfiguration.md ## 1. Parameter configuration -To start, you can either download a copy of the parameter file or clone/fork the repository. +To start, you can either download a copy of the parameter file according the version of AMBA-ALZ you are going to deploy or clone/fork the repository. -- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-09-02/patterns/alz/alzArm.param.json) +- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-11-01/patterns/alz/alzArm.param.json) aligned to the latest release +- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/alzArm.param.json) aligned to the main branch The following instructions apply universally, regardless of your alignment with ALZ or if you have a single management group. @@ -49,6 +48,10 @@ The following instructions apply universally, regardless of your alignment with {{< hint type=note >}} You can use multiple email addresses, ARM Roles, Webhooks, or Event Hubs (though using multiple Event Hubs is not recommended as per ALZ guidance). If you set multiple entries, ensure they are entered as a single string with values separated by commas. For example: + + + + ```json "ALZMonitorActionGroupEmail": { "value": [ @@ -70,7 +73,11 @@ The following instructions apply universally, regardless of your alignment with } ``` + + + {{< /hint >}} + To disable initiative assignments, set the value of any of the following parameters to **"No"**: _```enableAMBAConnectivity```_, _```enableAMBAIdentity```_, _```enableAMBALandingZone```_, _```enableAMBAManagement```_, or _```enableAMBAServiceHealth```_. ### If you are aligned to ALZ diff --git a/docs/content/patterns/alz/Overview/ALZ-Pattern.md b/docs/content/patterns/alz/Overview/ALZ-Pattern.md index 0c82f33c5..8af833880 100644 --- a/docs/content/patterns/alz/Overview/ALZ-Pattern.md +++ b/docs/content/patterns/alz/Overview/ALZ-Pattern.md @@ -1,5 +1,5 @@ --- -title: The ALZ Pattern +title: The Azure Landing Zones (ALZ) Pattern geekdocCollapseSection: true weight: 10 --- @@ -10,11 +10,11 @@ The Azure Monitor Baseline Alerts (AMBA) for Azure Landing Zones (ALZ) is a best A frequent question from customers is, "What should we monitor in Azure?" and "What thresholds should we set for our alerts?" -There isn't a definitive list of what to monitor when deploying to Azure because it depends on the services used and their usage patterns. This dictates what to monitor, the metrics to collect, and the errors to alert on. +There is not a definitive list of what to monitor when deploying to Azure because it depends on the services used and their usage patterns. This dictates what to monitor, the metrics to collect, and the errors to alert on. -Microsoft addresses this with various 'insights or solutions' for popular services, such as [Storage Insights](https://learn.microsoft.com/en-us/azure/storage/common/storage-insights-overview), [VM Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-overview), and [Container Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/container-insights-overview). However, this doesn't cover everything. +Microsoft addresses this with various 'insights or solutions' for popular services, such as [Storage Insights](https://learn.microsoft.com/en-us/azure/storage/common/storage-insights-overview), [VM Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-overview), and [Container Insights](https://learn.microsoft.com/en-us/azure/azure-monitor/containers/container-insights-overview). However, this does not cover everything. -This project focuses on monitoring for Azure Landing Zones, providing a common set of Azure resources/services configured similarly across organizations. It also includes guidance for custom brownfield scenarios that don't align with ALZ. This serves as a starting point for addressing "What should be monitored in Azure?" and demonstrates how to monitor at scale using Infrastructure-as-Code principles. +This project focuses on monitoring for Azure Landing Zones, providing a common set of Azure resources/services configured similarly across organizations. It also includes guidance for custom brownfield scenarios that do not align with ALZ. This serves as a starting point for addressing "What should be monitored in Azure?" and demonstrates how to monitor at scale using Infrastructure-as-Code principles. This project offers an opinionated view on monitoring key components of your Azure Landing Zone within the Platform and Landing Zone scope, including: @@ -54,7 +54,7 @@ If you encounter a problem, please file an issue in our GitHub repository [GitHu ## Deployment Guide -Refer to our [Deployment Guide](../../Howto/deploy/Introduction-to-deploying-the-ALZ-Pattern) for guidance on consuming the contents of this repository. +Refer to [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) for guidance on consuming the contents of this repository. ## Known Issues @@ -80,10 +80,8 @@ Details on contributing to this repository can be found in the [Contributor Guid When you deploy the IP located in this repository, Microsoft can identify the installation with the deployed Azure resources. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through customer usage attribution and governed by [Microsoft's privacy policies](https://www.microsoft.com/trustcenter). -If you don't wish to send usage data to Microsoft or need more details, refer to the [Disable telemetry tracking](../../Howto/Telemetry) guide. +If you do not wish to send usage data to Microsoft or need more details, refer to the [Disable telemetry tracking](../../Howto/Telemetry) guide. ## Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third-party's policies. - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/Overview/Whats-New.md b/docs/content/patterns/alz/Overview/Whats-New.md index 4055f9a4c..c7edf49ce 100644 --- a/docs/content/patterns/alz/Overview/Whats-New.md +++ b/docs/content/patterns/alz/Overview/Whats-New.md @@ -8,13 +8,43 @@ For the latest updates, visit the [Releases](https://github.com/Azure/azure-moni To update your deployment with the latest release, refer to the [Update to new releases](../../HowTo/UpdateToNewReleases) guide. -## 2024-09-02 +## 2024-11-01 ### New Features -- **AMBA Portal Accelerator**: Introducing the Azure Monitor Baseline Alerts Accelerator, now in preview! Deploy alerts quickly and confidently through the Azure Portal UI. For detailed instructions, see [Deploy via the Azure Portal (Preview)](../deploy/Deploy-via-Azure-Portal-UI). +- Added a new policy definition to audit/update Recovery Vault ASR Health Alerting to Azure monitor alerts. +- **Script consolidation**: *Remove-AMBADeployments.ps1*, *Remove-AMBANotificationAssets.ps1*, *Start-AMBACleanup.ps1*, *Start-AMBAOldArpCleanup.ps1* and *Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1* scripts have been consolidated into a single new one called [***Start-AMBA-ALZ-Maintenance.ps1***](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBA-ALZ-Maintenance.ps1) [[#352](https://github.com/Azure/azure-monitor-baseline-alerts/pull/352): Consolidate maintenance scripts]. With this enhancement, it is now possible to remove alerts for resources which have been deletedf (orphaned alerts). + +### Bug Fixes + +- Fixed [[#323](https://github.com/Azure/azure-monitor-baseline-alerts/pull/323)]: Ensure -WhatIf parameter is honored by all scripts commands and fix hybrid disconnected alert bug +- Fixed [[#342](https://github.com/Azure/azure-monitor-baseline-alerts/pull/342)]: Github issue link and Management Subscription Id fix +- Fixed [[#346](https://github.com/Azure/azure-monitor-baseline-alerts/pull/346)]: Update useCommonSchema to useCommonAlertSchema in Deploy_ServiceHealth_ActionGroups and Deploy_Suppression_AlertProcessing_Rule Policy Definitions +- Fixed [[#357](https://github.com/Azure/azure-monitor-baseline-alerts/pull/357)]: Resolve the ExpressRoute QoS remediation issue +- Fixed [[#362](https://github.com/Azure/azure-monitor-baseline-alerts/pull/362)]: Standardization on param usage for failingPeriods and evaluationPeriods +- Fixed [[#381](https://github.com/Azure/azure-monitor-baseline-alerts/pull/381)]: Bugged Connectivity policy initiative + override tag name case consistency + tag override documentation update -- **Modular Initiatives**: The former Landing Zone Initiative is deprecated. We now offer a modular approach with distinct components. For more details, visit [Policy Initiatives](../Policy-Initiatives). +### Documentation Updates + +- Documentation update about: + - Update to new releases pages now brings more clarity + - Update to new releases pages contain samples using the new consolidated maintenance script. [Updating to release 2024-09-02](../../HowTo/UpdateToNewReleases#2024-09-02), [Updating to release 2024-03-01](../../HowTo/UpdateToNewReleases#2024-03-01) + - Clarification on how to identify the pseudoRootManagementGroup as the one parenting the Platform and Landing Zones management groups. + - Updated AMBA diagrams. [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) + - Remediation command for the ***Deploy Azure Monitor Baseline Alerts for Recovery Services*** policy initiative added to the list. [Remediate Policies](../../HowTo/deploy/Remediate-Policies) + +### Tools + +- **Automation:** + - Removed the previous workflow that automates the process of creating ARM templates for Azure Policies/ PolicySets because of a security issue. + - New workflow to ensure policy updates and to verify the Bicep build has been run by the contributor. + +## 2024-09-02 + +### New Features + +- **AMBA Portal Accelerator**: Introducing the Azure Monitor Baseline Alerts Accelerator, now in preview! Deploy alerts quickly and confidently through the Azure Portal UI. For detailed instructions, see [Deploy via the Azure Portal (Preview)](../../HowTo/deploy/Deploy-via-Azure-Portal-UI). +- **Modular Initiatives**: The former Landing Zone Initiative is deprecated. We now offer a modular approach with distinct components. For more details, visit [Policy Initiatives](../../Getting-started/Policy-Initiatives). - Key Management - Load Balancing @@ -24,7 +54,7 @@ To update your deployment with the latest release, refer to the [Update to new r - VM - Web -- **Threshold Override**: Adjust alert thresholds for specific resources using a tag. This feature is available for metrics and log alerts. Learn more: [Alert Threshold Override](../Available_features/Threshold-Override). +- **Threshold Override**: Adjust alert thresholds for specific resources using a tag. This feature is available for metrics and log alerts. Learn more: [Alert Threshold Override](../../HowTo/Threshold-Override). - **Custom Tags to Disable Monitoring**: Specify a tag name and values to disable monitoring for certain resources. @@ -49,10 +79,10 @@ To update your deployment with the latest release, refer to the [Update to new r ### Documentation Updates -- Added new policies for ExpressRoute Ports to Connectivity table. [Policy Initiatives](../Policy-Initiatives). -- Updated documentation on unsupported/unrecommended Tenant Root Group deployment. [FAQ](../FAQ). -- New guidance for bringing your own Managed Identity. [Bring Your Own User Assigned Managed Identity](../Available_features/Bring-Your-Own-User-Assigned-Managed-Identity). -- Updated Policy Initiatives documentation to include Policy Reference ID and display names. [Policy Initiatives](../Policy-Initiatives). +- Added new policies for ExpressRoute Ports to Connectivity table. [Policy Initiatives](../../Getting-started/Policy-Initiatives). +- Updated documentation on unsupported/unrecommended Tenant Root Group deployment. [FAQ](../../Resources/FAQ). +- New guidance for bringing your own Managed Identity. [Bring Your Own User Assigned Managed Identity](../../HowTo/Bring-Your-Own-User-Assigned-Managed-Identity). +- Updated Policy Initiatives documentation to include Policy Reference ID and display names. [Policy Initiatives](../../Getting-started/Policy-Initiatives). ### Tools @@ -122,7 +152,7 @@ To update your deployment with the latest release, refer to the [Update to new r ### Documentation Updates -- Updated [Deploy with GitHub Actions](../deploy/Deploy-with-GitHub-Actions) addressing [Issue #102](https://github.com/Azure/azure-monitor-baseline-alerts/issues/102). +- Updated [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions) addressing [Issue #102](https://github.com/Azure/azure-monitor-baseline-alerts/issues/102). - Updated guidance for AMA in [Monitoring and Alerting](../../Getting-started/Monitoring-and-Alerting). ## 2023-11-14 @@ -149,5 +179,3 @@ To update your deployment with the latest release, refer to the [Update to new r - Added guidance for Server Health alert rules - [Deploy only Service Health Alerts](../../HowTo/deploy/Deploy-only-Service-Health-Alerts). - New documentation on updating to a new release - [Update to new releases](../../HowTo/UpdateToNewReleases). - FAQ Updates - [Frequently Asked Questions](../../Resources//FAQ). - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/FAQ.md b/docs/content/patterns/alz/Resources/FAQ.md index 4768cff8f..b3fef5c21 100644 --- a/docs/content/patterns/alz/Resources/FAQ.md +++ b/docs/content/patterns/alz/Resources/FAQ.md @@ -35,6 +35,7 @@ weight: 80 ## How much does it cost to run the ALZ Baseline solution? > The cost of running the ALZ Baseline solution varies based on several factors, including the number of alert rules deployed, the number of subscriptions inheriting the baseline policies, and the resources within each subscription that match the policy rules. Each alert rule costs approximately $0.1 per month1. +> > - Alert rules are charged based on the number of evaluations. > - If the alert rule evaluates data continuously throughout the month, the cost is approximately $0.11. > - If the rule evaluates data intermittently (e.g., due to the monitored resource being down and not sending telemetry), the cost is prorated based on the time the rule was actively evaluating data. @@ -44,14 +45,13 @@ weight: 80 > {{< hint type=Note >}} It is advisable to evaluate the costs in a non-production environment before full deployment to ensure a clear understanding of the potential expenses.{{< /hint >}} > > For detailed cost estimates related to your deployment, please refer to the [Azure Monitor Pricing](https://azure.microsoft.com/en-us/pricing/details/monitor/) page. Additionally, you can collaborate with your local Microsoft account team to develop a rough order of magnitude (RoM) cost estimate. - > 1 Note that costs may vary slightly depending on the deployment region. The costs mentioned are based on pricing as of April 2023. ## Can I access the Visio diagrams displayed in the documentation? > Yes, you can access the Visio diagrams 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 +## Can I use AMBA-ALZ without cloning/forking a GitHub repository >

Yes, as long as the ARM templates are publicly accessible. This solution includes several linked templates that must be accessible publicly. When the top-level ARM template is submitted to Azure Resource Manager, the linked templates are not automatically uploaded and need to be pulled in at deploy time from Azure. Therefore, they must be referenced using a URL accessible from Azure (e.g., via a public GitHub repository).

> @@ -79,5 +79,3 @@ weight: 80 > - Resource creation will fail. > - Deployment of action groups and/or alert processing rules will fail. For AMBA-specific issues, refer to the [Failed to deploy action group(s) and/or alert processing rule(s)](../Known-Issues#failed-to-deploy-action-groups-andor-alert-processing-rules) section in the [Known Issues](../Known-Issues) documentation. > - Editing action groups will result in an Azure portal page error. For AMBA-specific issues, refer to the [Failed to edit action group(s)](../Known-Issues#failed-to-edit-action-groups) section in the [Known Issues](../Known-Issues) documentation. - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/Known-Issues.md b/docs/content/patterns/alz/Resources/Known-Issues.md index 8cab62c18..e526e43ff 100644 --- a/docs/content/patterns/alz/Resources/Known-Issues.md +++ b/docs/content/patterns/alz/Resources/Known-Issues.md @@ -70,7 +70,7 @@ weight: 100 > ### Cause > > When attempting to deploy to a different region, such as "uksouth", after a previous deployment in another region, an error may occur. This issue persists even after performing a cleanup (refer to [Cleaning up a Deployment](../../HowTo/Cleaning-up-a-Deployment) for more details). The error arises because deployment entries from the previous operation still exist, causing a region conflict that prevents the new deployment. - +> > ### Resolution > > Situation 1: You are attempting to deploy to a different region than the one used in a previous deployment. It is not necessary to deploy to the same scope in a different region, as the definitions and assignments are scoped to a management group and are not region-specific. No further action is required. @@ -83,15 +83,15 @@ weight: 100 > 4. Select all the deployment instances related to AMBA and click **_Delete_**. > > {{< hint type=Note >}} To recognize the deployment names belonging to AMBA, select those whose names start with: - +> > 1. amba- > 2. pid- > 3. alzArm > 4. ambaPreparingToLaunch - -If you've only deployed AMBA once, you have 14 deployment instances. - -{{< /hint >}} +> +>If you have only deployed AMBA-ALZ once, you have 14 deployment instances. +> +>{{< /hint >}} ## Failed to deploy because of the limit of 800 deployments per management group has been reached @@ -110,21 +110,21 @@ If you've only deployed AMBA once, you have 14 deployment instances. > To resolve this issue, follow these steps: > > 1. Navigate to **_Management Groups_** -> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) where AMBA deployment was targeted +> 2. Select the management group (corresponding to the value entered for the _enterpriseScaleCompanyPrefix_ during the deployment) where AMBA-ALZ deployment was targeted > 3. Click **_Deployment_** > 4. Select all the deployments that could be deleted (example: instances of previous deployments related to AMBA) and click **_Delete_** > 5. Run the deployment > -> {{< hint type=Note >}} To recognize the deployment names belonging to AMBA, select those whose names start with: - +> {{< hint type=Note >}} To recognize the deployment names belonging to AMBA-ALZ, select those whose names start with: +> > 1. amba- > 2. pid- > 3. alzArm > 4. ambaPreparingToLaunch - -If you've only deployed AMBA once, you have 14 deployment instances. - -{{< /hint >}} +> +>If you have only deployed AMBA-ALZ once, you have 14 deployment instances. +> +>{{< /hint >}} ## Failed to deploy because of 'location' property not specified @@ -146,9 +146,11 @@ If you've only deployed AMBA once, you have 14 deployment instances. > ### Cause > > The new [Bring Your Own User Assigned Managed Identity (BYO UAMI)](../../HowTo/Bring-your-own-Managed-Identity) feature allows you to either use an existing User Assigned Managed Identity (UAMI) or create a new one within the management subscription. This process automatically assigns the Monitoring Reader role to the UAMI at the parent pseudo root Management Group. If a new UAMI is created, ensure the management subscription ID is correctly specified. +> > ### Resolution > > Ensure that the management subscription ID is accurately specified in the parameter file: +> > ![New UAMI deployed by the template](../../media/alz-UAMI-Param-Example-2.png) ## Failed to deploy action group(s) and/or alert processing rule(s) @@ -167,7 +169,7 @@ If you've only deployed AMBA once, you have 14 deployment instances. > ### Cause > > When action groups and alert processing rules are deployed, the subscription name is included in their display names. If the subscription name contains invalid characters, the deployment will fail, resulting in the misleading error mentioned above. - +> > ### Resolution > > Rename the subscription to exclude invalid characters. Refer to the [Naming rules and restrictions for Azure resources](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules) for a list of supported characters. For instance, alert suppression rules only permit alphanumeric characters, underscores, and hyphens. Specifically, alphanumeric characters include: @@ -205,5 +207,3 @@ If you've only deployed AMBA once, you have 14 deployment instances. > - **_0_** through **_9_** (numbers) > > Once the subscription has been renamed to exclude invalid characters, delete the existing action groups (those with names starting with **_ag-AMBA-_** or **_ag-AMBA-SH-_**) and rerun the remediation process. - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md b/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md deleted file mode 100644 index 39fb5cdc1..000000000 --- a/docs/content/patterns/alz/Resources/Moving-from-preview-to-GA.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Moving from preview to GA -geekdocCollapseSection: true -weight: 101 ---- -When transitioning from the preview version to the General Availability (GA) version, it is necessary to remove all resources deployed by the ALZ Monitor solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all such resources, including: - -- Metric Alerts -- Activity Log Alerts -- Resource Groups (created for to contain alert resources) -- Policy Assignments -- Policy Definitions -- Policy Set Definitions -- Policy Assignment remediation identity role assignments - -All resources deployed by the initial ALZ Monitor deployment, as well as those created dynamically by 'deploy if not exist' policies, are tagged, marked in metadata, or described (depending on resource capabilities) with `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is crucial for the cleanup script to identify and remove the resources. If this metadata has been altered or removed, the cleanup script will not recognize those resources for deletion. - -## Cleanup Script Execution - -{{< hint type=Important >}} -It is strongly advised to **thoroughly** test the script in a non-production environment before deploying it to production. These sample scripts are not covered by any Microsoft standard support program or service. They are provided "AS IS" without any warranty, express or implied. Microsoft disclaims all implied warranties, including but not limited to, implied warranties of merchantability or fitness for a particular purpose. The user assumes all risks associated with the use or performance of the sample scripts and documentation. Microsoft, its authors, or any contributors to the creation, production, or delivery of the scripts shall not be liable for any damages, including but not limited to, loss of business profits, business interruption, loss of business information, or other financial losses, arising from the use or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. -{{< /hint >}} - -### Download the script file - -Follow these steps to download the cleanup script file. Alternatively, you can clone the repository from GitHub and ensure you have the latest version by fetching the `main` branch. - -1. Navigate to the [AMBA project on GitHub](https://github.com/Azure/azure-monitor-baseline-alerts). -2. Browse to the `patterns/alz/scripts` directory. -3. Locate and open the **Start-ALZMonitorCleanup.ps1** script file. -4. Click on the **Raw** button to view the raw content of the script. -5. Save the file as **Start-ALZMonitorCleanup.ps1**. - -### Executing the Script - -1. Launch PowerShell. -2. Install the **Az.ResourceGraph** module by running: `Install-Module Az.ResourceGraph`. -3. Navigate to the directory containing the **Start-ALZMonitorCleanup.ps1** script. -4. Sign in to Azure using the `Connect-AzAccount` command. Ensure the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. -5. Execute the script with one of the following options: - - {{% include "PowerShell-ExecutionPolicy.md" %}} - - **Generate a list of the resource IDs which would be deleted by this script:** - - ```powershell - ./Start-ALZMonitorCleanup.ps1 -ReportOnly - ``` - - **Show output of what would happen if deletes executed:** - - ```powershell - ./Start-ALZMonitorCleanup.ps1 -WhatIf - ``` - - **Delete all resources deployed by the ALZ-Monitor IaC without prompting for confirmation:** - - ```powershell - ./Start-ALZMonitorCleanup.ps1 -Force - ``` - -## Next steps -- For customizing policy assignments, refer to [Customize Policy Assignment](../../HowTo/deploy/Customize-Policy-Assignment). -- For deployment using GitHub Actions, refer to [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions). -- For deployment using Azure DevOps Pipelines, refer to [Deploy with Azure Pipelines](../../HowTo/deploy/Deploy-with-Azure-Pipelines). -- For deployment using Azure CLI, refer to [Deploy with Azure CLI](../../HowTo/deploy/Deploy-with-Azure-CLI). -- For deployment using Azure PowerShell, refer to [Deploy with Azure PowerShell](../../HowTo/deploy/Deploy-with-Azure-PowerShell). - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/Resources/Versioning.md b/docs/content/patterns/alz/Resources/Versioning.md index 1416e840a..ff3a70829 100644 --- a/docs/content/patterns/alz/Resources/Versioning.md +++ b/docs/content/patterns/alz/Resources/Versioning.md @@ -9,5 +9,3 @@ The main output of this repository is a set of Azure Policy initiatives and corr To facilitate the adoption of policies, a new release of the repository will be issued whenever one or more policies are updated with breaking changes, in accordance with the [Azure Policy versioning guidance](https://github.com/Azure/azure-policy/blob/master/built-in-policies/README.md#versioning). Guidance for updating existing deployments to new versions will be provided with each release. - -[Back to top of page](.) diff --git a/docs/content/patterns/alz/Whats-New.md b/docs/content/patterns/alz/Whats-New.md deleted file mode 100644 index 903d7c42b..000000000 --- a/docs/content/patterns/alz/Whats-New.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: What's New -geekdocCollapseSection: true -weight: 09 ---- - -For the latest updates, visit the [Releases](https://github.com/Azure/azure-monitor-baseline-alerts/releases) page. - -To update your deployment with the latest release, refer to the [Update to new releases](../../HowTo/UpdateToNewReleases) guide. - -## 2024-11-01 - -### New features - -- Added a new policy definition to audit/update Recovery Vault ASR Health Alerting to Azure monitor alerts. -- **Script consolidation**: *Remove-AMBADeployments.ps1*, *Remove-AMBANotificationAssets.ps1*, *Start-AMBACleanup.ps1*, *Start-AMBAOldArpCleanup.ps1* and *Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1* scripts have been consolidated into a single new one called [***Start-AMBA-ALZ-Maintenance.ps1***](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBA-ALZ-Maintenance.ps1) [[#352](https://github.com/Azure/azure-monitor-baseline-alerts/pull/352): Consolidate maintenance scripts]. With this enhancement, it is now possible to remove alerts for resources which have been deletedf (orphaned alerts). - -### Bug fixes - -- Fixed [[#323](https://github.com/Azure/azure-monitor-baseline-alerts/pull/323)]: Ensure -WhatIf parameter is honored by all scripts commands and fix hybrid disconnected alert bug -- Fixed [[#342](https://github.com/Azure/azure-monitor-baseline-alerts/pull/342)]: Github issue link and Management Subscription Id fix -- Fixed [[#346](https://github.com/Azure/azure-monitor-baseline-alerts/pull/346)]: Update useCommonSchema to useCommonAlertSchema in Deploy_ServiceHealth_ActionGroups and Deploy_Suppression_AlertProcessing_Rule Policy Definitions -- Fixed [[#357](https://github.com/Azure/azure-monitor-baseline-alerts/pull/357)]: Resolve the ExpressRoute QoS remediation issue -- Fixed [[#362](https://github.com/Azure/azure-monitor-baseline-alerts/pull/362)]: Standardization on param usage for failingPeriods and evaluationPeriods -- Fixed [[#381](https://github.com/Azure/azure-monitor-baseline-alerts/pull/381)]: Bugged Connectivity policy initiative + override tag name case consistency + tag override documentation update - -### Documentation updates - -- Documentation update about: - - Update to new releases pages now brings more clarity - - Update to new releases pages contain samples using the new consolidated maintenance script. [Updating to release 2024-09-02](./UpdateToNewReleases/Update_to_release_2024-09-02), [Updating to release 2024-03-01](./UpdateToNewReleases/Update_to_release_2024-03-01) - - Clarification on how to identify the pseudoRootManagementGroup as the one parenting the Platform and Landing Zones management groups. - - Updated AMBA diagrams. [Introduction to deploying the ALZ Pattern](./deploy/Introduction-to-deploying-the-ALZ-Pattern) - - Remediation command for the ***Deploy Azure Monitor Baseline Alerts for Recovery Services*** policy initiative added to the list. [Remediate Policies](./deploy/Remediate-Policies) - -### Tools - -- **Automation:** - - Removed the previous workflow that automates the process of creating ARM templates for Azure Policies/ PolicySets because of a security issue. - - New workflow to ensure policy updates and to verify the Bicep build has been run by the contributor. - -## 2024-09-02 - -### New features - -- **AMBA Portal Accelerator**: Introducing the Azure Monitor Baseline Alerts Accelerator, now in preview! Deploy alerts quickly and confidently through the Azure Portal UI. For detailed instructions, see [Deploy via the Azure Portal (Preview)](../deploy/Deploy-via-Azure-Portal-UI). - -- **Modular Initiatives**: The former Landing Zone Initiative is deprecated. We now offer a modular approach with distinct components. For more details, visit [Policy Initiatives](../Policy-Initiatives). - - Key Management - - Load Balancing - - Network Changes - - Recovery Services - - Storage - - VM - - Web - -- **Threshold Override**: Adjust alert thresholds for specific resources using a tag. This feature is available for metrics and log alerts. Learn more: [Alert Threshold Override](../Available_features/Threshold-Override). - -- **Custom Tags to Disable Monitoring**: Specify a tag name and values to disable monitoring for certain resources. Learn more: [Disabling Policies]() - -- New alert rule for Azure Key Vault Managed HSM, included in Identity and Key Management initiatives. -- New Daily Cap threshold alert for Log Analytics workspace, added to the Management initiative. -- New Application Insight Throttling alert, included in the Web initiative. -- New ActivityLog Alert for deleting Application Insight, added to the Web initiative. -- Ability to change Application Gateway dynamic alert sensitivity. - -### Bug fixes - -- Fixed [[#280](https://github.com/Azure/azure-monitor-baseline-alerts/issues/280)]: AGW Compute Units Alert and AGW Unhealthy Host Count Alert remain non-compliant after successful remediation -- Fixed [[#278](https://github.com/Azure/azure-monitor-baseline-alerts/issues/278)]: Deploy VNetG ExpressRoute CPU Utilization Alert remediation fails -- Fixed [[#284](https://github.com/Azure/azure-monitor-baseline-alerts/issues/284)]: AMBA policy ALZ_ServiceHealth_ActionGroups Missing when remediating AMBA policies -- Fixed [[#253](https://github.com/Azure/azure-monitor-baseline-alerts/issues/253)]: Deploying AMBA, older version used in documentation -- Fixed [[#261](https://github.com/Azure/azure-monitor-baseline-alerts/issues/261)]: displayname VMLowOSDisk(Write/Read)LatencyAlert should be VMHighOSDisk(Write/Read)LatencyAlert -- Fixed [[#260](https://github.com/Azure/azure-monitor-baseline-alerts/issues/260)]: No treshold parameter for ALZ alerts ALZ_WSFMemoryPercentage, ALZ_WSFCPUPercentage. -- Fixed casing in metadata. -- Fixed casing in policies. -- Fixed default values for multiple parameters used in the VM and Hybrid initiatives. - -### Documentation Updates - -- Added new policies for ExpressRoute Ports to Connectivity table. [Policy Initiatives](../Policy-Initiatives). -- Updated documentation on unsupported/unrecommended Tenant Root Group deployment. [FAQ](../FAQ). -- New guidance for bringing your own Managed Identity. [Bring Your Own User Assigned Managed Identity](../Available_features/Bring-Your-Own-User-Assigned-Managed-Identity). -- Updated Policy Initiatives documentation to include Policy Reference ID and display names. [Policy Initiatives](../Policy-Initiatives). - -### Tools - -- **Automation**: New workflow automates ARM template creation for Azure Policies/PolicySets, triggered by pull request events. - -## 2024-06-05 - -### New Features - -- Added new PIDs for additional deployment methods. See [Disable telemetry tracking](../../HowTo/Telemetry) for more information. -- New initiative to monitor Azure Arc-enabled Virtual Machines. [Alerting-HybridVM](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/policySetDefinitions/Deploy-HybridVM-Alerts.json). - -### Bug fixes - -- Changed the value of field minFailingPeriodsToAlert and numberOfEvaluationPeriods in the existenceCondition for the above alerts from 2 to 4 to fix the compliance evaluation issue. -- Changed the value of timeAggregation to Average for both Deploy AGW BackendLastByteResponseTime and Deploy AGW ApplicationGatewayTotalTime policy definitions. [Issue #194](https://github.com/Azure/azure-monitor-baseline-alerts/issues/194) -- Fixing case sensitive parameters [Issue #185](https://github.com/Azure/azure-monitor-baseline-alerts/issues/185) - -### Documentation Updates - -- Updated Deploy only Service Health Alert documentation for json-strings in cloud shell. - -## 2024-04-12 - -### New Features - -- Updated Existence Condition to detect and remediate configuration drift. The following parameters were added to the Existence Condition of the policies: - - Static alerts: EvaluationFrequency, WindowSize, Threshold, Severity, Operator, autoMitigate - - Dynamic alerts: alertSensitivity, numberOfEvaluationPeriods, minFailingPeriodsToAlert - -- Added suppression Alert Processing Rule in notification Assets policy. See [Temporarily disabling notifications](../../HowTo/Temporarily-disabling-notifications) for details. -- Email address for Action Group is no longer mandatory. -- Bring your own Action Group and/or Alert Processing Rules. See [Bring Your Own Notifications (BYON)](../../HowTo/Bring-your-own-Notifications) for details. - -### Bug Fixes - -- Fixed operator for `SNATPortUtilization` for Azure Firewall. -- Corrected name for Deploy Activity Log Storage Account Delete Policy. - -- Updated deployment documentation to use the latest release. -- Updated Deploy only Service Health Alert documentation. -- Updated AMBA-ALZ Diagrams to include new notification assets initiative and Action group options. [AMBA-Diagram](../../media/AMBA-Diagrams.vsdx). - - -### New Features - -- Enhanced action group for more notification and action choices: - - Email Azure Resource Manager Role - - Azure Function - - Event Hubs - - Logic App - - Webhook -- Service health initiative now has its own Action Group. -- Added [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) initiative. -- New policy for Storage Account Deletion. [Issue #76](https://github.com/Azure/azure-monitor-baseline-alerts/issues/76). -- Updated remediation script for better experience with new action group for Service Health. - -### Bug Fixes - -- Fixed: unable to deploy via pipeline using ubuntu-latest. [Issue #64](https://github.com/Azure/azure-monitor-baseline-alerts/issues/64). -- Fixed the PIP VIP alert existence condition to check only for standard SKU. [Issue #80](https://github.com/Azure/azure-monitor-baseline-alerts/issues/80). - -### Documentation Updates - -- Updated [Deploy with GitHub Actions](../deploy/Deploy-with-GitHub-Actions) addressing [Issue #102](https://github.com/Azure/azure-monitor-baseline-alerts/issues/102). -- Updated guidance for AMA in [Monitoring and Alerting](../../Getting-started/Monitoring-and-Alerting). - -## 2023-11-14 - -### New Features - -- Service Health Policy Set Definition now includes parameters to set Policy Effect. Default value is "deployIfNotExists". -- Added alert rules in Landing Zone Policy Set Definition: - - Front door (Microsoft.Cdn/profiles) - - Front door classic (Microsoft.Network/frontdoors) - - Traffic Manager (Microsoft.Network/trafficmanagerprofiles) - - App Service (Microsoft.Web/serverfarms) - -### Bug Fixes - -- Updated path in sample-workflow [Issue #30](https://github.com/Azure/azure-monitor-baseline-alerts/issues/30). -- Updated sample commands in Start-AMBARemediation.ps1 [Pull #49](https://github.com/Azure/azure-monitor-baseline-alerts/pull/49). -- Fixed Role Assignment cleanup script [Issue #42](https://github.com/Azure/azure-monitor-baseline-alerts/issues/42). -- Fixed VSCode template validation error [Issue #43](https://github.com/Azure/azure-monitor-baseline-alerts/issues/43). - -### Documentation Updates - - - - -- How to modify individual policies - [How to modify individual policies](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern/#how-to-modify-individual-policies). -- Added guidance for Server Health alert rules - [Deploy only Service Health Alerts](../../HowTo/deploy/Deploy-only-Service-Health-Alerts). -- New documentation on updating to a new release - [Update to new releases](../../HowTo/UpdateToNewReleases). -- FAQ Updates - [Frequently Asked Questions](../../Resources//FAQ). diff --git a/docs/content/patterns/alz/deploy/Deploy-with-Azure-CLI.md b/docs/content/patterns/alz/deploy/Deploy-with-Azure-CLI.md deleted file mode 100644 index b1dbb861e..000000000 --- a/docs/content/patterns/alz/deploy/Deploy-with-Azure-CLI.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Deploy with Azure CLI -weight: 30 ---- - -{{% include "parameterConfiguration.md" %}} - -## 3. Configuring variables for deployment - -The following commands apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. - -Open your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), and navigate to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. - -Run the following commands: - -```bash -location="Your Azure location of choice" -pseudoRootManagementGroup="The pseudo root management group id parenting the identity, management and connectivity management groups" -``` - -{{< hint type=Important >}} -When running Azure CLI from PowerShell the variables have to start with a $. - -Above-mentioned "pseudoRootManagementGroup" variable value, being the so called "pseudo root management group id", should _coincide_ with the value of the "enterpriseScaleCompanyPrefix" parameter, as set previously within the parameter files. - -The location variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. -{{< /hint >}} - -## 4. Deploying AMBA - -The following commands apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. - -Using your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), if you closed your previous session, navigate again to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. - -{{< hint type=note >}} -This should be tested in a safe environment. If you are subsequently looking to deploy to prod environments, consider leveraging the guidance found in [Customize Policy Assignment](../Customize-Policy-Assignment), to deploy and enable alerts in a controlled manner. - -If you customized the policies as documented at [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), make sure the run the deployment command using your own repository and branch in the ***--template-uri*** parameter value. Example: - - az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main - or branchname***/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" -{{< /hint >}} - -```bash -az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/2024-09-02/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" -``` - -## Next steps - -To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) diff --git a/docs/content/patterns/alz/deploy/Deploy-with-Azure-PowerShell.md b/docs/content/patterns/alz/deploy/Deploy-with-Azure-PowerShell.md deleted file mode 100644 index 27e2e28af..000000000 --- a/docs/content/patterns/alz/deploy/Deploy-with-Azure-PowerShell.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Deploy with Azure PowerShell -weight: 40 ---- - -{{% include "parameterConfiguration.md" %}} - -## 3. Configuring variables for deployment - -The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. - -Open a PowerShell prompt, navigate to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. - -Run the following commands: - -```powershell -$location = "Your Azure location of choice" -$pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" -``` - -{{< hint type=important >}} -Above-mentioned "pseudoRootManagementGroup" variable value, being the so called "pseudo root management group id", should _coincide_ with the value of the "parPolicyPseudoRootMgmtGroup" parameter, as set previously within the parameter files. - -The location variable refers to the deployment location. Deploying to multiple regions is not necessary as the definitions and assignments are scoped to a management group and are not region-specific. -{{< /hint >}} - -## 4. Deploy the policy definitions, initiatives and policy assignments with default settings - -{{< hint type=Important >}} -Deploying through PowerShell, requires authentication to Azure and the following modules: - -- Az.Accounts -- Az.Resources - -Before starting the deployment, make sure you logged in using the Connect-AzAccount PowerShell command and that the modules above are imported. -{{< /hint >}} - -The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. - -Using a PowerShell prompt, if you closed your previous session, navigate again to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives and run the command below. - -{{< hint type=note >}} -This should be tested in a safe environment. If you are later looking to deploy to prod environments, consider using the guidance found in [Customize Policy Assignment](../Customize-Policy-Assignment), to deploy and enable alerts in a controlled manner. - -If you customized the policies as documented at [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), make sure the run the deployment command using your own repository and branch in the _***-TemplateUri***_ parameter value. Example: - - New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location - -TemplateUri "https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or branchname***/patterns/alz/alzArm.json" - -TemplateParameterFile ".\patterns\alz\alzArm.param.json" -{{< /hint >}} - -```powershell -New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location -TemplateUri "https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/2024-09-02/patterns/alz/alzArm.json" -TemplateParameterFile ".\patterns\alz\alzArm.param.json" -``` - -## Next steps - -To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) diff --git a/docs/content/patterns/alz/deploy/Introduction-to-deploying-the-ALZ-Pattern.md b/docs/content/patterns/alz/deploy/Introduction-to-deploying-the-ALZ-Pattern.md deleted file mode 100644 index 06f360400..000000000 --- a/docs/content/patterns/alz/deploy/Introduction-to-deploying-the-ALZ-Pattern.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Introduction to deploying the ALZ Pattern -weight: 10 ---- - -## Background - -This guide describes how to get started with implementing alert policies and initiatives in your environment for testing and validation. In the guide, it is assumed that you will be using GitHub actions or manual deployment to implement policies, initiatives and policy assignments in your environment. - -The repo at present contains code and details for the following: - -- Policies to automatically create alerts, action groups and alert processing rules for different Azure resource types, centered around a recommended Azure Monitor Baseline for Alerting in a customer´ newly created or existing brownfield ALZ deployment. -- Initiatives grouping said policies into appropriate buckets for ease of policy assignment in alignment with ALZ Platform structure (Networking, Identity and Management). - -Alerts, action groups and alert processing rules are created as follows: - -1. All metric alerts are created in the resource group where the resource that is being monitored exists. For example, creating an ER circuit in a resource group covered by the policies will create the corresponding alerts in that same resource group. -2. Activity log alerts are created in a specific resource group (created specifically by and used for this solution) in each subscription, when the subscription is deployed. The resource group name is parameterized, with a default value of rg-amba-monitoring-001. -3. Resource health alerts are created in a specific resource group (created specifically by and used for this solution) in each subscription, when the subscription is deployed. The resource group name is parameterized, with a default value of rg-amba-monitoring-001. -4. Action groups and alert processing rules are created in a specific resource group (created specifically by and used for this solution) in each subscription, when the subscription is deployed. The resource group name is parameterized, with a default value of rg-amba-monitoring-001. - -## Prerequisites - -1. Microsoft Entra ID Tenant. -2. ALZ Management group hierarchy deployed as described [here](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-areas).* -3. Minimum one subscription, for when deploying alerts through policies. -4. Deployment Identity with `Owner` permission to the pseudo root management group. Owner permission is required to allow the Service Principal Account to create role-based access control assignments. -5. If deploying manually, i.e. via Azure CLI or PowerShell, ensure that you have [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview?tabs=bicep) installed and working, before attempting installation. See here for how to configure for [Azure CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-cli) and here for [PowerShell](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install#azure-powershell) -6. For the policies to work, the following Azure resource providers, normally registered by default, must be registered on all subscriptions in scope: - - Microsoft.AlertsManagement - - Microsoft.Insights - - See [here](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) for details on how to register a resource provider should you need to do so. - -7. For leveraging the log alerts for Virtual Machines, ensure that VM Insights is enabled for the Virtual Machines to be monitored. For more information on VM Insights deployment, see [here](https://learn.microsoft.com/en-us/azure/azure-monitor/vm/vminsights-enable-overview) . Note only the performance collection of the VM insights solution is required for the current alerts to deploy. - -{{< hint type=note >}} -While it´s recommended to implement the alert policies and initiatives to an ALZ Management Group hierarchy, it is not a technical requirement (avoid Tenant Root Group assignments, to minimize debugging inherited policies at lower-level mangement groups, see [CAF documentation](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups)). These policies and initiatives can be implemented in existing brownfield scenarios that don´t adhere to the ALZ Management Group hierarchy. For example, in hierarchies where there is a single management group, or where the structure does not align to ALZ. At least one management group is required. In case you haven't implemented management groups, we included guidance on how to get started. -{{< /hint >}} - -## Getting started - -- Fork this repo to your own GitHub organization, you should not create a direct clone of the repo. Pull requests based off direct clones of the repo will not be allowed. -- Clone the repo from your own GitHub organization to your developer workstation. -- Review your current configuration to determine what scenario applies to you. We have guidance that will help deploy these policies and initiatives whether you are aligned with Azure Landing Zones, or use other management group hierarchy, or you may not be using management groups at all. If you know your type of management group hierarchy, you can skip forward to your preferred deployment method: - - [Automated deployment with GitHub Actions](../Deploy-with-GitHub-Actions) (recommended method) - - [Automated deployment with Azure Pipelines](../Deploy-with-Azure-Pipelines) (recommended method) - - [Manual deployment with Azure CLI](../Deploy-with-Azure-CLI) - - [Manual deployment with Azure PowerShell](../Deploy-with-Azure-PowerShell) - -### Determining your management group hierarchy - -Azure Landing Zones is a concept that provides a set of best practices, patterns, and tools for creating a cloud environment that is secure, Well-Architected, and easy to manage. Management groups are a key component of Azure Landing Zones, as they allow you to organize and manage your subscriptions and resources in a hierarchical structure. By using management groups, you can apply policies and access controls across multiple subscriptions and resources, making it easier to manage and govern your Azure environment. - -The initiatives provided in this repository align with the management group hierarchy guidelines of Azure Landing Zones. Effectively creating the following assignment mapping between the initiative and the management group: - -- Identity Initiative is assigned to the Identity management group. -- Management Initiative is assigned to the Management management group. -- Connectivity Initiative is assigned to the Connectivity management group. -- Landing Zone Initiative is assigned to the Landing Zone management group. -- Service Health Initiative is assigned to the intermediate (ALZ) root management group. - -The image below is an example of how a management group hierarchy looks like when you follow Azure Landing Zone guidance. Also illustrated in this image is the default recommended assignments of the initiatives. - -![ALZ Management group structure](../../media/alz-management-groups.png) - -The diagram below shows the flow using the orange dash-lines of the policy initiatives and their associated policy definitions. Notice how the Service Health Initiative is assigned at the pseudo root of the management group structure in this case the Contoso management group. This initiative contains the policy that deploys the alert processing rules and action group to each subscription. - -The other monitoring initiatives are each assigned at specific platform landing zone management groups and workload landing zones. The flows for these are in blue dash-lines. - -![Azure Monitor Baseline Alerts policy initiative flows](../../media/azure-monitor-baseline-alerts-policy-initiative-flow.svg) - -*Download a [Visio file](../../media/AMBA-Diagrams.vsdx) of this architecture.* - -If you have this management group hierarchy, you can skip forward to your preferred deployment method: - -- [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) -- [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) -- [Deploy with Azure CLI](../Deploy-with-Azure-CLI) -- [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) - -It´s important to understand why we assign initiatives to certain management groups. In the previous example, the assignment mapping was done this way because the associated resources within a subscription below a management group have a specific purpose. For example, below the Connectivity management group you will find a subscription that contains the networking components like Firewalls, Virtual WAN, Hub Networks, etc. Consequently, this is where we assign the connectivity initiative to get relevant alerting on those services. It wouldn't make sense to assign the connectivity initiative to other management groups when there are no relevant networking services deployed. - -We recognize that Azure allows for flexibility and choice, and you may not be aligned with ALZ. For example, you may have: - -- A management group structure that is not aligned to ALZ. Where you may only have a Platform management group without the sub management groups like Identity/ Management/ Connectivity. -- No management group structure. - -{{< hint type=note >}} -If you are looking to align your Azure environment to Azure landing zone, please see [Transition existing Azure environments to the Azure landing zone conceptual architecture](http://aka.ms/alz/brownfield) -{{< /hint >}} - -Suppose Identity / Management / Connectivity are combined in one Platform Management Group, the approach could be to assign the three corresponding initiatives to the Platform management group instead. Maybe you have a hierarchy where you organize by geography and/or business units instead of specific landing zones. Assignment mapping: - -- Identity Initiative is assigned to the Platform management group. -- Management Initiative is assigned to the Platform management group. -- Connectivity Initiative is assigned to the Platform management group. -- Landing Zone Initiative is assigned to the Geography management group. -- Service Health Initiative is assigned to the top-most level(s) in your management group hierarchy. - -The image below is an example of how the assignments could look like when the management group hierarchy is not aligned with ALZ. - -![Management group structure - unaligned](../../media/alz-management-groups-unaligned.png) - -We recommend that you review the [initiative definitions](https://github.com/Azure/azure-monitor-baseline-alerts/tree/main/patterns/alz/policySetDefinitions) to determine where best to apply the initiatives in your management group hierarchy. - -If you have this management group hierarchy, you can skip forward to your preferred deployment method: - -- [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) -- [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) -- [Deploy with Azure CLI](../Deploy-with-Azure-CLI) -- [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) - -If management groups were never configured in your environment, there are some additional steps that need to be implemented. To be able to deploy the policies and initiatives through the guidance and code we provide you need to create at least one management group, and by doing so the tenant root management group is created automatically. We strongly recommend following the [Azure Landing Zones guidance](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups) on management group design. - -Refer to our [documentation](https://learn.microsoft.com/en-us/azure/governance/management-groups/create-management-group-portal) on how to create management groups. - -If you implemented the recommended management group design, you can skip forward to your preferred deployment method, following the ALZ aligned guidance. - -- [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) -- [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) -- [Deploy with Azure CLI](../Deploy-with-Azure-CLI) -- [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) - -If you implemented a single management group, we recommend moving your production subscriptions into that management group, consult the steps in the [documentation](https://learn.microsoft.com/en-us/azure/governance/management-groups/manage#add-an-existing-subscription-to-a-management-group-in-the-portal) for guidance to add the subscriptions. - -{{< hint type=important >}} -To prevent unnecessary alerts, we recommend keeping development, sandbox, and other non-production subscriptions either in a different management group or below the tenant root group. -{{< /hint >}} - -The image below is an example of how the assignments look like when you are using a single management group. - -![Management group structure - single](../../media/alz-management-groups-single.png) - -## Customizing policy assignments - -As mentioned previously the above guidance will deploy policies, alerts and action groups with default settings. For details on how to customize policy and in particular initiative assignments please refer to [Customize Policy Assignment](../Customize-Policy-Assignment) - -## Customizing the AMBA policies - -Whatever way you may choose to consume the policies we do expect, and want, customers and partners to customize the policies to suit their needs and requirements for their design in their local copies of the policies. - -For example, if you want to include more thresholds, metrics, activity log alerts or similar, outside of what the parameters allow you to change and customize, then by opening the individual policy or initiative definitions you should be able to read, understand and customize the required lines to meet your requirements easily. - -This customized policy can then be deployed into your environment to deliver the desired functionality. - -### How to modify individual policies - -Policy files are stored in the 'services' folder. The **services** folder contains the baseline alert definitions, guidance, and example deployment scripts. It is grouped by resource category (for example, Compute), and then by resource type (for example, virtualMachines). The example folder structure below highlights the position of individual policy files: - -```plaintext -├── patterns -└── services - └── Compute - └── virtualMachines - ├── Deploy-VM-AvailableMemory-Alert.json - └── Deploy-VM-DataDiskReadLatency-Alert.json -``` - -To modify settings that are not parameterized, follow the steps below: - -1. Fork the repo. More info on how to fork a repo available on the [Fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) page. -2. Modify existing policies or add new ones based on your need. - {{< hint type=note >}} - Regardless you're modifying existing policies or adding new ones, you need to update the ***policies.bicep*** file. - {{< /hint >}} -3. Run the following command to update the above mentioned ***policies.bicep*** file: - - `bicep build .\patterns\alz\templates\policies.bicep --outfile .\patterns\alz\policyDefinitions\policies.json` - -4. Commit and sync the changes to your fork. -5. Deploy you local modified copy using the below command: - - ```AZ CLI - az deployment mg create --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or branchname***/patterns/alz/alzArm.json - --name "amba-GeneralDeployment" --location $location --management-group-id $pseudoRootManagementGroup --parameters .\patterns\alz\alzArm.param.json - ``` - -## Disabling Monitoring - -If you wish to disable monitoring for a resource or for alerts targeted at subscription level such as Activity Log, Service Health, and Resource Health. A "MonitorDisable" tag can be created with a value of "true" at the scope where you wish to disable monitor. This will effectively filter the resource or subscription from the compliance check for the policy. - -{{< hint type=Important >}} -If you believe the changes you have made should be more easily available to be customized by a parameter etc. in the policies, then please raise an [GitHub Issue](https://github.com/Azure/azure-monitor-baseline-alerts/issues) for a 'Feature Request' on the repository. - -If you wish to, also feel free to submit a pull request relating to the issue which we can review and work with you to potentially implement the suggestion/feature request. -{{< /hint >}} - -## Cleaning up an AMBA Deployment - -In some scenarios, it may be necessary to remove everything deployed by the ALZ Monitor solution. If you want to clean up all resources deployed, please refer to the instructions on running the [Cleaning up an AMBA Deployment](../../Cleaning-up-a-Deployment). - -## Next steps - -- To customize policy assignments, please proceed with [Customize Policy Assignment](../Customize-Policy-Assignment) -- To deploy with GitHub Actions, please proceed with [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) -- To deploy with Azure Pipelines, please proceed with [Deploy with Azure Pipelines](../Deploy-with-Azure-Pipelines) -- To deploy with Azure CLI, please proceed with [Deploy with Azure CLI](../Deploy-with-Azure-CLI) -- To deploy with Azure PowerShell, please proceed with [Deploy with Azure PowerShell](../Deploy-with-Azure-PowerShell) diff --git a/docs/content/patterns/alz/deploy/Remediate-Policies.md b/docs/content/patterns/alz/deploy/Remediate-Policies.md deleted file mode 100644 index c064d637c..000000000 --- a/docs/content/patterns/alz/deploy/Remediate-Policies.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Remediate Policies -weight: 80 ---- - -The policies are all deploy-if-not-exists, by default, meaning that any new deployments will be influenced by them. Therefore, if you are deploying in a green field scenario and will afterwards be deploying any of the covered resource types, including subscriptions, then the policies will take effect and the relevant alert rules, action groups and alert processing rules will be created. -If you are in a brownfield scenario on the other hand, policies will be reporting non-compliance for resources in scope, but to remediate non-compliant resources you will need to initiate remediation. This can be done either through the portal, on a policy-by-policy basis or you can run the *Start-AMBARemediation.ps1* script located in the *.\patterns\alz\scripts* folder to remediate all AMBA policies in scope as defined by management group pre-fix. - -{{< hint type=Important >}} -This script requires PowerShell 7.0 or higher and the following PowerShell modules: - -- [Az.Accounts](https://www.powershellgallery.com/packages/Az.Accounts) -- [Az.Resources](https://www.powershellgallery.com/packages/Az.Resources) - -{{< /hint >}} - -To use the script, do the following: - -- Log on to Azure PowerShell with an account with at least Resource Policy Contributor permissions at the pseudo-root management group level -- Navigate to the root of the cloned repo -- Set the variables -- Run the remediation script - - {{% include "PowerShell-ExecutionPolicy.md" %}} - -- For example, to remediate **Alerting-Management** initiative, assigned to the **alz-platform-management** Management Group run the following commands: - - ```powershell - #Modify the following variables to match your environment - $managementManagementGroup = "The management group id for Management" - ``` - - ```powershell - #Run the following commands to initiate remediation - .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $managementManagementGroup -policyName Alerting-Management - ``` - -- The script will return the output from the REST API calls, which should be a status code 201. If the script fails, check the error message and ensure that the management group name and policy name are correct. -- After running the script, you should be able to see a number of remediation tasks initiated at the alz-platform-management. - -For convenience, assuming that the management hierarchy is fully aligned to ALZ, below are the commands required to remediate all policies assigned through the guidance provided in this repo: - -```powershell -#Modify the following variables to match your environment -$pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" -$identityManagementGroup = "The management group id for Identity" -$managementManagementGroup = "The management group id for Management" -$connectivityManagementGroup = "The management group id for Connectivity" -$LZManagementGroup="The management group id for Landing Zones" -``` - -```powershell -#Run the following commands to initiate remediation -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName Notification-Assets -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName Alerting-ServiceHealth -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $connectivityManagementGroup -policyName Alerting-Connectivity -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $identityManagementGroup -policyName Alerting-Identity -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $managementManagementGroup -policyName Alerting-Management -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-KeyManagement -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-LoadBalancing -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-NetworkChanges -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-HybridVM -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-Storage -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-VM -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-Web -``` - -Should you need to remediate just one policy definition and not the entire policy initiative, you can run the remediation script targeted at the policy reference id that can be found under [Policy Initiatives](../../Policy-Initiatives). For example, to remediate the ***Deploy AMBA Notification Assets*** policy, run the command below: - -```powershell -#Run the following command to initiate remediation of a single policy definition -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName ALZ_AlertProcessing_Rule -``` diff --git a/docs/content/patterns/alz/deploy/parameterConfiguration.md b/docs/content/patterns/alz/deploy/parameterConfiguration.md deleted file mode 100644 index 7eca7d721..000000000 --- a/docs/content/patterns/alz/deploy/parameterConfiguration.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Parameter configuration -geekdocHidden: true ---- - -## 1. Parameter configuration - -To start, you can either download a copy of the parameter file or clone/fork the repository. - -- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-09-02/patterns/alz/alzArm.param.json) - -The following changes apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. - -- Change the value of the following parameters at the beginning of parameter file according to the instructions below: - - {{< hint type=note >}} - While it's technically possible to not add any notification information (no email, no ARM Role, no Logic App, etc.) it is strongly recommended to configure at least one option. - {{< /hint >}} - - - Change the value of _```enterpriseScaleCompanyPrefix```_ to the management group where you wish to deploy the policies and the initiatives. This is usually the so called "pseudo root management group", for example, in [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this would be the so called "Intermediate Root Management Group" (directly beneath the "Tenant Root Group"). - - Change the value of _```bringYourownUserAssignedManagedIdentity```_ to **Yes** if you have an existing user assigned managed identity with the ***Monitoring Reader*** role assigned at the pseudo root management group level or leave it to **No** if you would like to create a new one with the proper rights as part of the deployment process. - - Change the value of _```bringYourownUserAssignedManagedIdentityResourceId```_. If you set the _```bringYourownUserAssignedManagedIdentity```_ parameter to **Yes**, insert the resource id of your user assigned managed identity. If you left it with the default value of **No**, leave the value blank. - - Change the value of _```userAssignedManagedIdentityName```_ to a name of your preference. This parameter is used only if the _```bringYourownUserAssignedManagedIdentity```_ has been set to **No**. - - Change the value of _```managementSubscriptionId```_. If you set the _```bringYourownUserAssignedManagedIdentity```_ parameter to **No**, enter the subscriptionId of the management subscription, otherwise leave the default value. - - Change the value of _```ALZMonitorResourceGroupName```_ to the name of the resource group where the activity logs, resource health alerts, actions groups and alert processing rules will be deployed in. - - Change the value of _```ALZMonitorResourceGroupTags```_ to specify the tags to be added to said resource group. - - Change the value of _```ALZMonitorResourceGroupLocation```_ to specify the location for said resource group. - - Change the value of _```ALZMonitorActionGroupEmail```_ to the email address(es) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no email notification is used. - - Change the value of _```ALZLogicappResourceId```_ to the Logic app resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. - - Change the value of _```ALZLogicappCallbackUrl```_ to the Logic app callback url of the Logic app you want to use as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. To retrieve the callback url you can either use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/en-us/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic app in the Azure portal, go to _**Logic app designer**_, expand the trigger activity (_When an HTTP request is received_) and copy the value in the URL field using the 2-sheets icon. - - ![Get Logic app callback url](../../media/AMBA-LogicAppCallbackUrl.png) - - - Change the value of _```ALZArmRoleId```_ to the Azure Resource Manager Role(s) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no Azure Resource Manager Role notification is required. - - Change the value of _```ALZEventHubResourceId```_ to the Event Hubs to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Event Hubs is used. - - Change the value of _```ALZWebhookServiceUri```_ to the URI(s) to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Webhook is used. - - Change the value of _```ALZFunctionResourceId```_ to the Function resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. - - Change the value of _```ALZFunctionTriggerUrl```_ to the Function App trigger url of the function to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. To retrieve the Function App trigger url with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the menu top menu and copy the value in the URL field using the 2-sheets icon. - - ![Get function URL](../../media/AMBA-FunctionAppTriggerUrl.png) - - {{< hint type=note >}} - It is possible use multiple email addresses, as well as multiple Arm Roles, Webhooks or Event Hubs (not recommended as per ALZ guidance). Should you set multiple entries, make sure they are entered as single string with values separated by comma. Example: - - "ALZMonitorActionGroupEmail": { - "value": "action1@contoso.com , action2@contoso.com , action3@contoso.com" - }, - - "ALZArmRoleId": { - "value": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635, b24988ac-6180-42a0-ab88-20f7382dd24c" - }, - - "ALZWebhookServiceUri": { - "value": "https://webhookUri1.webhook.com, http://webhookUri2.webhook.com" - }, - {{< /hint >}} - -- If you would like to disable initiative assignments, you can change the value on one or more of the following parameters; _```enableAMBAConnectivity```_, _```enableAMBAIdentity```_, _```enableAMBALandingZone```_, _```enableAMBAManagement```_, _```enableAMBAServiceHealth```_ to _**"No"**_. - -### If you are aligned to ALZ - -- Change the value of _```platformManagementGroup```_ to the management group id for Platform. -- Change the value of _```IdentityManagementGroup```_ to the management group id for Identity. -- Change the value of _```managementManagementGroup```_ to the management group id for Management. -- Change the value of _```connectivityManagementGroup```_ to the management group id for Connectivity. -- Change the value of _```LandingZoneManagementGroup```_ to the management group id for Landing Zones. - -### If you are unaligned to ALZ - -- Change the value of _```platformManagementGroup```_ to the management group id for Platform. The same management group id may be repeated. -- Change the value of _```IdentityManagementGroup```_ to the management group id for Identity. The same management group id may be repeated. -- Change the value of _```managementManagementGroup```_ to the management group id for Management. The same management group id may be repeated. -- Change the value of _```connectivityManagementGroup```_ to the management group id for Connectivity. The same management group id may be repeated. -- Change the value of _```LandingZoneManagementGroup```_ to the management group id for Landing Zones. The same management group id may be repeated. - -{{< hint type=note >}} -For ease of deployment and maintenance we have kept the same variables. For example, if you combined Identity, Management and Connectivity into one management group you should configure the variables _```identityManagementGroup```_, _```managementManagementGroup```_ , _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the same management group id. -{{< /hint >}} - -### If you have a single management group - -- Change the value of _```platformManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```IdentityManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```managementManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```connectivityManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```LandingZoneManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". - -{{< hint type=note >}} -For ease of deployment and maintenance we have kept the same variables. Configure the variables _```enterpriseScaleCompanyPrefix```_, _```identityManagementGroup```_, _```managementManagementGroup```_, _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the pseudo root management group id. -{{< /hint >}} - -## 2. Example Parameter file - -The parameter file shown below has been truncated for brevity, compared to the samples included. - -```json -{ - "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "enterpriseScaleCompanyPrefix": { - "value": "contoso" - }, - "platformManagementGroup": { - "value": "contoso-platform" - }, - "IdentityManagementGroup": { - "value": "contoso-identity" - }, - "managementManagementGroup": { - "value": "contoso-management" - }, - "connectivityManagementGroup": { - "value": "contoso-connectivity" - }, - "LandingZoneManagementGroup": { - "value": "contoso-landingzones" - }, - "enableAMBAConnectivity": { - "value": "Yes" - }, - "enableAMBAIdentity": { - "value": "Yes" - }, - "enableAMBALandingZone": { - "value": "Yes" - }, - "enableAMBAManagement": { - "value": "Yes" - }, - "enableAMBAServiceHealth": { - "value": "Yes" - }, - "enableAMBANotificationAssets": { - "value": "Yes" - }, - "enableAMBAHybridVM": { - "value": "Yes" - }, - "telemetryOptOut": { - "value": "No" - }, - "bringYourOwnUserAssignedManagedIdentity": { - "value": "No" - }, - "bringYourOwnUserAssignedManagedIdentityResourceId": { - "value": "" - }, - "userAssignedManagedIdentityName": { - "value": "id-amba-prod-001" - }, - "managementSubscriptionId": { - "value": "" - }, - "ALZMonitorResourceGroupName": { - "value": "rg-amba-monitoring-001" - }, - "ALZMonitorResourceGroupLocation": { - "value": "eastus" - }, - "ALZMonitorResourceGroupTags": { - "value": { - "Project": "amba-monitoring" - } - } - . - . - . - . - } -} -``` From 57d73631e3a29c40527c2ce4ebb08fe7a187190f Mon Sep 17 00:00:00 2001 From: Patrisia Pascan Date: Fri, 6 Dec 2024 12:51:49 +0000 Subject: [PATCH 09/14] Updated documentation --- .../alz/Getting-started/Alerts-Details.md | 27 +++-- .../Monitoring-and-Alerting.md | 62 +++++----- .../HowTo/Bring-your-own-Managed-Identity.md | 4 +- .../alz/HowTo/Bring-your-own-Notifications.md | 18 +-- .../alz/HowTo/Cleaning-up-a-Deployment.md | 46 +++---- .../patterns/alz/HowTo/Disabling-Policies.md | 100 ++++++++-------- .../Moving-from-preview-to-GA.md | 16 +-- .../deploy/Customize-Policy-Assignment.md | 112 +++++++++--------- .../Deploy-only-Service-Health-Alerts.md | 45 +++---- .../alz/HowTo/deploy/Deploy-with-Azure-CLI.md | 23 ++-- .../deploy/Deploy-with-Azure-Pipelines.md | 23 ++-- .../deploy/Deploy-with-Azure-PowerShell.md | 36 +++--- .../deploy/Deploy-with-GitHub-Actions.md | 25 ++-- ...troduction-to-deploying-the-ALZ-Pattern.md | 12 +- .../deploy/PowerShell-ExecutionPolicy.md | 8 +- .../alz/HowTo/deploy/Remediate-Policies.md | 31 +++-- .../HowTo/deploy/parameterConfiguration.md | 21 ++-- .../patterns/alz/Overview/Whats-New.md | 76 ++++++------ 18 files changed, 336 insertions(+), 349 deletions(-) diff --git a/docs/content/patterns/alz/Getting-started/Alerts-Details.md b/docs/content/patterns/alz/Getting-started/Alerts-Details.md index 5c41b987d..d946470e1 100644 --- a/docs/content/patterns/alz/Getting-started/Alerts-Details.md +++ b/docs/content/patterns/alz/Getting-started/Alerts-Details.md @@ -4,37 +4,37 @@ geekdocCollapseSection: true weight: 30 --- -Download specific alerts for AMBA-ALZ pattern by clicking on the Download icon (highlighted in red below) in the top right corner of the page. +To download specific alerts for the AMBA-ALZ pattern, click the Download icon (highlighted in red below) in the top right corner of the page. ![Alert-Details Download icon](../../media/AlertDetailsDownloadReference.png) -To view which policy alert rules are part of the AMBA-ALZ pattern, visit the [Policy-Initiatives](../Policy-Initiatives) page. +For details on which policy alert rules are included in the AMBA-ALZ pattern, visit the [Policy-Initiatives](../Policy-Initiatives) page. -The resources, metric alerts, and their configurations serve as an initial guide to help you address key monitoring questions such as "What should we monitor in Azure?" and "What alert settings should we use?". These settings are designed to cover the most common components of an Azure Landing Zone. However, we recommend customising these settings to better align with your specific monitoring requirements and usage of Azure. +The provided resources, metric alerts, and configurations are intended as a starting point to address key monitoring questions such as "What should we monitor in Azure?" and "What alert settings should we use?". These settings cover the most common components of an Azure Landing Zone. However, we recommend customizing these settings to better suit your specific monitoring needs and Azure usage. -If you have suggestions for other resources that should be included, open an Issue on this page providing the Azure resource provider and settings you would like implemented. We can not guarantee their implementation but we will carefully consider them. Alternatively, if you would like to contribute directly, follow the steps in the [Contributor Guide](../../../../contributing). +If you have suggestions for additional resources to include, open an Issue on this page with the Azure resource provider and settings you would like to see implemented. While we cannot guarantee implementation, we will carefully consider all suggestions. Alternatively, if you wish to contribute directly, follow the steps in the [Contributor Guide](../../../../contributing). -## AMBA-ALZ pattern Metric Alerts Settings +## AMBA-ALZ Pattern Metric Alerts Settings -The values shown for Aggregation, Operator, Threshold, WindowSize, Frequency, and Severity are derived from field experience and customer implementations. Alerts are based on Microsoft public guidance where available (indicated by a 'Yes' in the Verified column) and practical application experience where public guidance is not available (indicated by a 'No' in the Verified column). Links to Product Group guidance are provided in the References column. Where no guidance is available, a link to the description of the Metric on learn.microsoft.com is included. +The values for Aggregation, Operator, Threshold, WindowSize, Frequency, and Severity are based on field experience and customer implementations. Alerts are derived from Microsoft public guidance where available (indicated by 'Yes' in the Verified column) and practical application experience where public guidance is not available (indicated by 'No' in the Verified column). Links to Product Group guidance are provided in the References column. Where no guidance is available, a link to the metric description on learn.microsoft.com is included. -The Scope column indicates where we scoped the alerts as described in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern). +The Scope column indicates where alerts are scoped as described in [Introduction to deploying the AMBA-ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern). -Only a limited number of resources support metric alert rules scoped at the subscription level, and these metric alerts are applicable only to resources deployed within the same region. The Support for Multiple Resources column indicates which resources support metric alerts at the subscription level. For a comprehensive list of resources that support metric alert rules at the subscription level, please click [here](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-types#monitor-multiple-resources). +Only a limited number of resources support metric alert rules scoped at the subscription level, and these metric alerts apply only to resources deployed within the same region. The Support for Multiple Resources column indicates which resources support metric alerts at the subscription level. For a comprehensive list of resources that support metric alert rules at the subscription level, click [here](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-types#monitor-multiple-resources). {{< hint type=note >}} -We have designed the table to minimize the need for horizontal scrolling, but it still contains a substantial amount of information. We recommend clicking on the specific alert name to directly access the JSON definition of the alert you're interested in. +The table is designed to minimize horizontal scrolling, but it contains substantial information. We recommend clicking on the specific alert name to directly access the JSON definition of the alert. {{< /hint >}} {{< alzMetricAlerts >}} -1 See "Why are the availability alert thresholds lower than 100% in this solution when the product group documentaion recommends 100%?" in the [FAQ](../../Resources/FAQ) for more details. +1 For more details on why the availability alert thresholds are lower than 100% in this solution when the product group documentation recommends 100%, see the [FAQ](../../Resources/FAQ). -## AMBA-ALZ pattern Activity Log Alerts +## AMBA-ALZ Pattern Activity Log Alerts ### Activity Log Resource Health -Refer to the following two sections to promptly identify any Service Health issues with an Azure resource. This will save you the effort of further troubleshooting and allow you to focus on communicating with your user base or incorporating these alerts into your business continuity actions (remediations). +Refer to the following sections to quickly identify any Service Health issues with an Azure resource. This will save you time troubleshooting and allow you to focus on communicating with your user base or incorporating these alerts into your business continuity actions (remediations). {{< alzActivityLogResourceHealthAlerts >}} @@ -52,7 +52,7 @@ While there is no specific guidance per resource type, the provided information ## VM Insights Log Alerts -Once VM Insights has been enabled in your environment, the following alert rules can be configured via the Baseline Alerts framework. +Once VM Insights is enabled in your environment, the following alert rules can be configured via the Baseline Alerts framework. N/A: Not applicable, not used in the query or used as a parameter. @@ -67,3 +67,4 @@ Security Alerts and Job Failure alerts are summarized in the "[Using Backup Cent | PolicyName | Component | Category | Scope | Support for Multiple Resources | Verified | References | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------|----------|--------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Deploy RV Backup Health Monitoring Alerts](../../../services/RecoveryServices/vaults/Modify-RSV-BackupHealth-Alert.json) | Microsoft.RecoveryServices/Vaults | Microsoft.RecoveryServices/vaults/monitoringSettings.classicAlertSettings.alertsForCriticalOperations | Resource | No | Y | [Azure Monitor Alerts for Azure Backup](https://learn.microsoft.com/en-us/azure/backup/backup-azure-monitoring-built-in-monitor?tabs=recovery-services-vaults#azure-monitor-alerts-for-azure-backup)
[Move to Azure Monitor Alerts](https://learn.microsoft.com/en-us/azure/backup/move-to-azure-monitor-alerts) | + diff --git a/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md b/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md index e4950437b..7584776f1 100644 --- a/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md +++ b/docs/content/patterns/alz/Getting-started/Monitoring-and-Alerting.md @@ -6,17 +6,17 @@ weight: 20 ## AMBA-ALZ Monitor Alert Approach -The overall strategy for enabling alerts in AMBA-ALZ pattern involves using Azure Policy to deploy relevant alerts as resources are created, configuring action groups, and then using Alert Processing Rules to activate alerts and link them to the action group. +The strategy for enabling alerts in the AMBA-ALZ pattern involves using Azure Policy to deploy alerts as resources are created, configuring action groups, and using Alert Processing Rules to activate alerts and link them to the action group. -There are two main principles/approaches to enabling alerting in AMBA-ALZ pattern : +There are two main approaches to enabling alerting in the AMBA-ALZ pattern: ### Centralized -In a **centralized** alerting approach, a single Action Group is used for all alerts, which means a unified alerting email (distribution group) address or other configured actions. +In a **centralized** alerting approach, a single Action Group is used for all alerts, resulting in a unified alerting email (distribution group) address or other configured actions. -Metric alerts are deployed with resources in the same resource group, while platform alerts like Service Health and Activity are created in a dedicated resource group within a subscription typically located in the Management platform management group. A single Alert Action Group in this subscription is configured with a central alerting email address and Alert Processing Rules in order to enable filters and connect alerts to the Alert Action Group. +Metric alerts are deployed with resources in the same resource group, while platform alerts like Service Health and Activity are created in a dedicated resource group within a subscription, typically located in the Management platform management group. A single Alert Action Group in this subscription is configured with a central alerting email address and Alert Processing Rules to enable filters and connect alerts to the Alert Action Group. -For example, in the context of AMBA-ALZ pattern, a single centralised action group is deployed in the "rg-amba-monitoring-001" resource group within a subscription in the Management platform management group. +For example, in the AMBA-ALZ pattern, a single centralized action group is deployed in the "rg-amba-monitoring-001" resource group within a subscription in the Management platform management group. ### Decentralized @@ -24,20 +24,20 @@ In a **decentralized** approach, each subscription has a dedicated Action Group, Metric alerts are deployed with resources in the same resource group, while platform alerts such as Service Health and Activity are created in a dedicated resource group for each subscription. Alert Action Groups are established in each landing zone subscription, allowing different operational areas and landing zone subscriptions to have distinct alerting email addresses (e.g., networking, identity, operations, workloads) or other supported actions. Alert Processing Rules are created to enable filters and connect alerts to the Action Groups. -For example, in the context of AMBA-ALZ pattern , a graphic representation of the flow is provided below. +For example, in the AMBA-ALZ pattern, a graphic representation of the flow is provided below. ![ALZ alerting](../../media/AMBA-focused-rg-alz-monitor-alert-flow.png) ### AMBA-ALZ Approach -In AMBA-ALZ pattern, a decentralized approach is adopted to provide maximum flexibility in directing alerts. For more information review [What are Azure Monitor Alerts?](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-overview). +In the AMBA-ALZ pattern, a decentralized approach is adopted to provide maximum flexibility in directing alerts. For more information, review [What are Azure Monitor Alerts?](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-overview). - Each subscription will have a single Action Group, allowing customers to configure specific actions per subscription, such as different email addresses or other supported actions. - Alert Processing Rules will target the Action Group in the subscription where the alert originated. -As this is a work in progress, the initial configuration provided by AMBA-ALZ will set up all Action Groups with the same email distribution group/address through Azure Policy. Future updates may include alternative or additional actions, such as configuring different email distribution groups based on the subscription, service, or workload owners. +Initially, AMBA-ALZ will set up all Action Groups with the same email distribution group/address through Azure Policy. Future updates may include alternative or additional actions, such as configuring different email distribution groups based on the subscription, service, or workload owners. -AMBA-ALZ Alerts, Action Groups and Alert Processing Rules are deployed using Azure Policy defined in the platform native Azure Policy JSON format. +AMBA-ALZ Alerts, Action Groups, and Alert Processing Rules are deployed using Azure Policy defined in the platform native Azure Policy JSON format. ## AMBA-ALZ Pattern Monitor Alert Policy Definitions @@ -67,14 +67,13 @@ Log alerts are scoped at the subscription level. For policies to remediate and d Service and resource health events are recorded in the activity log, allowing us to create a subset of activity log alerts that notify on health events. These alerts are scoped to each subscription and include four separate alerts for each of the service health categories: Incident, Planned Maintenance, Security Advisories, and Health Advisories. - A resource health alert will be generated for any resource that enters an unavailable or degraded state, whether platform or user-initiated. We will disregard the unknown state to avoid erroneous alerting. ## AMBA-ALZ Monitor Alert Processing Rules [Alert Processing Rules](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/alerts-processing-rules) enable the filtering of alerts and assign alerts to the appropriate action groups based on filter criteria. -As this is currently a work in progress, for AMBA-ALZ we will implement a single Action Group per subscription, and deploy a single Alert Processing Rule without filters to manage alerts via the Action Group. This approach may be revised in the future. +For AMBA-ALZ, we will implement a single Action Group per subscription and deploy a single Alert Processing Rule without filters to manage alerts via the Action Group. This approach may be revised in the future. We still need to investigate appropriate filters for Alert Processing Rules for optimal alert processing. @@ -82,7 +81,7 @@ Available filters: - Alert condition - Alert context (payload) -- Alert rule id +- Alert rule ID - Alert name - Description - Monitor service @@ -102,28 +101,29 @@ Azure Backup now provides new and improved alerting capabilities via Azure Monit ```json { - "effect": "[[parameters('effect')]", - "details": { - "roleDefinitionIds": [ - "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" - ], - "conflictEffect": "audit", - "operations": [ - { - "operation": "addOrReplace", - "field": "Microsoft.RecoveryServices/vaults/monitoringSettings.classicAlertSettings.alertsForCriticalOperations", - "value": "Disabled" - }, - { - "operation": "addOrReplace", - "field": "Microsoft.RecoveryServices/vaults/monitoringSettings.azureMonitorAlertSettings.alertsForAllJobFailures", - "value": "Enabled" - } - ] - } + "effect": "[[parameters('effect')]", + "details": { + "roleDefinitionIds": [ + "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" + ], + "conflictEffect": "audit", + "operations": [ + { + "operation": "addOrReplace", + "field": "Microsoft.RecoveryServices/vaults/monitoringSettings.classicAlertSettings.alertsForCriticalOperations", + "value": "Disabled" + }, + { + "operation": "addOrReplace", + "field": "Microsoft.RecoveryServices/vaults/monitoringSettings.azureMonitorAlertSettings.alertsForAllJobFailures", + "value": "Enabled" + } + ] + } } ``` ### Notifications While alerts are generated by default and cannot be disabled for destructive operations, users have control over the notifications. This allows you to specify the email addresses (or other notification endpoints) to which alerts should be routed. Notifications are configured by an alert processing rule, which is created by default when deploying the AMBA-ALZ pattern. + diff --git a/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md index 6664dd858..7bf8df8a0 100644 --- a/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Managed-Identity.md @@ -6,7 +6,7 @@ weight: 95 ## Overview -The ***Bring Your Own User Assigned Managed Identity*** (BYO UAMI) feature, introduced in the [2024-06-05 release](../../Overview/Whats-New#2024-06-05), enables both Greenfield and Brownfield customers to create a new User Assigned Managed Identity (UAMI) during or after the deployment of AMBA-ALZ. Additionally, Brownfield customers who deployed the ALZ pattern before this feature was available can now configure existing UAMIs by setting a few parameters. This feature allows querying Azure Resource Graph (ARG) using Kusto Query Language and enhances log-based search alerts to include ARG queries for resource tags. +The ***Bring Your Own User Assigned Managed Identity*** (BYO UAMI) feature, introduced in the [2024-06-05 release](../../Overview/Whats-New#2024-06-05), allows both Greenfield and Brownfield customers to create a new User Assigned Managed Identity (UAMI) during or after the deployment of AMBA-ALZ. Brownfield customers who deployed the ALZ pattern before this feature was available can now configure existing UAMIs by setting a few parameters. This feature enables querying Azure Resource Graph (ARG) using Kusto Query Language and enhances log-based search alerts to include ARG queries for resource tags. ## How this feature works @@ -42,7 +42,7 @@ B. ***Creating a new UAMI.*** In this scenario, the deployment will: When a new UAMI is created by the deployment template, the ***Monitoring Reader*** role is *automatically assigned at the pseudo root Management Group level during deployment*. {{< /hint >}} -- Deploy any UAMI +- Deploy a new UAMI - Assign the *Monitoring Reader* role - Set the provided UAMI as the identity to be used in the necessary alerts diff --git a/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md index 1987871f0..2848a8112 100644 --- a/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md @@ -26,9 +26,9 @@ The deployment code includes conditions that control the deployment behavior bas A. ***Use your own AGs with the AMBA APR***: -- Does not deploy the AMBA SH AG -- Deploys the AMBA APR with the customer's AGs -- Deploys SH alerts pointing to the customer's AGs +- Does not deploy the AMBA SH AG. +- Deploys the AMBA APR with the customer's AGs. +- Deploys SH alerts pointing to the customer's AGs. Example parameter file for this scenario: @@ -36,8 +36,8 @@ Example parameter file for this scenario: B. ***Use your own AGs and APR***: -- Does not deploy any AMBA notification AG or APR assets or AMBA SH AG -- Deploys SH alerts pointing to the customer's AGs +- Does not deploy any AMBA notification AG or APR assets or AMBA SH AG. +- Deploys SH alerts pointing to the customer's AGs. Example parameter file for this scenario: @@ -57,9 +57,9 @@ The [conditional deployment behavior](../Bring-your-own-Notifications#conditiona To switch, customers need to: -- Update the parameter file to match one of the three scenarios discussed -- Redeploy the ALZ pattern -- Run the remediation for both [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) and [Alerting-ServiceHealth](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-ServiceHealth-Alerts.json) policy initiatives -- Remove notification assets deployed by ALZ patterns using the [**Remove-AMBANotificationAssets.ps1**](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/scripts/Remove-AMBANotificationAssets.ps1) script (_*** only if moving from ALZ notification assets to BYON_) +- Update the parameter file to match one of the three scenarios discussed. +- Redeploy the ALZ pattern. +- Run the remediation for both [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) and [Alerting-ServiceHealth](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-ServiceHealth-Alerts.json) policy initiatives. +- Remove notification assets deployed by ALZ patterns using the [**Remove-AMBANotificationAssets.ps1**](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/scripts/Remove-AMBANotificationAssets.ps1) script (_*** only if moving from ALZ notification assets to BYON_). The code will reconfigure the Service Health alerts to use either the customer's action groups or the ALZ pattern notification assets based on the selected scenario. diff --git a/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md b/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md index c2947b5ef..9bf3c21a5 100644 --- a/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md +++ b/docs/content/patterns/alz/HowTo/Cleaning-up-a-Deployment.md @@ -4,7 +4,7 @@ geekdocCollapseSection: true weight: 70 --- -In certain situations, you may need to remove all resources deployed by the AMBA-ALZ solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all deployed resources, including: +In some cases, you may need to remove all resources deployed by the AMBA-ALZ solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all deployed resources, including: - Metric Alerts - Activity Log Alerts @@ -23,7 +23,7 @@ All resources deployed as part of the initial AMBA deployment, as well as those It is strongly advised to **thoroughly** test the script in a non-production environment before deploying it to production. These sample scripts are not covered by any Microsoft standard support program or service. They are provided "AS IS" without any warranty, express or implied. Microsoft disclaims all implied warranties, including but not limited to, implied warranties of merchantability or fitness for a particular purpose. The user assumes all risks associated with the use or performance of the sample scripts and documentation. Microsoft, its authors, or any contributors to the creation, production, or delivery of the scripts shall not be liable for any damages, including but not limited to, loss of business profits, business interruption, loss of business information, or other financial losses, arising from the use or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. {{< /hint >}} -### Download the script file +### Download the Script File To download the cleanup script file, follow these steps. Alternatively, you can clone the repository from GitHub and ensure you are working with the latest version by fetching the latest `main` branch. @@ -37,10 +37,10 @@ To download the cleanup script file, follow these steps. Alternatively, you can 1. Launch PowerShell. 2. Ensure the following modules are installed: - 1. **Az.Accounts**: if not installed, use the `Install-Module Az.Accounts` to install it - 2. **Az.Resources**: if not installed, use the `Install-Module Az.Resources` to install it - 3. **Az.ResourceGraph**: if not installed, use the `Install-Module Az.ResourceGraph` to install it - 4. **Az.ManagedServiceIdentity**: if not installed, use the `Install-Module Az.ManagedServiceIdentity` to install it + - **Az.Accounts**: if not installed, use `Install-Module Az.Accounts` to install it. + - **Az.Resources**: if not installed, use `Install-Module Az.Resources` to install it. + - **Az.ResourceGraph**: if not installed, use `Install-Module Az.ResourceGraph` to install it. + - **Az.ManagedServiceIdentity**: if not installed, use `Install-Module Az.ManagedServiceIdentity` to install it. 3. Navigate to the directory containing the **Start-ALZ-Maintenance.ps1** script. 4. Set the _**$pseudoRootManagementGroup**_ variable using the command below: @@ -51,28 +51,28 @@ To download the cleanup script file, follow these steps. Alternatively, you can 5. Sign in to your Azure account using the `Connect-AzAccount` command. Ensure that the account has the necessary permissions to remove Policy Assignments, Policy Definitions, and resources at the required Management Group scope. 6. Run the script with one of the following options: - {{% include "PowerShell-ExecutionPolicy.md" %}} + {{% include "PowerShell-ExecutionPolicy.md" %}} - **Get full help on script usage help:** + **Get full help on script usage:** - ```powershell - Get-help ./Start-AMBA-ALZ-Maintenance.ps1 - ``` + ```powershell + Get-help ./Start-AMBA-ALZ-Maintenance.ps1 + ``` - **Show output of what would happen if deletes executed:** + **Show output of what would happen if deletes executed:** - ```powershell - ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz -WhatIf - ``` + ```powershell + ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz -WhatIf + ``` - **Execute the script asking for confirmation before deleting the resources deployed by AMBA-ALZ:** + **Execute the script asking for confirmation before deleting the resources deployed by AMBA-ALZ:** - ```powershell - ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz - ``` + ```powershell + ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz + ``` - **Execute the script without asking for confirmation before deleting the resources deployed by AMBA-ALZ.** + **Execute the script without asking for confirmation before deleting the resources deployed by AMBA-ALZ:** - ```powershell - ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz -Confirm:$false - ``` + ```powershell + ./Start-AMBA-ALZ-Maintenance.ps1 -pseudoRootManagementGroup $pseudoRootManagementGroup -cleanItems Amba-Alz -Confirm:$false + ``` diff --git a/docs/content/patterns/alz/HowTo/Disabling-Policies.md b/docs/content/patterns/alz/HowTo/Disabling-Policies.md index 06f55bc92..65b019a8d 100644 --- a/docs/content/patterns/alz/HowTo/Disabling-Policies.md +++ b/docs/content/patterns/alz/HowTo/Disabling-Policies.md @@ -1,27 +1,27 @@ --- -title: Disable policies +title: Disable Policies geekdocCollapseSection: true weight: 60 --- -The AMBA-ALZ pattern offers various methods to enable or disable the effects of the policies. +The AMBA-ALZ pattern provides several methods to enable or disable policy effects. -1. **Parameter: AlertState** - Configures the state of the alert rule, enabling deployment of alert rules in a disabled state or disabling existing alert rules at scale through policy. -2. **Parameter: PolicyEffect** - Defines the effect of a Policy Definition, allowing the policy to be deployed in a disabled state. -3. **Tag: MonitorDisable** - Specifies whether a resource should be evaluated, enabling exclusion of selected resources from monitoring. +1. **Parameter: AlertState** - Manages the state of alert rules, allowing deployment in a disabled state or disabling existing alert rules at scale through policy. +2. **Parameter: PolicyEffect** - Specifies the effect of a Policy Definition, enabling deployment in a disabled state. +3. **Tag: MonitorDisable** - Determines if a resource should be monitored, allowing exclusion of specific resources from monitoring. -## AlertState parameter +## AlertState Parameter -In scenarios where it is not feasible to test alerts in a development or test environment, the AlertState parameter has been introduced for all metric alerts. This parameter, named by combining {resourceType}, {metricName}, and AlertState (e.g., VnetGwTunnelIngressAlertState), allows for the controlled disabling of one or more alerts deployed via policies. This feature is particularly useful in situations where an alert storm occurs and a rollback process is necessary as part of a change request. +When testing alerts in a development or test environment is not feasible, the AlertState parameter is used for all metric alerts. This parameter, named by combining {resourceType}, {metricName}, and AlertState (e.g., VnetGwTunnelIngressAlertState), allows controlled disabling of alerts deployed via policies. This is useful during alert storms or rollback processes. -### Allowed values +### Allowed Values - "true" - Alert rule will be enabled. (Default) - "false" - Alert rule will be disabled. -### How it works +### How It Works -The **AlertState** parameter serves dual purposes: compliance evaluation and configuring the state of the alert rule. The value assigned to the **AlertState** parameter is transferred to the **enabled** parameter, which is a component of the policy's existenceCondition. +The **AlertState** parameter is used for compliance evaluation and configuring the alert rule state. The value assigned to **AlertState** is transferred to the **enabled** parameter within the policy's existenceCondition. ```json "existenceCondition": { @@ -29,7 +29,7 @@ The **AlertState** parameter serves dual purposes: compliance evaluation and con { "field": "Microsoft.Insights/metricAlerts/criteria.Microsoft-Azure-Monitor-SingleResourceMultipleMetricCriteria.allOf[*].metricNamespace", "equals": "Microsoft.Automation/automationAccounts" -   }, + }, { "field": "Microsoft.Insights/metricAlerts/criteria.Microsoft-Azure-Monitor-SingleResourceMultipleMetricCriteria.allOf[*].metricName", "equals": "TotalJob" @@ -46,31 +46,30 @@ The **AlertState** parameter serves dual purposes: compliance evaluation and con } ``` -If "allOf" evaluates to true, the policy effect is satisfied, and the deployment does not proceed. To disable an existing alert rule, set the AlertState parameter to "false". This change causes "allOf" to evaluate as false, triggering the deployment that updates the "enabled" property of the alert rule to false. +If "allOf" evaluates to true, the policy effect is satisfied, and deployment does not proceed. To disable an alert rule, set AlertState to "false", causing "allOf" to evaluate as false and updating the "enabled" property to false. -### Deployment steps +### Deployment Steps -These are the high-level steps to disable policies: +1. Set AlertState to "false" for relevant policies via command line or parameter file. +2. Deploy the policies and assignments. +3. Identify non-compliant policies based on alerts to be disabled. Remediate these policies through the portal or use the script at [patterns/alz/scripts/Start-AMBARemediation](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBARemediation.ps1). -1. Set the AlertState parameter to "false" for the relevant policies, either via command line or parameter file. -2. Deploy the policies and assignments as previously described. -3. After deployment and policy evaluation, identify non-compliant policies based on the alerts to be disabled. Remediate these policies through the portal on a policy-by-policy basis or use the script available at [patterns/alz/scripts/Start-AMBARemediation](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBARemediation.ps1) to remediate all ALZ-Monitor policies in scope as defined by the management group prefix. +Note: This approach disables alerts but does not delete them. Delete alerts manually if needed. Ensure successful remediation before engaging PolicyEffect to avoid deploying new alerts. -Note: This approach will disable the alerts but not delete them. To delete alerts, you must do so manually. Ensure successful remediation before engaging the PolicyEffect to avoid deploying new alerts, as disabling the policy will prevent turning off alerts via policy until it is re-enabled. +## PolicyEffect Parameter -## PolicyEffect parameter +Alert rules are evaluated based on best practices, field experience, customer feedback, alert type, and potential impact. Disabling a policy can prevent unnecessary or duplicate alerts. For example, while deploying an alert rule for VPN Gateway Bandwidth Utilization, disabling alert rules for VPN Gateway Egress and Ingress prevents redundant notifications. -In practice, alert rules are evaluated based on best practices, field experience, customer feedback, alert type, and potential impact. There are scenarios where disabling a policy is beneficial to avoid unnecessary or duplicate alerts. For instance, while we deploy an alert rule for VPN Gateway Bandwidth Utilization, we have disabled the alert rules for VPN Gateway Egress and Ingress to prevent redundant notifications. The default settings are designed to offer a balanced baseline, but adjustments may be necessary to better align with your specific requirements. -### Allowed values +### Allowed Values -- "deployIfNotExists" - The policy will deploy the alert rule if the specified conditions are met. This is the default setting for most policies. -- "disabled" - The policy will be created, but it will not deploy the corresponding alert rule. +- "deployIfNotExists" - Deploys the alert rule if conditions are met. (Default) +- "disabled" - Creates the policy without deploying the alert rule. -### How it works +### How It Works -The **PolicyEffect** parameter configures the effect of the Policy Definition. In the initiatives and example parameter files, this parameter is named by combining {resourceType}, {metricName}, and PolicyEffect (e.g., ERCIRQoSDropBitsinPerSecPolicyEffect). The value assigned to the **PolicyEffect** parameter is transferred to the **effect** parameter, which determines the policy's effect. +The **PolicyEffect** parameter configures the Policy Definition effect. Named by combining {resourceType}, {metricName}, and PolicyEffect (e.g., ERCIRQoSDropBitsinPerSecPolicyEffect), the value is transferred to the **effect** parameter, determining the policy's effect. ```json "policyRule": { @@ -87,16 +86,16 @@ The **PolicyEffect** parameter configures the effect of the Policy Definition. I ] }, "then": { - "effect": "[[parameters('effect')]", + "effect": "[[parameters('effect')]" + } +} ``` -## MonitorDisable parameter +## MonitorDisable Parameter -It is also possible to exclude specific resources from monitoring. For instance, you might not want to monitor pre-production or development environments. The **MonitorDisable** parameter includes the tag name and tag value to determine whether a resource should be monitored. By default, creating a tag named **MonitorDisable** with the value **"true"** will prevent the deployment of alert rules on those resources. This can be easily adjusted to use existing tags and tag values. For example, you could configure the parameters with the tag name **Environment** and tag values such as **Production**, **Test**, or **Sandbox** to exclude resources in these environments (refer to the sample parameter section). +Exclude specific resources from monitoring by using the **MonitorDisable** parameter. By default, a tag named **MonitorDisable** with the value **"true"** prevents alert rule deployment on those resources. Adjust to use existing tags and values, such as **Environment** with values **Production**, **Test**, or **Sandbox**. ```json -. -. "ALZMonitorDisableTagName": { "value": "MonitorDisable" }, @@ -107,35 +106,34 @@ It is also possible to exclude specific resources from monitoring. For instance, "Dev", "Sandbox" ] -}, -. -. +} ``` -This deployment will implement policy definitions that will only be evaluated and remediated if the specified tag values are not present in the provided list. +This deployment evaluates and remediates policy definitions only if specified tag values are not present. -### How it works +### How It Works -The policy rule proceeds only if "allOf" evaluates to true. This means the deployment will continue as long as the tag specified by the MonitorDisableTagName parameter does not exist or does not contain any of the values listed in the MonitorDisableTagValues parameter. If the tag contains one of the specified values, the "allOf" condition will evaluate to false because the _"notIn": "[parameters('MonitorDisableTagValues')]"_ condition is not met, thereby halting the evaluation and remediation process. +The policy rule proceeds if "allOf" evaluates to true, meaning deployment continues if the tag specified by MonitorDisableTagName does not exist or does not contain any values listed in MonitorDisableTagValues. If the tag contains a specified value, "allOf" evaluates to false, halting evaluation and remediation. ```json - "policyRule": { - "if": { - "allOf": [ - { - "field": "type", - "equals": "Microsoft.Automation/automationAccounts" - }, - { - "field": "[[concat('tags[', parameters('MonitorDisableTagName'), ']')]", - "notIn": "[[parameters('MonitorDisableTagValues')]" - } - ] +"policyRule": { + "if": { + "allOf": [ + { + "field": "type", + "equals": "Microsoft.Automation/automationAccounts" }, + { + "field": "[[concat('tags[', parameters('MonitorDisableTagName'), ']')]", + "notIn": "[[parameters('MonitorDisableTagValues')]" + } + ] + } +} ``` -Given the varying resource scopes to which this method can be applied, the approach for log-based alerts differs slightly. For example, virtual machine alerts are scoped to the subscription level, and tagging the subscription would disable all targeted policies. +For log-based alerts, the approach differs slightly. For example, virtual machine alerts are scoped to the subscription level, and tagging the subscription disables all targeted policies. -With the introduction of the _**Bring Your Own User Assigned Managed Identity (BYO UAMI)**_ feature in the [2024-06-05](../../Overview/Whats-New#2024-06-05) release, and the capability to query Azure Resource Graph using Azure Monitor (refer to [Quickstart: Create alerts with Azure Resource Graph and Log Analytics](https://learn.microsoft.com/en-us/azure/governance/resource-graph/alerts-query-quickstart?tabs=azure-resource-graph)), it is now feasible to disable individual alerts for both Azure and hybrid virtual machines post-creation. This enhancement addresses requests to stop alerting for virtual machines that are offline for maintenance, providing a timely solution. +With the **Bring Your Own User Assigned Managed Identity (BYO UAMI)** feature in the [2024-06-05](../../Overview/Whats-New#2024-06-05) release, and the ability to query Azure Resource Graph using Azure Monitor (refer to [Quickstart: Create alerts with Azure Resource Graph and Log Analytics](https://learn.microsoft.com/en-us/azure/governance/resource-graph/alerts-query-quickstart?tabs=azure-resource-graph)), it is now possible to disable individual alerts for Azure and hybrid virtual machines post-creation. This addresses requests to stop alerting for virtual machines offline for maintenance. -To disable alerts for your virtual machines after they are created, ensure that you tag the relevant resources appropriately. The alert queries have been updated to reference resource properties in [Azure Resource Graph](https://learn.microsoft.com/en-us/azure/governance/resource-graph/overview). If a resource contains the specified tag name and tag value, it will be included in an exclusion list, preventing alerts from being generated for those resources. This approach allows for dynamic and rapid exclusion of necessary resources from alerts without needing to delete the alert. Simply tag the resource and run the remediation process again. +To disable alerts for virtual machines, tag the relevant resources appropriately. Updated alert queries reference resource properties in [Azure Resource Graph](https://learn.microsoft.com/en-us/azure/governance/resource-graph/overview). If a resource contains the specified tag name and value, it is included in an exclusion list, preventing alerts. This allows dynamic exclusion of resources from alerts without deleting the alert. Tag the resource and run the remediation process again. diff --git a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md index 5b6979d53..b4008cdc4 100644 --- a/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md +++ b/docs/content/patterns/alz/HowTo/UpdateToNewReleases/Moving-from-preview-to-GA.md @@ -1,9 +1,9 @@ --- -title: Moving from preview to GA +title: Transitioning from Preview to General Availability (GA) geekdocCollapseSection: true weight: 101 --- -When transitioning from the preview version to the General Availability (GA) version, it is necessary to remove all resources deployed by the ALZ Monitor solution. The following instructions provide a detailed guide on executing a PowerShell script to delete all such resources, including: +To transition from the preview version to the General Availability (GA) version of the ALZ Monitor solution, you must remove all previously deployed resources. Follow these instructions to execute a PowerShell script that deletes the following resources: - Metric Alerts - Activity Log Alerts @@ -14,15 +14,15 @@ When transitioning from the preview version to the General Availability (GA) ver - Action Groups - Alert Processing Rules -All resources deployed by the initial ALZ Monitor deployment, as well as those created dynamically by 'deploy if not exist' policies, are tagged, marked in metadata, or described (depending on resource capabilities) with `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is crucial for the cleanup script to identify and remove the resources. If this metadata has been altered or removed, the cleanup script will not recognize those resources for deletion. +All resources deployed by the ALZ Monitor solution, including those created dynamically by 'deploy if not exist' policies, are tagged or marked with `_deployed_by_alz_monitor` or `_deployed_by_alz_monitor=True`. This metadata is essential for the cleanup script to identify and remove the resources. If this metadata has been altered or removed, the script will not recognize those resources for deletion. ## Cleanup Script Execution {{< hint type=Important >}} -It is strongly advised to **thoroughly** test the script in a non-production environment before deploying it to production. These sample scripts are not covered by any Microsoft standard support program or service. They are provided "AS IS" without any warranty, express or implied. Microsoft disclaims all implied warranties, including but not limited to, implied warranties of merchantability or fitness for a particular purpose. The user assumes all risks associated with the use or performance of the sample scripts and documentation. Microsoft, its authors, or any contributors to the creation, production, or delivery of the scripts shall not be liable for any damages, including but not limited to, loss of business profits, business interruption, loss of business information, or other financial losses, arising from the use or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. +It is strongly recommended to **thoroughly** test the script in a non-production environment before deploying it to production. These sample scripts are not covered by any Microsoft standard support program or service. They are provided "AS IS" without any warranty, express or implied. Microsoft disclaims all implied warranties, including but not limited to, implied warranties of merchantability or fitness for a particular purpose. The user assumes all risks associated with the use or performance of the sample scripts and documentation. Microsoft, its authors, or any contributors to the creation, production, or delivery of the scripts shall not be liable for any damages, including but not limited to, loss of business profits, business interruption, loss of business information, or other financial losses, arising from the use or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. {{< /hint >}} -### Download the script file +### Download the Script File Follow these steps to download the cleanup script file. Alternatively, you can clone the repository from GitHub and ensure you have the latest version by fetching the `main` branch. @@ -42,13 +42,13 @@ Follow these steps to download the cleanup script file. Alternatively, you can c {{% include "PowerShell-ExecutionPolicy.md" %}} - **Generate a list of the resource IDs which would be deleted by this script:** + **Generate a list of the resource IDs that would be deleted by this script:** ```powershell ./Start-ALZMonitorCleanup.ps1 -ReportOnly ``` - **Show output of what would happen if deletes executed:** + **Show output of what would happen if deletes were executed:** ```powershell ./Start-ALZMonitorCleanup.ps1 -WhatIf @@ -60,7 +60,7 @@ Follow these steps to download the cleanup script file. Alternatively, you can c ./Start-ALZMonitorCleanup.ps1 -Force ``` -## Next steps +## Next Steps - For customizing policy assignments, refer to [Customize Policy Assignment](../../HowTo/deploy/Customize-Policy-Assignment). - For deployment using GitHub Actions, refer to [Deploy with GitHub Actions](../../HowTo/deploy/Deploy-with-GitHub-Actions). diff --git a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md index cf8c46da7..386394ffb 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md +++ b/docs/content/patterns/alz/HowTo/deploy/Customize-Policy-Assignment.md @@ -6,95 +6,95 @@ weight: 20 ## Introduction -The policies and initiatives in this repository can be deployed using their default configurations, as described in [Introduction to deploying the AMBA-ALZ pattern](../Introduction-to-deploying-the-ALZ-Pattern). These default settings are intended for general use. However, there may be scenarios where you need to adjust the initiative assignment for specific policies to meet your monitoring requirements or to implement alerts gradually in an existing environment. This document outlines various scenarios and provides guidance on how to modify these assignments. +This document provides guidance on customizing policy assignments for the policies and initiatives in this repository. While default configurations are available as described in [Introduction to deploying the AMBA-ALZ pattern](../Introduction-to-deploying-the-ALZ-Pattern), you may need to adjust these settings to meet specific monitoring requirements or to implement alerts incrementally in an existing environment. -## Modify initiative assignment +## Modify Initiative Assignment -When assigning initiatives, you may need to adjust alert thresholds for one or more metric alerts. This can be achieved by specifying the relevant parameters in a parameter file. For your convenience, we provide a comprehensive parameter file that includes all configurable parameters for each initiative. It is recommended to use this file as a template to create your own parameter file, as the parameters may change over time, potentially affecting your alert configurations. +To adjust alert thresholds for one or more metric alerts, specify the relevant parameters in a parameter file. A comprehensive parameter file template is provided, which includes all configurable parameters for each initiative. Use this template to create your own parameter file, as parameters may change over time, potentially affecting your alert configurations. -### Parameter file +### Parameter File -We provide you with 2 versions of the parameter file: +Two versions of the parameter file are available: -1. [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-11-01/patterns/alz/alzArm.param.json) aligned to the latest release -2. [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/alzArm.param.json) aligned to the main branch +1. [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-11-01/patterns/alz/alzArm.param.json) aligned with the latest release. +2. [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/alzArm.param.json) aligned with the main branch. -### Applying changes to the parameter file +### Applying Changes to the Parameter File -To adjust the threshold values for Virtual Network Gateway Express Route CPU utilization from the default value of 80 to 90, and for Virtual Network Gateway Egress traffic from 1 to 1000, you need to include these changes in a parameter file as demonstrated below. These specific thresholds will be applied to the individual policy assignment, while all other policy values will remain at their default settings. Note that the parameter file shown below is truncated for brevity compared to the full samples provided. +To adjust the threshold values for Virtual Network Gateway Express Route CPU utilization from 80 to 90, and for Virtual Network Gateway Egress traffic from 1 to 1000, include these changes in a parameter file as shown below. These specific thresholds will apply to the individual policy assignment, while all other policy values will remain at their default settings. Note that the parameter file shown below is truncated for brevity. {{< hint type=Note >}} -The parameter file includes the default values as documented. However, the _Policy assignment parameter reference type_ will change for all parameters when using the template parameter file. Even if a parameter's value remains unmodified, it will be marked as a _User defined parameter_ after deployment because it is explicitly defined in the parameter file. To prevent this, you can create custom parameter files that only include the parameters you wish to modify. +The parameter file includes default values as documented. However, the _Policy assignment parameter reference type_ will change for all parameters when using the template parameter file. Even if a parameter's value remains unmodified, it will be marked as a _User defined parameter_ after deployment because it is explicitly defined in the parameter file. To prevent this, create custom parameter files that only include the parameters you wish to modify. {{< /hint >}} ```json { - "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "enterpriseScaleCompanyPrefix": { - "value": "contoso" + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "enterpriseScaleCompanyPrefix": { + "value": "contoso" + }, + "policyAssignmentParametersCommon": { + "value": { + "ALZMonitorResourceGroupName": { + "value": "rg-amba-monitoring-001" }, - "policyAssignmentParametersCommon": { - "value": { - "ALZMonitorResourceGroupName": { - "value": "rg-amba-monitoring-001" - }, - "ALZMonitorResourceGroupTags": { - "value": { - "Project": "amba-monitoring" - } - }, - "ALZMonitorResourceGroupLocation": { - "value": "eastus" - } - } + "ALZMonitorResourceGroupTags": { + "value": { + "Project": "amba-monitoring" + } }, - "policyAssignmentParametersConnectivity": { - "value": { - "VnetGwERCpuUtilThreshold": { - "value": "90" - }, - "VnetGwTunnelEgressThreshold": { - "value": "1000" - } - } + "ALZMonitorResourceGroupLocation": { + "value": "eastus" } + } + }, + "policyAssignmentParametersConnectivity": { + "value": { + "VnetGwERCpuUtilThreshold": { + "value": "90" + }, + "VnetGwTunnelEgressThreshold": { + "value": "1000" + } + } } + } } ``` -### Metric alert policy parameters +### Metric Alert Policy Parameters The following parameters can be modified for metric alert policies. In the initiatives, these parameters are prefixed with a specific string to denote the relevant metric. | **Parameter Name** | **Parameter Description** | -|----------|----------| -| severity | 0 - 4 indicating alert severity | -| windowSize | Indicating the time window where the alert performs the true/false evaluation | -| evaluationFrequency | Indicating how often evaluation takes place inside the time window | -| effect | Can be either DeployIfNotExists or Disabled (modify is allowed for the recovery services vault alert) | -| autoMitigate | Indicates whether the the alert will auto-resolve if the alert condition is no longer true | -| threshold | Indicates a numerical threshold for when the alert would trigger. Not relevant to all alerts as some are configured with dynamic rather than fixed thresholds | -| enabled | Whether the alert is enabled or not | +|--------------------|---------------------------| +| severity | 0 - 4 indicating alert severity | +| windowSize | Time window for alert evaluation | +| evaluationFrequency| Frequency of evaluation within the time window | +| effect | DeployIfNotExists or Disabled (modify allowed for recovery services vault alert) | +| autoMitigate | Whether the alert auto-resolves if the condition is no longer true | +| threshold | Numerical threshold for alert trigger (not relevant to all alerts) | +| enabled | Whether the alert is enabled or not | -### Activity log, Service health alert and action group policy parameters +### Activity Log, Service Health Alert, and Action Group Policy Parameters -The following parameters can be changed for activity log, service health alert and action group policies. +The following parameters can be changed for activity log, service health alert, and action group policies. | **Parameter Name** | **Parameter Description** | -|----------|----------| -| ALZMonitorResourceGroupName | The name of the resource group for the alerts | -| ALZMonitorResourceGroupTags | Any tags than need to be added to the resource group created | -| ALZMonitorResourceGroupLocation | The location of the resource group for the alerts | +|--------------------|---------------------------| +| ALZMonitorResourceGroupName | Name of the resource group for the alerts | +| ALZMonitorResourceGroupTags | Tags to be added to the resource group | +| ALZMonitorResourceGroupLocation | Location of the resource group for the alerts | -The parameters mentioned above specify the resource group where activity log alerts will be placed. If the resource group does not exist, it will be created. The `tags` parameter can accept multiple tags if needed, but tags are only applied at the resource group level. By default, the `tags` parameter is set to a single tag with the name *environment* and the value *test*. You can add more tags as required or leave it empty. +These parameters specify the resource group where activity log alerts will be placed. If the resource group does not exist, it will be created. The `tags` parameter can accept multiple tags if needed, but tags are only applied at the resource group level. By default, the `tags` parameter is set to a single tag with the name *environment* and the value *test*. You can add more tags as required or leave it empty. ### Disabling Policies -To review the options for disabling policies, visit [Disabling Policies](../../Disabling-Policies) +For options on disabling policies, visit [Disabling Policies](../../Disabling-Policies). -## Next steps +## Next Steps - To deploy using Azure Portal UI, visit [Deploy via the Azure Portal (Preview)](../Deploy-via-Azure-Portal-UI) - To deploy with GitHub Actions, visit [Deploy with GitHub Actions](../Deploy-with-GitHub-Actions) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md index 8035c1d81..a6541e8ba 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-only-Service-Health-Alerts.md @@ -31,19 +31,19 @@ The following changes apply to all scenarios, whether you are aligned or unalign - Change the value of the following parameters at the beginning of the parameter file according to the instructions below: {{< hint type=note >}} - While it's technically possible to not add any notification information (no email, no ARM Role, no Logic App, etc.) it is strongly recommended to configure at least one option. + While it's technically possible to not add any notification information (no email, no ARM Role, no Logic App, etc.) it is recommended to configure at least one option. {{< /hint >}} - Change the value of _```enterpriseScaleCompanyPrefix```_ to the management group where you wish to deploy the policies and the initiatives. This is usually the so called "pseudo root management group", for example, in [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this would be the so called "Intermediate Root Management Group" (directly beneath the "Tenant Root Group"). - Change the value of _```bringYourownUserAssignedManagedIdentity```_ to **Yes** if you have an existing user assigned managed identity with the ***Monitoring Reader*** role assigned at the pseudo root management group level or leave it to **No** if you would like to create a new one with the proper rights as part of the deployment process. - - Change the value of _```bringYourownUserAssignedManagedIdentityResourceId```_. If you set the _```bringYourownUserAssignedManagedIdentity```_ parameter to **Yes**, insert the resource id of your user assigned managed identity. If you left it with the default value of **No**, leave the value blank. + - Change the value of _```bringYourownUserAssignedManagedIdentityResourceId```_. If you set the _```bringYourownUserAssignedManagedIdentity```_ parameter to **Yes**, insert the resource ID of your user assigned managed identity. If you left it with the default value of **No**, leave the value blank. - Change the value of _```userAssignedManagedIdentityName```_ to a name of your preference. This parameter is used only if the _```bringYourownUserAssignedManagedIdentity```_ has been set to **No**. - Change the value of _```managementSubscriptionId```_. If you set the _```bringYourownUserAssignedManagedIdentity```_ parameter to **No**, enter the subscriptionId of the management subscription, otherwise leave the default value. - Change the value of _```ALZMonitorResourceGroupName```_ to the name of the resource group where the activity logs, resource health alerts, actions groups and alert processing rules will be deployed in. - Change the value of _```ALZMonitorResourceGroupTags```_ to specify the tags to be added to said resource group. - Change the value of _```ALZMonitorResourceGroupLocation```_ to specify the location for said resource group. - Change the value of _```ALZMonitorActionGroupEmail```_ to the email address(es) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no email notification is used. - - Change the value of _```ALZLogicappResourceId```_ to the Logic app resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. + - Change the value of _```ALZLogicappResourceId```_ to the Logic app resource ID to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. - Change the value of _```ALZLogicappCallbackUrl```_ to the Logic app callback url of the Logic app you want to use as action for the alerts (including Service Health alerts). Leave the value blank if no Logic app is used. To retrieve the callback url you can either use the [_**Get-AzLogicAppTriggerCallbackUrl**_](https://learn.microsoft.com/en-us/powershell/module/az.logicapp/get-azlogicapptriggercallbackurl) PowerShell command or navigate to the Logic app in the Azure portal, go to _**Logic app designer**_, expand the trigger activity (_When an HTTP request is received_) and copy the value in the URL field using the 2-sheets icon. ![Get Logic app callback url](../../../media/AMBA-LogicAppCallbackUrl.png) @@ -51,7 +51,7 @@ The following changes apply to all scenarios, whether you are aligned or unalign - Change the value of _```ALZArmRoleId```_ to the Azure Resource Manager Role(s) where notifications of the alerts (including Service Health alerts) are sent to. Leave the value blank if no Azure Resource Manager Role notification is required. - Change the value of _```ALZEventHubResourceId```_ to the Event Hubs to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Event Hubs is used. - Change the value of _```ALZWebhookServiceUri```_ to the URI(s) to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Webhook is used. - - Change the value of _```ALZFunctionResourceId```_ to the Function resource id to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. + - Change the value of _```ALZFunctionResourceId```_ to the Function resource ID to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. - Change the value of _```ALZFunctionTriggerUrl```_ to the Function App trigger url of the function to be used as action for the alerts (including Service Health alerts). Leave the value blank if no Function is used. To retrieve the Function App trigger url with the corresponding code, navigate to the HTTP-triggered functions in the Azure portal, go to _**Code + Test**_, select **Get function URL** from the menu top menu and copy the value in the URL field using the 2-sheets icon. ![Get function URL](../../../media/AMBA-FunctionAppTriggerUrl.png) @@ -87,19 +87,20 @@ The following changes apply to all scenarios, whether you are aligned or unalign #### If you are aligned to ALZ -- Change the value of _```platformManagementGroup```_ to the management group id for Platform. -- Change the value of _```IdentityManagementGroup```_ to the management group id for Identity. -- Change the value of _```managementManagementGroup```_ to the management group id for Management. -- Change the value of _```connectivityManagementGroup```_ to the management group id for Connectivity. -- Change the value of _```LandingZoneManagementGroup```_ to the management group id for Landing Zones. +- Change the value of _```platformManagementGroup```_ to the management group ID for Platform. +- Change the value of _```IdentityManagementGroup```_ to the management group ID for Identity. +- Change the value of _```managementManagementGroup```_ to the management group ID for Management. +- Change the value of _```connectivityManagementGroup```_ to the management group ID for Connectivity. +- Change the value of _```LandingZoneManagementGroup```_ to the management group ID for Landing Zones. #### If you are unaligned to ALZ -- Change the value of _```platformManagementGroup```_ to the management group id for Platform. The same management group id may be repeated. -- Change the value of _```IdentityManagementGroup```_ to the management group id for Identity. The same management group id may be repeated. -- Change the value of _```managementManagementGroup```_ to the management group id for Management. The same management group id may be repeated. -- Change the value of _```connectivityManagementGroup```_ to the management group id for Connectivity. The same management group id may be repeated. -- Change the value of _```LandingZoneManagementGroup```_ to the management group id for Landing Zones. The same management group id may be repeated. +- Change the value of _```platformManagementGroup```_ to the management group ID for Platform. The same management group ID may be repeated. +- Change the value of _```IdentityManagementGroup```_ to the management group ID for Identity. The same management group ID may be repeated. +- Change the value of _```IdentityManagementGroup```_ to the management group ID for Identity. The same management group ID may be repeated. +- Change the value of _```managementManagementGroup```_ to the management group ID for Management. The same management group ID may be repeated. +- Change the value of _```connectivityManagementGroup```_ to the management group ID for Connectivity. The same management group ID may be repeated. +- Change the value of _```LandingZoneManagementGroup```_ to the management group ID for Landing Zones. The same management group ID may be repeated. {{< hint type=note >}} For ease of deployment and maintenance we have kept the same variables. For example, if you combined Identity, Management and Connectivity into one management group you should configure the variables _```identityManagementGroup```_, _```managementManagementGroup```_ , _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the same management group id. @@ -107,14 +108,14 @@ For ease of deployment and maintenance we have kept the same variables. For exam #### If you have a single management group -- Change the value of _```platformManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```IdentityManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```managementManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```connectivityManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". -- Change the value of _```LandingZoneManagementGroup```_ to the pseudo root management group id, also called the "Intermediate Root Management Group". +- Change the value of _```platformManagementGroup```_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". +- Change the value of _```IdentityManagementGroup```_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". +- Change the value of _```managementManagementGroup```_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". +- Change the value of _```connectivityManagementGroup```_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". +- Change the value of _```LandingZoneManagementGroup```_ to the pseudo root management group ID, also called the "Intermediate Root Management Group". {{< hint type=note >}} -For ease of deployment and maintenance we have kept the same variables. Configure the variables _```enterpriseScaleCompanyPrefix```_, _```identityManagementGroup```_, _```managementManagementGroup```_, _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the pseudo root management group id. +For ease of deployment and maintenance we have kept the same variables. Configure the variables _```enterpriseScaleCompanyPrefix```_, _```identityManagementGroup```_, _```managementManagementGroup```_, _```connectivityManagementGroup```_ and _```LZManagementGroup```_ with the pseudo root management group ID. {{< /hint >}} ### 2. Example Parameter file @@ -230,13 +231,13 @@ The parameter file shown below has been truncated for brevity, compared to the s ### 3. Configuring variables for deployment -Open your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), and navigate to the root of the cloned repo and log on to Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and Policy Set Definitions. +Open your preferred command-line tool (Windows PowerShell, Cmd, Bash or other Unix shells), and navigate to the root of the cloned repo and log into Azure with an account with at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and Policy Set Definitions. Run the following commands: ```bash location="Your Azure location of choice" -pseudoRootManagementGroup="The pseudo root management group id parenting the Platform and Landing Zones management groups" +pseudoRootManagementGroup="The pseudo root management group ID parenting the Platform and Landing Zones management groups" ``` {{< hint type=Important >}} diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md index 3445eca92..115945822 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-CLI.md @@ -5,32 +5,32 @@ weight: 30 {{% include "parameterConfiguration.md" %}} -## 3. Configuring variables for deployment +## 3. Configuring Variables for Deployment -The following commands are applicable to all scenarios, regardless of whether you are aligned with ALZ, unaligned, or managing a single management group. +The following commands are applicable to all scenarios, whether aligned with ALZ, unaligned, or managing a single management group. -Open your preferred command-line tool (Windows PowerShell, Cmd, Bash, or other Unix shells) and navigate to the root directory of the cloned repository. Log in to Azure using an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where the policies and initiatives will be created. +Open your preferred command-line tool (Windows PowerShell, Cmd, Bash, or other Unix shells) and navigate to the root directory of the cloned repository. Log in to Azure using an account with at least Resource Policy Contributor access at the root of the management group hierarchy where the policies and initiatives will be created. -Run the following commands: +Execute the following commands: ```bash location="Your Azure location of choice" -pseudoRootManagementGroup="The pseudo root management group ID parenting the identity, management and connectivity management groups" +pseudoRootManagementGroup="The pseudo root management group ID parenting the identity, management, and connectivity management groups" ``` {{< hint type=Important >}} When executing Azure CLI commands from PowerShell, ensure that variables are prefixed with a `$` symbol. -The `pseudoRootManagementGroup` variable should _match_ the value of the `enterpriseScaleCompanyPrefix` parameter, as defined in the parameter files. +The `pseudoRootManagementGroup` variable should match the value of the `enterpriseScaleCompanyPrefix` parameter, as defined in the parameter files. The `location` variable specifies the deployment region. It is not required to deploy to multiple regions as the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} ## 4. Deploying AMBA-ALZ -The following commands are applicable to all scenarios, whether you are aligned with ALZ, unaligned, or managing a single management group. +The following commands are applicable to all scenarios, whether aligned with ALZ, unaligned, or managing a single management group. -Use your preferred command-line tool (Windows PowerShell, Cmd, Bash, or other Unix shells), to navigate to the root directory of the cloned repository. Log in to Azure using an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where the policies and initiatives will be created. +Use your preferred command-line tool (Windows PowerShell, Cmd, Bash, or other Unix shells) to navigate to the root directory of the cloned repository. Log in to Azure using an account with at least Resource Policy Contributor access at the root of the management group hierarchy where the policies and initiatives will be created. {{< hint type=note >}} For testing purposes, it is recommended to deploy in a safe environment first. When preparing for a production deployment, refer to the [Customize Policy Assignment](../Customize-Policy-Assignment) guide to deploy and enable alerts in a controlled and secure manner. @@ -38,8 +38,7 @@ For testing purposes, it is recommended to deploy in a safe environment first. W If you have customized the policies as described in [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), ensure that you run the deployment command using your own repository and branch in the `--template-uri` parameter. For example: ```bash - az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main - or branchname***/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" + az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or branchname***/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" ``` {{< /hint >}} @@ -48,6 +47,6 @@ If you have customized the policies as described in [How to modify individual po az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/2024-11-01/patterns/alz/alzArm.json --location $location --management-group-id $pseudoRootManagementGroup --parameters ".\patterns\alz\alzArm.param.json" ``` -## Next steps +## Next Steps -To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) +To remediate non-compliant policies, continue with [Policy Remediation](../Remediate-Policies) diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md index 789ed226f..0cdab9cbc 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-Pipelines.md @@ -5,9 +5,9 @@ weight: 50 {{% include "parameterConfiguration.md" %}} -## 3. Configure and run the pipeline +## 3. Configure and Run the Pipeline -First, set up your Azure DevOps project to use a pipeline hosted on GitHub by following the instructions [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/github?view=azure-devops&tabs=yaml#access-to-github-repositories). Ensure the pipeline is configured to use the [sample-pipeline.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-pipeline.yml) file. +To begin, configure your Azure DevOps project to use a pipeline hosted on GitHub by following the instructions [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/repos/github?view=azure-devops&tabs=yaml#access-to-github-repositories). Ensure the pipeline is set up to use the [sample-pipeline.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-pipeline.yml) file. {{< hint type=note >}} If you have customized the policies as described in [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), ensure that the **inlineScript** in the pipeline file points to your repository and branch. For example: @@ -19,22 +19,21 @@ If you have customized the policies as described in [How to modify individual po {{< /hint >}} -Additionally, in your Azure DevOps project, set up a service connection to your Azure subscription by following the instructions in the [Connect to Azure by using an Azure Resource Manager service connection](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&tabs=yaml) guide. Ensure that the service connection targets the intermediate root management group for ALZ-aligned deployments or the specific management group where you intend to deploy the policies and initiatives for ALZ-unaligned deployments. +Additionally, configure a service connection to your Azure subscription in your Azure DevOps project by following the instructions in the [Connect to Azure by using an Azure Resource Manager service connection](https://docs.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops&tabs=yaml) guide. Ensure that the service connection targets the intermediate root management group for ALZ-aligned deployments or the specific management group where you intend to deploy the policies and initiatives for ALZ-unaligned deployments. -### Modify variables and run the pipeline +### Modify Variables and Run the Pipeline -- Modify the following values in [sample-pipeline.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-pipeline.yml): - - Change _Location: "norwayeast"_, to your preferred Azure region - - Change _ManagementGroupPrefix: "alz"_, to the pseudo root management -- Go to Azure Pipelines and run the pipeline created. +- Update the following values in [sample-pipeline.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-pipeline.yml): + - Change _Location: "norwayeast"_ to your preferred Azure region. + - Change _ManagementGroupPrefix: "alz"_ to the pseudo root management group. +- Navigate to Azure Pipelines and run the created pipeline. {{< hint type=important >}} -Ensure that the value of the `ManagementGroupPrefix` variable matches the `parPolicyPseudoRootMgmtGroup` parameter value set in the parameter files. This alignment is crucial for the correct deployment of policies. - +Ensure that the `ManagementGroupPrefix` variable matches the `parPolicyPseudoRootMgmtGroup` parameter value set in the parameter files. This alignment is crucial for the correct deployment of policies. The `Location` variable specifies the deployment region. It is not required to deploy to multiple regions since the policy definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} -## Next steps +## Next Steps -To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) +To remediate non-compliant policies, proceed with [Policy remediation](../Remediate-Policies). diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md index cbaeee0eb..a5ffcf1c9 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-Azure-PowerShell.md @@ -5,57 +5,55 @@ weight: 40 {{% include "parameterConfiguration.md" %}} -## 3. Configuring variables for deployment +## 3. Configuring Variables for Deployment -The following steps apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. +These steps are applicable to all scenarios, whether aligned or unaligned with ALZ, or if you have a single management group. -Open a PowerShell prompt and navigate to the root of the cloned repository. Log in to Azure with an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. +1. Open a PowerShell prompt and navigate to the root of the cloned repository. +2. Log in to Azure with an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. -Run the following commands: +Execute the following commands: ```powershell $location = "Your Azure location of choice" -$pseudoRootManagementGroup = "The pseudo root management group id parenting the identity, management and connectivity management groups" +$pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management, and connectivity management groups" ``` {{< hint type=important >}} -The `pseudoRootManagementGroup` variable must _match_ the value of the `parPolicyPseudoRootMgmtGroup` parameter as defined in the parameter files. +The `pseudoRootManagementGroup` variable must match the value of the `parPolicyPseudoRootMgmtGroup` parameter as defined in the parameter files. The `location` variable specifies the deployment region. It is not required to deploy to multiple regions since the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} -## 4. Deploy the policy definitions, initiatives and policy assignments with default settings +## 4. Deploy Policy Definitions, Initiatives, and Policy Assignments with Default Settings -{{< hint type=Important >}} +{{< hint type=important >}} Deploying through PowerShell requires authentication to Azure and the following modules: - Az.Accounts - Az.Resources -Before starting the deployment, ensure you logged in using the Connect-AzAccount PowerShell command and that the modules above have been imported. +Before starting the deployment, ensure you have logged in using the `Connect-AzAccount` PowerShell command and that the modules above have been imported. {{< /hint >}} -The following steps apply to all scenarios, whether you are aligned or unaligned with ALZ or have a single management group. +These steps are applicable to all scenarios, whether aligned or unaligned with ALZ, or if you have a single management group. If you have closed your previous session, open a PowerShell prompt and navigate to the root of the cloned repository. Log in to Azure with an account that has at least Resource Policy Contributor access at the root of the management group hierarchy where you will be creating the policies and initiatives. Then, run the following command: {{< hint type=note >}} For testing purposes, it is recommended to deploy in a safe environment first. When preparing for production deployment, refer to the [Customize Policy Assignment](../Customize-Policy-Assignment) guide to deploy and enable alerts in a controlled manner. -If you have customized the policies as described in [How to modify individual policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), ensure that you run the deployment command using your own repository and branch in the _**-TemplateUri**_ parameter. For example: - - ```PowerShell - New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location - -TemplateUri "https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or branchname***/patterns/alz/alzArm.json" - -TemplateParameterFile ".\patterns\alz\alzArm.param.json" - ``` +If you have customized the policies as described in [How to Modify Individual Policies](../Introduction-to-deploying-the-ALZ-Pattern#how-to-modify-individual-policies), ensure that you run the deployment command using your own repository and branch in the `-TemplateUri` parameter. For example: +```powershell +New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location -TemplateUri "https://raw.githubusercontent.com/***YourGithubFork***/azure-monitor-baseline-alerts/***main or branchname***/patterns/alz/alzArm.json" -TemplateParameterFile ".\patterns\alz\alzArm.param.json" +``` {{< /hint >}} ```powershell New-AzManagementGroupDeployment -Name "amba-GeneralDeployment" -ManagementGroupId $pseudoRootManagementGroup -Location $location -TemplateUri "https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/2024-11-01/patterns/alz/alzArm.json" -TemplateParameterFile ".\patterns\alz\alzArm.param.json" ``` -## Next steps +## Next Steps -To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) +To remediate non-compliant policies, continue with [Policy Remediation](../Remediate-Policies). diff --git a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md index fa850da99..04ea846d1 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md +++ b/docs/content/patterns/alz/HowTo/deploy/Deploy-with-GitHub-Actions.md @@ -5,11 +5,11 @@ weight: 60 {{% include "parameterConfiguration.md" %}} -## 3. Configure and run the workflow +## 3. Configure and Run the Workflow First, configure your OpenID Connect as described [here](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Cwindows#use-the-azure-login-action-with-openid-connect). -To deploy through GitHub actions, refer to the [sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml). +To deploy using GitHub Actions, refer to the [sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml). {{< hint type=note >}} If you have customized the policies as described in [How to modify individual policies](./Introduction-to-deploying-the-ALZ-Pattern.md#how-to-modify-individual-policies), ensure that the workflow file's **run** command points to your specific repository and branch. For example: @@ -18,27 +18,26 @@ If you have customized the policies as described in [How to modify individual po run: | az deployment mg create --name "amba-GeneralDeployment" --template-uri https://raw.githubusercontent.com/___YourGithubFork___/azure-monitor-baseline-alerts/___MainOrBranchname___/patterns/alz/alzArm.json --location ${{ env.Location }} --management-group-id ${{ env.ManagementGroupPrefix }} --parameters .\patterns\alz\alzArm.param.json ``` - {{< /hint >}} -### Modify variables and run the workflow +### Modify Variables and Run the Workflow -- Modify the following values in [amba-sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml): - - Change _Location: "norwayeast"_, to your preferred Azure region - - Change _ManagementGroupPrefix: "alz"_, to the pseudo root management group ID parenting the identity, management and connectivity management groups -- Save the customized [amba-sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml) in the _**.github/workflow**_ folder +- Update the following values in [amba-sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml): + - Change _Location: "norwayeast"_ to your preferred Azure region. + - Change _ManagementGroupPrefix: "alz"_ to the pseudo root management group ID that parents the identity, management, and connectivity management groups. +- Save the customized [amba-sample-workflow.yml](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/examples/sample-workflow.yml) in the _**.github/workflow**_ folder. {{< hint type=important >}} - The file name _**must** perfectly_ match the name at line **1** of the sample file. You may eventually replace spaces with **-** + The file name _**must** perfectly_ match the name at line **1** of the sample file. You may replace spaces with **-** if necessary. {{< /hint >}} ![Workflow file name](../../../media/WorkflowFileName.png) ![Workflow saved](../../../media/WorkflowSaved.png) - For additional details on workflows, refer to the GitHub documentation: [Creating starter workflows for your organization](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization) + For additional details on workflows, refer to the GitHub documentation: [Creating starter workflows for your organization](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization). -- Visit GitHub actions and run the action _**Deploy AMBA**_ +- Visit GitHub Actions and run the action _**Deploy AMBA**_. ![Deploy AMBA action](../../../media/DeployAmbaAction.png) @@ -48,6 +47,6 @@ The value of the "ManagementGroupPrefix" variable, referred to as the "pseudo ro The `Location` variable specifies the deployment region. It is not required to deploy to multiple regions since the definitions and assignments are scoped to a management group and are not region-specific. {{< /hint >}} -## Next steps +## Next Steps -To remediate non-compliant policies, continue with [Policy remediation](../Remediate-Policies) +To remediate non-compliant policies, continue with [Policy Remediation](../Remediate-Policies). diff --git a/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md b/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md index 1ce867a1e..ba7aac543 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md +++ b/docs/content/patterns/alz/HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern.md @@ -38,7 +38,7 @@ Alerts, action groups, and alert processing rules are created as follows: While it is recommended to implement the alert policies and initiatives within an ALZ Management Group hierarchy, it is not a strict technical requirement. Avoid assigning policies to the Tenant Root Group to minimize debugging inherited policies at lower-level management groups (refer to the [CAF documentation](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups)). These policies and initiatives can also be applied in existing brownfield scenarios that do not follow the ALZ Management Group hierarchy, such as hierarchies with a single management group or those that do not align with ALZ. At least one management group is required. If management groups have not been implemented, guidance on how to get started is provided. {{< /hint >}} -## Getting started +## Getting Started - Fork this repository to your own GitHub organization. Do not create a direct clone of the repository, as pull requests from direct clones will not be accepted. - Clone the repository from your GitHub organization to your local development environment. @@ -50,7 +50,7 @@ While it is recommended to implement the alert policies and initiatives within a - [Manual deployment with Azure CLI](../Deploy-with-Azure-CLI) - [Manual deployment with Azure PowerShell](../Deploy-with-Azure-PowerShell) -### Determining your management group hierarchy +### Determining your Management Group Hierarchy Azure Landing Zones provide a framework of best practices, patterns, and tools for establishing a secure, Well-Architected, and manageable cloud environment. A crucial element of Azure Landing Zones is the use of management groups, which enable the organization and management of subscriptions and resources in a hierarchical structure. Management groups facilitate the application of policies and access controls across multiple subscriptions and resources, simplifying the governance and management of your Azure environment. @@ -137,11 +137,11 @@ The following image illustrates an example of how the assignments appear when ut ![Management group structure - single](../../../media/alz-management-groups-single.png) -## Customizing policy assignments +## Customizing Policy Assignments For instructions on customizing policy and initiative assignments, please refer to [Customize Policy Assignment](../Customize-Policy-Assignment). -## Customizing the AMBA-ALZ policies +## Customizing the AMBA-ALZ Policies We encourage customers and partners to tailor the policies to meet their specific needs and requirements. Customize the policies in your local copies to align with your design preferences. @@ -149,7 +149,7 @@ If you need to include additional thresholds, metrics, or activity log alerts be You can then deploy this customized policy into your environment to achieve the desired functionality. -### How to modify individual policies +### How to Modify Individual Policies Policy files are located in the `services` directory. This directory contains baseline alert definitions, guidance, and example deployment scripts. The structure is organized by resource category (e.g., Compute) and then by resource type (e.g., virtualMachines). The example folder structure below shows the location of individual policy files: @@ -195,7 +195,7 @@ If you have suggestions or feature requests, consider submitting a pull request. In certain situations, you may need to remove all resources deployed by the AMBA-ALZ solution. For detailed instructions on how to clean up an AMBA-ALZ deployment, refer to the [Cleaning up an AMBA-ALZ Deployment](../../Cleaning-up-a-Deployment) guide. -## Next steps +## Next Steps - For instructions on customizing policy assignments, refer to [Customize Policy Assignment](../Customize-Policy-Assignment). - For deploying using Azure Portal UI, refer to [Deploy via the Azure Portal (Preview)](../Deploy-via-Azure-Portal-UI). diff --git a/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md b/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md index 0c1cc6bbb..55ed57983 100644 --- a/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md +++ b/docs/content/patterns/alz/HowTo/deploy/PowerShell-ExecutionPolicy.md @@ -1,21 +1,21 @@ --- -title: PowerShell ExecutionPolicy +title: PowerShell Execution Policy geekdocHidden: true --- {{< hint type=Important >}} -To run PowerShell scripts provided in the ALZ pattern, you may need to _**temporarily**_ change the execution policy if it is not set to _**Unrestricted**_. Verify the current execution policy by executing the following command: +To execute the PowerShell scripts provided in the ALZ pattern, you may need to _**temporarily**_ modify the execution policy if it is not set to _**Unrestricted**_. Check the current execution policy by running the following command: ```PowerShell Get-ExecutionPolicy ``` -If the current execution policy is not set to _**Unrestricted**_, execute the following command to change it to **Unrestricted**: +If the execution policy is not _**Unrestricted**_, change it to **Unrestricted** by running: ```PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted ``` -After running your scripts, you may revert the execution policy to its original setting if desired. +After executing your scripts, you can revert the execution policy to its original setting if needed. {{< /hint >}} diff --git a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md index b8ceb1c9f..ddc12a46a 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md +++ b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md @@ -3,9 +3,9 @@ title: Remediate Policies weight: 80 --- -The policies are configured as deploy-if-not-exists by default. This means that any new deployments will be affected by these policies. In a greenfield scenario, where you are deploying new resources, including subscriptions, the policies will automatically create the relevant alert rules, action groups, and alert processing rules. +By default, the policies are set to deploy-if-not-exists. This configuration affects any new deployments. In a greenfield scenario, where new resources and subscriptions are deployed, the policies will automatically create the necessary alert rules, action groups, and alert processing rules. -In a brownfield scenario, the policies will report non-compliance for existing resources within their scope. To remediate these non-compliant resources, you need to initiate remediation. This can be done through the Azure portal on a policy-by-policy basis, or by running the *Start-AMBARemediation.ps1* script located in the *.\patterns\alz\scripts* folder. This script will remediate all AMBA-ALZ policies in scope as defined by the management group prefix. +In a brownfield scenario, the policies will report non-compliance for existing resources within their scope. To remediate these non-compliant resources, you need to initiate remediation. This can be done through the Azure portal on a policy-by-policy basis or by running the *Start-AMBARemediation.ps1* script located in the *.\patterns\alz\scripts* folder. This script will remediate all AMBA-ALZ policies in scope as defined by the management group prefix. {{< hint type=Important >}} This script requires PowerShell 7.0 or higher, and the following PowerShell modules: @@ -24,25 +24,24 @@ To use the script, follow these steps: {{% include "./PowerShell-ExecutionPolicy.md" %}} -- For instance, to remediate the **Alerting-Management** initiative assigned to the **alz-platform-management** Management Group, execute the following commands: +For example, to remediate the **Alerting-Management** initiative assigned to the **alz-platform-management** Management Group, execute the following commands: - ```powershell - #Modify the following variables to match your environment - $managementManagementGroup = "The management group id for Management" - ``` +```powershell +# Modify the following variables to match your environment +$managementManagementGroup = "The management group id for Management" +``` - ```powershell - #Run the following commands to initiate remediation - .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $managementManagementGroup -policyName Alerting-Management - ``` +```powershell +# Run the following commands to initiate remediation +.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $managementManagementGroup -policyName Alerting-Management +``` -- The script will output the results of the REST API calls, typically returning a status code 201. If the script encounters an error, review the error message and verify that the management group name and policy name are correct. -- Upon successful execution of the script, you should observe multiple remediation tasks initiated within the **alz-platform-management** management group. +The script will output the results of the REST API calls, typically returning a status code 201. If the script encounters an error, review the error message and verify that the management group name and policy name are correct. Upon successful execution of the script, you should observe multiple remediation tasks initiated within the **alz-platform-management** management group. For convenience, assuming that the management hierarchy is fully aligned with the Azure Landing Zones (ALZ) architecture, the following commands can be used to remediate all policies assigned as per the guidance provided in this repository: ```powershell -#Modify the following variables to match your environment +# Modify the following variables to match your environment $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" $identityManagementGroup = "The management group ID for Identity" $managementManagementGroup = "The management group ID for Management" @@ -51,7 +50,7 @@ $LZManagementGroup="The management group ID for Landing Zones" ``` ```powershell -#Run the following commands to initiate remediation +# Run the following commands to initiate remediation .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName Notification-Assets .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName Alerting-ServiceHealth .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $connectivityManagementGroup -policyName Alerting-Connectivity @@ -71,6 +70,6 @@ $LZManagementGroup="The management group ID for Landing Zones" To remediate a single policy definition instead of the entire policy initiative, use the remediation script with the specific policy reference ID available on the [Policy Initiatives](../../../Getting-started/Policy-Initiatives) page. For example, to remediate the **Deploy AMBA Notification Assets** policy, execute the following command: ```powershell -#Run the following command to initiate remediation of a single policy definition +# Run the following command to initiate remediation of a single policy definition .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName ALZ_AlertProcessing_Rule ``` diff --git a/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md b/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md index 69d6369b7..1f339e82a 100644 --- a/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md +++ b/docs/content/patterns/alz/HowTo/deploy/parameterConfiguration.md @@ -1,25 +1,25 @@ --- -title: Parameter configuration +title: Parameter Configuration geekdocHidden: true --- {{< hint type=Important >}} -Updating from the _**preview**_ version is not supported. If you deployed the _**preview**_ version, please proceed with [Moving from preview to GA](../../../Resources/Moving-from-preview-to-GA) before continuing. +Updating from the _**preview**_ version is not supported. If you deployed the _**preview**_ version, please follow the steps in [Moving from preview to GA](../../../Resources/Moving-from-preview-to-GA) before proceeding. {{< /hint >}} -## 1. Parameter configuration +## 1. Parameter Configuration -To start, you can either download a copy of the parameter file according the version of AMBA-ALZ you are going to deploy or clone/fork the repository. +To begin, either download the appropriate parameter file for the version of AMBA-ALZ you are deploying or clone/fork the repository. -- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-11-01/patterns/alz/alzArm.param.json) aligned to the latest release -- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/alzArm.param.json) aligned to the main branch +- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/2024-11-01/patterns/alz/alzArm.param.json) for the latest release. +- [alzArm.param.json](https://github.com/azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/alzArm.param.json) for the main branch. The following instructions apply universally, regardless of your alignment with ALZ or if you have a single management group. - Modify the values of the following parameters at the beginning of the parameter file as per the instructions below: {{< hint type=note >}} - It is highly recommended to configure at least one notification option (email, ARM Role, Logic App, etc.) to ensure you receive alerts. While it is technically possible to proceed without any notification settings, doing so is not advised. + It is highly recommended to configure at least one notification option (email, ARM Role, Logic App, etc.) to ensure you receive alerts. Proceeding without any notification settings is not advised. {{< /hint >}} - Set the value of _```enterpriseScaleCompanyPrefix```_ to the management group where you intend to deploy the policies and initiatives. Typically, this is the "pseudo root management group." In [ALZ terminology](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/resource-org-management-groups), this refers to the "Intermediate Root Management Group" located directly beneath the "Tenant Root Group." @@ -48,10 +48,6 @@ The following instructions apply universally, regardless of your alignment with {{< hint type=note >}} You can use multiple email addresses, ARM Roles, Webhooks, or Event Hubs (though using multiple Event Hubs is not recommended as per ALZ guidance). If you set multiple entries, ensure they are entered as a single string with values separated by commas. For example: - - - - ```json "ALZMonitorActionGroupEmail": { "value": [ @@ -73,9 +69,6 @@ The following instructions apply universally, regardless of your alignment with } ``` - - - {{< /hint >}} To disable initiative assignments, set the value of any of the following parameters to **"No"**: _```enableAMBAConnectivity```_, _```enableAMBAIdentity```_, _```enableAMBALandingZone```_, _```enableAMBAManagement```_, or _```enableAMBAServiceHealth```_. diff --git a/docs/content/patterns/alz/Overview/Whats-New.md b/docs/content/patterns/alz/Overview/Whats-New.md index c7edf49ce..c45afdcb6 100644 --- a/docs/content/patterns/alz/Overview/Whats-New.md +++ b/docs/content/patterns/alz/Overview/Whats-New.md @@ -12,39 +12,38 @@ To update your deployment with the latest release, refer to the [Update to new r ### New Features -- Added a new policy definition to audit/update Recovery Vault ASR Health Alerting to Azure monitor alerts. -- **Script consolidation**: *Remove-AMBADeployments.ps1*, *Remove-AMBANotificationAssets.ps1*, *Start-AMBACleanup.ps1*, *Start-AMBAOldArpCleanup.ps1* and *Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1* scripts have been consolidated into a single new one called [***Start-AMBA-ALZ-Maintenance.ps1***](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBA-ALZ-Maintenance.ps1) [[#352](https://github.com/Azure/azure-monitor-baseline-alerts/pull/352): Consolidate maintenance scripts]. With this enhancement, it is now possible to remove alerts for resources which have been deletedf (orphaned alerts). +- Introduced a new policy definition to audit/update Recovery Vault ASR Health Alerting to Azure Monitor alerts. +- **Script Consolidation**: The scripts *Remove-AMBADeployments.ps1*, *Remove-AMBANotificationAssets.ps1*, *Start-AMBACleanup.ps1*, *Start-AMBAOldArpCleanup.ps1*, and *Start-AMBAPolicyInitiativesAndAssignmentsCleanup.ps1* have been merged into a single script named [***Start-AMBA-ALZ-Maintenance.ps1***](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/scripts/Start-AMBA-ALZ-Maintenance.ps1) [[#352](https://github.com/Azure/azure-monitor-baseline-alerts/pull/352): Consolidate maintenance scripts]. This enhancement allows the removal of alerts for deleted resources (orphaned alerts). ### Bug Fixes -- Fixed [[#323](https://github.com/Azure/azure-monitor-baseline-alerts/pull/323)]: Ensure -WhatIf parameter is honored by all scripts commands and fix hybrid disconnected alert bug -- Fixed [[#342](https://github.com/Azure/azure-monitor-baseline-alerts/pull/342)]: Github issue link and Management Subscription Id fix -- Fixed [[#346](https://github.com/Azure/azure-monitor-baseline-alerts/pull/346)]: Update useCommonSchema to useCommonAlertSchema in Deploy_ServiceHealth_ActionGroups and Deploy_Suppression_AlertProcessing_Rule Policy Definitions -- Fixed [[#357](https://github.com/Azure/azure-monitor-baseline-alerts/pull/357)]: Resolve the ExpressRoute QoS remediation issue -- Fixed [[#362](https://github.com/Azure/azure-monitor-baseline-alerts/pull/362)]: Standardization on param usage for failingPeriods and evaluationPeriods -- Fixed [[#381](https://github.com/Azure/azure-monitor-baseline-alerts/pull/381)]: Bugged Connectivity policy initiative + override tag name case consistency + tag override documentation update +- Resolved [[#323](https://github.com/Azure/azure-monitor-baseline-alerts/pull/323)]: Ensured the -WhatIf parameter is honored by all script commands and fixed the hybrid disconnected alert bug. +- Resolved [[#342](https://github.com/Azure/azure-monitor-baseline-alerts/pull/342)]: Fixed GitHub issue link and Management Subscription ID. +- Resolved [[#346](https://github.com/Azure/azure-monitor-baseline-alerts/pull/346)]: Updated useCommonSchema to useCommonAlertSchema in Deploy_ServiceHealth_ActionGroups and Deploy_Suppression_AlertProcessing_Rule Policy Definitions. +- Resolved [[#357](https://github.com/Azure/azure-monitor-baseline-alerts/pull/357)]: Fixed the ExpressRoute QoS remediation issue. +- Resolved [[#362](https://github.com/Azure/azure-monitor-baseline-alerts/pull/362)]: Standardized parameter usage for failingPeriods and evaluationPeriods. +- Resolved [[#381](https://github.com/Azure/azure-monitor-baseline-alerts/pull/381)]: Fixed Connectivity policy initiative, tag name case consistency, and updated tag override documentation. ### Documentation Updates -- Documentation update about: - - Update to new releases pages now brings more clarity - - Update to new releases pages contain samples using the new consolidated maintenance script. [Updating to release 2024-09-02](../../HowTo/UpdateToNewReleases#2024-09-02), [Updating to release 2024-03-01](../../HowTo/UpdateToNewReleases#2024-03-01) - - Clarification on how to identify the pseudoRootManagementGroup as the one parenting the Platform and Landing Zones management groups. - - Updated AMBA diagrams. [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) - - Remediation command for the ***Deploy Azure Monitor Baseline Alerts for Recovery Services*** policy initiative added to the list. [Remediate Policies](../../HowTo/deploy/Remediate-Policies) +- Improved clarity on the 'Update to new releases' page. +- Added examples using the new consolidated maintenance script to the 'Update to new releases' page: [Updating to release 2024-09-02](../../HowTo/UpdateToNewReleases#2024-09-02), [Updating to release 2024-03-01](../../HowTo/UpdateToNewReleases#2024-03-01). +- Clarified identification of the pseudoRootManagementGroup as the parent of the Platform and Landing Zones management groups. +- Updated AMBA diagrams in the [Introduction to deploying the ALZ Pattern](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern) section. +- Added remediation command for the ***Deploy Azure Monitor Baseline Alerts for Recovery Services*** policy initiative to the [Remediate Policies](../../HowTo/deploy/Remediate-Policies) list. ### Tools - **Automation:** - - Removed the previous workflow that automates the process of creating ARM templates for Azure Policies/ PolicySets because of a security issue. - - New workflow to ensure policy updates and to verify the Bicep build has been run by the contributor. + - Removed the previous workflow that automated the creation of ARM templates for Azure Policies/PolicySets due to a security issue. + - Introduced a new workflow to ensure policy updates and verify the Bicep build has been run by the contributor. ## 2024-09-02 ### New Features -- **AMBA Portal Accelerator**: Introducing the Azure Monitor Baseline Alerts Accelerator, now in preview! Deploy alerts quickly and confidently through the Azure Portal UI. For detailed instructions, see [Deploy via the Azure Portal (Preview)](../../HowTo/deploy/Deploy-via-Azure-Portal-UI). -- **Modular Initiatives**: The former Landing Zone Initiative is deprecated. We now offer a modular approach with distinct components. For more details, visit [Policy Initiatives](../../Getting-started/Policy-Initiatives). +- **AMBA Portal Accelerator**: Launched the Azure Monitor Baseline Alerts Accelerator in preview, enabling quick and confident alert deployment through the Azure Portal UI. For detailed instructions, see [Deploy via the Azure Portal (Preview)](../../HowTo/deploy/Deploy-via-Azure-Portal-UI). +- **Modular Initiatives**: Deprecated the former Landing Zone Initiative in favor of a modular approach with distinct components. For more details, visit [Policy Initiatives](../../Getting-started/Policy-Initiatives). - Key Management - Load Balancing @@ -54,46 +53,46 @@ To update your deployment with the latest release, refer to the [Update to new r - VM - Web -- **Threshold Override**: Adjust alert thresholds for specific resources using a tag. This feature is available for metrics and log alerts. Learn more: [Alert Threshold Override](../../HowTo/Threshold-Override). +- **Threshold Override**: Allows adjustment of alert thresholds for specific resources using a tag. This feature is available for metrics and log alerts. Learn more: [Alert Threshold Override](../../HowTo/Threshold-Override). - **Custom Tags to Disable Monitoring**: Specify a tag name and values to disable monitoring for certain resources. -- New alert rule for Azure Key Vault Managed HSM, included in Identity and Key Management initiatives. -- New Daily Cap threshold alert for Log Analytics workspace, added to the Management initiative. -- New Application Insight Throttling alert, included in the Web initiative. -- New ActivityLog Alert for deleting Application Insight, added to the Web initiative. -- Ability to change Application Gateway dynamic alert sensitivity. +- Added new alert rules for Azure Key Vault Managed HSM, included in Identity and Key Management initiatives. +- Added a new Daily Cap threshold alert for Log Analytics workspace, included in the Management initiative. +- Added a new Application Insight Throttling alert, included in the Web initiative. +- Added a new ActivityLog Alert for deleting Application Insight, included in the Web initiative. +- Enabled changing Application Gateway dynamic alert sensitivity. - **Deprecated** the Landing Zone Initiative. ### Bug Fixes -- Fixed [[#280](https://github.com/Azure/azure-monitor-baseline-alerts/issues/280)]: AGW Compute Units Alert and AGW Unhealthy Host Count Alert remain non-compliant after remediation. -- Fixed [[#278](https://github.com/Azure/azure-monitor-baseline-alerts/issues/278)]: Deploy VNetG ExpressRoute CPU Utilization Alert remediation fails. -- Fixed [[#284](https://github.com/Azure/azure-monitor-baseline-alerts/issues/284)]: AMBA policy ALZ_ServiceHealth_ActionGroups missing during remediation. -- Fixed [[#253](https://github.com/Azure/azure-monitor-baseline-alerts/issues/253)]: Older version used in documentation. -- Fixed [[#261](https://github.com/Azure/azure-monitor-baseline-alerts/issues/261)]: Display name VMLowOSDisk(Write/Read)LatencyAlert should be VMHighOSDisk(Write/Read)LatencyAlert. -- Fixed [[#260](https://github.com/Azure/azure-monitor-baseline-alerts/issues/260)]: No threshold parameter for ALZ alerts ALZ_WSFMemoryPercentage, ALZ_WSFCPUPercentage. +- Resolved [[#280](https://github.com/Azure/azure-monitor-baseline-alerts/issues/280)]: Fixed AGW Compute Units Alert and AGW Unhealthy Host Count Alert non-compliance after remediation. +- Resolved [[#278](https://github.com/Azure/azure-monitor-baseline-alerts/issues/278)]: Fixed Deploy VNetG ExpressRoute CPU Utilization Alert remediation failure. +- Resolved [[#284](https://github.com/Azure/azure-monitor-baseline-alerts/issues/284)]: Fixed missing AMBA policy ALZ_ServiceHealth_ActionGroups during remediation. +- Resolved [[#253](https://github.com/Azure/azure-monitor-baseline-alerts/issues/253)]: Updated older version used in documentation. +- Resolved [[#261](https://github.com/Azure/azure-monitor-baseline-alerts/issues/261)]: Corrected display name VMLowOSDisk(Write/Read)LatencyAlert to VMHighOSDisk(Write/Read)LatencyAlert. +- Resolved [[#260](https://github.com/Azure/azure-monitor-baseline-alerts/issues/260)]: Added threshold parameter for ALZ alerts ALZ_WSFMemoryPercentage, ALZ_WSFCPUPercentage. - Fixed casing in metadata and policies. - Fixed default values for multiple parameters in VM and Hybrid initiatives. ### Documentation Updates -- Added new policies for ExpressRoute Ports to Connectivity table. [Policy Initiatives](../../Getting-started/Policy-Initiatives). +- Added new policies for ExpressRoute Ports to the Connectivity table. [Policy Initiatives](../../Getting-started/Policy-Initiatives). - Updated documentation on unsupported/unrecommended Tenant Root Group deployment. [FAQ](../../Resources/FAQ). -- New guidance for bringing your own Managed Identity. [Bring Your Own User Assigned Managed Identity](../../HowTo/Bring-Your-Own-User-Assigned-Managed-Identity). +- Provided new guidance for bringing your own Managed Identity. [Bring Your Own User Assigned Managed Identity](../../HowTo/Bring-Your-Own-User-Assigned-Managed-Identity). - Updated Policy Initiatives documentation to include Policy Reference ID and display names. [Policy Initiatives](../../Getting-started/Policy-Initiatives). ### Tools -- **Automation**: New workflow automates ARM template creation for Azure Policies/PolicySets, triggered by pull request events. +- **Automation**: Introduced a new workflow to automate ARM template creation for Azure Policies/PolicySets, triggered by pull request events. ## 2024-06-05 ### New Features - Added new PIDs for additional deployment methods. See [Disable telemetry tracking](../../HowTo/Telemetry) for more information. -- New initiative to monitor Azure Arc-enabled Virtual Machines. [Alerting-HybridVM](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/policySetDefinitions/Deploy-HybridVM-Alerts.json). +- Introduced a new initiative to monitor Azure Arc-enabled Virtual Machines. [Alerting-HybridVM](https://github.com/Azure/azure-monitor-baseline-alerts/blob/main/patterns/alz/policySetDefinitions/Deploy-HybridVM-Alerts.json). ### Bug Fixes @@ -142,12 +141,12 @@ To update your deployment with the latest release, refer to the [Update to new r - Webhook - Service health initiative now has its own Action Group. - Added [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) initiative. -- New policy for Storage Account Deletion. [Issue #76](https://github.com/Azure/azure-monitor-baseline-alerts/issues/76). -- Updated remediation script for better experience with new action group for Service Health. +- Introduced a new policy for Storage Account Deletion. [Issue #76](https://github.com/Azure/azure-monitor-baseline-alerts/issues/76). +- Updated remediation script for better experience with the new action group for Service Health. ### Bug Fixes -- Fixed: unable to deploy via pipeline using ubuntu-latest. [Issue #64](https://github.com/Azure/azure-monitor-baseline-alerts/issues/64). +- Resolved: unable to deploy via pipeline using ubuntu-latest. [Issue #64](https://github.com/Azure/azure-monitor-baseline-alerts/issues/64). - Fixed PIP VIP alert existence condition to check only for standard SKU. [Issue #80](https://github.com/Azure/azure-monitor-baseline-alerts/issues/80). ### Documentation Updates @@ -178,4 +177,5 @@ To update your deployment with the latest release, refer to the [Update to new r - How to modify individual policies - [How to modify individual policies](../../HowTo/deploy/Introduction-to-deploying-the-ALZ-Pattern/#how-to-modify-individual-policies). - Added guidance for Server Health alert rules - [Deploy only Service Health Alerts](../../HowTo/deploy/Deploy-only-Service-Health-Alerts). - New documentation on updating to a new release - [Update to new releases](../../HowTo/UpdateToNewReleases). -- FAQ Updates - [Frequently Asked Questions](../../Resources//FAQ). +- FAQ Updates - [Frequently Asked Questions](../../Resources/FAQ). + From 36238968b4f3798d52589e1e487fff5ac6d99530 Mon Sep 17 00:00:00 2001 From: Bruno Gabrielli Date: Fri, 6 Dec 2024 16:32:37 +0100 Subject: [PATCH 10/14] Add platform management group to remediation steps --- .../content/patterns/alz/HowTo/deploy/Remediate-Policies.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md index ddc12a46a..756854d0c 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md +++ b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md @@ -43,6 +43,7 @@ For convenience, assuming that the management hierarchy is fully aligned with th ```powershell # Modify the following variables to match your environment $pseudoRootManagementGroup = "The pseudo root management group ID parenting the identity, management and connectivity management groups" +$platformManagementGroup = "The management group ID for Platform" $identityManagementGroup = "The management group ID for Identity" $managementManagementGroup = "The management group ID for Management" $connectivityManagementGroup = "The management group ID for Connectivity" @@ -53,6 +54,8 @@ $LZManagementGroup="The management group ID for Landing Zones" # Run the following commands to initiate remediation .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName Notification-Assets .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $pseudoRootManagementGroup -policyName Alerting-ServiceHealth +.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $platformManagementGroup -policyName Alerting-HybridVM +.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $platformManagementGroup -policyName Alerting-VM .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $connectivityManagementGroup -policyName Alerting-Connectivity .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $identityManagementGroup -policyName Alerting-Identity .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $managementManagementGroup -policyName Alerting-Management @@ -60,9 +63,8 @@ $LZManagementGroup="The management group ID for Landing Zones" .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-LoadBalancing .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-NetworkChanges .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-RecoveryServices - -.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-HybridVM .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-Storage +.\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-HybridVM .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-VM .\patterns\alz\scripts\Start-AMBARemediation.ps1 -managementGroupName $LZManagementGroup -policyName Alerting-Web ``` From ceec1a768f01497b885031b805cf82423df3b3f6 Mon Sep 17 00:00:00 2001 From: Bruno Gabrielli Date: Fri, 6 Dec 2024 16:35:48 +0100 Subject: [PATCH 11/14] Update script link in notification instructions --- docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md index 2848a8112..477cd72e4 100644 --- a/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md +++ b/docs/content/patterns/alz/HowTo/Bring-your-own-Notifications.md @@ -60,6 +60,6 @@ To switch, customers need to: - Update the parameter file to match one of the three scenarios discussed. - Redeploy the ALZ pattern. - Run the remediation for both [Notification Assets](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-Notification-Assets.json) and [Alerting-ServiceHealth](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/policySetDefinitions/Deploy-ServiceHealth-Alerts.json) policy initiatives. -- Remove notification assets deployed by ALZ patterns using the [**Remove-AMBANotificationAssets.ps1**](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/scripts/Remove-AMBANotificationAssets.ps1) script (_*** only if moving from ALZ notification assets to BYON_). +- Remove notification assets deployed by ALZ patterns using the [**Start-AMBA-ALZ-Maintenance.ps1**](https://raw.githubusercontent.com/Azure/azure-monitor-baseline-alerts/main/patterns/alz/scripts/Start-AMBA-ALZ-Maintenance.ps1) script (_*** only if moving from ALZ notification assets to BYON_) The code will reconfigure the Service Health alerts to use either the customer's action groups or the ALZ pattern notification assets based on the selected scenario. From ad3ce2067ebf947fc626b49f43bb48a30aafc20b Mon Sep 17 00:00:00 2001 From: Patrisia Pascan Date: Fri, 6 Dec 2024 15:40:36 +0000 Subject: [PATCH 12/14] Fix formatting issue in Remediate-Policies.md --- docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md index 756854d0c..b93878d32 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md +++ b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md @@ -21,7 +21,7 @@ To use the script, follow these steps: 2. Navigate to the root directory of the cloned repository. 3. Set the necessary variables. 4. Execute the remediation script. - +a {{% include "./PowerShell-ExecutionPolicy.md" %}} For example, to remediate the **Alerting-Management** initiative assigned to the **alz-platform-management** Management Group, execute the following commands: From 9711ae6bc49e4a43cae84f31c4fad8934142d266 Mon Sep 17 00:00:00 2001 From: Patrisia Pascan Date: Fri, 6 Dec 2024 15:40:57 +0000 Subject: [PATCH 13/14] Fix formatting issue in Remediate-Policies.md --- docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md index b93878d32..756854d0c 100644 --- a/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md +++ b/docs/content/patterns/alz/HowTo/deploy/Remediate-Policies.md @@ -21,7 +21,7 @@ To use the script, follow these steps: 2. Navigate to the root directory of the cloned repository. 3. Set the necessary variables. 4. Execute the remediation script. -a + {{% include "./PowerShell-ExecutionPolicy.md" %}} For example, to remediate the **Alerting-Management** initiative assigned to the **alz-platform-management** Management Group, execute the following commands: From 7e70024ee3b6de721463f8d8bcaf61c65c329e6f Mon Sep 17 00:00:00 2001 From: Patrisia Pascan Date: Fri, 6 Dec 2024 15:47:24 +0000 Subject: [PATCH 14/14] Remove VSCode settings file --- .vscode/settings.json | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index ec8672c04..000000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "editor.suggest.showStatusBar": true -}