VPN / Private Access

What is Private Access?

Kovra Cloud databases are always internal to the cluster and never exposed to the public internet. Private access via WireGuard VPN lets you:

• Connect to your databases from your local machine using tools like psql or GUI clients
• Access applications configured with private access mode
• Reach internal Kubernetes services within your tenant namespace

Private access is available on Business ($300/mo) and Enterprise Cloud ($450/mo) plans only. Developer and Team plans do not include VPN.

Architecture

Each tenant gets a dedicated WireGuard pod deployed in their namespace when VPN is enabled. The architecture uses:

• One WireGuard peer per organization (no multi-peer support)
• Shared Network Load Balancer (NLB) across all Business/Enterprise tenants
• Unique NodePort allocated per tenant from a pre-seeded port pool
• Deterministic subnet derived from the tenant UUID (format: 10.X.Y.0/24)

The VPN endpoint hostname is vpn.cloud.kovra.dev with a per-tenant port.

Enabling VPN

Prerequisites

• Business or Enterprise Cloud plan
• Tenant in ready status

Step-by-Step

1. Navigate to the VPN page in the dashboard sidebar
2. Click Enable VPN
3. Wait for the VPN status to transition from enabling to enabled (typically a few seconds)
4. Download the WireGuard configuration file

VPN Status Lifecycle

Downloading WireGuard Config

After enabling VPN, the WireGuard configuration file is available for download on the VPN page. You can download it at any time while VPN is enabled.

Example Configuration

[Interface]
PrivateKey = <your-private-key>
Address = 10.42.128.2/24
DNS = 10.96.0.10
 
[Peer]
PublicKey = <server-public-key>
AllowedIPs = 10.96.0.0/12, 10.0.0.0/8
Endpoint = vpn.cloud.kovra.dev:31001
PersistentKeepalive = 25

Configuration details:

• Address — Your assigned client IP within the VPN subnet
• DNS — Points to the Kubernetes CoreDNS service for in-cluster name resolution
• AllowedIPs — Routes Kubernetes service and pod network traffic through the VPN tunnel
• PersistentKeepalive — Keeps the connection alive through NAT devices

Connecting from Your Devices

macOS

1. Install WireGuard from the Mac App Store
2. Open WireGuard and click Import Tunnel(s) from File
3. Select the downloaded .conf file (or paste the configuration)
4. Click Activate to connect

Linux

1. Install WireGuard:

   # Ubuntu/Debian
   sudo apt install wireguard
    
   # Fedora
   sudo dnf install wireguard-tools

2. Save the configuration:

   sudo tee /etc/wireguard/kovra.conf << 'EOF'
   <paste your configuration here>
   EOF
   sudo chmod 600 /etc/wireguard/kovra.conf

3. Connect:

   sudo wg-quick up kovra

4. Disconnect:

   sudo wg-quick down kovra

Windows

1. Install WireGuard from wireguard.com/install 
2. Open WireGuard and click Import Tunnel(s) from File
3. Select the downloaded .conf file
4. Click Activate to connect

iOS

1. Install WireGuard from the App Store
2. Tap + then Create from QR code or Create from file or archive
3. Import the configuration
4. Toggle the tunnel on

Android

1. Install WireGuard from Google Play
2. Tap + then Import from file or archive or Scan from QR code
3. Import the configuration
4. Toggle the tunnel on

Accessing Databases via VPN

Once connected to the VPN, you can access your databases using their internal Kubernetes service DNS names.

Connecting with psql

# Connect via VPN (after activating WireGuard tunnel)
psql "postgresql://user:password@kovra-db-a1b2c3d4-rw.kovra-abcd1234.svc.cluster.local:5432/app?sslmode=require"

Connecting with a GUI Client

Use any PostgreSQL client (pgAdmin, DBeaver, DataGrip, etc.) with these settings:

Important: The VPN must be active for the DNS resolution and connection to work. The DNS server at 10.96.0.10 (Kubernetes CoreDNS) resolves in-cluster service names.

Disabling VPN

To disable VPN, navigate to the VPN page and click Disable VPN. This:

• Terminates the WireGuard pod
• Releases the allocated NodePort back to the pool
• Clears all VPN keys and configuration from the database
• Disconnects any active VPN clients

Warning: Disabling VPN immediately disconnects all active sessions. Any tools connected via VPN will lose their connection.

Regenerating VPN Configuration

If you need to rotate keys (for example, if you suspect a key compromise or want to revoke access from a device), click Regenerate Keys on the VPN page.

After regenerating:

1. The old configuration immediately stops working
2. All connected clients are disconnected
3. Download the new configuration and import it into your WireGuard client
4. The endpoint and client IP remain the same; only the keys change

Error Handling

Common Errors

Next Steps

• Managed Databases — Create databases to access via VPN
• App Deployment Guide — Configure private access for your apps
• Billing & Usage — Plans that include VPN