Skip to content

Commit 7f13ad0

Browse files
xenschrismetz09tengqmTim Bannister
authored
Document using SOCKS5 to access Kubernetes API (#31527)
* ofeat: add SOCKS5 proxy documentation Goal of this commit is to document the usage of SOCKS5 proxies to reach the Kubernetes API. * Apply suggestions from code review Co-authored-by: chrismetz09 <[email protected]> * Apply suggestions from code review Co-authored-by: Qiming Teng <[email protected]> * fix: apply contributors suggestions * fix: apply contributors suggestions * Update content/en/docs/tasks/extend-kubernetes/socks5-proxy-access-api.md Co-authored-by: Tim Bannister <[email protected]> * fix: apply new contributors suggestions * Update content/en/docs/tasks/extend-kubernetes/socks5-proxy-access-api.md Co-authored-by: Tim Bannister <[email protected]> * feat: add cleanup and furter reading sections * fix: comment on SOCKS5 proxy * nit * fix: workflow Co-authored-by: chrismetz09 <[email protected]> Co-authored-by: Qiming Teng <[email protected]> Co-authored-by: Tim Bannister <[email protected]>
1 parent 8170154 commit 7f13ad0

File tree

1 file changed

+145
-0
lines changed

1 file changed

+145
-0
lines changed

‎content/en/docs/tasks/extend-kubernetes/socks5-proxy-access-api.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: Use a SOCKS5 Proxy to Access the Kubernetes API
3+
content_type: task
4+
weight: 42
5+
min-kubernetes-server-version: v1.24
6+
---
7+
<!-- overview -->
8+
9+
{{< feature-state for_k8s_version="v1.24" state="stable" >}}
10+
11+
This page shows how to use a SOCKS5 proxy to access the API of a remote Kubernetes cluster.
12+
This is useful when the cluster you want to access does not expose its API directly on the public internet.
13+
14+
## {{% heading "prerequisites" %}}
15+
16+
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
17+
18+
You need SSH client software (the `ssh` tool), and an SSH server running on the remote server.
19+
You must be able to log in to the SSH server on the remote server.
20+
21+
<!-- steps -->
22+
23+
## Task context
24+
25+
{{< note >}}
26+
This example tunnels traffic using SSH, with the SSH client and server acting as a SOCKS proxy.
27+
You can instead use any other kind of [SOCKS5](https://en.wikipedia.org/wiki/SOCKS#SOCKS5) proxies.
28+
{{</ note >}}
29+
30+
Figure 1 represents what you're going to achieve in this task.
31+
32+
* You have a client computer from where you're going to create requests to talk to the Kubernetes API
33+
* The Kubernetes server/API is hosted on a remote server.
34+
* You will use SSH client and server software to create a secure SOCKS5 tunnel between the local and
35+
the remote server. The HTTPS traffic between the client and the Kubernetes API will flow over the SOCKS5
36+
tunnel, which is itself tunnelled over SSH.
37+
38+
{{< mermaid >}}
39+
graph LR;
40+
41+
subgraph local[Local client machine]
42+
client([client])-- local <br> traffic .-> local_ssh[Local SSH <br> SOCKS5 proxy];
43+
end
44+
local_ssh[SSH <br>SOCKS5 <br> proxy]-- SSH Tunnel -->sshd
45+
46+
subgraph remote[Remote server]
47+
sshd[SSH <br> server]-- local traffic -->service1;
48+
end
49+
client([client])-. proxied HTTPs traffic <br> going through the proxy .->service1[Kubernetes API];
50+
51+
classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
52+
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
53+
classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
54+
class ingress,service1,service2,pod1,pod2,pod3,pod4 k8s;
55+
class client plain;
56+
class cluster cluster;
57+
{{</ mermaid >}}
58+
Figure 1. SOCKS5 tutorial components
59+
60+
## Using ssh to create a SOCKS5 proxy
61+
62+
This command starts a SOCKS5 proxy between your client machine and the remote server.
63+
The SOCKS5 proxy lets you connect to your cluster's API server.
64+
65+
```shell
66+
# The SSH tunnel continues running in the foreground after you run this
67+
ssh -D 1080 -q -N [email protected]
68+
```
69+
70+
* `-D 1080`: opens a SOCKS proxy on local port :1080.
71+
* `-q`: quiet mode. Causes most warning and diagnostic messages to be suppressed.
72+
* `-N`: Do not execute a remote command. Useful for just forwarding ports.
73+
* `[email protected]`: the remote SSH server where the Kubernetes cluster is running.
74+
75+
## Client configuration
76+
77+
To explore the Kubernetes API you'll first need to instruct your clients to send their queries through
78+
the SOCKS5 proxy we created earlier.
79+
80+
For command-line tools, set the `https_proxy` environment variable and pass it to commands that you run.
81+
82+
```shell
83+
export https_proxy=socks5h://localhost:1080
84+
```
85+
86+
When you set the `https_proxy` variable, tools such as `curl` route HTTPS traffic through the proxy
87+
you configured. For this to work, the tool must support SOCKS5 proxying.
88+
89+
{{< note >}}
90+
In the URL https://localhost/api, `localhost` does not refer to your local client computer.
91+
Instead, it refers to the endpoint on the remote server knows as `localhost`.
92+
The `curl` tool sends the hostname from the HTTPS URL over SOCKS, and the remote server
93+
resolves that locally (to an address that belongs to its loopback interface).
94+
{{</ note >}}
95+
96+
```shell
97+
curl -k -v https://localhost/api
98+
```
99+
100+
To use the official Kubernetes client `kubectl` with a proxy, set the `proxy-url` element
101+
for the relevant `cluster` entry within your `~/.kube/config` file. For example:
102+
103+
```yaml
104+
apiVersion: v1
105+
clusters:
106+
- cluster:
107+
certificate-authority-data: LRMEMMW2 # shortened for readability
108+
server: https://localhost # the "Kubernetes API" in the diagram above
109+
proxy-url: socks5://localhost:1080 # the "SSH SOCKS5 proxy" in the diagram above (DNS resolution over socks is built-in)
110+
name: default
111+
contexts:
112+
- context:
113+
cluster: default
114+
user: default
115+
name: default
116+
current-context: default
117+
kind: Config
118+
preferences: {}
119+
users:
120+
- name: default
121+
user:
122+
client-certificate-data: LS0tLS1CR== # shortened for readability
123+
client-key-data: LS0tLS1CRUdJT= # shortened for readability
124+
```
125+
126+
If the tunnel is operating and you use `kubectl` with a context that uses this cluster, you can interact with your cluster through that proxy. For example:
127+
128+
```shell
129+
kubectl get pods
130+
```
131+
132+
```console
133+
NAMESPACE NAME READY STATUS RESTARTS AGE
134+
kube-system coredns-85cb69466-klwq8 1/1 Running 0 5m46s
135+
```
136+
137+
## Clean up
138+
139+
Stop the ssh port-forwarding process by pressing `CTRL+C` on the terminal where it is running.
140+
141+
Type `unset https_proxy` in a terminal to stop forwarding http traffic through the proxy.
142+
143+
## Further reading
144+
145+
* [OpenSSH remote login client](https://man.openbsd.org/ssh)

0 commit comments

Comments
 (0)