Architecture

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.

​

Overview

The RDE Portal is a web application hosted by Qovery at rde.qovery.com. It consists of three components: a web frontend, an API server (Backend-for-Frontend), and a database - all managed by Qovery. The portal orchestrates workspace containers that run on your Kubernetes cluster. A critical design principle: your cluster is never exposed to the internet. Qovery agents running on your cluster initiate all connections outbound to the Qovery control plane via TLS/gRPC. The control plane never connects inbound to your infrastructure. This page explains the architecture, connectivity model, and data flow. For security-specific details - data residency, token management, and compliance - see the dedicated Security & Data Residency page.

​

High-Level Architecture

Key: All arrows from your cluster point outbound. Your cluster initiates connections to the Qovery control plane - not the other way around. No inbound ports are required on your infrastructure.

​

Cluster Connectivity Model

This is the foundation of the RDE Portal’s security architecture. Your Kubernetes cluster runs Qovery agents - Engine, Shell agent, and other components - that maintain persistent outbound TLS/gRPC connections to the Qovery control plane. Your cluster never exposes inbound ports to the internet. All portal operations flow through this cluster-initiated tunnel:

1. Qovery agents on your cluster establish and maintain outbound TLS/gRPC connections to the Qovery control plane. This is the only external communication from your cluster.
2. The portal sends requests to the Qovery control plane (same Qovery infrastructure).
3. The control plane relays the request through the already-established tunnel to the agent on your cluster.
4. The agent executes the operation locally - shell session, port forward, deployment - and returns the result through the same tunnel.

​

Components

​

Web Frontend

The frontend renders the workspace dashboard, editor, and admin panels. It handles user authentication and opens secure connections for terminal sessions and live previews. The frontend never communicates directly with the Qovery API or your cluster. All requests go through the API server.

​

API Server (Backend-for-Frontend)

The API server acts as the gateway between the frontend and Qovery services. It handles:

• Authentication - Verifies JWTs on every request
• Authorization - Enforces blueprint ACLs, workspace ownership, and admin role checks
• API proxying - Translates portal operations into Qovery API calls using the two-client model
• Streaming relay - Bridges terminal sessions and port-forward connections between the browser and Qovery’s control plane
• Business logic - Publish workflows, blueprint discovery, catalog assembly, workspace lifecycle management

​

Database

A database that stores portal-specific configuration. It does not store any user code, workspace data, or AI conversations. The database holds:

• Organization settings (encrypted admin token, branding, limits)
• Blueprint access control rules
• Blueprint display configuration
• Publish workflow state (requests, approvals, trust rules)
• Member role assignments
• User tags and workspace tag assignments
• One-time authentication tickets for secure sessions
• Connection audit logs (shell and preview session history)
• IP firewall rules and blocked connection events

​

Qovery Control Plane

The portal communicates with the Qovery control plane for all resource management: listing projects, cloning environments, deploying services, managing members, and reading deployment status. The control plane in turn communicates with your cluster through the agent-initiated tunnel. The control plane also provides:

• Shell exec - Interactive terminal sessions relayed through the agent to containers on your cluster
• Port forwarding - TCP tunnels relayed through the agent to container ports, used for live preview

​

Authentication Flow

Users authenticate through Auth0 (auth.qovery.com) using the PKCE authorization code flow - the same authentication used by the Qovery Console. On every request, the JWT is verified to determine the user’s identity and permissions before any operation is executed.

​

Two-Client Model

The API server maintains two Qovery API clients for each authenticated request: Why two clients? The portal needs to perform operations on behalf of users that those users may not have direct Qovery RBAC permissions for. For example, cloning a blueprint environment into a new project requires admin-level access. The two-client model separates authorization (verified via the user’s JWT) from execution (performed via the admin token).

​

Convention-Based Discovery

The portal does not maintain a separate database of workspaces. Instead, it discovers workspaces through metadata tags stored on each Qovery environment. When the portal needs to list a user’s workspaces, it:

1. Queries the Qovery API for environments in the organization
2. Reads the metadata tags on each environment
3. Filters for environments that contain the RDE metadata
4. Matches workspaces to the current user by owner email

Key metadata tags:

​

Terminal & Preview

​

Terminal (Shell Exec)

The portal provides interactive terminal sessions that connect to containers running in your Kubernetes cluster - without exposing your cluster to the internet. Connection flow:

1. The frontend requests a shell ticket - a one-time token with a 30-second TTL
2. The frontend opens a secure connection to the API server, passing the shell ticket for authentication
3. The API server validates the ticket (single-use, not expired) and sends the request to the Qovery control plane
4. The control plane relays the session through the cluster-initiated tunnel to the Qovery Shell agent on your cluster
5. The Shell agent connects to the workspace container locally and streams the terminal session
6. Keystrokes and terminal output are relayed bidirectionally through the entire chain in real time

​

Live Preview (Port Forward)

The preview panel renders the user’s running application in an iframe without requiring a public URL or ingress configuration. How it works:

1. The frontend sends HTTP requests to the API server’s preview endpoint
2. The API server forwards the request to the Qovery control plane
3. The control plane relays the request through the cluster-initiated tunnel to the Qovery agent on your cluster
4. The agent forwards the request to the workspace container’s application port locally
5. The response is relayed back through the same tunnel to the browser

Workspaces do not need public domains, load balancers, or ingress rules for development previews. Your cluster is never exposed.

​

Deployment Architecture

The RDE Portal uses a split deployment model: the portal is hosted by Qovery as a managed service at rde.qovery.com, while workspace containers run on your Kubernetes cluster. You do not need to deploy or maintain the portal infrastructure - Qovery handles updates, availability, and scaling. You only manage your Kubernetes cluster where workspaces run.

​

Data Model

The portal splits data storage between its database and the Qovery API:

​

Next Steps