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

# Install Qovery on other Kubernetes clusters with the CLI

> Install Qovery with qovery cluster install on any Kubernetes cluster other than EKS, GKE and Kapsule, such as AKS, k3s, OpenShift or an on-premise cluster.

## Overview

Qovery runs on any Kubernetes cluster. The `qovery 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.

> [!NOTE]
>
> 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](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md). See [Which installation to use](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok-supported-setups.md#which-installation-to-use).
>
> This installation is available on every Qovery plan, including Free.

## Clusters this installation covers

> [card] Cloud Managed
>
> * Azure AKS
> * DigitalOcean DOKS
> * Other managed Kubernetes services

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

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

## Requirements

> [!TIP]
>
> Kubernetes 1.31 or later

> [!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):

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

`qovery cluster install` generates a Helm values file and the Helm commands that install the `qovery` chart.

> [!WARNING]
>
> The values file holds the credential your cluster uses to connect to Qovery. Do not commit it to version control or share it, and delete it once the installation is done.

The values file enables:

**Qovery components**:

* Qovery engine and cluster agent (run and track deployments)
* Qovery shell agent (terminal access to your services)

**Platform components**:

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

To keep a component you already run, such as cert-manager, turn off the Qovery copy in the values file before you run the Helm commands.

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

> [tab] Cloud Load Balancer
>
> Automatically provisioned by cloud provider:
>
> * AWS: ALB/NLB
> * GCP: Google Cloud Load Balancer
> * Azure: Azure Load Balancer

> [tab] 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

> [card] Dedicated Namespace
>
> Use dedicated `qovery` namespace for Qovery components

> [card] Resource Quotas
>
> Set resource quotas per namespace to prevent resource exhaustion

> [card] Network Policies
>
> Implement network policies for namespace isolation

> [card] Regular Updates
>
> Keep Kubernetes and Qovery agent updated regularly

## Troubleshooting

> [accordion] 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

> [accordion] Load Balancer Pending
>
> **For Cloud**: Check cloud provider quotas and permissions
>
> **For On-Premise**: Install MetalLB and configure IP pool

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

## Platform-Specific Guides

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

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


## Related topics

- [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)
- [Supported cluster setups for your own cluster](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok-supported-setups.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.