Overview
Qovery runs on any Kubernetes cluster. Theqovery cluster install command of the Qovery CLI installs Qovery on a cluster you already run, such as Azure AKS, k3s, OpenShift or an on-premise cluster. You keep control of your cluster infrastructure, and Qovery manages application deployments on it.
Use this installation for any cluster other than Amazon EKS, Google GKE and Scaleway Kapsule, for example Azure AKS, k3s or an on-premise cluster. For an EKS, GKE or Kapsule cluster, use the Qovery Operator installation. See Which installation to use.This installation is available on every Qovery plan, including Free.
Clusters this installation covers
Cloud Managed
- Azure AKS
- DigitalOcean DOKS
- Other managed Kubernetes services
Self-Managed
- Vanilla Kubernetes
- Rancher
- OpenShift
- k3s/k3d
- Tanzu
On-Premise
- EKS Anywhere
- Bare metal Kubernetes
- VMware vSphere
- Private cloud
Requirements
Kubernetes 1.31 or later
kubectl access with cluster-admin permissions
LoadBalancer support (cloud or MetalLB for on-premise)
Storage class for persistent volumes
Quick Start
1
Install Qovery CLI
Download and install the Qovery CLI (or update to the latest version):
- Linux
- MacOS
- Windows
- Docker
- *nix
- Arch Linux
- Manual
To download and install Qovery CLI on any Linux distribution:
2
Install Qovery on your cluster
Run the following command from your terminal and follow the instructions:This interactive command will guide you through the installation process and configure the Qovery agent on your cluster.
3
Verify Qovery Pods
Check that all Qovery pods are running in your cluster:
4
Verify in Qovery Console
Your cluster should now show as “Running” in the Qovery Console.
What Qovery Installs
qovery cluster install generates a Helm values file and the Helm commands that install the qovery chart.
The values file enables:
Qovery components:
- Qovery engine and cluster agent (run and track deployments)
- Qovery shell agent (terminal access to your services)
- Envoy Gateway, with the Gateway API CRDs and the Qovery GatewayClass and Gateway (exposes your applications)
- cert-manager (TLS certificates)
- ExternalDNS (domain management)
- metrics-server (autoscaling)
- Loki and Alloy (application logs)
Networking Requirements
Inbound
- Port 443: HTTPS traffic to applications
- Port 80: HTTP traffic (redirects to 443)
Outbound
- Qovery API:
https://api.qovery.com - Container Registries: ECR, Docker Hub, GCR, etc.
- Git Providers: GitHub, GitLab, Bitbucket
Load Balancer
- Cloud Load Balancer
- MetalLB (On-Premise)
Automatically provisioned by cloud provider:
- AWS: ALB/NLB
- GCP: Google Cloud Load Balancer
- Azure: Azure Load Balancer
Storage Configuration
Ensure default storage class exists:- NFS: Network File System
- Ceph: Distributed storage
- Local Path: Local storage (not recommended for production)
Best Practices
Dedicated Namespace
Use dedicated
qovery namespace for Qovery componentsResource Quotas
Set resource quotas per namespace to prevent resource exhaustion
Network Policies
Implement network policies for namespace isolation
Regular Updates
Keep Kubernetes and Qovery agent updated regularly
Troubleshooting
Agent Not Connecting
Agent Not Connecting
Check:
- Agent pods running:
kubectl get pods -n qovery - Agent logs:
kubectl logs -n qovery -l app=qovery-agent - Outbound internet access from cluster
- API token is correct
Load Balancer Pending
Load Balancer Pending
For Cloud: Check cloud provider quotas and permissionsFor On-Premise: Install MetalLB and configure IP pool
Storage Issues
Storage Issues
Check:
- Storage class exists:
kubectl get sc - Default storage class set
- Provisioner is working
- Sufficient storage capacity
Platform-Specific Guides
EKS Anywhere
Deploy on EKS Anywhere with Qovery
AWS, GCP and Scaleway
Connect a cluster with the Qovery Operator