Self-help support for Azure using Help API : CLI Extension

Nithya Sivam

Today, Azure customers navigate across multiple tools, portals and knowledge bases to troubleshoot Azure incidents. Azure is now introducing Help API, an offering that streamlines and simplifies troubleshooting steps by returning relevant solutions associated with the problem, wherever you need them! Help API empowers you and/or your users to access rich, Azure curated self-help solutions, diagnostics and troubleshooters from your preferred interface, without the need to create a support case, thereby putting the power of troubleshooting issues in your own hands, within minutes from when the issue occurs! In this blogpost we will explore key features of Azure Help API from the command line.

Key features

Whether you are a direct consumer of Azure services or a reseller supporting your end users by troubleshooting issues with Azure resources, you can customize your troubleshooting experience suited to your specific needs, by integrating with Help API. Azure offers a wide range of high-quality solutions that are today only exposed via Azure portal Support + Troubleshooting experiences. Using Help API involves a two-step process.

1. Discovery Solution: This is the first point of entry which returns a set of relevant solutions associated with your problem. This version of Help API does not support natural language functionality (currently in development); hence you can pre-classify your problem with the problem classification API, prior to solutions discovery.
2. Solution execution: Invokes the specific solution to help you resolve the issue.

This blogpost specifically focuses, but not limited to 3 most impactful solution offerings: Diagnostics, Azure Solutions and Troubleshooters.

Setting Up the Environment

Prerequisites

• Azure CLI: How to install the Azure CLI | Microsoft Learn
• Azure Subscription
• Authorization requirements: For diagnostics, you must have reader access role for the resource on which the diagnostics is executed to invoke the diagnostics for that resourceAzure

Install SelfHelp Extension

Install this extension using the below CLI command. For details on each command, use -h or –help.

Az extension add –name self-help

Exploring Key Features of Self-Help CLI Extension

A. Discovery Solutions

DiscoverySolution is the initial entry point within Help API, which returns relevant solutions associated with the problem. Prior to using Discovery Solutions, you must classify your problem using problemclassification API. Discovery Solutions returns a list of relevant diagnostics and solutions using the input parameters : problemclassificationId AND resourceUri or resourceType. The resourceType/resourceUri is optional for discovery solutions, although recommended for targeted solutions.

Request Example:

# Gets list of solution metadata for an azure resource.
az self-help discovery-solution list --filter "ProblemClassificationId eq '00000000-0000-0000-0000-000000000000'" --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

Response Example:

The discovery solutions response consists of the following properties:

B. Diagnostics

Diagnostics are a powerful solution type that access product resources or other relevant data and provide the root cause of the issue and the steps to address the issue. Diagnostics are invoked using Help API in 2 steps.

Step 1: ‘Create diagnostics’ creates a diagnostic for a specific resource using solutionId from discovery solutions

Example:

# Creates a diagnostic for a resource

az self-help diagnostic create –diagnostic-name diagnostic-name –insights [{solutionId:demo2InsightV2}] –scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

Step 2: ‘Get diagnostics’ gets the diagnostics using the ‘diagnosticsResourceName’ chosen while creating the diagnostic

Example:

az self-help diagnostic show --diagnostic-name diagnostic-name --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

C. Solutions

Azure solutions comprise a comprehensive library of self-help resources that have been thoughtfully curated by Azure engineers to enable customers troubleshoot any Azure issue related to their subscription or resource . Azure solutions are a rich library of one or more other impactful solution components such as troubleshooters, diagnostics, data visualizations, video tutorials, diagrams, images, graphs , troubleshooting textual instructions, etc. The unique aspect about ‘solutions’ is that it is a one stop shop for all relevant content associated with your problem and/or resource. To invoke ‘solutions’ you follow 3 steps:

Step 1: ‘Create Solution’ creates a solution for the specific Azure resource or subscription using the inputs ‘solutionId’ from discovery solutions

Example:

# Creates a solution for a resource

az self-help solution create --solution-name solution-name --trigger-criteria [{name:solutionid,value:Demo2InsightV2}] --parameters {} --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mythe resourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

Step 2: ‘Get Solution’ gets the solution using the applicable solutionResourceName

Example:

# Creates a solution for a resource

az self-help solution show –solution-name solution-name --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

Step 3: ‘Update solution’ updates additional information needed to execute the solution

Example:

# Updates solution for a resource.

az self-help solution update --solution-name solution-name --trigger-criteria [{name:ReplacementKey,value:<!--56ee7509-92e1-4b9e-97c2-dda53065294c-->}] --parameters {SearchText:CanNotRDP,SymptomId:KeyVaultVaultNotFoundInsight} --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

D. Troubleshooter

Troubleshooters is a type of Azure solutions that dynamically guides you through your troubleshooting steps using a combination of backend resource signals and user inputs through step by step workflows. There are 5 steps to invoke troubleshooters:

Step 1: ‘Create Troubleshooter’ creates the specific troubleshooter action under a resource using the ‘solutionId’ as trigger

Example:

# Creates a troubleshooter for a resource

az self-help troubleshooter create –troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --solution-id e104dbdf-9e14-4c9f-bc78-21ac90382231 --parameters {ResourceUri:'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'} --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

Step 2 : ‘Get Troubleshooter’ gets the troubleshooter instance which includes the result of the troubleshooter being executed

Example:

# Gets a troubleshooter for a resource
az self-help troubleshooter show --troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

Step 3: ‘Restart Troubleshooter’ restarts the troubleshooter API using applicable troubleshooter resource name as the input

Example:

# Restarts troubleshooter for a resource

az self-help troubleshooter restart --troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

Step 4: ‘End Troubleshooter’ ends the troubleshooter action

Example:

# Ends a troubleshooter instance

az self-help troubleshooter end --troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --scope 'subscriptions/0d0fcd2e-c4fd-4349-8497-200edb3923c6/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

Step 5: ‘Continue Troubleshooter’ uses ‘stepId’ and ‘responses’ as trigger to continue the troubleshooting steps for the respective troubleshooter

Example:

# Continues troubleshooter for a resource.

az self-help troubleshooter continue --troubleshooter-name 12345678-BBBb-cCCCC-0000-123456789012 --step-id step-id --responses [] --scope 'subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresourceGroup/providers/Microsoft.KeyVault/vaults/test-keyvault-non-read'

E. CheckNameAvailability

This API is used to check the uniqueness of a resource name used for a diagnostic, troubleshooter or solutions.

Example:

# Check resource uniqueness

Az self-help check-name-availability --scope subscriptions/00000000-0000-0000-0000-000000000000 --name diagnostic-name --type 'Microsoft.Help/diagnostics' az self-help check-name-availability --scope subscriptions/00000000-0000-0000-0000-000000000000 --name solution-name --type 'Microsoft.Help/solutions' az self-help check-name-availability --scope subscriptions/00000000-0000-0000-0000-000000000000 --name 12345678-BBBb-cCCCC-0000-123456789012 --type 'Microsoft.Help/troubleshooters' 

Best Practices

• To get relevant solutions always use DiscoverySolutions first, followed by execution of solutions or diagnostics
• problemclassificationId AND resourceUri will fetch more targeted solutions via DiscoverySolutions
• Use checknameavailability feature to check for resource name uniqueness, and finally use the solution id found in the response that fits the most of your diagnostics scenario to invoke any of our 3 solution types: diagnostics, solutions, and troubleshooters.

Send us your feedback

Thank you for exploring the key features of Azure Help API CLI Extension with us. We value your feedback in helping us scale and improve your troubleshooting experience with Help API. If you have feedback or suggestions while using Help API CLI extension, please share your thoughts with us using the following channels.

• Email: helpapi@microsoft.com
• Yammer
• Github

Nithya Sivam Senior Product Manager, Azure Incident Care and Experiences

Follow