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

# BYOK with the Qovery CLI

> Install Qovery with the Qovery CLI on a Kubernetes cluster that the Qovery Operator does not support yet

## Overview

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

> [!WARNING]
>
> This installation is kept for providers that the Qovery Operator does not support yet and on-premise clusters. For an AWS, GCP or Scaleway cluster, use [Bring Your Own Kubernetes (BYOK)](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md).

## Supported Kubernetes

> **Cloud Managed**
>
> * AWS EKS
> * Google GKE
> * Azure AKS
> * Scaleway Kapsule
> * DigitalOcean DOKS

> **Self-Managed**
>
> * Vanilla Kubernetes
> * Rancher
> * OpenShift
> * k3s/k3d
> * Tanzu

> **On-Premise**
>
> * EKS Anywhere
> * Bare metal Kubernetes
> * VMware vSphere
> * Private cloud

## Requirements

> [!TIP]
>
> Kubernetes 1.24 or higher

> [!TIP]
>
> kubectl access with cluster-admin permissions

> [!TIP]
>
> LoadBalancer support (cloud or MetalLB for on-premise)

> [!TIP]
>
> Storage class for persistent volumes

## Quick Start

**1. Install Qovery CLI**

Download and install the Qovery CLI (or update to the latest version):

**Linux**

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

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

**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.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](https://brew.sh).

```bash theme={null}
# 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:

```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.

**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.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](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
```

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

**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. Install Qovery on your cluster**

Run the following command from your terminal and follow the instructions:

```bash theme={null}
qovery auth
qovery context set
qovery cluster install
```

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:

```bash theme={null}
kubectl get pods -n qovery
```

**4. Verify in Qovery Console**

Your cluster should now show as "Running" in the Qovery Console.

## What Qovery Installs

**Core Components**:

* Qovery Agent (deployment manager)
* Qovery Shell Agent (for terminal access)

**Optional Components** (if not present):

* Nginx Ingress Controller
* Cert-Manager (SSL certificates)
* External-DNS (domain management)
* Metrics Server

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

Automatically provisioned by cloud provider:

* AWS: ALB/NLB
* GCP: Google Cloud Load Balancer
* Azure: Azure Load Balancer

**MetalLB (On-Premise)**

Install MetalLB for bare metal:

```bash theme={null}
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.12/config/manifests/metallb-native.yaml

# Configure IP pool
cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: first-pool
  namespace: metallb-system
spec:
  addresses:
  - 192.168.1.240-192.168.1.250
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: first-pool
  namespace: metallb-system
spec:
  ipAddressPools:
  - first-pool
EOF
```

## Storage Configuration

Ensure default storage class exists:

```yaml theme={null}
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: standard
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: kubernetes.io/gce-pd  # Change based on your provider
parameters:
  type: pd-standard
```

For on-premise, consider:

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

> **Resource 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**
>
> **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**
>
> **For Cloud**: Check cloud provider quotas and permissions
>
> **For On-Premise**: Install MetalLB and configure IP pool

> **Storage Issues**
>
> **Check**:
>
> * Storage class exists: `kubectl get sc`
> * Default storage class set
> * Provisioner is working
> * Sufficient storage capacity

## Platform-Specific Guides

> **[EKS Anywhere](https://www.qovery.com/docs/configuration/integrations/kubernetes/eks/eks-anywhere.md)**
>
> Deploy on EKS Anywhere with Qovery

> **[AWS, GCP and Scaleway](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md)**
>
> Connect a cluster with the Qovery Operator


## Related topics

- [Qovery CLI](https://www.qovery.com/docs/cli/overview.md)
- [Import Environment Variables with the Qovery CLI](https://www.qovery.com/docs/getting-started/guides/advanced-tutorials/import-env-vars-cli.md)
- [Customizing Preview URL with Qovery CLI](https://www.qovery.com/docs/getting-started/guides/advanced-tutorials/customizing-preview-url-with-qovery-cli.md)
- [Bring Your Own Kubernetes (BYOK)](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md)
- [BYOK (Bring Your Own Kubernetes)](https://www.qovery.com/docs/getting-started/installation/kubernetes.md)


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