Proxy Forwarding
Route traffic through a Kubernetes cluster to reach internal or external services, and carry UDP through a relay pod.
Proxy forwarding sends traffic through your Kubernetes cluster to reach hosts your local machine can't connect to directly.
Basic proxy configuration
{
"alias": "Internal API via Proxy",
"workload_type": "proxy",
"remote_address": "internal-api.company.com",
"remote_port": 443,
"local_port": 8443,
"namespace": "default",
"context": "prod-cluster",
"protocol": "tcp"
}This forwards localhost:8443 through a kftray-server relay pod to internal-api.company.com:443. The destination is remote_address plus remote_port, and the cluster is where the connection starts. A proxy config doesn't need a service field.
The kftray-server relay
The kftray-server relay pod runs in your Kubernetes cluster. It receives traffic from your local port forward and sends it to the remote_address target.
You need the relay for:
- Proxy forwards to hosts outside the target workload
- UDP forwarding for service, pod and proxy workloads
- Reaching services outside the cluster from the cluster network
- Reaching internal corporate services through cluster network policies
- Connecting to services that allow your cluster's outbound IP addresses
kftray creates a separate, uniquely named Deployment for each UDP or proxy forward in the config's namespace. Stopping the forward removes its owned relay resources. Customized legacy Pod manifests use a standalone Pod instead. See relay deployment and cleanup for resource requests, limits and ownership labels.
- Proxy startup waits for the relay's TCP listener instead of using a fixed delay.
- kftray keeps existing startup probes. An unready sidecar doesn't stop a started relay from forwarding.
- If the relay pod fails, kftray tries to recover the forward up to five times, waiting 2, 4, 8, 16 and 32 seconds between attempts.
- The server resources view in the desktop app lists the relay pods kftray created, so you can remove leftovers.
Cluster permissions required
The default relay needs permission to create Deployments in the target namespace. Startup also reads and watches Pods and opens pods/portforward connections. Cleanup needs permission to list and delete Deployments and Pods. The legacy standalone-Pod path needs permission to create Pods instead of Deployments.
Check Deployment creation with kubectl auth can-i create deployments.apps -n <namespace>. Proxy and UDP relay creation does not create a Service.
Cancelled starts
If you cancel a start and kftray can't finish the rollback, it reports cleanup_incomplete. A relay pod, a loopback alias or a hosts entry can stay behind, so check the server resources view.
UDP through the relay
UDP forwards also use kftray-server. Set protocol to udp with the proxy workload to reach an external DNS server:
{
"alias": "dns-proxy",
"workload_type": "proxy",
"remote_address": "8.8.8.8",
"remote_port": 53,
"local_port": 5353,
"namespace": "default",
"context": "my-k8s-cluster",
"protocol": "udp"
}A service or pod config with "protocol": "udp" also goes through the relay. See port forwarding.
Use cases
Internal corporate APIs
{
"alias": "HR API",
"workload_type": "proxy",
"remote_address": "hr-api.internal.company.com",
"remote_port": 8080,
"local_port": 9000,
"namespace": "default",
"context": "corp-cluster",
"protocol": "tcp"
}This reaches internal APIs through the corporate cluster's network, even when your machine is outside the VPN.
Cloud services with IP restrictions
{
"alias": "Restricted cloud API",
"workload_type": "proxy",
"remote_address": "restricted-api.cloud-provider.com",
"remote_port": 443,
"local_port": 8443,
"namespace": "production",
"context": "prod-cluster",
"protocol": "tcp"
}This reaches cloud services that allow your cluster's outbound IP addresses. The traffic comes from the cluster, so your local IP doesn't need access.