Skip to main content
Qovery runs on any Kubernetes cluster. There are two ways to install it on a cluster you already run, and the provider of your cluster decides which one to use. Both are available on every Qovery plan, including Free. To try Qovery before you connect a real cluster, run qovery demo up. It creates a local k3s cluster with Docker and installs the Qovery Operator on it. The table below applies to clusters you run yourself: the local demo is the only k3s setup that uses the Operator. See Local cluster for development.

​
Which installation to use

Both installations need Kubernetes 1.31 or later. The rest of this page covers the Qovery Operator installation: the checks to run before you install, its prerequisites and the components that must not already run on the cluster. Most failed installations come from a component that already exists on the cluster, such as cert-manager, or from a missing default StorageClass. Run the preflight first: it takes a few seconds and changes nothing on the cluster.

​
Check your cluster before you install

The preflight reads your cluster with your current kubeconfig context and reports each check as PASS, WARN, FAIL or SKIP, with the fix for each problem. It needs no Qovery account and is available from Qovery CLI 1.180.0.
1

Install the Qovery CLI

To download and install Qovery CLI on any Linux distribution:
The install script does not verify the binary’s integrity. For security-sensitive environments, use the Manual tab to download a pinned release and verify its checksum against the official checksums.txt published with each release.
2

Point kubectl to your cluster

The preflight checks this context. To check another one, pass --context <name> and, if needed, --kubeconfig <path>.
3

Run the preflight

If Loki will store logs in object storage (s3, gcs or s3Compatible) instead of the default pvc storage, add --loki-object-storage. Add --json for a machine-readable report.
4

Fix the failed checks

The command exits with status 1 when at least one check fails. A failed check would make the installation or the first deployment of the cluster fail, so fix it and run the preflight again. A warning does not block the installation but can break a feature, for example autoscaling without metrics-server.
The preflight only sends read requests and one permission review to the Kubernetes API. It creates, changes and deletes nothing, and it reads no Secret content.

​
What the preflight checks

The table describes the checks for the Qovery Operator installation. When the preflight picks the installation with the Qovery CLI (any cluster other than EKS, GKE or Kapsule, or --install-path cli):
  • An existing cert-manager, ExternalDNS or Envoy Gateway is a warning, not a failure. qovery cluster install installs these components too: turn off the Qovery copy in the Helm values file it generates, or remove the existing one.
  • An existing Helm release qovery is your CLI installation, so it passes.
  • The cloud provider result tells you which installation to use and never fails.
The preflight also reports the provider of your nodes and the installation to use. This result is informational and never fails the preflight: on EKS, GKE or Kapsule it confirms the Qovery Operator installation, and on any other cluster it recommends the installation with the Qovery CLI.

​
What the preflight does not check

Some prerequisites cannot be verified without creating a resource on the cluster. Check them yourself:
  • Outbound access and public DNS from a Pod. The lookup must return an address:
    This command creates a temporary Pod and deletes it when it ends.
  • Public load balancers. The preflight only looks at LoadBalancer Services that already exist. If there are none, it reports SKIP. The Qovery gateway needs the cluster to create a public load balancer.
  • Free capacity. The preflight compares the allocatable CPU and memory of each node with what a build needs. It does not know what your workloads already use.
Once the Operator is installed, Qovery runs more checks before each deployment of the cluster. See Preflight checks.

​
Operator installation: providers and versions

Kubernetes 1.30 can reject part of the Gateway API CRDs that Qovery installs, and older versions lack an API they use. The preflight fails below 1.30 and warns on 1.30. For any other cluster, such as Azure AKS, k3s or an on-premise cluster, use the installation with the Qovery CLI.

​
Operator installation: prerequisites

The full list, with the cloud credential permissions, is in Prerequisites. In short, the cluster needs:
  • kubectl access with cluster-admin rights and helm on your machine, only to install the Operator once.
  • At least one Linux node with 4 vCPU and 8 GiB of memory free, for the builder pods.
  • A default StorageClass, unless Loki stores logs in object storage. On EKS, the Amazon EBS CSI driver add-on with its IAM role.
  • The ability to create a public load balancer for a Service of type LoadBalancer. On EKS, the public subnets must carry the kubernetes.io/role/elb=1 tag.
  • A working cluster DNS (CoreDNS) that resolves public names.
  • Outbound internet access to Qovery and to public container registries.
  • metrics-server, for services with autoscaling.

​
Components that must not already run on the cluster

Qovery installs these components in the qovery namespace and manages them. It does not take over an installation that already exists.
Uninstalling cert-manager, ExternalDNS or Envoy Gateway removes the certificates, DNS records or routes they manage. Check what depends on them before you remove them, or use a dedicated cluster for Qovery.

​
Get help

If the preflight reports a problem you cannot fix, or you are not sure which installation fits your cluster, contact Qovery Support through your usual channel: in-app chat, shared Slack or Microsoft Teams channel, or email. Include the output of qovery cluster preflight --json. It contains no credential.