KubeVPN

KubeVPN 将本地机器连接到远程 Kubernetes 集群网络。核心工作流：
connect（VPN 隧道）、proxy（流量拦截）、run（本地 Pod 模拟）、sync（本地代码 → 集群克隆）。

安装

bash
brew install kubevpn # macOS
curl -fsSL https://kubevpn.dev/install.sh | sh # Linux/macOS
kubectl krew install kubevpn/kubevpn # kubectl 插件
scoop bucket add extras && scoop install kubevpn # Windows

核心工作流

1. Connect — 访问集群网络

bash
kubevpn connect
kubevpn connect -n <命名空间>
kubevpn connect --context <上下文名称>
kubevpn disconnect --all

连接后，可直接访问集群资源：
bash
ping
curl <服务名称>:<端口>
curl <服务名称>.<命名空间>.svc.cluster.local:<端口>

2. Proxy — 拦截入站流量

拦截工作负载的集群入站流量并转发到本地机器。
如果尚未连接，proxy 也会自动连接到集群。

bash
kubevpn proxy deployment/<名称>
kubevpn proxy deployment/<名称> -n <命名空间>

网格模式：仅匹配标头的请求发送到本地

kubevpn proxy deployment/<名称> --headers foo=bar kubevpn proxy deployment/<名称> --headers foo=bar --headers env=dev # AND 逻辑

端口映射

kubevpn proxy deployment/<名称> --portmap 9080:8080 kubevpn proxy deployment/<名称> --portmap udp/9080:5000

同时处理多个工作负载

kubevpn proxy deployment/authors deployment/productpage

kubevpn leave deployment/<名称> # 停止代理，恢复工作负载

3. Run — 在本地 Docker 中模拟 Pod

在本地 Docker 容器中运行工作负载，具有相同的环境变量、卷和网络。

bash
kubevpn run deployment/<名称>
kubevpn run deployment/<名称> --entrypoint /bin/bash # 交互式 Shell
kubevpn run deployment/<名称> --no-proxy # 不拦截流量
kubevpn run deployment/<名称> --dev-image golang:1.21 --entrypoint bash
kubevpn run deployment/<名称> --headers foo=bar # 网格模式

4. Sync — 在集群中热重载本地代码

在集群内部克隆工作负载，并将本地目录同步到克隆中。
克隆具有与原始工作负载相同的环境/卷/网络。支持通过 --headers 进行网格路由。

bash
kubevpn sync deployment/<名称> --sync ~/code:/app/code
kubevpn sync deployment/<名称> --sync ~/code:/app/code --headers foo=bar

kubevpn unsync deployment/<名称>-sync-xxxxx # 移除同步资源

5. Alias — 命名配置快捷方式

在 ~/.kubevpn/config.yaml 中定义命名别名，避免重复输入长标志。支持 Needs 依赖链（在连接集群 B 之前先连接集群 A）。

bash
kubevpn alias dev # 运行配置中 dev 下定义的标志
kubevpn alias jumper # 仅连接到跳板集群

配置文件格式请参见 commands.md。

通过 SSH 堡垒机/跳板主机

所有 connect/proxy/run/sync 命令都支持 SSH 跳转：
bash
kubevpn connect --ssh-addr 192.168.1.100:22 --ssh-username root --ssh-keyfile ~/.ssh/id_rsa
kubevpn connect --ssh-alias dev # 使用 ~/.ssh/config 别名
kubevpn proxy deployment/<名称> --ssh-alias dev --headers foo=bar

参考文件

• - commands.md — 所有 kubevpn 命令的完整标志参考（包括 alias、connection、route、ssh、image、logs、quit）
• architecture.md — connect/proxy/mesh 模式的内部工作原理

常见模式

目标	命令
在本地访问集群 IP/服务	kubevpn connect
使用保存的别名连接

kubevpn alias <名称> | | 调试服务（接收其所有流量） | kubevpn proxy deployment/<名称> | | 仅调试我的请求（不干扰他人） | kubevpn proxy deployment/<名称> --headers x-user=me | | 在本地重现 Pod 环境 | kubevpn run deployment/<名称> --entrypoint sh | | 在集群环境中热重载本地代码 | kubevpn sync deployment/<名称> --sync ~/code:/app | | 检查连接状态 | kubevpn status | | 强制恢复卡住的工作负载 | kubevpn reset deployment/<名称> | | 完全停止 kubevpn（守护进程 + 连接） | kubevpn quit | | 从集群中移除所有 kubevpn | kubevpn uninstall | | 复制镜像到私有仓库 | kubevpn image copy <源> <目标> | | 跟踪守护进程日志 | kubevpn logs -f |

注意事项

• - proxy、run 和 sync 如果尚未连接，会自动连接到集群
• 可以同时连接多个集群；使用 kubevpn status 或 kubevpn connection list 查看
• disconnect 清理 DNS/hosts；quit 还会完全停止守护进程 gRPC 服务器
• 服务器组件在首次使用时自动部署（或预安装：helm install kubevpn kubevpn/kubevpn）
• 支持 HTTP、gRPC、Thrift、WebSocket、TCP、UDP、ICMP
• 如果工作负载因注入容器而卡住，请使用 kubevpn reset deployment/<名称>
• 当 ghcr.io 不可访问时，使用 kubevpn image copy 将镜像镜像到私有仓库