Quickstart Guide

Get ktube running in your Kubernetes cluster in under 5 minutes.

Prerequisites

Kubernetes cluster (kind, minikube, or cloud provider)
kubectl configured with cluster access
Provider credentials (Cloudflare API token, ngrok authtoken, etc.)

1. Install ktube

Install the ktube operator and CRDs:

kubectl apply -f https://ktube.dev/install.yaml

Verify the installation:

kubectl get pods -n ktube-system
# NAME                              READY   STATUS    RESTARTS   AGE
# ktube-operator-6d8f9b7c4d-xxx     1/1     Running   0          30s
# ktube-dashboard-7b8c9d6e5f-yyy    1/1     Running   0          30s

2. Create a Provider

First, create a secret with your provider credentials:

kubectl create secret generic cloudflare-api-token \
  --from-literal=token=YOUR_API_TOKEN \
  -n ktube-system

Then create a TunnelProvider:

kubectl apply -f - <<EOF
apiVersion: ktube.dev/v1alpha1
kind: TunnelProvider
metadata:
  name: my-cloudflare
spec:
  type: cloudflare
  cloudflare:
    accountId: YOUR_ACCOUNT_ID
    apiTokenSecretRef:
      name: cloudflare-api-token
      namespace: ktube-system
      key: token
EOF

3. Create a Tunnel

kubectl apply -f - <<EOF
apiVersion: ktube.dev/v1alpha1
kind: Tunnel
metadata:
  name: my-tunnel
  namespace: default
spec:
  providerRef:
    name: my-cloudflare
EOF

Check the tunnel status:

kubectl get tunnels
# NAME        PROVIDER        STATUS   AGE
# my-tunnel   my-cloudflare   Ready    30s

4. Expose a Service

Create a TunnelBinding to expose your service:

kubectl apply -f - <<EOF
apiVersion: ktube.dev/v1alpha1
kind: TunnelBinding
metadata:
  name: my-app
  namespace: default
spec:
  tunnelRef:
    name: my-tunnel
  hostname: my-app.example.com
  service:
    name: my-service
    port: 8080
EOF

Your service is now accessible at https://my-app.example.com!

Quick Tunnel (Development)

For development, use Quick Tunnel mode to get an auto-generated URL without DNS configuration:

kubectl apply -f - <<EOF
apiVersion: ktube.dev/v1alpha1
kind: TunnelBinding
metadata:
  name: dev-binding
spec:
  tunnelRef:
    name: my-tunnel
  quickTunnel: true
  service:
    name: my-service
    port: 8080
EOF

Check the binding for your auto-generated URL:

kubectl get tunnelbindings
# NAME          TUNNEL      URL                                  STATUS
# dev-binding   my-tunnel   https://xxx-yyy.trycloudflare.com   Ready

Access the Dashboard

Port-forward the dashboard to manage tunnels via UI:

kubectl port-forward -n ktube-system svc/ktube-dashboard 3000:3000

Open http://localhost:3000 in your browser.