docs: add doc for ib-kubernetes and ufm #3673
Conversation
cyclinder
force-pushed
the
docs/ib-kubernetes
branch
2 times, most recently
from
c69e8ed
to
7541f19
Compare
|
(1) 所有内容 整合到 rmda-ib.md 中，作为 Infiniband 场景下 IB-SRIOV CNI 的 可选安装部分 |
cyclinder
force-pushed
the
docs/ib-kubernetes
branch
from
7541f19
to
357f3b8
Compare
docs/usage/rdma-ib.md
Outdated
| @@ -215,6 +215,8 @@ The following steps demonstrate how to use [IB-SRIOV](https://github.com/k8snetw | |||
| # succeed to visit the service on the other POD | |||
| ~# ib_read_lat 172.91.0.115 | |||
|
|
|||
| 7. Subnet management can be implemented in combination with IB-Kubernetz and UFM, refer to the document [UFM and IB-Kubernetes](./ib-kubernetes.md). | |||
There was a problem hiding this comment.
我建议是直接把所有内容（其中也需要 安装 spiderpool 什么的了 ） 弄到 这个 md 中的 一个 二级标题 ，不需要单独一个 md
There was a problem hiding this comment.
这样显得原文太冗长了，本身这是可选项
There was a problem hiding this comment.
它们是非常紧密的，没关系，拆开了反而会影响一些小白 搞不清 章节关系和场景 ，它们并不能像我们一样 能够弄明白 ，并且你也因此不需要再双方两个 md 之间 交代这么多上下文关系 和 安装要求 。其它文章 五六百行 都比这个 长
可以往这个 md 最后 加一个 二级标题 新启
There was a problem hiding this comment.
理性讨论：感觉有点反了，反而是小白更不会去关注ib-kubernetes他也不懂，如果他不是小白，那他可能会去点击一下了解更多，因为是小白不懂 ib-kubernetes 的可能更大，所以默认隐藏比较好。
也因此不需要再双方两个 md 之间 交代这么多上下文关系 和 安装要求
另一个md 已经基本没有额外的安装要求了，如果有，可删减
There was a problem hiding this comment.
这里的小白是指 不熟悉 spiderpool 或者 不熟悉 spiderpool 文档编排的人，并不是 他不懂 Infiniband ，反而 ufm 是 Infiniband 用户重要的组件
（1）并不希望 有多个 md 同时 讨论 Infiniband， 我作为 用户，我希望 章节编排是清晰的 。 因为这个md 是关于 Infiniband 话题的所有内容，ib-kubernetes 是这个大块下的一个子内容。 清晰的章节编排，统一的 Infiniband 入口，很有利于用户找内容。
（2） 就目前的 [ib-kubernetes-zh_CN.md] ，并不能独自闭环它的使用，只是说明了安装。 例如，没有 使用前的 安装依赖说明，务必是 Infiniband 网络，如何检测主机是否有 Infiniband 网卡 ，是否能运行 sriov ； 它没有 运行 pod 的验证 ；得写重复安装 ib-sriov 配置等内容。。。。 这些种种，可以和本md 的 sriov 进行 内容和步骤复用 ，本身 它们就是一个 Infiniband 网络的 完整方案。这样的编排可降低后续 文档 维护成本，避免双份 不同步 ， 或者需要修改两边
我希望 本md 在 sriov 操作步骤中，其中 的一个步骤 插入 ， 跳转 到 本md 尾部 的 ib-kubernetes 二级标题，完成 ib-kubernetes 的安装。而后继续 走 sriov 的步骤 ，一起完成 双方的相互依赖和验证
（3）原文太冗长了 并不站得住脚 -- 你可以提出另一外有说服力的原因
There was a problem hiding this comment.
并不希望 有多个 md 同时 讨论 Infiniband， 我作为 用户，我希望 章节编排是清晰的 。 因为这个md 是关于 Infiniband 话题的所有内容，ib-kubernetes 是这个大块下的一个子内容。 清晰的章节编排，统一的 Infiniband 入口，很有利于用户找内容。
多个 md 讨论 Infiniband 章节编排同样是清晰的，因为入口只有一个，此文档只是作为 Infiniband 文档的一个跳转。此文档着重将 ib-kuebrnetes 本身以及与 ib-sriov-cni 的联动。另外我认为 ib-kubernetes 和 ufm 跟 rdma-ib.md 关联性没有那么大，更像是一个高级操作。
就目前的 [ib-kubernetes-zh_CN.md] ，并不能独自闭环它的使用，只是说明了安装。 例如，没有 使用前的 安装依赖说明，务必是 Infiniband 网络，如何检测主机是否有 Infiniband 网卡 ，是否能运行 sriov ； 它没有 运行 pod 的验证 ；得写重复安装 ib-sriov 配置等内容。。。。 这些种种，可以和本md 的 sriov 进行 内容和步骤复用 ，本身 它们就是一个 Infiniband 网络的 完整方案。这样的编排可降低后续 文档 维护成本，避免双份 不同步 ， 或者需要修改两边
这篇文档的入口是 rdma-ib.md，所以是可以复用 rdma-ib.md 中的各种安装操作，将来有 Infiniband 环境文档的更新，只需要更新 rdma-ib.md 即可，并不会带来维护成本。
原文太冗长了 并不站得住脚 -- 你可以提出另一外有说服力的原因
可能描述不够准确，我的想法：本身知道 ib 网络的人就比较少，还了解 ib-kubernetes 和 ufm 的人更少之又少。把 ib-kubernetes 和 ufm 放进同篇md，有大概 300 行的知识盲区，对于小白来说是很影响阅读体验的。而对于小部分知道 ib-kubernetes 和 ufm 或者 想要了解 的人，那你自己点一下链接看就好。
这就好像做菜教程，不会把每道菜的详细做法在一个文档放出来，而是一个菜名一个链接，你想要了解那就跳转，不想了解就推出，我不会强制把所有内容都在一个文档去闭环。
cyclinder
force-pushed
the
docs/ib-kubernetes
branch
4 times, most recently
from
43f48a8
to
3238236
Compare
docs/usage/rdma-ib-zh_CN.md
Outdated
| @@ -217,6 +217,8 @@ | |||
| # 成功访问对方 Pod 的 RDMA 服务 | |||
| ~# ib_read_lat 172.91.0.115 | |||
|
|
|||
| 7. 可结合 ib-kubernetes 与 UFM 完成 Infiniband 子网管理功能，参考章节 [UFM 和 IB-Kubernetes](#使用-ib-kubernetes-和-ufm-实现-infiniband-网络管理)。 | |||
There was a problem hiding this comment.
建议加一些如下表达，会让运维更加清晰
【可选】对于具备 UFM 管理平台的环境，可..... ； 对于不具备 UFM 管理平台的环境，可忽略本步骤
signed-off-by: cyclinder <qifeng.guo@daocloud.io>
cyclinder
force-pushed
the
docs/ib-kubernetes
branch
from
3238236
to
19b078f
Compare
|
@cyclinder need cherry pick |
Thanks for contributing!
What type of PR is this?
What this PR does / why we need it:
docs: add doc for ib-kubernetes and ufm
Which issue(s) this PR fixes:
Fixes #
Special notes for your reviewer: