Architecture

KTube is a Kubernetes operator that manages tunnel lifecycle through Custom Resource Definitions (CRDs).

Overview

┌─────────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                        │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                   KTube Operator                         ││
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐    ││
│  │  │ Cloudflare  │ │   ngrok     │ │   Dev Tunnels   │    ││
│  │  │ Controller  │ │ Controller  │ │   Controller    │    ││
│  │  └──────┬──────┘ └──────┬──────┘ └───────┬─────────┘    ││
│  │         └───────────────┼────────────────┘              ││
│  │                         ▼                                ││
│  │              Reconciliation Loop                         ││
│  └─────────────────────────┬───────────────────────────────┘│
│                            ▼                                 │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              Your Kubernetes Services                    ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
              ┌──────────────────────────┐
              │        Internet          │
              │  (via tunnel providers)  │
              └──────────────────────────┘

Components

KTube Operator

The operator runs as a Deployment in ktube-system namespace and watches for changes to KTube CRDs.

Provider Controllers

Each tunnel provider has a dedicated controller that handles provider-specific logic:

  • Cloudflare Controller - Manages Cloudflare Tunnel API interactions
  • ngrok Controller - Manages ngrok tunnel connections
  • DevTunnels Controller - Manages Microsoft Dev Tunnels

KTube Dashboard

A web UI that provides visualization and management of tunnels. Runs as a separate Deployment and connects to the Kubernetes API.

Custom Resource Definitions

CRDPurposeScope
TunnelProviderConfigure provider credentialsCluster-scoped
TunnelDefine a tunnel instanceNamespaced
TunnelBindingBind services to tunnelsNamespaced

Reconciliation Flow

  1. User creates/updates a TunnelBinding resource
  2. Operator detects the change via Kubernetes watch
  3. Operator looks up the referenced Tunnel and TunnelProvider
  4. Provider controller creates/updates tunnel with the provider API
  5. Operator updates TunnelBinding status with the public URL

Next Steps