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

# Bring Your Own Kubernetes (BYOK)

> Connect any Kubernetes cluster to Qovery

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

## Supported Kubernetes

<CardGroup cols={3}>
  <Card title="Cloud Managed" icon="cloud">
    * AWS EKS
    * Google GKE
    * Azure AKS
    * Scaleway Kapsule
    * DigitalOcean DOKS
  </Card>

  <Card title="Self-Managed" icon="server">
    * Vanilla Kubernetes
    * Rancher
    * OpenShift
    * k3s/k3d
    * Tanzu
  </Card>

  <Card title="On-Premise" icon="building">
    * EKS Anywhere
    * Bare metal Kubernetes
    * VMware vSphere
    * Private cloud
  </Card>
</CardGroup>

## Requirements

<Check>Kubernetes 1.24 or higher</Check>
<Check>kubectl access with cluster-admin permissions</Check>
<Check>LoadBalancer support (cloud or MetalLB for on-premise)</Check>
<Check>Storage class for persistent volumes</Check>
<Check>Ingress controller (Nginx or similar)</Check>
<Check>Metrics server installed</Check>

## Quick Start

<Steps>
  <Step title="Install Qovery CLI">
    Download and install the Qovery CLI (or update to the latest version):

    <Tabs>
      <Tab title="Linux">
        <Tabs>
          <Tab title="*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.
            </Warning>
          </Tab>

          <Tab title="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>

          <Tab title="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
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="MacOS">
        <Tabs>
          <Tab title="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>

          <Tab title="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.
            </Warning>
          </Tab>

          <Tab title="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
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Windows">
        <Tabs>
          <Tab title="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>

          <Tab title="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>
        </Tabs>
      </Tab>

      <Tab title="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
        ```

        <Info>
          `ghcr.io` is the [GitHub Container Registry](https://github.com/Qovery/qovery-cli/pkgs/container/qovery-cli).
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install Qovery on your cluster">
    Run the following command from your terminal and follow the instructions:

    ```bash theme={null}
    qovery cluster install
    ```

    This interactive command will guide you through the installation process and configure the Qovery agent on your cluster.
  </Step>

  <Step title="Verify Qovery Pods">
    Check that all Qovery pods are running in your cluster:

    ```bash theme={null}
    kubectl get pods -n qovery
    ```
  </Step>

  <Step title="Verify in Qovery Console">
    Your cluster should now show as "Running" in the Qovery Console.
  </Step>
</Steps>

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

<Tabs>
  <Tab title="Cloud Load Balancer">
    Automatically provisioned by cloud provider:

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

  <Tab title="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
    EOF
    ```
  </Tab>
</Tabs>

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

<CardGroup cols={2}>
  <Card title="Dedicated Namespace" icon="folder-tree">
    Use dedicated `qovery` namespace for Qovery components
  </Card>

  <Card title="Resource Quotas" icon="gauge">
    Set resource quotas per namespace to prevent resource exhaustion
  </Card>

  <Card title="Network Policies" icon="shield">
    Implement network policies for namespace isolation
  </Card>

  <Card title="Regular Updates" icon="arrow-up">
    Keep Kubernetes and Qovery agent updated regularly
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="Load Balancer Pending">
    **For Cloud**: Check cloud provider quotas and permissions

    **For On-Premise**: Install MetalLB and configure IP pool
  </Accordion>

  <Accordion title="Storage Issues">
    **Check**:

    * Storage class exists: `kubectl get sc`
    * Default storage class set
    * Provisioner is working
    * Sufficient storage capacity
  </Accordion>
</AccordionGroup>

## Platform-Specific Guides

<CardGroup cols={2}>
  <Card title="AWS EKS BYOK" icon="https://mintcdn.com/qovery/Nvnl0g5BHzA0XQmy/images/logos/cloud-providers/aws-icon.svg?fit=max&auto=format&n=Nvnl0g5BHzA0XQmy&q=85&s=12ef689645255696bfa4054d6e3aeaff" href="/configuration/integrations/kubernetes/eks/byok" width="24" height="24" data-path="images/logos/cloud-providers/aws-icon.svg">
    Connect existing EKS cluster
  </Card>

  <Card title="EKS Anywhere" icon="building" href="/configuration/integrations/kubernetes/eks/eks-anywhere">
    Connect EKS Anywhere cluster
  </Card>

  <Card title="Generic Kubernetes" icon="dharmachakra" href="/configuration/integrations/kubernetes/byok">
    Detailed BYOK installation guide
  </Card>
</CardGroup>