Skip to content

Commit 6749ea6

Browse files
BetaCat0BetaCat0
committed
doc: Add documentation for enabling Kubelet proxy in Module Controller V2
1 parent da74a21 commit 6749ea6

7 files changed

Lines changed: 449 additions & 1 deletion

File tree

‎content/en/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: 6.6.4 Kubelet Proxy
3+
date: 2025-08-22T13:00:03+08:00
4+
description: Koupleless Module Controller V2 Kubelet Proxy
5+
weight: 930
6+
---
7+
8+
## Kubelet Proxy
9+
10+
The Kubelet Proxy is an enhanced feature of Module Controller V2 on the K8s side.
11+
It allows users to interact directly with Module Controller V2 using the ``kubectl`` tool,
12+
providing an operational experience similar to the native K8s Kubelet.
13+
14+
<div style="text-align: center;">
15+
<img align="center" width="800px" src="/img/module-controller-v2/kubelet_proxy_sequence_diagram.png"/>
16+
<p>Logs command schematic</p>
17+
</div>
18+
19+
## Iteration Plan
20+
21+
The adaptation will be carried out in two phases:
22+
23+
- [x] Use the proxy solution to provide logs capability for modules deployed in the Pod base -> **Completed**
24+
- [ ] Ensure semantic consistency and implement logs capability through tunnel or arklet for smooth transition -> *
25+
*Planned**
26+
27+
## Notes
28+
29+
Currently, only the logs capability is implemented, and the base must be deployed in the K8s cluster.

‎content/en/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: 5.7 Enable Kubelet Proxy
3+
date: 2025-08-22T13:00:03+08:00
4+
description: How to enable Koupleless Module Controller V2 Kubelet Proxy
5+
weight: 1100
6+
---
7+
8+
## Kubelet Proxy
9+
10+
Kubelet Proxy is an enhanced feature of Module Controller V2 on the K8s side.
11+
It allows users to interact directly with Module Controller V2 using the ``kubectl`` tool,
12+
providing an operational experience similar to the native K8s Kubelet.
13+
14+
For design details, please refer to
15+
the [documentation](/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy).
16+
17+
## Enable Kubelet Proxy
18+
19+
0. Deploy cert-manager to manage certificate generation and rotation
20+
cert-manager is a Kubernetes plugin for automating the management and rotation of TLS certificates. It helps generate
21+
and manage TLS certificates used for the Kubelet Proxy.
22+
Please refer to the [cert-manager documentation](https://cert-manager.io/docs/installation/) for installation
23+
instructions.
24+
Here is a simple installation example (v1.18.2):
25+
26+
```bash
27+
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.18.2/cert-manager.yaml
28+
```
29+
30+
After successful deployment, deploy the corresponding Issuer and Certificate:
31+
32+
- To create Issuer
33+
34+
```yaml
35+
apiVersion: cert-manager.io/v1
36+
kind: ClusterIssuer
37+
metadata:
38+
name: virtual-kubelet-issuer
39+
spec:
40+
selfSigned: {}
41+
```
42+
43+
- To create Cert
44+
45+
```yaml
46+
apiVersion: cert-manager.io/v1
47+
kind: Certificate
48+
metadata:
49+
name: virtual-kubelet-cert
50+
spec:
51+
secretName: virtual-kubelet-tls # secretName: virtual-kubelet-tls # The name of the Secret where the certificate is stored, which will be used later in the ModuleController
52+
duration: 2160h # 90 days
53+
renewBefore: 360h # renew 15 days before expiration
54+
issuerRef:
55+
name: virtual-kubelet-issuer # Reference to the above Issuer
56+
kind: ClusterIssuer
57+
commonName: koupleless-virtual-kubelet # Common Name
58+
usages:
59+
- server auth
60+
- digital signature
61+
- key encipherment
62+
```
63+
64+
After creation, you can use the following command to check whether the certificate secret was generated successfully:
65+
66+
If the output is similar to the following, the certificate has been generated successfully:
67+
68+
```bash
69+
kubectl get secret virtual-kubelet-tls
70+
```
71+
72+
If the output is similar to the following, the certificate has been generated successfully:
73+
74+
```
75+
NAME TYPE DATA AGE
76+
virtual-kubelet-tls kubernetes.io/tls 3 1m
77+
```
78+
79+
1. Add `pods/log` permission to the Role
80+
81+
```yaml
82+
kind: ClusterRole
83+
apiVersion: rbac.authorization.k8s.io/v1
84+
metadata:
85+
name: virtual-kubelet-role
86+
rules:
87+
- apiGroups: [""] # "" indicates the core API group
88+
resources: ["pods" , "pods/status", "pods/spec","nodes", "nodes/status", "events", "pods/log"]
89+
verbs: ["get", "watch", "list", "update", "patch", "create", "delete"]
90+
- apiGroups: [ "apps" ]
91+
resources: [ "deployments", "deployments/status", "deployments/spec", "daemonSets", "daemonSets/status", "daemonSets/spec" ]
92+
verbs: [ "get", "watch", "list" ]
93+
- apiGroups: [""] # "" indicates the core API group
94+
resources: ["configmaps", "secrets", "services"]
95+
verbs: ["get", "watch", "list"]
96+
- apiGroups: ["coordination.k8s.io"] # "" indicates the core API group
97+
resources: ["leases"]
98+
verbs: ["get", "watch", "list", "update", "patch", "create", "delete"]
99+
```
100+
101+
2. Create a Service for the ModuleController deployment
102+
103+
```yaml
104+
apiVersion: v1
105+
kind: Service
106+
metadata:
107+
name: module-controller
108+
namespace: default
109+
labels:
110+
app: module-controller
111+
virtual-kubelet.koupleless.io/kubelet-proxy-service: "true" # Necessary, indicates that this Service is used for Kubelet Proxy
112+
spec:
113+
selector:
114+
app: module-controller
115+
ports:
116+
- name: httptunnel # If HTTP tunneling is not enabled, please remove this port
117+
port: 7777
118+
targetPort: 7777
119+
- name: kubelet-proxy # Kubelet Proxy port
120+
port: 10250
121+
type: ClusterIP
122+
```
123+
124+
3. Modify the ENV configuration of ModuleController
125+
126+
```yaml
127+
apiVersion: apps/v1
128+
kind: Deployment
129+
metadata:
130+
name: module-controller
131+
spec:
132+
replicas: 1
133+
selector:
134+
matchLabels:
135+
app: module-controller
136+
template:
137+
metadata:
138+
labels:
139+
app: module-controller
140+
spec:
141+
serviceAccountName: virtual-kubelet
142+
volumes:
143+
- name: tls-certs
144+
secret:
145+
secretName: virtual-kubelet-tls # Necessary, mount the TLS certificate generated by cert-manager
146+
containers:
147+
- name: module-controller
148+
image: serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/release/module-controller-v2:<VERSION> # Please replace <VERSION> with the actual version number, e.g., v2.1.4
149+
imagePullPolicy: IfNotPresent
150+
resources:
151+
limits:
152+
cpu: "1000m"
153+
memory: "400Mi"
154+
ports:
155+
- name: httptunnel # If HTTP tunneling is not enabled, please remove this port
156+
containerPort: 7777
157+
- name: kubelet-proxy # Kubelet Proxy port
158+
containerPort: 10250
159+
env:
160+
- name: ENABLE_HTTP_TUNNEL
161+
value: "true"
162+
- name: NAMESPACE # Necessary, the namespace where ModuleController is deployed
163+
valueFrom:
164+
fieldRef:
165+
fieldPath: metadata.namespace
166+
- name: KUBELET_PROXY_ENABLED # Necessary, enable Kubelet Proxy
167+
value: "true"
168+
volumeMounts: # Necessary, mount the TLS certificate generated by cert-manager
169+
- name: tls-certs
170+
mountPath: /etc/virtual-kubelet/tls
171+
readOnly: true
172+
```
173+
174+
## Verify Kubelet Proxy
175+
176+
Assume that a module named `biz1-web-single-host` has been deployed and the Module Controller has enabled the Kubelet
177+
Proxy.
178+
179+
```
180+
NAME READY STATUS RESTARTS AGE
181+
base-76d79d8599-f64jt 1/1 Running 0 13d
182+
biz1-web-single-host-786dfc476f-qsp7q 1/1 Running 0 7m40s
183+
module-controller-59f7bb765-8w84l 1/1 Running 0 13d
184+
```
185+
186+
At this point, you can directly access the module's logs using the kubectl command:
187+
188+
```bash
189+
kubectl logs --tail=50 biz1-web-single-host-786dfc476f-qsp7q
190+
```
191+
192+
It is expected to see normal log output. If an error occurs, it may indicate that the Kubelet Proxy is not properly
193+
configured or not enabled.

‎content/en/docs/tutorials/module-operation-v2/module-controller-deployment.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,13 @@ Below are some configurable environment variables and their explanations:
7373
- **CLIENT_ID**
7474
- Meaning: Optional, Module Controller instance ID. need to be unique in one env, will generate a random UUID in default.
7575

76+
- **KUBELET_PROXY_ENABLED**
77+
- Meaning: Flag to enable Kubelet proxy. If `true`, the Kubelet proxy will be enabled. For prerequisites to enable,
78+
please refer to documentation [here](/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy/).
79+
80+
- **KUBELET_PROXY_PORT**
81+
- Meaning: Port for Kubelet proxy. Default is 10250.
82+
7683
### Documentation Reference
7784

78-
For detailed structure and implementation, refer to the [documentation](/docs/contribution-guidelines/module-controller-v2/architecture/).
85+
For detailed structure and implementation, refer to the [documentation](/docs/contribution-guidelines/module-controller-v2/architecture/).

‎content/zh-cn/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: 6.6.4 Kubelet 代理
3+
date: 2025-08-22T13:00:03+08:00
4+
description: Koupleless Module Controller V2 Kubelet 代理
5+
weight: 930
6+
---
7+
8+
## Kubelet 代理
9+
10+
Kubelet 代理是 Module Controller V2 在 K8s 侧的增强功能，它允许用户通过 ``kubectl`` 工具直接与 Module Controller V2
11+
交互，提供类似于 K8s 原生 Kubelet 的操作体验。
12+
13+
<div style="text-align: center;">
14+
<img align="center" width="800px" src="/img/module-controller-v2/kubelet_proxy_sequence_diagram.png"/>
15+
<p>logs 命令示意图</p>
16+
</div>
17+
18+
## 迭代计划
19+
20+
适配分两阶段进行：
21+
22+
- [x] 使用 proxy 代理方案，为部署在 Pod 基座中的模块提供 logs 能力 -> **已完成**
23+
- [ ] 在保证语义的前提下，通过 tunnel 或 arklet 实现 logs 能力，完成平滑切换 -> **规划中**
24+
25+
## 注意事项
26+
27+
当前仅实现了 logs 能力，且基座必须部署在 K8s 集群中。

0 commit comments

Comments
 (0)