Architecture Overview

Understanding how ktube manages secure tunnels in your Kubernetes cluster.

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                       Internet                              │
│                    (Users / APIs)                           │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Provider Edge                            │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐              │
│  │Cloudflare │  │  ngrok    │  │Dev Tunnels│              │
│  │   Edge    │  │  Servers  │  │  Service  │              │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘              │
└────────┼──────────────┼──────────────┼────────────────────┘
                        │
         Outbound TLS Connections (no inbound rules)
                        │
┌───────────────────────┼───────────────────────────────────┐
│   Kubernetes Cluster  │                                   │
│                       ▼                                   │
│  ┌────────────────────────────────────────────────────┐   │
│  │              ktube-system Namespace                │   │
│  │                                                    │   │
│  │  ┌─────────────────┐    ┌────────────────────┐    │   │
│  │  │  ktube-operator │    │   ktube-dashboard  │    │   │
│  │  │                 │    │                    │    │   │
│  │  │  - Controllers  │    │  - Web UI          │    │   │
│  │  │  - Providers    │    │  - API             │    │   │
│  │  └────────┬────────┘    └────────────────────┘    │   │
│  │           │                                        │   │
│  └───────────┼────────────────────────────────────────┘   │
│              │                                            │
│  ┌───────────▼────────────────────────────────────────┐   │
│  │           Application Namespace                    │   │
│  │                                                    │   │
│  │  ┌─────────────────┐      ┌──────────────────┐    │   │
│  │  │   cloudflared   │◄────►│   Your Service   │    │   │
│  │  │   (Connector)   │      │                  │    │   │
│  │  └─────────────────┘      └──────────────────┘    │   │
│  │                                                    │   │
│  └────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────┘

Custom Resources

TunnelProvider (Cluster-scoped)

Stores provider credentials and configuration. One TunnelProvider can be used by multiple Tunnels across different namespaces.

apiVersion: ktube.dev/v1alpha1
kind: TunnelProvider
metadata:
  name: cloudflare-prod
spec:
  type: cloudflare    # cloudflare, ngrok, or devtunnels
  cloudflare:
    accountId: abc123
    apiTokenSecretRef:
      name: cf-token
      namespace: ktube-system
      key: token

Tunnel (Namespace-scoped)

Creates a managed tunnel instance. The operator provisions resources on the provider and deploys connector pods.

apiVersion: ktube.dev/v1alpha1
kind: Tunnel
metadata:
  name: prod-tunnel
  namespace: default
spec:
  providerRef:
    name: cloudflare-prod
  deployment:
    replicas: 2    # HA with multiple connectors

TunnelBinding (Namespace-scoped)

Exposes a Kubernetes service through a tunnel with a specific hostname or auto-generated URL.

apiVersion: ktube.dev/v1alpha1
kind: TunnelBinding
metadata:
  name: api-binding
  namespace: default
spec:
  tunnelRef:
    name: prod-tunnel
  hostname: api.example.com    # or quickTunnel: true
  protocol: https
  service:
    name: api-server
    port: 8080

Security Model

Outbound-Only Connections

Tunnel connectors establish persistent outbound connections to the provider's edge network. Traffic flows through these tunnels — no inbound firewall rules are required.

Secret Management

Provider credentials are stored in Kubernetes Secrets and referenced by TunnelProviders. The actual tokens never appear in CRD specs.

Reconciliation Flow

  1. TunnelProvider created → Operator validates credentials with provider API
  2. Tunnel created → Operator creates managed tunnel, deploys connector pods
  3. TunnelBinding created → Operator configures ingress rules, creates DNS records (Cloudflare)
  4. Status updated → Binding status shows public URL when ready

Next Steps