> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Supported cluster setups for your own cluster

> Qovery runs on any Kubernetes cluster: the Qovery Operator for EKS, GKE and Kapsule, the Qovery CLI for others. Check version, prerequisites and conflicts.

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](https://www.qovery.com/docs/configuration/integrations/kubernetes/docker.md).

## Which installation to use

| Your cluster | Installation | How it works |
| - | - | - |
| Amazon EKS (AWS), Google GKE (GCP) or Scaleway Kapsule | [Qovery Operator installation](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md) (Preview) | You create the cluster in the Qovery Console and install the Operator once with Helm. Qovery then installs and updates its stack on the cluster. |
| Any other cluster: Azure AKS, k3s, OpenShift, Rancher, on-premise or another provider | [Installation with the Qovery CLI](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok-legacy.md) | You run `qovery cluster install` with your kubeconfig pointing to the cluster. |

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**

> [tab] Linux
>
> > [tab] \*nix
> >
> > To download and install Qovery CLI on any Linux distribution:
> >
> > ```bash theme={null}
> > curl -s https://get.qovery.com | bash
> > ```
> >
> > > [!WARNING]
> > >
> > > 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](https://github.com/Qovery/qovery-cli/releases) published with each release.
>
> > [tab] Arch Linux
> >
> > Qovery is part of [AUR](https://aur.archlinux.org/packages) packages, so you can install it with [yay](https://github.com/Jguer/yay):
> >
> > ```bash theme={null}
> > yay qovery-cli
> > ```
>
> > [tab] Manual
> >
> > Install the Qovery CLI on Linux manually from a [pinned release](https://github.com/Qovery/qovery-cli/releases) to ensure you control what version is installed.
> >
> > Replace `X.Y.Z` with the version you want to install:
> >
> > ```bash theme={null}
> > VERSION=1.180.0  # version number without the 'v' prefix
> > ARCH=amd64      # use arm64 for ARM64
> > ARCHIVE="qovery-cli_${VERSION}_linux_${ARCH}.tar.gz"
> >
> > # Download the binary and checksums for your platform
> > curl -sL "https://github.com/Qovery/qovery-cli/releases/download/v${VERSION}/${ARCHIVE}" -o "${ARCHIVE}"
> > curl -sL "https://github.com/Qovery/qovery-cli/releases/download/v${VERSION}/checksums.txt" -o checksums.txt
> >
> > # Verify the checksum of the downloaded file only (fails if tampered)
> > grep "${ARCHIVE}" checksums.txt | sha256sum --check
> >
> > # Extract and install
> > tar -xzf "${ARCHIVE}"
> > mv qovery /usr/local/bin/qovery
> > chmod +x /usr/local/bin/qovery
> > ```

> [tab] MacOS
>
> > [tab] Homebrew
> >
> > The common solution to install a command line binary on the MacOS is to use [Homebrew](https://brew.sh).
> >
> > ```bash theme={null}
> > # Add Qovery brew repository
> > brew tap Qovery/qovery-cli
> >
> > # Install the CLI
> > brew install qovery-cli
> > ```
>
> > [tab] Script
> >
> > To download and install Qovery CLI from the command line:
> >
> > ```bash theme={null}
> > curl -s https://get.qovery.com | bash
> > ```
> >
> > > [!WARNING]
> > >
> > > 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](https://github.com/Qovery/qovery-cli/releases) published with each release.
>
> > [tab] Manual
> >
> > Install the Qovery CLI on macOS manually from a [pinned release](https://github.com/Qovery/qovery-cli/releases) to ensure you control what version is installed.
> >
> > Replace `X.Y.Z` with the version you want to install:
> >
> > ```bash theme={null}
> > VERSION=1.180.0  # version number without the 'v' prefix
> > ARCH=amd64      # use arm64 for Apple Silicon (M1/M2/M3)
> > ARCHIVE="qovery-cli_${VERSION}_darwin_${ARCH}.tar.gz"
> >
> > # Download the binary and checksums for your platform
> > curl -sL "https://github.com/Qovery/qovery-cli/releases/download/v${VERSION}/${ARCHIVE}" -o "${ARCHIVE}"
> > curl -sL "https://github.com/Qovery/qovery-cli/releases/download/v${VERSION}/checksums.txt" -o checksums.txt
> >
> > # Verify the checksum of the downloaded file only (fails if tampered)
> > grep "${ARCHIVE}" checksums.txt | shasum -a 256 --check
> >
> > # Extract and install
> > tar -xzf "${ARCHIVE}"
> > mv qovery /usr/local/bin/qovery
> > chmod +x /usr/local/bin/qovery
> > ```

> [tab] Windows
>
> > [tab] Scoop
> >
> > The classic way to install binaries on Windows is to use [Scoop](https://scoop.sh).
> >
> > ```bash theme={null}
> > # Add Qovery bucket
> > scoop bucket add qovery https://github.com/Qovery/scoop-qovery-cli
> >
> > # Install the CLI
> > scoop install qovery-cli
> > ```
>
> > [tab] Manual
> >
> > Install the Qovery CLI on Windows manually by downloading the [latest release](https://github.com/Qovery/qovery-cli/releases), and uncompress its content to `C:\Windows`.

> [tab] Docker
>
> Install Docker on your local machine and run the following command:
>
> ```bash theme={null}
> # Pull and Run the latest Qovery CLI
> docker run ghcr.io/qovery/qovery-cli:latest help
> ```
>
> Change `latest` by the version you want to use. For example, to use the version 0.58.4, run:
>
> ```bash theme={null}
> docker run ghcr.io/qovery/qovery-cli:0.58.4 help
> ```
>
> > [!NOTE]
> >
> > `ghcr.io` is the [GitHub Container Registry](https://github.com/Qovery/qovery-cli/pkgs/container/qovery-cli).

**2. Point kubectl to your cluster**

```bash theme={null}
kubectl config current-context
```

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

**3. Run the preflight**

```bash theme={null}
qovery cluster 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

| Check | Fails when | Warns when |
| - | - | - |
| Kubernetes API and version | The API is unreachable, or Kubernetes is older than 1.30 | Kubernetes is 1.30, or newer than 1.36 |
| cluster-admin permissions | Your kubeconfig user is not cluster-admin | |
| Node OS and architecture | No Ready Linux node with an `amd64` or `arm64` CPU | Some nodes cannot run Qovery, for example Windows nodes |
| Node size for builds | | No schedulable node has 4 vCPU and 8 GiB allocatable |
| Namespace `qovery` | The namespace is being deleted | |
| Existing Qovery CLI installation | The Helm release `qovery` of an installation with the Qovery CLI exists | |
| Existing cert-manager | cert-manager or its CRDs exist outside the Qovery installation | |
| Existing ExternalDNS | ExternalDNS runs outside the Qovery installation | |
| Existing Envoy Gateway | Envoy Gateway or its CRDs exist outside the Qovery installation | |
| Existing Gateway API CRDs | | The Gateway API CRDs were installed by another tool |
| Default StorageClass | No default StorageClass and Loki uses `pvc` storage | Several StorageClasses are marked as default |
| Amazon EBS CSI driver (AWS only) | The driver is missing and Loki uses `pvc` storage | The driver is missing and Loki uses object storage |
| Cluster DNS | The `kube-dns` Service has no ready endpoint | The `kube-dns` Service does not exist, so DNS could not be verified |
| LoadBalancer Services | | A LoadBalancer Service has no address |
| metrics-server | | The `metrics.k8s.io` API is not available |

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](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok-legacy.md).

### 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:

  ```bash theme={null}
  kubectl -n default run qovery-dns-preflight --rm -i --restart=Never --image=busybox:1.36 -- nslookup engine.qovery.com
  ```

  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](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md#preflight-checks).

## Operator installation: providers and versions

| | Supported |
| - | - |
| Providers | Amazon EKS (AWS), Google GKE (GCP), Scaleway Kapsule |
| Kubernetes versions | 1.31 or later |
| Node operating system | Linux |
| Node CPU architectures | `amd64` and `arm64` |
| Node autoscaling | Managed node groups, node pools and Karpenter. See the node label keys in [Create the cluster](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md#create-the-cluster). |

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](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok-legacy.md).

## Operator installation: prerequisites

The full list, with the cloud credential permissions, is in [Prerequisites](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md#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.

| Component | What Qovery installs | If it already runs on the cluster |
| - | - | - |
| cert-manager | cert-manager v1.20, Helm release `cert-manager` | Use a cluster without cert-manager, or uninstall it and its CRDs if nothing else uses it. |
| ExternalDNS | ExternalDNS for the domain provided by Qovery, Helm release `external-dns` | Use a cluster without ExternalDNS, or uninstall it if nothing else uses it. |
| Envoy Gateway | Envoy Gateway v1.9, Helm releases `envoy-gateway-crd` and `envoy-gateway`, plus the Qovery GatewayClass and Gateway in the releases `qovery-gateway-class` and `qovery-cluster-gateway` | Use a cluster without Envoy Gateway, or uninstall it and its CRDs if nothing else uses it. |
| Gateway API CRDs | The experimental channel of the Gateway API CRDs, bundle v1.6.1, from release `envoy-gateway-crd` | CRDs installed and kept up to date by another tool, such as the GKE Gateway API, a service mesh or a load balancer controller, can conflict with Qovery. On GKE, disable the Gateway API of the cluster if nothing uses it. Otherwise, contact Qovery Support before you install. |
| Existing Qovery CLI installation | | A cluster installed with `qovery cluster install` holds the Helm release `qovery`. The Qovery Operator does not take it over. Uninstall it with `helm -n qovery uninstall qovery` and remove its cert-manager, ExternalDNS and Gateway resources, or use another cluster. |

> [!WARNING]
>
> 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.


## Related topics

- [Clusters](https://www.qovery.com/docs/configuration/clusters.md)
- [Bring Your Own Kubernetes (BYOK)](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md)
- [qovery cluster](https://www.qovery.com/docs/cli/commands/cluster.md)
- [Local Cluster for Development](https://www.qovery.com/docs/configuration/integrations/kubernetes/docker.md)
- [Create Your Cluster](https://www.qovery.com/docs/getting-started/quickstart/cloud.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.