docs: update doc (#333)

This commit is contained in:
naison
2024-09-14 20:01:58 +08:00
committed by GitHub
parent 0763e8a201
commit 9d917ae9cb
8 changed files with 128 additions and 35 deletions

View File

@@ -89,6 +89,9 @@ kubectl delete -f https://raw.githubusercontent.com/kubenetworks/kubevpn/master/
### Connect to k8s cluster network
use command `kubevpn connect` connect to k8s cluster network, prompt `Password:` need to input computer
password. to enable root operation (create a tun device).
```shell
➜ ~ kubevpn connect
Password:
@@ -126,6 +129,8 @@ Configured DNS service
➜ ~
```
already connected to cluster network, use command `kubevpn status` to check status
```shell
➜ ~ kubevpn status
ID Mode Cluster Kubeconfig Namespace Status
@@ -133,6 +138,8 @@ ID Mode Cluster Kubeconfig Namespace Status
➜ ~
```
use pod `productpage-788df7ff7f-jpkcs` IP `172.29.2.134`
```shell
➜ ~ kubectl get pods -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
@@ -144,6 +151,8 @@ ratings-77b6cd4499-zvl6c 1/1 Running 0
reviews-85c88894d9-vgkxd 1/1 Running 0 24d 172.29.2.249 192.168.0.5 <none> <none>
```
use `ping` to test connection, seems good
```shell
➜ ~ ping 172.29.2.134
PING 172.29.2.134 (172.29.2.134): 56 data bytes
@@ -157,6 +166,8 @@ PING 172.29.2.134 (172.29.2.134): 56 data bytes
round-trip min/avg/max/stddev = 54.293/55.380/56.270/0.728 ms
```
use service `productpage` IP `172.21.10.49`
```shell
➜ ~ kubectl get services -o wide
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
@@ -169,6 +180,8 @@ ratings ClusterIP 172.21.3.247 <none> 9080/TCP
reviews ClusterIP 172.21.8.24 <none> 9080/TCP 114d app=reviews
```
use command `curl` to test service connection
```shell
➜ ~ curl 172.21.10.49:9080
<!DOCTYPE html>
@@ -180,8 +193,18 @@ reviews ClusterIP 172.21.8.24 <none> 9080/TCP
<meta name="viewport" content="width=device-width, initial-scale=1">
```
seems good too~
### Domain resolve
support k8s dns name resolve.
a Pod/Service named `productpage` in the `default` namespace can successfully resolve by following name:
- `productpage`
- `productpage.default`
- `productpage.default.svc.cluster.local`
```shell
➜ ~ curl productpage.default.svc.cluster.local:9080
<!DOCTYPE html>
@@ -214,12 +237,19 @@ use [Domain resolve](./README.md#domain-resolve)
### Connect to multiple kubernetes cluster network
- Mode `lite`: can connect to multiple cluster network, design for only connecting to multiple cluster network.
- Mode `Full`: not only connect to cluster network, it also supports proxy workloads inbound traffic to local PC.
already connected cluster `ccijorbccotmqodvr189g` with mode `full`
```shell
➜ ~ kubevpn status
ID Mode Cluster Kubeconfig Namespace Status
0 full ccijorbccotmqodvr189g /Users/naison/.kube/config default Connected
```
then connect to another cluster `ccidd77aam2dtnc3qnddg` with mode `lite`
```shell
➜ ~ kubevpn connect -n default --kubeconfig ~/.kube/dev_config --lite
Starting connect
@@ -234,6 +264,8 @@ Configured DNS service
+----------------------------------------------------------+
```
use command `kubevpn status` to check connection status
```shell
➜ ~ kubevpn status
ID Mode Cluster Kubeconfig Namespace Status
@@ -244,6 +276,8 @@ ID Mode Cluster Kubeconfig Namespace Status
### Reverse proxy
use command `kubevpn proxy` to proxy all inbound traffic to local computer.
```shell
➜ ~ kubevpn proxy deployment/productpage
Connected to cluster
@@ -294,20 +328,20 @@ then run it
export selector=productpage
export pod=`kubectl get pods -l app=${selector} -n default -o jsonpath='{.items[0].metadata.name}'`
export pod_ip=`kubectl get pod $pod -n default -o jsonpath='{.status.podIP}'`
curl -v -H "a: 1" http://$pod_ip:9080/health
curl -v -H "foo: bar" http://$pod_ip:9080/health
```
response would like below
```
curl -v -H "a: 1" http://$pod_ip:9080/health
curl -v -H "foo: bar" http://$pod_ip:9080/health
* Trying 192.168.72.77:9080...
* Connected to 192.168.72.77 (192.168.72.77) port 9080 (#0)
> GET /health HTTP/1.1
> Host: 192.168.72.77:9080
> User-Agent: curl/7.87.0
> Accept: */*
> a: 1
> foo: bar
>
>>Received request: GET /health from xxx.xxx.xxx.xxx:52974
* Mark bundle as not supporting multiuse
@@ -331,10 +365,10 @@ Hello world!%
### Reverse proxy with mesh
Support HTTP, GRPC and WebSocket etc. with specific header `"a: 1"` will route to your local machine
Support HTTP, GRPC and WebSocket etc. with specific header `"foo: bar"` will route to your local machine
```shell
➜ ~ kubevpn proxy deployment/productpage --headers a=1
➜ ~ kubevpn proxy deployment/productpage --headers foo=bar
Connected to cluster
Injecting inbound sidecar for deployment/productpage
Checking rollout status for deployment/productpage
@@ -347,7 +381,7 @@ Rollout successfully for deployment/productpage
➜ ~
```
first access without header "a: 1", it will access existing pod on kubernetes cluster.
first access without header "foo: bar", it will access existing pod on kubernetes cluster.
```shell
➜ ~ curl productpage:9080
@@ -361,10 +395,10 @@ first access without header "a: 1", it will access existing pod on kubernetes cl
...
```
Now let's access local service with header `"a: 1"`
Now let's access local service with header `"foo: bar"`
```shell
➜ ~ curl productpage:9080 -H "a: 1"
➜ ~ curl productpage:9080 -H "foo: bar"
>>Received request: GET / from xxx.xxx.xxx.xxx:51296
Hello world!
```
@@ -387,7 +421,7 @@ Run the Kubernetes pod in the local Docker container, and cooperate with the ser
the specified header to the local, or all the traffic to the local.
```shell
➜ ~ kubevpn dev deployment/authors --headers a=1 --entrypoint sh
➜ ~ kubevpn dev deployment/authors --headers foo=bar --entrypoint sh
Starting connect
Got network CIDR from cache
Use exist traffic manager
@@ -470,7 +504,7 @@ Here is how to access pod in local docker container
```shell
export authors_pod=`kubectl get pods -l app=authors -n default -o jsonpath='{.items[0].metadata.name}'`
export authors_pod_ip=`kubectl get pod $authors_pod -n default -o jsonpath='{.status.podIP}'`
curl -kv -H "a: 1" http://$authors_pod_ip:80/health
curl -kv -H "foo: bar" http://$authors_pod_ip:80/health
```
Verify logs of nginx container
@@ -622,7 +656,7 @@ OK: 8 MiB in 19 packages
>> Container Received request: GET / from 127.0.0.1:41230
Hello world!/opt/microservices #
/opt/microservices # curl authors:9080/health -H "a: 1"
/opt/microservices # curl authors:9080/health -H "foo: bar"
>>Received request: GET /health from 223.254.0.109:57930
Hello world!/opt/microservices #
/opt/microservices # curl localhost:9080/health
@@ -659,6 +693,8 @@ kubectl delete -f https://raw.githubusercontent.com/kubenetworks/kubevpn/master/
### Multiple Protocol
support OSI model layers 3 and above, protocols like `ICMP`, `TCP`, and `UDP`...
- TCP
- UDP
- ICMP
@@ -833,7 +869,8 @@ restart docker and retry
## Architecture
Architecture can be found [here](/docs/en/Architecture.md) and [website](https://www.kubevpn.cn/docs/architecture/connect).
Architecture can be found [here](/docs/en/Architecture.md)
and [website](https://www.kubevpn.cn/docs/architecture/connect).
## Contributions

View File

@@ -78,6 +78,8 @@ kubectl apply -f https://raw.githubusercontent.com/kubenetworks/kubevpn/master/s
### 链接到集群网络
使用命令 `kubevpn connect` 链接到集群,请注意这里需要输入电脑密码。因为需要 `root` 权限。(创建虚拟网卡)
```shell
➜ ~ kubevpn connect
Password:
@@ -115,6 +117,8 @@ Configured DNS service
➜ ~
```
提示已经链接到集群了。使用命令 `kubevpn status` 检查一下状态。
```shell
➜ ~ kubectl get pods -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
@@ -126,6 +130,8 @@ ratings-77b6cd4499-zvl6c 1/1 Running 0
reviews-85c88894d9-vgkxd 1/1 Running 0 24d 172.29.2.249 192.168.0.5 <none> <none>
```
找一个 pod 的 IP比如 `productpage-788df7ff7f-jpkcs` 的 IP `172.29.2.134`
```shell
➜ ~ ping 172.29.2.134
PING 172.29.2.134 (172.29.2.134): 56 data bytes
@@ -139,6 +145,8 @@ PING 172.29.2.134 (172.29.2.134): 56 data bytes
round-trip min/avg/max/stddev = 54.293/55.380/56.270/0.728 ms
```
测试应该可以直接 Ping 通,说明本地可以正常访问到集群网络了。
```shell
➜ ~ kubectl get services -o wide
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
@@ -151,6 +159,8 @@ ratings ClusterIP 172.21.3.247 <none> 9080/TCP
reviews ClusterIP 172.21.8.24 <none> 9080/TCP 114d app=reviews
```
找一个 service 的 IP比如 `productpage` 的 IP `172.21.10.49`,试着访问一下服务 `productpage`
```shell
➜ ~ curl 172.21.10.49:9080
<!DOCTYPE html>
@@ -162,8 +172,16 @@ reviews ClusterIP 172.21.8.24 <none> 9080/TCP
<meta name="viewport" content="width=device-width, initial-scale=1">
```
可以看到也可以正常访问,也就是可以在本地访问到集群的 pod 和 service 了~
### 域名解析功能
支持 k8s dns 解析。比如一个名为 `productpage` 的 Pod 或者 Service 处于 `default` 命名空间下可以被如下域名正常解析到:
- `productpage`
- `productpage.default`
- `productpage.default.svc.cluster.local`
```shell
➜ ~ curl productpage.default.svc.cluster.local:9080
<!DOCTYPE html>
@@ -175,8 +193,15 @@ reviews ClusterIP 172.21.8.24 <none> 9080/TCP
<meta name="viewport" content="width=device-width, initial-scale=1">
```
可以看到能够被正常解析,并且返回相应内容。
### 短域名解析功能
连接到此命名空间下,可以直接使用 `service` name 的方式访问,否则访问其它命令空间下的服务,需要带上命令空间作为域名的一部分,使用如下的域名即可。
- `productpage.default`
- `productpage.default.svc.cluster.local`
```shell
➜ ~ curl productpage:9080
<!DOCTYPE html>
@@ -188,14 +213,25 @@ reviews ClusterIP 172.21.8.24 <none> 9080/TCP
...
```
可以看到直接使用 service name 的方式,可以正常访问到集群资源。
### 链接到多集群网络
有个两个模式
- 模式 `lite`: 可以链接到多个集群网络,但是仅支持链接到多集群。
- 模式 `full`: 不仅支持链接到单个集群网络,还可以拦截工作负载流量到本地电脑。
可以看到已经链接到了一个集群 `ccijorbccotmqodvr189g`,是 `full` 模式
```shell
➜ ~ kubevpn status
ID Mode Cluster Kubeconfig Namespace Status
0 full ccijorbccotmqodvr189g /Users/naison/.kube/config default Connected
```
此时还可以使用 `lite` 模式链接到其它集群
```shell
➜ ~ kubevpn connect -n default --kubeconfig ~/.kube/dev_config --lite
Starting connect
@@ -210,6 +246,8 @@ Configured DNS service
+----------------------------------------------------------+
```
使用命令 `kubevpn status` 查看当前链接状态。
```shell
➜ ~ kubevpn status
ID Mode Cluster Kubeconfig Namespace Status
@@ -218,8 +256,12 @@ ID Mode Cluster Kubeconfig Namespace Status
➜ ~
```
可以看到连接到了多个集群。
### 反向代理
使用命令 `kubevpn proxy` 代理所有的入站流量到本地电脑。
```shell
➜ ~ kubevpn proxy deployment/productpage
Connected to cluster
@@ -234,6 +276,8 @@ Rollout successfully for deployment/productpage
➜ ~
```
此时在本地使用 `go` 启动一个服务,用于承接流量。
```go
package main
@@ -250,6 +294,8 @@ func main() {
}
```
使用 `service` name 的方式,直接访问集群中的 `productpage` 服务。
```shell
➜ ~ curl productpage:9080
Hello world!%
@@ -257,12 +303,14 @@ Hello world!%
Hello world!%
```
可以看到直接击中了本地电脑的服务。
### 反向代理支持 service mesh
支持 HTTP, GRPC 和 WebSocket 等, 携带了指定 header `"a: 1"` 的流量,将会路由到本地
支持 HTTP, GRPC 和 WebSocket 等, 携带了指定 header `"foo: bar"` 的流量,将会路由到本地
```shell
➜ ~ kubevpn proxy deployment/productpage --headers a=1
➜ ~ kubevpn proxy deployment/productpage --headers foo=bar
Connected to cluster
Injecting inbound sidecar for deployment/productpage
Checking rollout status for deployment/productpage
@@ -275,6 +323,8 @@ Rollout successfully for deployment/productpage
➜ ~
```
不带 header 直接访问集群资源,可以看到返回的是集群中的服务内容。
```shell
➜ ~ curl productpage:9080
<!DOCTYPE html>
@@ -287,8 +337,10 @@ Rollout successfully for deployment/productpage
...
```
带上特定 header 访问集群资源,可以看到返回了本地服务的内容。
```shell
➜ ~ curl productpage:9080 -H "a: 1"
➜ ~ curl productpage:9080 -H "foo: bar"
Hello world!%
```
@@ -310,7 +362,7 @@ Rollout successfully for deployments/productpage
Docker。
```shell
➜ ~ kubevpn dev deployment/authors --headers a=1 --entrypoint sh
➜ ~ kubevpn dev deployment/authors --headers foo=bar --entrypoint sh
Starting connect
Got network CIDR from cache
Use exist traffic manager
@@ -528,7 +580,7 @@ OK: 8 MiB in 19 packages
>> Container Received request: GET / from 127.0.0.1:41230
Hello world!/opt/microservices #
/opt/microservices # curl authors:9080/health -H "a: 1"
/opt/microservices # curl authors:9080/health -H "foo: bar"
>>Received request: GET /health from 223.254.0.109:57930
Hello world!/opt/microservices #
/opt/microservices # curl localhost:9080/health
@@ -546,6 +598,8 @@ exit
➜ ~
```
可以看到实际上是在本地使用 `Docker` 启动了三个容器。
```text
➜ ~ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
@@ -557,6 +611,8 @@ d0b3dab8912a naison/kubevpn:v2.0.0 "/bin/bash" 5 minute
### 支持多种协议
支持 OSI 模型三层及三层以上的协议,例如:
- TCP
- UDP
- ICMP

View File

@@ -56,17 +56,17 @@ func CmdClone(f cmdutil.Factory) *cobra.Command {
or
kubevpn clone deployment authors productpage
# clone with mesh, traffic with header a=1, will hit cloned workloads, otherwise hit origin workloads
kubevpn clone deployment/productpage --headers a=1
# clone with mesh, traffic with header foo=bar, will hit cloned workloads, otherwise hit origin workloads
kubevpn clone deployment/productpage --headers foo=bar
# clone workloads which api-server behind of bastion host or ssh jump host
kubevpn clone deployment/productpage --ssh-addr 192.168.1.100:22 --ssh-username root --ssh-keyfile ~/.ssh/ssh.pem --headers a=1
kubevpn clone deployment/productpage --ssh-addr 192.168.1.100:22 --ssh-username root --ssh-keyfile ~/.ssh/ssh.pem --headers foo=bar
# It also supports ProxyJump, like
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌────────────┐
│ pc ├────►│ ssh1 ├────►│ ssh2 ├────►│ ssh3 ├─────►... ─────► │ api-server │
└──────┘ └──────┘ └──────┘ └──────┘ └────────────┘
kubevpn clone service/productpage --ssh-alias <alias> --headers a=1
kubevpn clone service/productpage --ssh-alias <alias> --headers foo=bar
# Support ssh auth GSSAPI
kubevpn clone service/productpage --ssh-addr <HOST:PORT> --ssh-username <USERNAME> --gssapi-keytab /path/to/keytab
@@ -155,7 +155,7 @@ func CmdClone(f cmdutil.Factory) *cobra.Command {
return nil
},
}
cmd.Flags().StringToStringVarP(&options.Headers, "headers", "H", map[string]string{}, "Traffic with special headers (use `and` to match all headers) with reverse it to target cluster cloned workloads, If not special, redirect all traffic to target cluster cloned workloads. eg: --headers a=1 --headers b=2")
cmd.Flags().StringToStringVarP(&options.Headers, "headers", "H", map[string]string{}, "Traffic with special headers (use `and` to match all headers) with reverse it to target cluster cloned workloads, If not special, redirect all traffic to target cluster cloned workloads. eg: --headers foo=bar --headers env=dev")
cmd.Flags().BoolVar(&config.Debug, "debug", false, "Enable debug mode or not, true or false")
cmd.Flags().StringVar(&config.Image, "image", config.Image, "Use this image to startup container")
cmd.Flags().BoolVar(&transferImage, "transfer-image", false, "transfer image to remote registry, it will transfer image "+config.OriginImage+" to flags `--image` special image, default: "+config.Image)

View File

@@ -163,7 +163,7 @@ func CmdConnect(f cmdutil.Factory) *cobra.Command {
cmd.Flags().BoolVar(&transferImage, "transfer-image", false, "transfer image to remote registry, it will transfer image "+config.OriginImage+" to flags `--image` special image, default: "+config.Image)
cmd.Flags().StringVar((*string)(&connect.Engine), "engine", string(config.EngineRaw), fmt.Sprintf(`transport engine ("%s"|"%s") %s: use gvisor and raw both (both performance and stable), %s: use raw mode (best stable)`, config.EngineMix, config.EngineRaw, config.EngineMix, config.EngineRaw))
cmd.Flags().BoolVar(&foreground, "foreground", false, "Hang up")
cmd.Flags().BoolVar(&lite, "lite", false, "connect to multiple cluster in lite mode, you needs to special this options")
cmd.Flags().BoolVar(&lite, "lite", false, "connect to multiple cluster in lite mode. mode \"lite\": design for only connecting to multiple cluster network. mode \"full\": not only connect to cluster network, it also supports proxy workloads inbound traffic to local PC.")
handler.AddExtraRoute(cmd.Flags(), extraRoute)
pkgssh.AddSshFlags(cmd.Flags(), sshConf)

View File

@@ -45,8 +45,8 @@ func CmdDev(f cmdutil.Factory) *cobra.Command {
- develop service
kubevpn dev service/productpage
# Develop workloads with mesh, traffic with header a=1, will hit local PC, otherwise no effect
kubevpn dev service/productpage --headers a=1
# Develop workloads with mesh, traffic with header foo=bar, will hit local PC, otherwise no effect
kubevpn dev service/productpage --headers foo=bar
# Develop workloads without proxy traffic
kubevpn dev service/productpage --no-proxy

View File

@@ -54,20 +54,20 @@ func CmdProxy(f cmdutil.Factory) *cobra.Command {
or
kubevpn proxy deployment authors productpage
# Reverse proxy with mesh, traffic with header a=1, will hit local PC, otherwise no effect
kubevpn proxy service/productpage --headers a=1
# Reverse proxy with mesh, traffic with header foo=bar, will hit local PC, otherwise no effect
kubevpn proxy service/productpage --headers foo=bar
# Reverse proxy with mesh, traffic with header a=1 and b=2, will hit local PC, otherwise no effect
kubevpn proxy service/productpage --headers a=1 --headers b=2
# Reverse proxy with mesh, traffic with header foo=bar and env=dev, will hit local PC, otherwise no effect
kubevpn proxy service/productpage --headers foo=bar --headers env=dev
# Connect to api-server behind of bastion host or ssh jump host and proxy kubernetes resource traffic into local PC
kubevpn proxy deployment/productpage --ssh-addr 192.168.1.100:22 --ssh-username root --ssh-keyfile ~/.ssh/ssh.pem --headers a=1
kubevpn proxy deployment/productpage --ssh-addr 192.168.1.100:22 --ssh-username root --ssh-keyfile ~/.ssh/ssh.pem --headers foo=bar
# It also supports ProxyJump, like
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌────────────┐
│ pc ├────►│ ssh1 ├────►│ ssh2 ├────►│ ssh3 ├─────►... ─────► │ api-server │
└──────┘ └──────┘ └──────┘ └──────┘ └────────────┘
kubevpn proxy service/productpage --ssh-alias <alias> --headers a=1
kubevpn proxy service/productpage --ssh-alias <alias> --headers foo=bar
# Support ssh auth GSSAPI
kubevpn proxy service/productpage --ssh-addr <HOST:PORT> --ssh-username <USERNAME> --gssapi-keytab /path/to/keytab
@@ -176,7 +176,7 @@ func CmdProxy(f cmdutil.Factory) *cobra.Command {
return nil
},
}
cmd.Flags().StringToStringVarP(&connect.Headers, "headers", "H", map[string]string{}, "Traffic with special headers (use `and` to match all headers) with reverse it to local PC, If not special, redirect all traffic to local PC. eg: --headers a=1 --headers b=2")
cmd.Flags().StringToStringVarP(&connect.Headers, "headers", "H", map[string]string{}, "Traffic with special headers (use `and` to match all headers) with reverse it to local PC, If not special, redirect all traffic to local PC. format: <KEY>=<VALUE> eg: --headers foo=bar --headers env=dev")
cmd.Flags().StringArrayVar(&connect.PortMap, "portmap", []string{}, "Port map, map container port to local port, format: [tcp/udp]/containerPort:localPort, If not special, localPort will use containerPort. eg: tcp/80:8080 or udp/5000:5001 or 80 or 80:8080")
cmd.Flags().BoolVar(&config.Debug, "debug", false, "Enable debug mode or not, true or false")
cmd.Flags().StringVar(&config.Image, "image", config.Image, "Use this image to startup container")

View File

@@ -28,7 +28,7 @@ base on reverse mode, using envoy as proxy, if headers have special key-value pa
│ │ cloud
─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─┘─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
│ │ local
header: a=1
header: foo=bar
┌───┘──────┐ │
│ ServiceB'├─────────────┘
└──────────┘

View File

@@ -264,7 +264,7 @@ func addVirtualRule(v []*controlplane.Virtual, nodeID string, port []v1.Containe
})
}
// 2) if already proxy deployment/xxx with header a=1. also want to add b=2
// 2) if already proxy deployment/xxx with header foo=bar. also want to add env=dev
for j, rule := range v[index].Rules {
if rule.LocalTunIPv4 == tunIP.LocalTunIPv4 &&
rule.LocalTunIPv6 == tunIP.LocalTunIPv6 {
@@ -274,7 +274,7 @@ func addVirtualRule(v []*controlplane.Virtual, nodeID string, port []v1.Containe
}
}
// 3) if already proxy deployment/xxx with header a=1, other user can replace it to self
// 3) if already proxy deployment/xxx with header foo=bar, other user can replace it to self
for j, rule := range v[index].Rules {
if reflect.DeepEqual(rule.Headers, headers) {
v[index].Rules[j].LocalTunIPv6 = tunIP.LocalTunIPv6