Doc: Add documentation for enabling Kubelet proxy in Module Controller V2 #122
Conversation
WalkthroughAdds new English and Chinese docs introducing and enabling the Kubelet Proxy for Module Controller V2, including TLS/RBAC/Service/Deployment setup and verification. Updates deployment docs to include KUBELET_PROXY_ENABLED and KUBELET_PROXY_PORT environment variables. No code/public API changes. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant U as User
participant K as kubectl
participant APIS as Kubernetes API Server
participant SVC as Service (module-controller)
participant KP as Module Controller (Kubelet Proxy)
participant P as Pod/Module
U->>K: kubectl logs <pod>
K->>APIS: REST request (authn/authz)
APIS->>SVC: Route to port 10250 (kubelet-proxy)
SVC->>KP: Forward request (mTLS with VK TLS secret)
KP->>P: Fetch logs (internal access)
P-->>KP: Log stream
KP-->>APIS: Proxied response/stream
APIS-->>K: Logs
K-->>U: Display logs
note over KP,SVC: Ports used: 10250 (kubelet-proxy), 7777 (httptunnel)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (25)
content/zh-cn/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md (4)
10-11: Use single backticks for inline code.Replace
kubectlwithkubectlfor consistency with the rest of the docs.- Kubelet 代理是 Module Controller V2 在 K8s 侧的增强功能，它允许用户通过 ``kubectl`` 工具直接与 Module Controller V2 + Kubelet 代理是 Module Controller V2 在 K8s 侧的增强功能，它允许用户通过 `kubectl` 工具直接与 Module Controller V2
13-16: Add alt text and prefer Hugo figure shortcode for the image.Improves accessibility (MD045) and keeps styling consistent with Hugo sites.
-<div style="text-align: center;"> - <img align="center" width="800px" src="/img/module-controller-v2/kubelet_proxy_sequence_diagram.png"/> - <p>logs 命令示意图</p> -</div> +{{< figure src="/img/module-controller-v2/kubelet_proxy_sequence_diagram.png" alt="Kubelet Proxy logs 命令时序图" caption="logs 命令示意图" width="800px" >}}
22-24: Confirm the proper noun “arklet”.If this refers to a specific component, ensure the spelling and casing are correct or link to its doc the first time it appears.
25-27: Cross-link the enablement tutorial from the Notes.Gives readers a direct path to actionable steps.
-当前仅实现了 logs 能力，且基座必须部署在 K8s 集群中。 +当前仅实现了 logs 能力，且基座必须部署在 K8s 集群中。启用与配置步骤请参考《[启用 Kubelet 代理](/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy/)》。content/en/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md (3)
10-13: Polish wording and use single backticks.Minor readability/terminology improvements; “for Kubernetes” reads better than “on the K8s side.”
-The Kubelet Proxy is an enhanced feature of Module Controller V2 on the K8s side. -It allows users to interact directly with Module Controller V2 using the ``kubectl`` tool, -providing an operational experience similar to the native K8s Kubelet. +The Kubelet Proxy is an enhanced feature of Module Controller V2 for Kubernetes. +It allows users to interact directly with Module Controller V2 using the `kubectl` tool, +providing an operational experience similar to the native Kubernetes Kubelet.
14-17: Add alt text and prefer Hugo figure shortcode.Resolves MD045 and keeps styling consistent.
-<div style="text-align: center;"> - <img align="center" width="800px" src="/img/module-controller-v2/kubelet_proxy_sequence_diagram.png"/> - <p>Logs command schematic</p> -</div> +{{< figure src="/img/module-controller-v2/kubelet_proxy_sequence_diagram.png" alt="Kubelet Proxy logs sequence diagram" caption="Logs command schematic" width="800px" >}}
29-29: Link to the enablement tutorial from Notes.Helps readers proceed directly.
-Currently, only the logs capability is implemented, and the base must be deployed in the K8s cluster. +Currently, only the logs capability is implemented, and the base must be deployed in the K8s cluster. For enablement steps, see [Enable Kubelet Proxy](/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy/).content/en/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md (7)
10-13: Polish wording and use single backticks.-Kubelet Proxy is an enhanced feature of Module Controller V2 on the K8s side. -It allows users to interact directly with Module Controller V2 using the ``kubectl`` tool, -providing an operational experience similar to the native K8s Kubelet. +Kubelet Proxy is an enhanced feature of Module Controller V2 for Kubernetes. +It allows users to interact directly with Module Controller V2 using the `kubectl` tool, +providing an operational experience similar to the native Kubernetes Kubelet.
19-25: Rename “0.” to “1. (Prerequisite)”.Lists starting at zero are surprising; framing cert-manager as a prerequisite reads better.
-0. Deploy cert-manager to manage certificate generation and rotation +1. (Prerequisite) Deploy cert-manager to manage certificate generation and rotation
51-51: Clean up duplicated comment on secretName.- 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 + secretName: virtual-kubelet-tls # The name of the Secret where the certificate is stored; it will be mounted by ModuleController
54-58: Add SANs to the Certificate (CN alone is deprecated).Modern TLS clients validate Subject Alternative Names; include the Service DNS names to avoid handshake issues.
issuerRef: name: virtual-kubelet-issuer # Reference to the above Issuer kind: ClusterIssuer commonName: koupleless-virtual-kubelet # Common Name + dnsNames: + - module-controller.default.svc + - module-controller.default.svc.cluster.local
116-121: Be explicit with targetPort and call out port overrides.Helps when KUBELET_PROXY_PORT is changed from the default.
- name: kubelet-proxy # Kubelet Proxy port - port: 10250 + port: 10250 + targetPort: 10250
159-168: Optionally include KUBELET_PROXY_PORT in the Deployment.Keeps Deployment, Service, and docs aligned if the default port is overridden.
- name: KUBELET_PROXY_ENABLED # Necessary, enable Kubelet Proxy value: "true" + - name: KUBELET_PROXY_PORT # Optional, override if not using the default + value: "10250"
141-146: Ensure the ServiceAccount exists.The spec references serviceAccountName: virtual-kubelet; provide or link to its manifest (or the doc where it’s created) to avoid a failed Deployment.
content/en/docs/tutorials/module-operation-v2/module-controller-deployment.md (1)
76-82: Clarify the port alignment requirement.Make it explicit that the env var must match the Service’s kubelet-proxy port.
- **KUBELET_PROXY_PORT** - - Meaning: Port for Kubelet proxy. Default is 10250. + - Meaning: Port for Kubelet proxy. Default is 10250. Ensure it matches the Service port named `kubelet-proxy`.content/zh-cn/docs/tutorials/module-operation-v2/module-controller-deployment.md (2)
76-79: 小建议：更顺畅的表述。“启用方式”前加空格和冒号统一风格，同时明确“参考文档”。
- **KUBELET_PROXY_ENABLED** -- 含义: Kubelet 代理启用标志，若为 `true`，将启用 kubelet - 代理。启用方式，请参考[文档](/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy/)。 +- 含义: Kubelet 代理启用标志，若为 `true`，将启用 Kubelet 代理。启用方式请参考：[文档](/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy/)。
80-82: 强调端口需与 Service 保持一致。- **KUBELET_PROXY_PORT** -- 含义: Kubelet 代理端口，当 KUBELET_PROXY_ENABLED 设置为 `true` 时生效，默认值为 10250。 +- 含义: Kubelet 代理端口，当 `KUBELET_PROXY_ENABLED` 设置为 `true` 时生效，默认值为 10250。请确保与 Service 中 `kubelet-proxy` 端口一致。content/zh-cn/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md (8)
10-14: Use Hugo relref for i18n-stable internal link将硬编码路径替换为 Hugo 的 relref，避免多语言与路径重构导致的链接失效。例如：
- 现有：/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy
- 建议：{{< relref "/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy" >}}
这也避免在 zh-cn 页面中意外跳转到英文页面。
-设计请参考[文档](/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy) +设计请参考[文档]({{< relref "/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy" >}})
17-21: Step numbering nit: start from 1 for consistency当前从“0.”开始，后续为“1./2./3.”，读者可能误解为先决条件之外的步骤。建议统一从“1.”开始或将“0.”改为“前置条件”小节标题。
22-24: Pinning cert-manager is fine; add readiness wait to avoid race conditions安装后立即创建 ClusterIssuer/Certificate 可能在 CRDs/控制器未就绪时失败。建议加入等待命令。
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.18.2/cert-manager.yaml +kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=120s +kubectl -n cert-manager rollout status deploy/cert-manager --timeout=120s +kubectl -n cert-manager rollout status deploy/cert-manager-cainjector --timeout=120s
98-116: Service: explicitly set targetPort for kubelet-proxy; keep labels consistent为 kubelet-proxy 端口显式声明 targetPort，可读性更好；同时可考虑补充标准化 app.kubernetes.io 标签（可选）。
- name: kubelet-proxy # Kubelet 代理端口，与 ModuleController ENV 中的 KUBELET_PROXY_PORT 保持一致 port: 10250 + targetPort: 10250
168-177: Validation precheck: advise confirming SA/RBAC and Service selector在验证前，建议先检查：
- SA 与 ClusterRoleBinding 是否存在且命名空间匹配
- Service selector 是否能选中 module-controller Pod
添加两条 kubectl 命令可帮助快速自检。kubectl get sa/virtual-kubelet -n default kubectl get clusterrolebinding virtual-kubelet-binding kubectl get endpoints module-controller -n default
179-186: Include namespace in kubectl logs and add failure triage hints建议补充 -n <命名空间> 参数，避免因默认命名空间不同导致的困惑；同时给出失败时的排查要点。
-kubectl logs --tail=50 biz1-web-single-host-786dfc476f-qsp7q +kubectl logs -n default --tail=50 biz1-web-single-host-786dfc476f-qsp7q +# 若失败，建议排查： +# 1) module-controller 日志中是否有 kubelet-proxy 启动与监听端口日志 +# 2) TLS Secret 是否已挂载到容器预期路径 +# 3) Service/Endpoints 是否指向 module-controller Pod +# 4) RBAC 是否正确绑定至 ServiceAccount
98-116: Optional hardening: restrict kubelet-proxy port exposure via NetworkPolicy为减少攻击面，可限制至 namespace 内部或仅允许运维入口访问 10250 端口（具体依据集群 CNI/部署拓扑调整）。
apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: allow-kubelet-proxy-internal namespace: default spec: podSelector: matchLabels: app: module-controller policyTypes: ["Ingress"] ingress: - ports: - port: 10250 from: - namespaceSelector: matchLabels: kubernetes.io/metadata.name: default # 如需仅允许特定 Pod/命名空间，请按需收窄
8-12: Terminology consistency: “Kubernetes” vs “K8s” and spacing around English terms全文中同时出现“K8s”“Kubernetes”，建议在同一文档内统一术语；同时中英文之间保留空格，如 “Kubernetes 插件”、“Module Controller V2”。
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (1)
static/img/module-controller-v2/kubelet_proxy_sequence_diagram.pngis excluded by!**/*.png
📒 Files selected for processing (6)
content/en/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md(1 hunks)content/en/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md(1 hunks)content/en/docs/tutorials/module-operation-v2/module-controller-deployment.md(1 hunks)content/zh-cn/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md(1 hunks)content/zh-cn/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md(1 hunks)content/zh-cn/docs/tutorials/module-operation-v2/module-controller-deployment.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
content/zh-cn/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md
14-14: Images should have alternate text (alt text)
(MD045, no-alt-text)
content/en/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md
15-15: Images should have alternate text (alt text)
(MD045, no-alt-text)
🪛 LanguageTool
content/en/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md
[grammar] ~11-~11: There might be a mistake here.
Context: ...ontroller V2 using the kubectl tool, providing an operational experience simi...
(QB_NEW_EN)
[grammar] ~14-~14: There might be a mistake here.
Context: ...et. For design details, please refer to the [documentation](/docs/contribution-g...
(QB_NEW_EN)
[grammar] ~21-~21: There might be a mistake here.
Context: ...certificates used for the Kubelet Proxy. Please refer to the [cert-manager docume...
(QB_NEW_EN)
[grammar] ~23-~23: There might be a mistake here.
Context: ...tion/) for installation instructions. Here is a simple installation example (v...
(QB_NEW_EN)
[grammar] ~176-~176: There might be a mistake here.
Context: ...odule Controller has enabled the Kubelet Proxy. ``` NAME ...
(QB_NEW_EN)
content/en/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md
[grammar] ~11-~11: There might be a mistake here.
Context: ...ontroller V2 using the kubectl tool, providing an operational experience simi...
(QB_NEW_EN)
🔇 Additional comments (6)
content/zh-cn/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md (1)
14-15: Image asset verified
The referenced image/img/module-controller-v2/kubelet_proxy_sequence_diagram.pngis present atstatic/img/module-controller-v2/kubelet_proxy_sequence_diagram.png. No further changes are needed.content/en/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md (1)
15-15: Image asset verified
The image filekubelet_proxy_sequence_diagram.pngis present atstatic/img/module-controller-v2/kubelet_proxy_sequence_diagram.png. No further action needed.content/zh-cn/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md (4)
2-6: Title/weight look fine; verify section numbering alignment with sidebar ordering“5.7”与
weight: 1100看起来合理，但请确认在同目录下的其它文档权重与编号规则一致，避免侧边栏排序与前缀编号不一致。
60-71: LGTM: Secret validation step is clear该检查步骤直观明了，有助于快速判断证书是否就绪。
148-153: Container ports look consistent; OK端口与 Service 映射一致；读者若禁用 HTTP 管道，已注明可移除 7777 端口，说明清晰。
162-166: Clarify expected cert/key filenames or envs挂载 TLS Secret 时，通常文件名为 tls.crt 与 tls.key。若 ModuleController 需要非默认路径或文件名，请在文档中明确（或提供相应 ENV/参数示例），减少对读者的猜测。
content/en/docs/contribution-guidelines/module-controller-v2/virtual-kubelet-proxy.md
Show resolved
Hide resolved
content/en/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md
Show resolved
Hide resolved
content/en/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md
Show resolved
Hide resolved
content/zh-cn/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md
Show resolved
Hide resolved
content/zh-cn/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md
Show resolved
Hide resolved
content/zh-cn/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md
Show resolved
Hide resolved
content/zh-cn/docs/tutorials/module-operation-v2/enable-virtual-kubelet-proxy.md
Show resolved
Hide resolved
2 participants
Module Controller v2 kubelet proxy 相关的文档，代码部分见：koupleless/module-controller#42
Summary by CodeRabbit