Azure Permission Requirements

Understand the Azure permissions Qovery needs and how to scope them to resource groups

Qovery requires specific Azure permissions to provision and manage AKS clusters. You can choose between two permission models depending on your security requirements.

Permission Models

Subscription-Level (Default)

Simplest approach. The Service Principal has roles at the subscription level. Required for initial cluster provisioning.

Resource-Group-Scoped

After initial deployment, scope permissions down to specific resource groups for tighter security.

Option 1: Subscription-Level Permissions (Default)

This is the default and simplest approach. During initial cluster setup, the Service Principal is assigned the following roles at the subscription level:

Role	Purpose
Contributor	Create and manage all Azure resources (AKS, VMs, VNets, Load Balancers, Storage, etc.)
User Access Administrator	Assign roles to managed identities created by AKS

Subscription-level permissions are required for the initial cluster provisioning. You can scope them down to resource groups after the first successful deployment.

Option 2: Resource-Group-Scoped Permissions

After the initial cluster deployment completes successfully, you can restrict the Service Principal permissions to only the specific resource groups that Qovery manages. This follows the principle of least privilege.

Steps to Scope Permissions

1. Complete Initial Deployment

   Deploy your cluster with subscription-level permissions (Option 1). Wait for the cluster to reach Running status in the Qovery console.

2. Identify the Resource Groups

   Qovery creates two resource groups during deployment:

   Main resource group:

   qovery-<cluster-short-id>
   

   You can find the cluster short ID in the Qovery console on the cluster settings page.

   Node resource group (managed by AKS):

   qovery-<cluster-short-id>-nodes
   

   Qovery automatically sets this deterministic name during cluster creation.

   You can find both resource groups in the Azure Portal by searching for qovery-.

3. Pre-Register Required Resource Providers

   Before removing subscription-level permissions, you must pre-register the required Azure resource providers. See the Resource Provider Registration section below.

4. Remove Subscription-Level Role Assignments

   In the Azure Portal:

   1. Go to Subscriptions > select your subscription
   2. Click Access control (IAM)
   3. Click Role assignments
   4. Find the Qovery Service Principal entries
   5. Remove both the Contributor and User Access Administrator role assignments at subscription level
5. Add Resource-Group-Scoped Roles

   For each of the two resource groups (main and node), add the following roles:

   1. Go to the resource group in Azure Portal
   2. Click Access control (IAM)
   3. Click Add > Add role assignment
   4. Assign Contributor role to the Qovery Service Principal
   5. Repeat to assign User Access Administrator role

   You must add both roles to both resource groups. Missing a role or resource group will cause deployment failures.

6. Verify Permissions

   Trigger a redeployment of the cluster from the Qovery console to verify everything works correctly with the scoped permissions.

Using Azure CLI

You can also scope permissions using the Azure CLI:

# Set your variables
SP_OBJECT_ID="<service-principal-object-id>"
SUBSCRIPTION_ID="<your-subscription-id>"
MAIN_RG="qovery-<cluster-short-id>"
NODE_RG="qovery-<cluster-short-id>-nodes"

# Remove subscription-level roles
az role assignment delete \
  --assignee "$SP_OBJECT_ID" \
  --role "Contributor" \
  --scope "/subscriptions/$SUBSCRIPTION_ID"

az role assignment delete \
  --assignee "$SP_OBJECT_ID" \
  --role "User Access Administrator" \
  --scope "/subscriptions/$SUBSCRIPTION_ID"

# Add roles scoped to the main resource group
az role assignment create \
  --assignee "$SP_OBJECT_ID" \
  --role "Contributor" \
  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$MAIN_RG"

az role assignment create \
  --assignee "$SP_OBJECT_ID" \
  --role "User Access Administrator" \
  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$MAIN_RG"

# Add roles scoped to the node resource group
az role assignment create \
  --assignee "$SP_OBJECT_ID" \
  --role "Contributor" \
  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$NODE_RG"

az role assignment create \
  --assignee "$SP_OBJECT_ID" \
  --role "User Access Administrator" \
  --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$NODE_RG"

Pre-Register Required Azure Resource Providers

When using resource-group-scoped permissions, the Service Principal cannot register resource providers at the subscription level. You must pre-register them as a one-time admin operation before scoping down permissions.

Resource provider registration is a subscription-level operation. It must be done by a user or service principal with subscription-level access before you remove subscription-level role assignments.

Required Resource Providers

Resource Provider	Purpose
Microsoft.ContainerService	AKS cluster management
Microsoft.Network	Virtual networks, load balancers, NAT gateways
Microsoft.Compute	Virtual machine scale sets for node pools
Microsoft.Storage	Managed disks and storage accounts
Microsoft.ManagedIdentity	Managed identities used by AKS
Microsoft.Authorization	Role assignments for managed identities
Microsoft.OperationsManagement	Container Insights and monitoring solutions
Microsoft.OperationalInsights	Log Analytics workspaces

Registration Commands

Run these commands in Azure Cloud Shell (Bash) or any terminal with the Azure CLI installed:

az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.Network
az provider register --namespace Microsoft.Compute
az provider register --namespace Microsoft.Storage
az provider register --namespace Microsoft.ManagedIdentity
az provider register --namespace Microsoft.Authorization
az provider register --namespace Microsoft.OperationsManagement
az provider register --namespace Microsoft.OperationalInsights

Verify Registration Status

Check that all providers are registered:

az provider show --namespace Microsoft.ContainerService --query "registrationState" -o tsv
az provider show --namespace Microsoft.Network --query "registrationState" -o tsv
az provider show --namespace Microsoft.Compute --query "registrationState" -o tsv
az provider show --namespace Microsoft.Storage --query "registrationState" -o tsv
az provider show --namespace Microsoft.ManagedIdentity --query "registrationState" -o tsv
az provider show --namespace Microsoft.Authorization --query "registrationState" -o tsv
az provider show --namespace Microsoft.OperationsManagement --query "registrationState" -o tsv
az provider show --namespace Microsoft.OperationalInsights --query "registrationState" -o tsv

All providers should show Registered. Registration can take a few minutes to complete.

Entra ID Requirements

Qovery requires the Cloud Application Administrator role in Microsoft Entra ID (formerly Azure Active Directory) to create and manage application registrations.

What Qovery Uses Entra ID For

Action	Description
Application Registration	Creates an App Registration for authentication with your Azure subscription
Short-Lived Credentials	Generates credentials with a 4-hour expiration for each deployment
No Stored Secrets	No long-lived secrets are stored; credentials are regenerated on demand

The 4-hour credential expiration provides strong security by limiting the window of exposure. Credentials are automatically regenerated for each deployment operation.

Node Resource Group Naming

Qovery automatically sets the AKS node resource group name to a deterministic value:

qovery-<cluster-short-id>-nodes

This predictable naming makes it easy to pre-scope Service Principal permissions to both resource groups before the initial deployment, enabling you to start with resource-group-scoped permissions from day one.

The node resource group name is set automatically by Qovery and cannot be customized. This ensures a consistent and predictable naming convention across all Qovery-managed AKS clusters.

Troubleshooting

Deployment fails after scoping permissions

Symptoms: Cluster update or application deployment fails with authorization errors.

Solutions:

1. Verify that both Contributor and User Access Administrator roles are assigned on both resource groups
2. Check that all required resource providers are registered (see Pre-Register Required Azure Resource Providers)
3. Ensure the Service Principal object ID matches the one used by Qovery
4. Wait a few minutes after assigning roles — Azure role assignments can take up to 5 minutes to propagate

Resource provider registration errors

Symptoms: Errors mentioning resource provider not registered.

Solutions:

1. Re-register the missing resource provider using the commands above
2. Resource provider registration requires subscription-level access — use a subscription admin to run the registration
3. Verify registration status with az provider show --namespace <provider> --query "registrationState"

Cannot identify the node resource group

Symptoms: You cannot find the AKS node resource group in the Azure Portal.

Solutions:

1. In the Azure Portal, go to your AKS cluster resource
2. Under Properties, look for the Node resource group field
3. Alternatively, run: az aks show --resource-group qovery-<cluster-short-id> --name <cluster-name> --query "nodeResourceGroup" -o tsv

Entra ID permission errors

Symptoms: Errors related to application registration or credential creation.

Solutions:

1. Verify the service principal has Cloud Application Administrator role in Entra ID
2. Check that the Entra ID tenant matches the one configured in Qovery
3. Contact your Azure AD administrator to grant the required Entra ID role

Related Resources

Install Qovery on Azure

Step-by-step Azure installation guide

Qovery-Managed AKS

AKS cluster configuration reference

Cloud Credentials

Manage cloud provider credentials

Cluster Advanced Settings

Advanced cluster configuration options