Skip to main content

​
Overview

Bring Your Own Kubernetes (BYOK) allows you to connect your existing AKS cluster to Qovery. You maintain full control over your cluster while Qovery manages application deployments.

​
Prerequisites

Existing AKS cluster (Kubernetes 1.24+)
kubectl access with cluster-admin permissions
Azure service principal or managed identity for Qovery
Azure Disk CSI driver installed
Load Balancer or Application Gateway configured

​
Setup

1

Get Qovery Agent Manifests

In Qovery Console:
  1. Settings → Clusters → Add Cluster
  2. Select “Bring Your Own Kubernetes”
  3. Choose “Azure AKS”
  4. Download Helm values or kubectl manifests
2

Install Qovery Agent

Using Helm (recommended):
helm repo add qovery https://helm.qovery.com
helm repo update

helm install qovery-agent qovery/qovery-agent \
  --namespace qovery \
  --create-namespace \
  --values qovery-values.yaml
Or using kubectl:
kubectl apply -f qovery-agent.yaml
3

Verify Connection

Check agent status:
kubectl get pods -n qovery
# qovery-agent-* should be Running
In Qovery Console, cluster should show as “Connected”
4

Deploy Applications

Start deploying applications to your BYOK cluster

​
What Qovery Installs

Qovery Agent:
  • Manages application deployments
  • Communicates with Qovery Control Plane
  • Handles secrets and configuration
Optional Components (if not present):
  • Nginx Ingress Controller
  • Cert-Manager (for SSL certificates)
  • External-DNS (for domain management)
  • Metrics Server

​
Requirements

​
Kubernetes Version

  • Minimum: 1.24
  • Recommended: 1.27+
  • Maximum: 1.29

​
Required Addons

  • Storage
  • Load Balancer
  • Metrics
Azure Disk CSI Driver:AKS clusters have this enabled by default. Verify:
kubectl get csidriver disk.csi.azure.com
Storage Class:
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: managed-premium
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: disk.csi.azure.com
parameters:
  storageaccounttype: Premium_LRS
  kind: Managed

​
Azure RBAC Permissions

Qovery needs Azure permissions for:
  • Creating/managing Load Balancers and Public IPs
  • Managing Azure DNS zones (if using)
  • Azure Container Registry access (if using ACR)
Example service principal roles:
  • Network Contributor (for load balancers)
  • DNS Zone Contributor (for DNS management)
  • AcrPull (for ACR access)
# Create service principal for Qovery
az ad sp create-for-rbac --name qovery-agent --role Contributor \
  --scopes /subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP

# Assign specific roles
az role assignment create \
  --assignee APP_ID \
  --role "Network Contributor" \
  --scope /subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP

az role assignment create \
  --assignee APP_ID \
  --role "DNS Zone Contributor" \
  --scope /subscriptions/SUBSCRIPTION_ID/resourceGroups/DNS_RESOURCE_GROUP

​
Cluster Configuration

​
Resource Requirements

Minimum:
  • 2 nodes (Standard_B2s or larger)
  • 4 vCPUs total
  • 8 GB RAM total
Recommended:
  • 3+ nodes across availability zones
  • Auto-scaling enabled
  • Mix of regular and Spot VMs

​
Networking

VNet Requirements:
  • Dedicated subnet for AKS nodes
  • Separate subnet for pods (Azure CNI)
  • NAT Gateway or Azure Firewall for outbound
  • Network Security Groups configured
Network Plugins:
  • Azure CNI (recommended for production)
  • Kubenet (simpler, fewer IP requirements)

​
DNS Configuration

Option 1: External-DNS (automated) 
helm install external-dns bitnami/external-dns \
  --set provider=azure \
  --set azure.resourceGroup=YOUR_RG \
  --set azure.tenantId=YOUR_TENANT \
  --set azure.subscriptionId=YOUR_SUB \
  --set txtOwnerId=my-cluster
Option 2: Manual DNS management
  • Create Azure DNS records manually for each application
  • Point to load balancer public IP

​
Best Practices

Separate Namespaces

  • Use dedicated namespace for Qovery (qovery)
  • Separate namespaces per environment
  • Apply resource quotas
  • Network policies for isolation

Access Control

  • Use Azure AD integration
  • Create managed identity for Qovery
  • Use RBAC for least privilege
  • Rotate service principal credentials regularly

High Availability

  • Multi-zone node distribution
  • Zone-redundant storage
  • Pod disruption budgets
  • Regular backups to Azure Backup

Monitoring

  • Enable Azure Monitor for containers
  • Set up alerts for Qovery agent
  • Monitor cluster resource usage
  • Integrate with Azure Log Analytics

​
Troubleshooting

Solutions:
  • Verify agent pods are running: kubectl get pods -n qovery
  • Check agent logs: kubectl logs -n qovery -l app=qovery-agent
  • Ensure outbound internet access (NAT Gateway configured)
  • Verify API token is correct
  • Check Network Security Group rules
Solutions:
  • Check node capacity and resources
  • Verify storage class exists and works
  • Ensure ingress controller is working
  • Check for network policy blocking traffic
  • Review Azure Monitor logs
Solutions:
  • Verify service principal has Network Contributor role
  • Check Network Security Group allows traffic
  • Ensure subnet has available IP addresses
  • Review load balancer health probes
  • Check Azure Activity Log for errors

​
Next Steps

Deploy Application

Deploy your first application

Cluster Configuration

Configure cluster settings

Qovery-Managed AKS

Consider Qovery-managed for easier management

Kubernetes Documentation

Generic Kubernetes BYOK guide