Deploying Kuploy to Kubernetes

Deploy Kuploy or Kuploy Cloud to an existing Kubernetes cluster using kuploy-k8s.

Prerequisites

• Kubernetes cluster (v1.23+) — no cluster? See Local Dev Cluster to set one up with k3d
• kubectl configured with cluster access
• PostgreSQL (running in cluster or external)
• Redis (running in cluster or external)
• nginx Ingress controller
• A storage class for PVCs (--storage-class, default: longhorn)
• Optional: cert-manager for automatic TLS

Quick Start

git clone https://github.com/kuploy/kuploy-k8s.git
cd kuploy-k8s
pip install -r requirements.txt

# Check prerequisites
python deploy.py preflight

# Deploy OSS edition
python deploy.py

# Deploy Cloud edition (with billing & quotas)
python deploy.py --edition cloud

Editions

Edition	Image	Description
oss	ceduth/kuploy:latest	Open-source self-hosted version
cloud	ceduth/kuploy-cloud:latest	Multi-tenant with billing, licensing & quotas

Cloud Edition Configuration

When deploying Cloud edition, you'll be prompted for:

Variable	Required	Description
STRIPE_SECRET_KEY	Yes	Stripe API secret key
STRIPE_WEBHOOK_SECRET	Yes	Stripe webhook signing secret
BETTER_AUTH_SECRET	Yes	Authentication secret (32+ chars)
LICENSE_KEY	Yes	License key from kuploy.app
LICENSE_HUB_URL	No	License Hub URL (default: https://kuploy.app)
PLATFORM_ADMIN_EMAIL	Yes	Email of first platform admin

SMTP configuration is optional and prompted separately.

Example Cloud Deployment

python deploy.py --edition cloud \
  --domain console.example.com \
  --cert-issuer letsencrypt-prod \
  --db-namespace database \
  --postgres-service postgresql \
  --redis-service redis-master

CLI Options

Flag	Default	Description
--edition	oss	Edition: oss or cloud
--domain	(prompted)	Domain for Kuploy dashboard
--db-namespace	database	Namespace where PostgreSQL/Redis run
--app-namespace	kuploy	Namespace for Kuploy deployment
--postgres-service	postgresql	PostgreSQL service name
--postgres-secret	(none)	Admin secret for creating user/db
--redis-service	redis-master	Redis service name
--redis-secret	redis	Redis secret (for password)
--storage-class	longhorn	Storage class for PVCs
--ingress-class	nginx	Ingress class
--ingress-ip	(auto)	LoadBalancer external IP
--cert-issuer	letsencrypt-prod	cert-manager ClusterIssuer
--replicas	1	Number of replicas

Ingress IP Configuration

The deployer needs to know the external IP of your ingress controller for DNS setup.

Auto-Detection (Recommended)

By default, deploy.py auto-discovers LoadBalancer services in your cluster:

1. Finds all services with type: LoadBalancer
2. Lists their external IPs
3. Prompts you to select one (or uses the first by default)

This works well for interactive deployments on most cloud providers.

Manual Override

Use --ingress-ip when:

• CI/CD automation - No interactive prompt available
• LB provisioning delay - IP not yet assigned when deployer runs
• Multiple LoadBalancers - Skip selection prompt
• Bare-metal/MetalLB - Auto-discovery may be unreliable

python deploy.py --ingress-ip 203.0.113.50 --domain console.example.com

tip

For scripted/automated deployments, always use --ingress-ip to avoid interactive prompts.

What Gets Deployed

kuploy/                          # namespace
├── kuploy (Deployment)          # Kuploy server
├── kuploy (Service)             # ClusterIP service
├── kuploy (Ingress)             # nginx ingress + TLS
├── kuploy-data (PVC)            # Persistent storage
├── kuploy-secrets (Secret)      # DB/Redis credentials + edition secrets
├── kuploy (ServiceAccount)      # With ClusterRole for deploying apps
└── buildkitd (StatefulSet)      # Container image builder

Resource Requirements

Kuploy Server

Resource	Request	Limit
CPU	100m	2000m
Memory	256Mi	2Gi

Buildkit

Resource	Request	Limit
CPU	500m	4000m
Memory	1Gi	8Gi
Storage	20Gi cache + 10Gi workspace

Next Steps

After deployment:

1. Link your license — Required for Cloud edition
2. Cloud Billing Setup — Configure Stripe and seed plans (Cloud edition)
3. Configure the admin dashboard — Platform admin setup
4. Deploy your first app — Start deploying applications
5. Kubernetes Operations — Day-2 operations and troubleshooting