Troubleshoot Azure prerequisites validation for Azure Operator Nexus clusters

This article helps you diagnose and resolve Azure prerequisites validation failures that can block cluster deployment or runtime upgrades.

Overview

Azure Operator Nexus validates that user-provided Azure resources are accessible before proceeding with cluster deployment or runtime upgrades. This validation ensures the cluster can successfully use:

• Log Analytics Workspace: For software extension installation and metrics collection
• Storage Account: For storing run command output
• Key Vault: For credential rotation and secret storage

If validation fails, the deployment or upgrade action doesn't proceed until you resolve the issue.

Check validation status

Using the Azure portal

1. Navigate to your Operator Nexus Cluster resource in the Azure portal.
2. Select Resource JSON or Export template to view the cluster properties.
3. Look for the conditions array and find the AzurePrerequisitesReady condition.
4. A status of True indicates all resources are validated. A status of False indicates a validation failure.

Using Azure CLI

az networkcloud cluster show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "conditions[?contains(type, 'AzurePrerequisitesReady')]"

Example output for a successful validation:

[
  {
    "type": "AzurePrerequisitesReady",
    "status": "True",
    "lastTransitionTime": "2026-01-15T10:30:00Z",
    "reason": "ValidationPassed",
    "message": "{\"schemaVersion\":\"v1\",\"lastValidated\":\"2026-01-15T10:30:00Z\",...}"
  }
]

Example output for a failed validation:

[
  {
    "type": "AzurePrerequisitesReady",
    "status": "False",
    "lastTransitionTime": "2026-01-15T10:30:00Z",
    "reason": "ValidationFailed",
    "message": "{\"schemaVersion\":\"v1\",\"errors\":[{\"code\":\"KeyVaultAccessDenied\",\"message\":\"...\",\"remediation\":\"...\"}]}"
  }
]

Check individual resource conditions

For more detailed information, check the individual resource conditions:

# Log Analytics Workspace validation
az networkcloud cluster show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "conditions[?contains(type, 'AzureLogAnalyticsReady')]"

# Storage Account validation
az networkcloud cluster show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "conditions[?contains(type, 'AzureCommandOutputReady')]"

# Key Vault validation
az networkcloud cluster show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "conditions[?contains(type, 'AzureSecretArchiveReady')]"

Log Analytics Workspace validation errors

The following table lists error codes for Log Analytics Workspace validation failures:

Resolve Log Analytics Workspace permissions

To assign the required role:

# Get the managed identity principal ID
PRINCIPAL_ID=$(az networkcloud cluster show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "identity.principalId" -o tsv)

# Assign Log Analytics Contributor role
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Log Analytics Contributor" \
  --scope "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.OperationalInsights/workspaces/{workspace-name}"

Storage Account validation errors

The following table lists error codes for Storage Account (blob container) validation failures:

Resolve Storage Account permissions

To assign the required role:

# Get the managed identity principal ID
PRINCIPAL_ID=$(az networkcloud cluster show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "identity.principalId" -o tsv)

# Assign Storage Blob Data Contributor role
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Storage Blob Data Contributor" \
  --scope "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account-name}"

Configure Storage Account firewall

If your storage account has firewall rules enabled:

1. In the Azure portal, navigate to your storage account.
2. Select Networking under Security + networking.
3. Under Exceptions, select Allow Azure services on the trusted services list to access this storage account.
4. If users need to access run command output directly, add their IP addresses to the firewall allowlist.

Key Vault validation errors

The following table lists error codes for Key Vault validation failures:

Resolve Key Vault permissions

Key Vault requires specific permissions for secret management. Assign the required role:

# Get the managed identity principal ID
PRINCIPAL_ID=$(az networkcloud cluster show \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --query "identity.principalId" -o tsv)

# Assign the Operator Nexus Key Vault Writer Service Role
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Operator Nexus Key Vault Writer Service Role (Preview)" \
  --scope "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.KeyVault/vaults/{vault-name}"

Configure Key Vault firewall

If your Key Vault has firewall rules enabled:

1. In the Azure portal, navigate to your Key Vault.
2. Select Networking under Settings.
3. Under Exceptions, select Allow trusted Microsoft services to bypass this firewall.
4. If users need direct Key Vault access, add their IP addresses to the firewall allowlist.

Common scenarios

Scenario: Validation fails immediately after cluster creation

Symptoms: The AzurePrerequisitesReady condition shows False with access denied errors immediately after creating the cluster.

Cause: Role assignments can take several minutes to propagate after being created.

Solution:

1. Verify the role assignments are correct using the Azure portal or CLI.
2. Wait 5-10 minutes for propagation.
3. Validation automatically retries on the next reconciliation cycle.

Scenario: Validation was working but now fails

Symptoms: A cluster that was previously healthy now shows validation failures.

Cause: Possible causes include:

• Role assignments were removed or modified
• Resource was deleted or moved
• Managed identity was deleted or reconfigured
• Firewall rules were changed

Solution:

1. Check the specific error code in the condition message.
2. Verify the resource still exists and is accessible.
3. Confirm role assignments are still in place.
4. Review any recent changes to network or firewall configuration.

Scenario: Deployment times out waiting for validation

Symptoms: The deployment action fails with a message indicating Azure prerequisites validation didn't complete within the timeout period.

Cause: Validation has a 10-minute timeout. If issues can't be resolved within this window, the deployment fails.

Solution:

1. Check the AzurePrerequisitesReady condition for specific errors.
2. Resolve the underlying issue (permissions, firewall, resource existence).
3. Restart the deployment action after fixing the issue.

Scenario: User-assigned managed identity not working

Symptoms: Validation fails with identity-related errors when using a user-assigned managed identity.

Cause: The user-assigned identity might not be correctly associated with the cluster or might lack permissions.

Solution:

1. Verify the identity is assigned to the cluster resource.
2. Confirm the identityResourceId in cluster settings matches the identity's ARM resource ID.
3. Assign the required roles to the user-assigned identity (not the system-assigned identity).

Retry validation

After correcting the resource configuration or role assignments, validation automatically retries on the next cluster reconciliation (typically within 2 minutes).

To force an immediate validation retry:

1. Add or update an annotation on the cluster to trigger reconciliation.
2. Wait for the AzurePrerequisitesReady condition to update.

For deployment or upgrade actions that failed due to validation:

1. Fix the underlying resource or permission issue.
2. If the action is still in progress, it automatically retries after validation passes.
3. If the action was marked as failed, restart the deployment or upgrade action.

Get additional help

If validation continues to fail after following the remediation steps:

1. Verify identity principal ID: Confirm the managed identity's principal ID matches what's assigned on the resources.

   # For system-assigned identity
   az networkcloud cluster show \
     --name <cluster-name> \
     --resource-group <resource-group> \
     --query "identity.principalId"
   
   # For user-assigned identity
   az identity show \
     --name <identity-name> \
     --resource-group <identity-resource-group> \
     --query "principalId"
   

2. Check role assignments:

   az role assignment list \
     --assignee <principal-id> \
     --all \
     --output table
   

3. Review Azure activity logs for the target resources to see if requests are being received and why they might be failing.

4. Contact support: If issues persist, open a support request with Microsoft including:

   • Cluster resource ID
   • Validation error codes and messages
   • Managed identity principal ID
   • Resource IDs for the failing resources

Related content

• Cluster Managed Identity and User Provided Resources
• Cluster deployment overview
• Cluster runtime upgrade overview
• Configure cluster deployment