Edit

Troubleshoot the failed deployment of a Kubernetes application offer

  • Article

This article discusses how to troubleshoot a failed deployment of a Kubernetes application offer that was accepted on the Microsoft Azure Marketplace. When you initiate the purchase of a Kubernetes offer, Azure deploys an Azure Resource Manager template (ARM template) that tries to install the required resources to fulfill the offer. However, the ARM template deployment might fail for various reasons.

Troubleshooting checklist

Examine the deployment operation logs

To determine the cause of the deployment failure, you have to examine the deployment operation logs. If you're still viewing the Your deployment failed page in the Azure portal, begin at step 5 of the following procedure. If, instead, you exited the Azure portal or navigated to another portal page, follow all these steps:

  1. In the Azure portal, search for and select Resource groups.

  2. In the list of resource groups, select the name of the resource group in which you tried to deploy the Kubernetes application.

  3. On the Overview page of your resource group, locate the Essentials section, and then select the hyperlinked text that appears next to the Deployments field. This text displays the success rate of your resource group's resource deployment history (for example, 4 failed, 30 succeeded).

  4. In the list of attempted deployments for your resource group, select the Deployment name value of the deployment that failed, based on the following corresponding fields:

    • Last modified (a time stamp)
    • Duration
    • Status (shows Failed instead of Succeeded)

  5. In the Deployment details list on the deployment page, locate the Resource for which the Status field has a value of Conflict. Select the Operation details link for that resource.

    Screenshot of the 'Your deployment failed' page and the list of deployment details for a failed Kubernetes resource deployment.

  6. In the Operation details pane, locate the Status property (shows a value of Conflict), and examine the Status message box below the property.

    Screenshot of the 'Operation details' pane on the 'Your deployment failed' page for a failed Kubernetes resource deployment.

    The JSON code within the status message shows a status property of Failed. It also shows an error property that contains the child properties of code (an error code name, such as "ExtensionOperationFailed") and message (an error message description, such as "The extension operation failed with the following error: Failed to resolve the extension version from the given values."). The JSON code resembles the following text:

    {
    "status": "Failed",
    "error": {
        "code": "ExtensionOperationFailed",
        "message": "The extension operation failed with the following error: Failed to resolve the extension version from the given values."
    }
}

The following sections discuss the cause and solution for some common failure scenarios.

Cause 1: The application didn't install on the selected AKS cluster

If the Kubernetes application didn't install on the selected Azure Kubernetes Service (AKS) cluster, you receive an error message that resembles the following text:

Request failed to https://management.azure.com/subscriptions/<subscription-guid>/resourceGroups/resourceGroup/providers/Microsoft.ContainerService/managedclusters/aks-cluster/extensionaddons/default?api-version=2021-03-01. Error code: Forbidden. Reason: Forbidden.

{  
  "error": {  
    "code": "AuthorizationFailed",  
    "message": "The client '<client-guid>' with object id '<client-guid>' does not have authorization to perform action 'Microsoft.ContainerService/managedclusters/extensionaddons/read' over scope '/subscriptions/<subscription-guid>/resourceGroups/resourceGroup/providers/Microsoft.ContainerService/managedclusters/aks-cluster/extensionaddons/default' or the scope is invalid. If access was recently granted, please refresh your credentials."  
  }  
}

Solution 1a: Register the Microsoft.KubernetesConfiguration resource provider

Register the Microsoft.KubernetesConfiguration resource provider. In this case, the installation failed because the Microsoft.KubernetesConfiguration resource provider is required for you to deploy the Kubernetes application. For registration instructions, see the "Register resource providers" section in the Deploy a container offer from Azure Marketplace article.

Solution 1b: Maintain the health of the AKS cluster

In general, you should check the health of the AKS cluster to prevent other issues from occurring during the installation period. To make sure that the cluster is healthy, resolve issues that are identified on the cluster.

Solution 1c: Examine the Azure Monitor activity log

What if the cluster is healthy, but the installation still fails? In that case, examine the Azure Monitor activity log within the AKS cluster to find the cause of the failure at that stage of the installation.

Cause 2: The subscription has resource constraints

Because your Azure subscription has resource constraints, you experience a failure that produces an error message that's similar to the following text:

The 'unknown' payment instrument(s) is not supported for offer with OfferId: '<offer-name>', PlanId '<subscription-plan-name>'.

Solution 2: Make sure your subscription meets the necessary billing configuration

Verify the subscription's billing configuration to make sure that it meets the resource requirements of the Kubernetes application. For more information, see Purchase validation checks.

Cause 3: The offer wasn't available in your region

You receive an error message that states that the offer can't be sold in a certain geographical region. The error message might resemble the following text:

The Offer: '<offer-name>' cannot be purchased by subscription: '<subscription-guid>' as it is not to be sold in market: '<two-letter-region-code'.

Solution 3: Recheck whether and where the offer is still available

Verify that the offer is still available, and double-check the regions that the offer applies to.

Cause 4: An internal server error occurred

The Kubernetes application didn't install because an extension resource didn't install. This failure generates the following error message:

Extension failed to deploy with Internal server error

Solution 4: Delete and reinstall the extension

First, delete the extension resource that's a part of the offer purchase. Then, reinstall the extension.

Cause 5: The Helm chart didn't install

Errors in the Helm chart generate the following error message:

Failed to install chart from path [] for release

Solution 5: Recheck the entries that you made in the ARM template

Make sure that the values and selections that you entered on the Azure portal for the ARM template deployment are acceptable in the Kubernetes application.

Before the subscription can be used, you need to accept the legal terms of the image. Otherwise, you get the following error message:

You have not accepted the legal terms on this subscription: '<subscription-guid>' for this plan. Before the subscription can be used, you need to accept the legal terms of the image.

You can deploy through the Azure portal. The Azure portal provides a UI experience for reading and accepting the legal terms.

Next steps

Troubleshoot errors when deploying AKS cluster extensions

Third-party information disclaimer

The third-party products that this article discusses are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, about the performance or reliability of these products.

Contact us for help

If you have questions or need help, create a support request, or ask Azure community support. You can also submit product feedback to Azure feedback community.