BYOK (Bring Your Own Kubernetes)

Install Qovery on your own Kubernetes cluster

Qovery Self-Managed (also known as BYOK: Bring Your Own Kubernetes) is a self-hosted version of Qovery. It allows you to install Qovery on your own Kubernetes cluster.

For Kubernetes Experts Only: Qovery BYOK is for Kubernetes experts who want to manage their own Kubernetes cluster.

Qovery automatically updates ONLY the Qovery applications (agent, shell-agent, etc.) via the Qovery Helm chart. With the self-managed offer, it will be up to you to manage any dependency components (ingress, DNS, logging), making sure they run with the right version over time.

The dependencies provided with the Qovery Helm chart are here to help you with the bootstrap, and are not maintained by Qovery.

Prerequisites

Before you begin, ensure you have:

An operational Kubernetes cluster (any distribution)

Minimum 4 CPUs and 8GB RAM available in your cluster

kubectl installed and configured for cluster access

helm package manager installed

Active Qovery account - Sign up here

Installation

Step 1: Install Qovery CLI

Install the Qovery CLI on your local machine:

Linux

*nix

To download and install Qovery CLI on any Linux distribution:

curl -s https://get.qovery.com | bash

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.

Arch Linux

Qovery is part of AUR packages, so you can install it with yay:

yay qovery-cli

Manual

Install the Qovery CLI on Linux manually from a pinned release to ensure you control what version is installed.

Replace X.Y.Z with the version you want to install:

VERSION=1.48.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

MacOS

Homebrew

The common solution to install a command line binary on the MacOS is to use Homebrew.

# Add Qovery brew repository
brew tap Qovery/qovery-cli

# Install the CLI
brew install qovery-cli

Script

To download and install Qovery CLI from the command line:

curl -s https://get.qovery.com | bash

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.

Manual

Install the Qovery CLI on macOS manually from a pinned release to ensure you control what version is installed.

Replace X.Y.Z with the version you want to install:

VERSION=1.48.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

Windows

Scoop

The classic way to install binaries on Windows is to use Scoop.

# Add Qovery bucket
scoop bucket add qovery https://github.com/Qovery/scoop-qovery-cli

# Install the CLI
scoop install qovery-cli

Manual

Install the Qovery CLI on Windows manually by downloading the latest release, and uncompress its content to C:\Windows.

Docker

Install Docker on your local machine and run the following command:

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

docker run ghcr.io/qovery/qovery-cli:0.58.4 help

ghcr.io is the GitHub Container Registry.

Step 2: Authenticate

Authenticate with your Qovery account:

qovery auth

This will open a browser window for authentication.

For headless environments (CI/CD, remote servers) without a graphical interface, use qovery auth --headless and follow the instructions to authenticate manually.

Step 3: Deploy to Kubernetes

Run the installation command and follow the interactive prompts:

qovery cluster install

The installation typically takes 5-10 minutes.

Post-Installation

After successful deployment:

1. Validate Installation: Check that all Qovery components are running:

   kubectl get pods -n qovery
   

2. Verify in Console: Log in to Qovery Console to confirm your cluster appears with a Connected status.

3. Deploy Applications: You can now start deploying your applications through the Qovery Console.

For comprehensive validation steps and troubleshooting, see the BYOK Integration Guide.

Next Steps

Deploy Your First App

Follow our quickstart guide

BYOK Advanced Configuration

Detailed setup and configuration options

Qovery Helm Chart

View on GitHub

Get Help

Contact support

Kubernetes Changelog

Kubernetes cluster related updates