Migration Guide

Overview

This guide covers migrating your workloads to Kovra Cloud from three scenarios:

1. Migrating from BYOC (Bring Your Own Cluster) within Kovra
2. Migrating from other platforms (Heroku, Railway, Render)
3. Database migration steps

Migrating from BYOC to Kovra Cloud

If you are already using Kovra with your own Kubernetes clusters, migrating to Kovra Cloud simplifies your infrastructure management while keeping your applications and workflows intact.

Step 1: Plan Selection

1. Review the Kovra Cloud plans and select one that matches your current resource usage
2. Compare your current vCPU, RAM, and storage consumption against the plan limits
3. Count your databases to ensure the plan’s database quota is sufficient

Step 2: Provision a Kovra Cloud Tenant

When you select a plan, a tenant is automatically provisioned for your organization. Wait until the tenant status is ready before deploying apps.

Step 3: Recreate Applications

For each application running on your BYOC cluster:

1. Create a new application targeting Kovra Cloud from your existing Git repository
2. Copy environment variables from the old application to the new one
3. Configure custom domains (if applicable) on the new application

Step 4: Migrate Databases

See Database Migration Steps below for detailed instructions.

Step 5: DNS Cutover

See DNS Cutover Checklist below.

Step 6: Decommission BYOC Resources

After verifying that everything works on Kovra Cloud:

1. Remove old applications from the BYOC cluster
2. Delete the BYOC cluster configuration from Kovra
3. Decommission or repurpose your Kubernetes cluster

Migrating from Other Platforms

From Heroku

Applications:

1. Ensure your app has a Dockerfile or buildable source (Kovra Cloud deploys via Helm charts, not buildpacks)
2. Push your code to a GitHub or GitLab repository
3. Connect your Git provider in Kovra (Settings > Integrations)
4. Import your repository
5. Create a Kovra Cloud application from the imported repository
6. Migrate environment variables:

   # Export from Heroku
   heroku config -a my-app --json > env.json

   Then set each variable in Kovra Cloud via the Variables API or dashboard.

Databases:

1. Create a managed database in Kovra Cloud
2. Export from Heroku Postgres:

   heroku pg:backups:capture -a my-app
   heroku pg:backups:download -a my-app

3. Import into Kovra Cloud (see Database Migration Steps)

Add-ons: Heroku add-ons (Redis, Elasticsearch, etc.) must be replaced with equivalent services. Kovra Cloud currently supports managed PostgreSQL. For other services, deploy them as applications within your tenant namespace.

From Railway

Applications:

1. Export your Railway project configuration
2. Push source code to GitHub/GitLab if not already there
3. Create a Kovra Cloud application from the repository
4. Migrate environment variables from Railway’s Variables tab
5. If using Railway’s Procfile or nixpacks.toml, convert to a Dockerfile

Databases:

1. Create a managed database in Kovra Cloud
2. Connect to your Railway database and export:

   pg_dump -Fc -h <railway-host> -U <user> -d <db> > backup.dump

3. Import into Kovra Cloud (see Database Migration Steps)

From Render

Applications:

1. Ensure you have a Dockerfile or supported build configuration
2. Push code to GitHub/GitLab
3. Create a Kovra Cloud application from the repository
4. Migrate environment variables from Render’s Environment tab
5. Update health check paths if different

Databases:

1. Create a managed database in Kovra Cloud
2. Use Render’s external connection details to export:

   pg_dump -Fc -h <render-host> -U <user> -d <db> > backup.dump

3. Import into Kovra Cloud (see Database Migration Steps)

Database Migration Steps

Prerequisites

• A Kovra Cloud managed database in ready status
• The connection URL for the new database (from the database detail API)
• For importing data: a Business or Enterprise Cloud plan with VPN enabled (or run the import from within the cluster)

Step 1: Export from Source

Create a logical backup of your source database:

# Custom format (recommended for flexibility)
pg_dump -Fc -h <source-host> -U <source-user> -d <source-db> > backup.dump
 
# Plain SQL (alternative)
pg_dump -h <source-host> -U <source-user> -d <source-db> > backup.sql

Step 2: Connect to Kovra Cloud Database

You need network access to the Kovra Cloud database. Two options:

Option A: Via VPN (Business/Enterprise Cloud)

1. Enable VPN for your tenant
2. Connect via WireGuard
3. Use the internal service DNS to connect

Option B: Via a temporary pod

Run a temporary pod in your tenant namespace to perform the import (requires kubectl access).

Step 3: Import into Kovra Cloud

# Custom format restore
pg_restore -h <kovra-db-host> -U <user> -d <database> backup.dump
 
# Plain SQL restore
psql -h <kovra-db-host> -U <user> -d <database> < backup.sql

Replace the host, user, and database values with those from your Kovra Cloud database connection URL.

Step 4: Verify Data

Connect to the new database and verify:

psql "<kovra-cloud-connection-url>"
 
# Check table counts
\dt+
 
# Verify critical data
SELECT count(*) FROM <important_table>;

Step 5: Update Application Configuration

Update your application’s DATABASE_URL environment variable to point to the new Kovra Cloud database and trigger a redeployment to apply the change.

DNS Cutover Checklist

When migrating applications with custom domains, follow this checklist to minimize downtime.

Pre-Cutover

• Application is deployed and healthy on Kovra Cloud
• Database is migrated and application can connect to it
• Environment variables are configured correctly
• TLS certificate is provisioned for the custom domain
• Smoke tests pass against the Kovra Cloud deployment (using the generated subdomain)

Cutover

• Lower the TTL on your DNS records 24-48 hours before cutover (set to 60-300 seconds)
• Update CNAME records to point to the Kovra Cloud target
• Monitor DNS propagation
• Verify the application responds correctly at the custom domain
• Check TLS certificate is serving correctly

Post-Cutover

• Monitor error rates and latency for 24-48 hours
• Verify all integrations (webhooks, OAuth callbacks, etc.) work with the new endpoints
• Update any hardcoded URLs in external services
• Restore DNS TTL to normal values (3600+ seconds)
• Decommission the old deployment after the monitoring period

Minimizing Downtime

For zero-downtime migration:

1. Run both old and new deployments simultaneously
2. Use DNS-based traffic shifting (low TTL CNAME swap)
3. Keep the old deployment running for 24-48 hours as a fallback
4. Only decommission after confirming the new deployment is stable

Common Migration Pitfalls

Next Steps

• Getting Started — Initial setup guide
• App Deployment Guide — Deploy and configure applications
• Managed Databases — Database provisioning details
• Billing & Usage — Choose the right plan for your migration