How-To Guide

Access kubectl via SOCKS5 Proxy

Type: How-To (Task-oriented)

Related: Security Model | Manage Contexts with ktx

Goal: Configure your local machine to access the Kubernetes API through a SOCKS5 proxy tunnel.

Time: ~10 minutes

Why needed: The Kubernetes API is restricted to jumphost IP (95.217.145.243) for security. You’ll access it through a SOCKS5 proxy tunnel.

Prerequisites

• SSH access to jumphost (95.217.145.243:2222)

• SSH key-based authentication configured

• kubectl installed locally

• Access to kubeconfig file (kube-hetzner/kup6s_kubeconfig.yaml)

Step 1: Configure SSH for Jumphost

Edit ~/.ssh/config on your local machine:

# Jumphost connection with auto SOCKS5 proxy
Host kup6s-jumphost
    HostName 95.217.145.243
    Port 2222
    User jensens
    DynamicForward 1080
    Compression yes
    RequestTTY no

What this does:

• DynamicForward 1080 - Automatically creates SOCKS5 proxy on localhost:1080 when connected

• Compression yes - Improves performance over the tunnel

• RequestTTY no - No interactive shell needed (just tunneling)

Step 2: Start SOCKS5 Proxy

You have two options: foreground (keeps terminal open) or background.

Option A: Background Mode (Recommended)

Start the proxy in the background using SSH config:

# Start proxy in background
ssh kup6s-jumphost -f sleep inf

Flags explained:

• -f - Run in background (forks after authentication)

• sleep inf - Keep connection alive indefinitely

• DynamicForward 1080 and Compression yes are inherited from SSH config

The SOCKS5 proxy is now active on localhost:1080.

Option B: Foreground Mode

Alternatively, keep the connection in the foreground (requires open terminal):

# Connect to jumphost (leave this terminal open)
ssh kup6s-jumphost

The proxy runs as long as the SSH session is active.

Verify Proxy is Running

# Check if SSH connection is active
ps aux | grep "ssh.*kup6s-jumphost"

# Test the proxy
curl -x socks5://localhost:1080 https://ifconfig.me
# Should show your jumphost's public IP (95.217.145.243)

Step 3: Configure kubectl to Use Proxy

# Set proxy environment variable
export HTTPS_PROXY=socks5://localhost:1080

# Set kubeconfig location
export KUBECONFIG=/path/to/kup6s/kube-hetzner/kup6s_kubeconfig.yaml

# Test kubectl access
kubectl get nodes

Expected output:

NAME                 STATUS   ROLES                       AGE   VERSION
kup6s-control-fsn1   Ready    control-plane,etcd,master   ...   v1.30.x+k3s1
kup6s-control-nbg1   Ready    control-plane,etcd,master   ...   v1.30.x+k3s1
kup6s-control-hel1   Ready    control-plane,etcd,master   ...   v1.30.x+k3s1
...

Step 4: Access Cluster Services

With the proxy running, you can access various cluster services:

Hubble UI (Network Observability)

cilium hubble ui
# Opens browser to http://localhost:12000

Port Forwarding to Services

# Example: Grafana
kubectl port-forward -n monitoring svc/grafana 3000:80
# Then open http://localhost:3000

# Example: ArgoCD
kubectl port-forward -n argocd svc/argocd-server 8080:443
# Then open https://localhost:8080

Daily Workflow

Quick Start

# Start proxy in background
ssh kup6s-jumphost -f sleep inf

# Use kubectl (same terminal)
export HTTPS_PROXY=socks5://localhost:1080
export KUBECONFIG=/path/to/kup6s/kube-hetzner/kup6s_kubeconfig.yaml
kubectl get pods -A

Add to Shell Profile (Optional)

Create a function that starts the proxy and sets variables on-demand.

For Bash/Zsh:

Add to ~/.bashrc or ~/.zshrc:

# KUP6S cluster access function
kup6s-connect() {
    # Check if proxy is already running
    if pgrep -f "ssh.*kup6s-jumphost" > /dev/null; then
        echo "✓ SOCKS5 proxy already running"
    else
        echo "Starting SOCKS5 proxy..."
        ssh kup6s-jumphost -f sleep inf
        sleep 1  # Give SSH time to establish connection
        echo "✓ SOCKS5 proxy started"
    fi

    # Set environment variables
    export HTTPS_PROXY=socks5://localhost:1080
    export KUBECONFIG="$HOME/kup6s/kube-hetzner/kup6s_kubeconfig.yaml"

    echo "✓ Environment configured for KUP6S cluster"
    echo "  HTTPS_PROXY=$HTTPS_PROXY"
    echo "  KUBECONFIG=$KUBECONFIG"
}

# Optional: Disconnect function
kup6s-disconnect() {
    pkill -f "ssh.*kup6s-jumphost"
    unset HTTPS_PROXY
    unset KUBECONFIG
    echo "✓ Proxy stopped and environment cleared"
}

Then:

source ~/.bashrc  # or ~/.zshrc
kup6s-connect     # Start proxy and configure environment
kubectl get nodes  # Works!
kup6s-disconnect  # When done

For Fish:

Add to ~/.config/fish/config.fish:

# KUP6S cluster access function
function kup6s-connect
    # Check if proxy is already running
    if pgrep -f "ssh.*kup6s-jumphost" > /dev/null
        echo "✓ SOCKS5 proxy already running"
    else
        echo "Starting SOCKS5 proxy..."
        ssh kup6s-jumphost -f sleep inf
        sleep 1  # Give SSH time to establish connection
        echo "✓ SOCKS5 proxy started"
    end

    # Set environment variables
    set -gx HTTPS_PROXY socks5://localhost:1080
    set -gx KUBECONFIG "$HOME/kup6s/kube-hetzner/kup6s_kubeconfig.yaml"

    echo "✓ Environment configured for KUP6S cluster"
    echo "  HTTPS_PROXY=$HTTPS_PROXY"
    echo "  KUBECONFIG=$KUBECONFIG"
end

# Optional: Disconnect function
function kup6s-disconnect
    pkill -f "ssh.*kup6s-jumphost"
    set -e HTTPS_PROXY
    set -e KUBECONFIG
    echo "✓ Proxy stopped and environment cleared"
end

Then:

source ~/.config/fish/config.fish
kup6s-connect     # Start proxy and configure environment
kubectl get nodes  # Works!
kup6s-disconnect  # When done

Optional: Auto-Start with Systemd

For automatic proxy startup on boot:

Create ~/.config/systemd/user/kup6s-socks-proxy.service:

[Unit]
Description=KUP6S SOCKS5 Proxy via Jumphost
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/ssh -D 1080 -N -C -p 2222 jensens@95.217.145.243 -o ServerAliveInterval=60 -o ServerAliveCountMax=3
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

Enable and start:

# Reload systemd
systemctl --user daemon-reload

# Enable auto-start on boot
systemctl --user enable kup6s-socks-proxy.service

# Start now
systemctl --user start kup6s-socks-proxy.service

# Check status
systemctl --user status kup6s-socks-proxy.service

Now the proxy starts automatically and reconnects on failure.

Troubleshooting

kubectl times out

Cause: HTTPS_PROXY not set or SOCKS proxy not running

Solution:

# Verify proxy is running
ps aux | grep "ssh.*kup6s-jumphost"

# Set proxy variable
export HTTPS_PROXY=socks5://localhost:1080

# Test with verbose output
kubectl get nodes -v=8

SOCKS proxy connection refused

Cause: Lost connection to jumphost or proxy not started

Solution:

# Kill stale connections
pkill -f "ssh.*kup6s-jumphost"

# Restart proxy
ssh kup6s-jumphost -f sleep inf

Permission denied errors

Cause: Wrong kubeconfig path or permissions

Solution:

# Verify kubeconfig exists
ls -la /path/to/kup6s/kube-hetzner/kup6s_kubeconfig.yaml

# Check file permissions
chmod 600 /path/to/kup6s/kube-hetzner/kup6s_kubeconfig.yaml

# Verify KUBECONFIG is set correctly
echo $KUBECONFIG

Cannot reach cluster after jumphost IP change

Cause: Firewall still configured with old jumphost IP

Solution: See Update Firewall Configuration for instructions on updating the allowed IP address.

Next Steps

• Deploy your first application

• Query Loki logs

• Monitor cluster with Grafana

Related Information

• Security Model - Why the API is restricted

• Cluster Capabilities - Technical reference