Deployment Architecture Overview

This document describes the Riptides deployment architecture, its core components, and how they interact. Use this as a reference when planning your Riptides deployment topology.

Components

Riptides consists of the following components:

Control Plane

The control plane is the central management component. It runs in a dedicated Kubernetes cluster (or namespace) and provides:

API Server — A Kubernetes-compatible API server (backed by Kine/SQLite embedded storage) that stores configuration resources such as identities, services, policies, verifiers, and join tokens.
Controllers — Watch API resources and reconcile desired state, including certificate issuance, policy distribution, and daemon registration.
OIDC Provider — Handles user authentication for the control plane UI and API. Integrates with external identity providers (GitHub, Google, etc.) to authenticate human operators.
Front Proxy — HTTPS endpoint (port 8443) for daemon communication and API access.
gRPC Server — gRPC endpoint (port 9443) for daemon attestation, certificate signing, and real-time policy updates.
Tunnel Server — Persistent tunnel endpoint (port 8001) for daemons behind NAT or restrictive firewalls.
HTTP Proxy — HTTP endpoint (port 8080) for health checks and readiness probes.

Frontend

A web-based UI deployed as a separate Helm chart. Provides visibility into:

Registered workloads and their identities
Active connections and mTLS status
Policy configuration and enforcement state

The frontend connects to the control plane’s GraphQL API.

Daemon

The daemon is the node-level daemon that runs on every machine in your workload environment. It is responsible for:

Communicating with the Riptides kernel module via the /dev/riptides character device
Connecting to the control plane for attestation and certificate issuance
Distributing certificates and policies to the kernel module
Collecting metadata from the host environment (process info, cloud instance metadata, Kubernetes pod context)
Signing certificate signing requests (CSRs) generated by the kernel module

On Kubernetes, the daemon is deployed as a DaemonSet. On bare metal or VMs, it runs as a systemd service or standalone process.

Driver (Kernel Module)

The Riptides kernel module provides transparent, in-kernel security for TCP sockets:

TLS/mTLS termination without application changes
SPIFFE-based identity enforcement
Policy-driven access control
Works with kTLS offload when available, falls back to an in-kernel TLS 1.3 implementation

The driver is loaded by the driver-loader init container (Kubernetes) or installed via DKMS/packages (bare metal).

Node Gatekeeper

An admission component deployed alongside the daemon in workload clusters. It validates and enforces node-level policies.

Deployment Topologies

Two-Cluster Model (Recommended for Production)

The recommended production topology separates the control plane from workload infrastructure:

+---------------------------+        +-----------------------------------+
|   CP Cluster              |        |   Workload Cluster                |
|                           |        |                                   |
|  +-------------------+    |  8443  |  +-----------------------------+ |
|  | controlplane      |<---+--------+--| daemon (DaemonSet)           | |
|  | (Deployment)      |    |  9443  |  | + driver-loader (init)      | |
|  +-------------------+    |<-------+--+-----------------------------+ |
|                           |  8001  |                                   |
|  +-------------------+    |<-------+  +-----------------------------+ |
|  | frontend          |    |        |  | node-gatekeeper             | |
|  | (Deployment)      |    |        |  | (DaemonSet)                 | |
|  +-------------------+    |        |  +-----------------------------+ |
+---------------------------+        +-----------------------------------+

CP Cluster contains:

controlplane — Deployment (typically 1 replica with embedded storage)
frontend — Deployment for the web UI

Workload Cluster contains:

daemon — DaemonSet with driver-loader init container on every node
node-gatekeeper — DaemonSet for node-level policy enforcement

This separation ensures that workload failures or resource pressure do not affect the control plane, and that the control plane’s API surface is isolated.

Single-Cluster Model (Development / Small Deployments)

For simpler environments, all components can run in a single cluster using separate namespaces:

+------------------------------------------------------+
|   Single Cluster                                      |
|                                                       |
|  Namespace: riptides-cp                               |
|  +-------------------+  +-------------------+         |
|  | controlplane      |  | frontend          |         |
|  +-------------------+  +-------------------+         |
|                                                       |
|  Namespace: riptides-system                           |
|  +-----------------------------+  +-----------------+ |
|  | daemon (DaemonSet)           |  | node-gatekeeper | |
|  | + driver-loader (init)      |  | (DaemonSet)     | |
|  +-----------------------------+  +-----------------+ |
+------------------------------------------------------+

Hybrid: Kubernetes + Bare Metal / VMs

Riptides supports mixed environments where some workloads run on Kubernetes and others on bare-metal servers or VMs. All daemons connect to the same control plane:

+---------------------+
|   CP Cluster        |
|  +---------------+  |        +-----------------------------+
|  | controlplane  |<-+--------| Kubernetes workload cluster |
|  +---------------+  |        | (daemon DaemonSet)           |
|                     |        +-----------------------------+
|                     |
|                     |        +-----------------------------+
|                     +--------| Bare-metal server           |
|                     |        | (daemon + kernel module)     |
|                     |        +-----------------------------+
|                     |
|                     |        +-----------------------------+
|                     +--------| EC2 instance                |
|                              | (daemon + kernel module)     |
+---------------------+        +-----------------------------+

Network Requirements

Workload nodes (Kubernetes or bare metal) must be able to reach the control plane on these ports:

Source	Destination	Port	Protocol	Purpose
Daemon	Control Plane	8443	HTTPS	API communication, certificate issuance
Daemon	Control Plane	9443	gRPC/TLS	Attestation, real-time policy updates
Daemon	Control Plane	8001	TCP/TLS	Tunnel (persistent connection)

If you use an ingress controller or load balancer in front of the control plane, map these ports (or use separate DNS records with TLS passthrough on port 443):

DNS Record	Backend Port	Purpose
`cp.example.com`	8443	HTTPS API
`grpc.example.com`	9443	gRPC
`tunnel.example.com`	8001	Tunnel

The control plane does not initiate connections to daemons. All communication is daemon-initiated, making deployment behind NAT and firewalls straightforward.

Environment-Specific Configuration

Riptides deployments are managed through per-environment directories, each containing Helm values files and a deployment manifest:

riptides-config/
  production/
    deploy.yaml
    cp-values.yaml
    daemon-values.yaml
    frontend-values.yaml
    ngk-values.yaml
    verifier.yaml
    oidc.yaml
  staging/
    deploy.yaml
    cp-values.yaml
    daemon-values.yaml
    ...

The deploy.yaml file defines which charts to deploy, their versions, registries, namespaces, and which values files to use:

cpCluster:
  clusterName: riptides-prod-cp
  clusterRegion: us-east-1
  deployments:
    controlplane:
      chart: controlplane
      version: v0.1.10
      registry: ghcr.io/riptideslabs/helm
      namespace: riptides-cp
      valuesFile: cp-values.yaml
    frontend:
      chart: frontend
      version: v0.1.4
      registry: ghcr.io/riptideslabs/helm
      namespace: riptides-cp
      valuesFile: frontend-values.yaml

workloadCluster:
  clusterName: riptides-prod-apps
  clusterRegion: us-east-1
  deployments:
    daemon:
      chart: daemon
      version: v0.1.17
      registry: ghcr.io/riptideslabs/helm
      namespace: riptides-system
      valuesFile: daemon-values.yaml
    node-gatekeeper:
      chart: node-gatekeeper
      version: v0.1.4
      registry: ghcr.io/riptideslabs/helm
      namespace: riptides-system
      valuesFile: ngk-values.yaml

This pattern allows you to version control environment-specific configuration while sharing the same charts and deployment process across environments.

Security Considerations

Secrets: OIDC client secrets and other sensitive values should never be stored in plain YAML. Use template files (.tmpl) and inject secrets at deploy time through your CI/CD system.
Trust domain: The trust domain (e.g., example.com) must be consistent across the control plane and all daemons. Changing it after deployment requires re-attestation of all daemons.
Network isolation: The control plane cluster should have restricted ingress — only daemon traffic on the required ports and administrative access to the frontend.