Skip to content

Access private Kubernetes clusters with kubectl

Connect kubectl to a private Kubernetes API server through a TCP tunnel and watch pod changes without a VPN, public IP, or router port forwarding.

You need Node.js 26.7 or later and a Tubu API key on the publisher machine. Follow the Quick start to get your key. Replace YOUR_API_KEY and choose an available Tubu domain in the examples. The publisher must reach the target service and connect outward to Tubu. Keep it running while access is needed.

Prepare access to the cluster

Run the Tubu publisher on an authorized machine that can reach the Kubernetes API server. Both machines need Node.js 26.7 or later. Your computer also needs kubectl and a valid kubeconfig with the cluster CA, credentials, and permission to list and watch pods in the selected namespace.

This recipe uses one TCP tunnel endpoint for API access. It can carry multiple client TCP connections. Kubernetes TLS and authentication pass through unchanged; the caller does not need a Tubu API key.

Publish the private Kubernetes API server

On the publisher inside the cluster network, replace 10.0.0.10:6443 with the API server address and port:

npx tubu-cli tcp tcp://10.0.0.10:6443 \
  --domain customer-kube.tubu.dev --authtoken YOUR_API_KEY

Replace customer-kube.tubu.dev with an available Tubu domain and YOUR_API_KEY with your Tubu API key. Wait for Tunnel ready and keep the publisher running.

Start a local listener

On your computer, use the same Tubu domain:

npx tubu-cli forward 16443 --domain customer-kube.tubu.dev

Wait for Listening. Keep this process running and open another terminal for kubectl. If port 16443 is occupied, choose another local port in both the forward command and the kubectl server URL.

Watch pod changes with kubectl

Replace YOUR_CONTEXT with the context for this cluster in your kubeconfig. Replace api.cluster.internal with a server name covered by the API server certificate, such as the hostname in your original cluster server URL. Use the existing kubeconfig credentials and CA; keep certificate verification enabled.

kubectl --context=YOUR_CONTEXT \
  --server=https://127.0.0.1:16443 \
  --tls-server-name=api.cluster.internal \
  get pods --watch

The command lists pods in the context’s namespace and keeps printing changes as they arrive. Add --namespace=YOUR_NAMESPACE to select another namespace. These command options leave your kubeconfig unchanged.

Press Ctrl+C to stop the watch. Stop both Tubu processes when finished. A single successful listing does not verify the watch: keep it open and check that a subsequent pod change appears.

See the kubectl get reference for watch and connection options.

Check connectivity, TLS, and permissions

  • Connection failure: check that both Tubu processes are running and that the publisher can reach the API server address and port.
  • Certificate error: check the kubeconfig CA and the name supplied to --tls-server-name against the API server certificate. Do not disable certificate verification.
  • Unauthorized: check the selected context and its credentials. If it uses a credential plugin, that plugin and its authentication service must be available on your computer.
  • Forbidden: ask the cluster administrator for list and watch permissions on pods in the selected namespace.
Get started with Tubu