AzRetirementMonitor

A PowerShell module for monitoring Azure service retirements and deprecation notices using Azure Advisor recommendations.

What Problem Does This Solve?

Azure services evolve constantly, with features, APIs, and entire services being retired or deprecated over time. Missing these retirement notifications can lead to:

• Service disruptions when deprecated features stop working
• Security vulnerabilities from running unsupported services
• Compliance issues when regulations require supported infrastructure
• Unexpected costs from forced migrations under time pressure

AzRetirementMonitor helps you proactively identify Azure resources affected by upcoming retirements by querying Azure Advisor for service upgrade and retirement recommendations across all your subscriptions. This gives you time to plan migrations and upgrades before services are discontinued.

How Do I Install It?

From PowerShell Gallery (Recommended)

Install-Module -Name AzRetirementMonitor -Scope CurrentUser

Manual Installation

1. Clone this repository:

   git clone https://github.com/cocallaw/AzRetirementMonitor.git

2. Import the module:

   Import-Module ./AzRetirementMonitor/AzRetirementMonitor.psd1

Prerequisites

• PowerShell 7.0 or later
• Authentication method (one of the following):
  • Azure CLI (az) - Default and recommended
  • Az.Accounts PowerShell module

How Do I Authenticate?

AzRetirementMonitor supports two authentication methods:

Option 1: Azure CLI (Default)

1. Install the Azure CLI

2. Log in to Azure:

   az login

3. Connect the module:

   Connect-AzRetirementMonitor

Option 2: Az PowerShell Module

1. Install Az.Accounts:

   Install-Module -Name Az.Accounts -Scope CurrentUser

2. Connect to Azure:

   Connect-AzAccount

3. Connect the module using Az PowerShell:

   Connect-AzRetirementMonitor -UseAzPowerShell

What Commands Are Available?

Connect-AzRetirementMonitor

Authenticates to Azure and obtains an access token for subsequent API calls.

The token is validated to ensure it's scoped to https://management.azure.com and is used exclusively for read-only Azure Advisor operations.

Parameters:

• -UseAzCLI (default): Use Azure CLI authentication
• -UseAzPowerShell: Use Az.Accounts PowerShell module authentication

# Using Azure CLI (default)
Connect-AzRetirementMonitor

# Using Az PowerShell module
Connect-AzRetirementMonitor -UseAzPowerShell

Disconnect-AzRetirementMonitor

Clears the access token stored by the module. This does not affect your Azure CLI or Az.Accounts session - you remain logged in to Azure.

The token is securely cleared from module memory and cannot be recovered after disconnection.

# Disconnect from AzRetirementMonitor
Disconnect-AzRetirementMonitor

Get-AzRetirementRecommendation

Retrieves Azure Advisor recommendations related to service retirements and deprecations. This function specifically returns only HighAvailability category recommendations with ServiceUpgradeAndRetirement subcategory.

# Get all retirement recommendations across all subscriptions
Get-AzRetirementRecommendation

# Get recommendations for specific subscriptions
Get-AzRetirementRecommendation -SubscriptionId "sub-id-1", "sub-id-2"

Parameters:

• SubscriptionId - One or more subscription IDs (defaults to all subscriptions)

Note: This function is hardcoded to return only recommendations where Category is 'HighAvailability' and SubCategory is 'ServiceUpgradeAndRetirement'.

Get-AzRetirementMetadataItem

Retrieves metadata about retirement recommendation types from Azure Advisor, filtered for HighAvailability category and ServiceUpgradeAndRetirement subcategory.

Get-AzRetirementMetadataItem

Export-AzRetirementReport

Exports retirement recommendations to various formats for reporting and analysis.

# Export to CSV
Get-AzRetirementRecommendation | Export-AzRetirementReport -OutputPath "report.csv" -Format CSV

# Export to JSON
Get-AzRetirementRecommendation | Export-AzRetirementReport -OutputPath "report.json" -Format JSON

# Export to HTML
Get-AzRetirementRecommendation | Export-AzRetirementReport -OutputPath "report.html" -Format HTML

Parameters:

• Recommendations - Recommendation objects from Get-AzRetirementRecommendation (accepts pipeline input)
• OutputPath - File path for the exported report
• Format - Export format: CSV, JSON, or HTML (default: CSV)

Understanding Impact Levels

Azure Advisor assigns an impact level (High, Medium, or Low) to each recommendation to help you prioritize actions:

• High Impact: Recommendations that can have the greatest positive effect on your environment, such as preventing service disruptions, avoiding security vulnerabilities, or addressing critical retirements. These should be addressed with highest priority.

• Medium Impact: Meaningful improvements with moderate effect. These recommendations are important but may have more flexible timelines than high-impact items.

• Low Impact: Beneficial optimizations with minor improvements. These are lower priority but still worth addressing when resources allow.

Impact levels are determined by Azure Advisor based on factors including potential business impact, risk severity, resource usage patterns, and the scope of affected resources. For retirement recommendations specifically, the impact level reflects the urgency and criticality of migrating away from deprecated services.

For more information, see Azure Advisor documentation.

Example Output

Get-AzRetirementRecommendation

PS> Connect-AzRetirementMonitor
Authenticated to Azure successfully

PS> Get-AzRetirementRecommendation

SubscriptionId   : 12345678-1234-1234-1234-123456789012
ResourceId       : /subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/myRG/providers/Microsoft.Compute/virtualMachines/myVM
ResourceName     : myVM
Category         : HighAvailability
Impact           : High
Problem          : Virtual machine is using a retiring VM size
Solution         : Migrate to a supported VM size before the retirement date
Description      : Basic A-series VM sizes will be retired on August 31, 2024
LastUpdated      : 2024-01-15T10:30:00Z
IsRetirement     : True
RecommendationId : abc123-def456-ghi789
LearnMoreLink    : https://learn.microsoft.com/azure/virtual-machines/sizes-previous-gen

Export-AzRetirementReport

PS> Get-AzRetirementRecommendation | Export-AzRetirementReport -OutputPath "./retirement-report.html" -Format HTML

This creates an HTML report with all retirement recommendations, including resource details, impact levels, and actionable solutions.

Example HTML Report:

Usage Workflow

Here's a typical workflow for monitoring Azure retirements:

# 1. Authenticate
Connect-AzRetirementMonitor

# 2. Get retirement recommendations
$recommendations = Get-AzRetirementRecommendation

# 3. Review the recommendations
$recommendations | Format-Table ResourceName, Impact, Problem, Solution

# 4. Export for team review
$recommendations | Export-AzRetirementReport -OutputPath "retirement-report.csv" -Format CSV

# 5. Get metadata about retirement types (optional)
Get-AzRetirementMetadataItem

# 6. Disconnect when finished (optional)
Disconnect-AzRetirementMonitor

How Does Authentication and Token Management Work?

Security Model

AzRetirementMonitor uses a read-only, scoped token approach to ensure security and isolation:

1. Token Acquisition: The module obtains a time-limited access token from your existing Azure authentication:

   • Azure CLI: Uses az account get-access-token to request a token from your logged-in session
   • Az.Accounts: Uses Get-AzAccessToken to request a token from your connected context
   • The module does not prompt for credentials or re-authenticate you

2. Token Storage: The token is stored in a module-scoped variable ($script:AccessToken):

   • Only accessible within the AzRetirementMonitor module
   • Not accessible to other PowerShell modules or sessions
   • Automatically cleared when the module is unloaded
   • Can be manually cleared with Disconnect-AzRetirementMonitor

3. Token Scope: The token is requested specifically for https://management.azure.com:

   • Only grants access to Azure Resource Manager APIs
   • Used exclusively for read-only operations (Azure Advisor recommendations)
   • Cannot be used to modify Azure resources

4. Module Isolation: The module's authentication is completely isolated:

   • Connect-AzRetirementMonitor does not authenticate you to Azure (you must already be logged in)
   • Connect-AzRetirementMonitor only requests an access token from your existing session
   • Disconnect-AzRetirementMonitor only clears the module's stored token
   • Disconnect-AzRetirementMonitor does not affect your Azure CLI or Az.Accounts session
   • You remain logged in to Azure CLI (az login) or Az.Accounts (Connect-AzAccount) after disconnecting

Token Lifecycle

# You authenticate to Azure first (outside the module)
az login  # or Connect-AzAccount

# Module requests a token from your session (does not re-authenticate)
Connect-AzRetirementMonitor

# Module uses the token for API calls
Get-AzRetirementRecommendation

# Module clears its token (you remain logged in to Azure)
Disconnect-AzRetirementMonitor

# You can still use Azure CLI/PowerShell
az account show  # Still works - you're still logged in

What the Module Cannot Do

For security and transparency, the module is designed with strict limitations:

• ❌ Cannot authenticate you to Azure (requires existing az login or Connect-AzAccount)
• ❌ Cannot modify, create, or delete Azure resources
• ❌ Cannot access tokens or credentials from other modules
• ❌ Cannot persist tokens beyond the PowerShell session
• ❌ Cannot disconnect you from Azure CLI or Az.Accounts
• ✅ Can only read Azure Advisor recommendations for retirement planning

Contributing Guidelines

We welcome contributions to AzRetirementMonitor! Here's how you can help:

Reporting Issues

• Use the GitHub issue tracker to report bugs or request features
• Provide clear reproduction steps for bugs
• Include PowerShell version, OS, and authentication method used

Pull Requests

1. Fork the repository and create a feature branch
2. Follow existing code style - use the same patterns as existing functions
3. Add tests for new functionality in the Tests/ directory
4. Update documentation if you change functionality
5. Keep changes focused - one feature or fix per PR
6. Test your changes with both authentication methods (Azure CLI and Az.Accounts)

Code Style

• Use approved PowerShell verbs (Get, Set, New, Remove, etc.)
• Include comment-based help for all public functions
• Use proper parameter validation
• Write verbose messages for troubleshooting
• Handle errors gracefully

Testing

Run the Pester tests before submitting:

# Install Pester if needed
Install-Module -Name Pester -Force -SkipPublisherCheck

# Run tests
Invoke-Pester ./Tests/AzRetirementMonitor.Tests.ps1

Development Setup

1. Clone the repository

2. Make your changes in a feature branch

3. Test locally by importing the module:

   Import-Module ./AzRetirementMonitor.psd1 -Force

4. Run tests and ensure they pass

5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

This module uses the Azure Advisor API to retrieve retirement recommendations. For more information about Azure Advisor, visit the Azure Advisor documentation.