Merge pull request #18 from lvlindv/main

Cleaning up md files and will move to wiki

Author: jfaurskov

1-Collect/readme.md

@@ -4,8 +4,9 @@ This project is next phase of Azure to Azure Migration toolkit driven by [jfaurs
 
 ## Wiki navigation
 
-- [What is Regions selection toolkit](./docs/wiki/Home.md)
-- [How to use Region Selection Toolkit](./docs/wiki/ToolkitHowTo.md)
+- [What is Regions selection toolkit](./docs/wiki/Introduction-to-Azure-Region-Selection-Toolkit.md)
+- [Getting Started](./docs/wiki/Setup-and-Prerequisites.md)
+- [How to use Region Selection Toolkit](./docs/wiki/Step-by-Step-Guide.md)
 - [Frequently Asked Questions](./docs/wiki/FAQ.md)
 - [Contributing](./docs/wiki/Contribution.md)
 - [Known Issues](./docs/wiki/KnownIssues.md)

2-AvailabilityCheck/readme.md

@@ -0,0 +1,37 @@
+# 1-Collect (Inventory Collection)
+Gathers the inventory of resources that will be evaluated. Run the script `Get-AzureServices.ps1` to collect the Azure resource inventory and properties, for yor relevant scope (resource group, subscription or multiple subscriptions). The script will generate a  `resources.json` and a `summary.json` file in the same directory. The `resources.json` file contains the full inventory of resources and their properties, while the `summary.json` file contains a summary of the resources collected. 
+
+## Examples 
+### If using Azure Resource Graph:
+Run the `Get-AzureServices.ps1` script with your target scope. For example:
+
+- To include Cost Information add parameter `-includeCost $true`. If you include this parameter, it will also generate a CSV file in the same directory. This CSV file can be used later in `3-CostInformation`. Note: This might take some time depending on how long it takes to download the cost information.
+
+```powershell
+Get-AzureServices.ps1 -includeCost $true
+```
+
+- To collect the inventory for a single resource group, cost not included, run the script as follows:
+
+```powershell
+Get-AzureServices.ps1 -scopeType resourceGroup -resourceGroupName <resource-group-name> -subscriptionId <subscription-id>
+```
+
+- To collect the inventory for a single subscription, cost not included, run the script as follows:
+
+```powershell
+Get-AzureServices.ps1 -scopeType subscription -subscriptionId <subscription-id>
+```
+
+- To collect the inventory for multiple subscriptions, you will need to create a json file containing the subscription ids in scope. See [here](./subscriptions.json) for a sample json file. Once the file is created, run the script as follows:
+
+```powershell
+Get-AzureServices.ps1 -multiSubscription -workloadFile <path-to-workload-file>
+```
+
+### If using an Azure Migrate export:
+Run `Get-RessourcesFromAM.ps1` against an Azure Migrate `Assessment.xlsx` file to convert the VM & Disk SKUs into the same output as `Get-AzureServices.ps1` For example:
+
+```powershell
+Get-RessourcesFromAM.ps1 -filePath "C:\path\to\Assessment.xlsx" -outputFile "C:\path\to\summary.json"
+```

README.md

@@ -0,0 +1,37 @@
+# 2-AvailabilityCheck
+
+## Availability check script
+This script evaluates the availability of Azure services, resources, and SKUs across all regions. When combined with the output from the 1-Collect script, it provides a comprehensive overview of potential migration destinations, identifying feasible regions and the reasons for their suitability or limitations, such as availability constraints per region.
+
+Note that this functionality is not yet complete and is a work in progress. Currently, this script associates every resource with its regional availability. Additionally, it maps the following SKUs to the regions where they are supported:
+- microsoft.compute/disks
+- microsoft.compute/virtualmachines
+- microsoft.sql/managedinstances
+- microsoft.sql/servers/databases
+- microsoft.storage/storageaccounts
+
+The `Get-AvailabilityInformation.ps1` script only needs to be run once to collect the availability information for all regions, which takes a little while. Run the following script: 
+
+```powershell
+Get-AvailabilityInformation.ps1
+```
+It will generate a number of json files in the same directory the important one is the `Availability_Mapping.json`
+
+## Filter by Region script
+
+To check the availability of the resources in scope in a specific region run following script:
+
+```powershell
+Get-Region.ps1 -Region <Target-region>
+```
+This will generate `Availability_Mapping_<Region>.json` in the same directory. 
+
+## Example:
+```powershell
+Get-AvailabilityInformation.ps1
+# Wait for the script to complete, this may take a while.
+Get-Region.ps1 -region <target-region1>
+# Example1: Get-Region.ps1 -region "east us"
+# Example2: Get-Region.ps1 -region "west us"
+# Example3: Get-Region.ps1 -region "sweden central"
+```

docs/wiki/1-Collect.md

@@ -1,6 +1,5 @@
-# Cost data retrieval and region comparison
-
-## About the scripts
+# 3-CostInformation 
+Cost data retrieval and region comparison
 
 ### Get-CostInformation.ps1
 
@@ -80,7 +79,7 @@ Instructions for use:
 
 #### Example
 
-``` text
+```powershell
 $regions = @("eastus", "brazilsouth", "australiaeast")
 .\Perform-RegionComparison.ps1 -regions $regions -outputType json
 ```

docs/wiki/2-AvailabilityCheck.md

@@ -1,19 +1,18 @@
-# Export Script
+# 7-Report
 
 This script generates formatted Excel (`.xlsx`)reports based on the output from the previous check script. The reports provide detailed information for each service, including:
 
-## Service Availability Report
+### Service Availability Report
 
 - **Resource type**
 - **Resource count**
 - **Implemented (origin) regions**
 - **Implemented SKUs**
-- **Selected (target) regions**
-- **Availability in the selected regions**
+- **Availability in the Selected (target) regions**
 
 ## Cost Comparison Report
 
-- **Azure Cost Meter ID**
+- **Meter ID**
 - **Service Name**
 - **Meter Name**
 - **Product Name**
@@ -28,13 +27,12 @@ These reports help you analyze service compatibility and cost differences across
 - This script requires the `ImportExcel` PowerShell module.
 - The script requires you to have run either the `2-AvailabilityCheck/Get-Region.ps1` or `3-CostInformation/Perform-RegionComparison.ps1` or both scripts to generate the necessary JSON input files for availability and cost data.
 
-## Usage Instructions
+## Example
 
-1. Open a PowerShell command line.
-2. Navigate to the `7-Report` folder.
-3. If you have created one or more availability JSON files using the `2-AvailabilityCheck/Get-Region.ps1` script, run the following commands, replacing the path with your actual file path(s):
+If you have created one or more availability JSON files using the `2-AvailabilityCheck/Get-Region.ps1` script, run the following commands, replacing the path with your actual file path(s):
 
-    ```powershell
-    .\Get-Report.ps1 -availabilityInfoPath `@("..\2-AvailabilityCheck\Availability_Mapping_Asia_Pacific.json", "..\2-AvailabilityCheck\Availability_Mapping_Europe.json")` -costComparisonPath "..\3-CostInformation\region_comparison_prices.json"
-    ```
+```powershell
+.\Get-Report.ps1 -availabilityInfoPath `@("..\2-AvailabilityCheck\Availability_Mapping_Asia_Pacific.json", "..\2-AvailabilityCheck\Availability_Mapping_Europe.json")` -costComparisonPath "..\3-CostInformation\region_comparison_prices.json"
+
+```
 The script generates an `.xlsx` and `.csv` files in the `7-report` folder, named `Availability_Report_CURRENTTIMESTAMP`.

3-CostInformation/README.md docs/wiki/3-CostInformation.md3-CostInformation/README.md renamed to docs/wiki/3-CostInformation.md

@@ -0,0 +1,32 @@
+# Introduction to the Region Selection Toolkit
+
+Selecting the right Azure region for a workload is a **critical decision** in any cloud deployment. Azure offers dozens of regions worldwide (each with unique capabilities and constraints), and region choice directly affects compliance, performance, resiliency, and cost. 
+A poor region choice can lead to issues like legal/regulatory problems, higher latency or poor user experience, and unnecessary expenses. 
+The **Region Selection Toolkit** is designed to simplify this complex decision. It helps **identifying the optimal Azure region** for their workloads by automating a multi-factor analysis that would be tedious and error-prone to do manually. 
+By considering technical, business, and even environmental factors, the toolkit provides data-driven recommendations for and helps you confidently plan scenarios such as moving to a new region, expanding an application into additional regions, or choosing a region for a new deployment.
+
+## What the Toolkit Does
+The Region Selection Toolkit **evaluates multiple key factors** to recommend the best region(s) for a given set of Azure resources. 
+Its holistic approach ensures you don’t overlook important criteria when comparing cloud regions. In particular, the toolkit performs:
+
+- **Inventory Collection:** It can automatically gather an inventory of your existing Azure resources (for example, via Azure Resource Graph) or accept input from an Azure Migrate assessment. 
+This inventory of services and components is the foundation for region analysis.
+
+- **Multi-Factor Region Analysis:** For each candidate region, the toolkit analyzes a wide range of criteria that are crucial for decision-making:
+
+  - _Service Availability & Roadmap:_ Verifies that all Azure services used by your workload are available (or planned) in the target region. It cross-references your workload’s resource types against Azure’s _products-by-region_ lists to avoid deploying into a region where required services are not supported. This factor helps prevent incompatibility or missing service issues.
+
+  - _Cost Differences:_ Compares estimated costs of running the workload in different regions. Azure service pricing can vary by region, so the toolkit pulls pricing for your resource inventory in each region, enabling side-by-side cost comparisons. This helps you weigh budget impacts and identify cost-effective regions without manual price research.
+
+  - _[In progress] Compliance and Geopolitical Factors:_ Accounts for data residency and regulatory requirements tied to geographic location. The toolkit flags if a region belongs to a special sovereignty (e.g. EU, US Gov, China) or has specific compliance certifications. This ensures your choice aligns with laws and policies (for example, GDPR in Europe or other regional regulations). In short, it helps you **choose a region that meets your organization’s compliance mandates and avoids legal risk.**
+
+  - _[In progress] Performance and Resiliency:_ Provides insight into performance-related considerations like network latency and infrastructure resiliency for each region. For example, it notes whether a region supports Availability Zones and identifies its paired region for disaster recovery purposes. These details help evaluate reliability (high availability and DR options) and potential latency impacts on end-users when choosing or moving to that region. (Future versions may integrate more detailed latency testing and capacity data.)
+
+  - _[In progress] Sustainability Metrics:_ Highlights the sustainability considerations of each region, such as regional carbon intensity or the availability of renewable energy. While this data may not always be available for every location, the toolkit surfaces whatever sustainability metrics it can (e.g. relative carbon footprint of running in Region A vs Region B). This helps organizations factor in environmental impact when selecting an Azure region, supporting corporate sustainability goals.
+
+- **Recommendation Report:** After analyzing the above factors, the toolkit generates a clear **Recommendation Report**. This report lists region choices for your workload and provides the reasoning behind each recommendation. Each recommendation is backed by data, allowing you to confidently present options to stakeholders or use the report as a blueprint for the actual deployment/migration.
+
+The toolkit is regularly updated to reflect new Azure regions and services, helping teams make informed, balanced decisions on region selection with speed and confidence.
+
+> [!NOTE]
+> The Region Selection Toolkit is modular and extensible. Not all features are fully implemented yet, like _Compliance and Geopolitical Factors, Performance and Resiliency, Sustainability Metrics and Capacity planning_ are in progress.