Skip to main content

​
Overview

Bring Your Own Kubernetes (BYOK) allows you to connect your existing Scaleway Kapsule cluster to Qovery. You maintain full control over your cluster while Qovery manages application deployments.

​
Prerequisites

Existing Scaleway Kapsule cluster (Kubernetes 1.24+)
kubectl access with cluster-admin permissions
Scaleway API credentials for Qovery
Block Storage CSI driver installed
Load Balancer configuration

​
Setup

1

Get Qovery Agent Manifests

In Qovery Console:
  1. Settings → Clusters → Add Cluster
  2. Select “Bring Your Own Kubernetes”
  3. Choose “Scaleway Kapsule”
  4. Download Helm values or kubectl manifests
2

Install Qovery Agent

Using Helm (recommended):
helm repo add qovery https://helm.qovery.com
helm repo update

helm install qovery-agent qovery/qovery-agent \
  --namespace qovery \
  --create-namespace \
  --values qovery-values.yaml
Or using kubectl:
kubectl apply -f qovery-agent.yaml
3

Verify Connection

Check agent status:
kubectl get pods -n qovery
# qovery-agent-* should be Running
In Qovery Console, cluster should show as “Connected”
4

Deploy Applications

Start deploying applications to your BYOK cluster

​
What Qovery Installs

Qovery Agent:
  • Manages application deployments
  • Communicates with Qovery Control Plane
  • Handles secrets and configuration
Optional Components (if not present):
  • Nginx Ingress Controller
  • Cert-Manager (for SSL certificates)
  • External-DNS (for domain management)
  • Metrics Server

​
Requirements

​
Kubernetes Version

  • Minimum: 1.24
  • Recommended: 1.27+
  • Maximum: 1.29

​
Required Addons

  • Storage
  • Load Balancer
  • Metrics
Scaleway Block Storage CSI Driver:Kapsule clusters have this enabled by default. Verify:
kubectl get csidriver block.csi.scaleway.com
Storage Class:
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: scw-bssd
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: block.csi.scaleway.com
parameters:
  type: sbs_volume
  encrypted: "true"

​
Scaleway IAM Permissions

Qovery needs Scaleway IAM permissions for:
  • Creating/managing Load Balancers
  • Managing DNS records (if using Scaleway DNS)
  • Container Registry access (if using Scaleway Registry)
Required API scopes:
  • LoadBalancerFullAccess
  • DNSFullAccess (if using Scaleway DNS)
  • ContainerRegistryReadOnly (if using registry)
# Create API key with appropriate permissions
# Via Scaleway Console: IAM → API Keys → Generate API Key
# Assign organization-level permissions or project-specific scopes

​
Cluster Configuration

​
Resource Requirements

Minimum:
  • 2 nodes (DEV1-M or larger)
  • 4 vCPUs total
  • 8 GB RAM total
Recommended:
  • 3+ nodes across multiple availability zones
  • Auto-scaling enabled
  • Use GP1 or PRO2 instance types for production

​
Networking

VPC Requirements:
  • Private VPC for node communication
  • Public IPs for load balancers
  • Firewall rules configured for ingress
  • Security Groups allowing required traffic
Private Network:
  • Nodes on private network
  • Load balancers on public network
  • No NAT gateway needed (free internal traffic)

​
DNS Configuration

Option 1: External-DNS with Scaleway DNS (automated) 
helm install external-dns bitnami/external-dns \
  --set provider=scaleway \
  --set scaleway.scwAccessKey=YOUR_ACCESS_KEY \
  --set scaleway.scwSecretKey=YOUR_SECRET_KEY \
  --set txtOwnerId=my-cluster
Option 2: Manual DNS management
  • Create DNS records manually for each application
  • Point to load balancer public IP

​
Best Practices

Separate Namespaces

  • Use dedicated namespace for Qovery (qovery)
  • Separate namespaces per environment
  • Apply resource quotas
  • Network policies for isolation

Access Control

  • Create dedicated API key for Qovery
  • Use RBAC for least privilege
  • Project-level API scopes (not organization-wide)
  • Rotate API keys regularly

High Availability

  • Multi-AZ node distribution
  • Pod disruption budgets
  • Regular backups to Scaleway Object Storage
  • Block Storage snapshots

Monitoring

  • Enable Scaleway Observability (Cockpit)
  • Set up alerts for Qovery agent
  • Monitor cluster resource usage
  • Track application health

​
Troubleshooting

Solutions:
  • Verify agent pods are running: kubectl get pods -n qovery
  • Check agent logs: kubectl logs -n qovery -l app=qovery-agent
  • Ensure outbound internet access
  • Verify API token is correct
  • Check security group rules
Solutions:
  • Check node capacity and resources
  • Verify storage class exists and works
  • Ensure ingress controller is working
  • Check for network policy blocking traffic
  • Review Scaleway Cockpit logs
Solutions:
  • Verify Scaleway Cloud Controller Manager is running
  • Check IAM permissions for load balancer creation
  • Ensure security groups allow health check traffic
  • Review load balancer annotations
  • Check Scaleway Console for errors

​
Cost Optimization Tips

Use Development Instances

Use DEV1 series for dev/test environments (lower cost)

Right-Size Nodes

Start with GP1-M and scale as needed

Enable Autoscaling

Scale down during off-hours automatically

Use Block Storage Efficiently

Delete unused volumes and enable compression

​
Next Steps

Deploy Application

Deploy your first application

Cluster Configuration

Configure cluster settings

Qovery-Managed Kapsule

Consider Qovery-managed for easier management

Kubernetes Documentation

Generic Kubernetes BYOK guide