Edit

Troubleshoot Azure Cloud Shell in a private virtual network

This article provides instructions for troubleshooting a private virtual network deployment of Azure Cloud Shell. For best results, and to be supportable, following the deployment instructions in the Deploy Azure Cloud Shell in a virtual network using quickstart templates article.

Verify you have the correct permissions

To configure Azure Cloud Shell in a virtual network, you must have the Owner role assignment on the subscription. To view and assign roles, see List owners of a subscription.

Unless otherwise noted, all the troubleshooting steps start in Subscriptions section of the Azure portal.

  1. Sign in to the Azure portal.
  2. On the Azure portal menu, search for Subscriptions. Select it from the available options.
  3. Select the subscription you want to view.

Verify resource provider registrations

Azure Cloud Shell needs access to certain Azure resources. That access is made available through resource providers. The following resource providers must be registered in your subscription:

  • Microsoft.CloudShell
  • Microsoft.ContainerInstance
  • Microsoft.Relay

To see all resource providers, and the registration status for your subscription:

  1. Go to the Settings section of left menu of your subscription page.

  2. Select Resource providers.

  3. In the search box, enter cloudshell to search for the resource provider.

  4. Select the Microsoft.CloudShell resource provider register from the provider list.

  5. Select Register to change the status from unregistered to Registered.

  6. Repeat the previous steps for the Microsoft.ContainerInstance and Microsoft.Relay resource providers.

    Screenshot of selecting resource providers in the Azure portal.

Verify Azure Container Instance Service role assignments

The Azure Container Instance Service service principal needs the Network Contributor role on the virtual network's container subnet, and the Contributor role on the Relay namespace.

Verify virtual network permissions

Verify the permissions by using the following steps:

  1. Go to the Settings section of left menu of your subscription page.
  2. Select Resource groups.
  3. Select the resource group you provided in the prerequisites for the deployment.
  4. Select the virtual network used by your Cloud Shell deployment.
  5. On the virtual network page, select Access control (IAM) in the left menu.
  6. Then select Role assignments from the top menu bar.
  7. In the search box, enter container.
  8. Verify that Azure Container Instance Service has the Network Contributor role at This resource scope or an inherited scope that applies to the container subnet.

If you scope the role assignment to only the container subnet, it doesn't appear in the Azure portal. Use Azure CLI or Azure PowerShell to verify the assignment at the subnet scope instead.

If the role is missing, follow Assign the necessary role to add it. Creating the assignment requires Microsoft.Authorization/roleAssignments/write access on the virtual network or subnet. The Owner, User Access Administrator, and Role Based Access Control Administrator roles include this permission.

Also verify that the container subnet is delegated to Microsoft.ContainerInstance/containerGroups. For instructions, see Add or remove subnet delegation.

Verify Relay permissions

  1. Return to the resource group and select the relay namespace resource with the type of Relay. The name should be the name of the relay namespace you provided in the deployment template.

  2. On relay page, select Access control (IAM), then select Role assignments from the top menu bar.

  3. In the search box, enter container.

  4. Verify that Azure Container Instance Service has the Contributor role.

    Screenshot showing the network relay role assignments.

When all else fails, redeploy Cloud Shell for a private virtual network

Before you redeploy Cloud Shell, you must delete the existing deployment. In the prerequisites for the deployment, you provided a resource group and a virtual network. If you created these resources specifically for this deployment, then it should be safe to delete them. If you used existing resources, then you shouldn't delete them.

The following list provides a description of the resources created by the deployment:

  • A Private endpoint resource named cloudshellRelayEndpoint.
  • A Network Interface resource named cloudshellRelayEndpoint.nic.<UUID> where <UUID> is a unique identifier added to the name.
  • A Virtual Network resource that you provided from the prerequisites.
  • A Private DNS zone named privatelink.servicebus.windows.net.
  • A Network security group resource with the name you provided in the deployment template.
  • A microsoft.network/privatednszones/virtualnetworklinks resource with a name starting the name of the relay namespace you provided in the deployment template.
  • A Relay resource with the name of the relay namespace you provided in the deployment template.
  • A Storage account resource with the name you provided in the deployment template.

Older deployments might also contain a microsoft.network/networkprofiles resource named aci-networkProfile-<location>, where <location> is the location of the resource group. Network profiles are no longer required for Cloud Shell in a virtual network.

After you remove the resources, you can redeploy Cloud Shell by following the steps in the Deploy Azure Cloud Shell in a virtual network using quickstart templates article.

You can find these resources by viewing the resource group in the Azure portal.

Screenshot of resources created by the deployment.

Open a support ticket

If you want to open a support ticket, you can do so from the Azure portal. Be sure to capture any error messages, including the Correlation Id and Activity Id values. Don't change any settings or delete any resources until instructed to by a support technician.

Follow these steps to open a support ticket:

  1. Select the Support & Troubleshooting icon on the top navigation bar in the Azure portal.

  2. From the Support & Troubleshooting pane, select Help + support.

  3. Select Create a support request at the top of the center pane.

  4. Follow the instructions to create a support ticket.

    Screenshot of creating a support ticket in the Azure portal.