记一次被文档bug所坑的经历

发表于:2020-7-23 10:48  作者:肖哥shelwin   来源:测试不将就

字体: | 上一篇 | 下一篇 |我要投稿 | 推荐标签: Bug 缺陷管理

  最近碰到一个需求,希望在docker容器里支持IPv6网络。一开始,我觉得这个需求应该十分简单。毕竟,通过执行ip addr show命令,可以查看到宿主机的所有网络接口同时拥有IPv4和IPv6地址,也就是说宿主机是支持IPv6的。
  作为寄生在宿主机上的docker容器,会不会天然就支持存在很久并非什么新鲜事物的IPv6呢?于是,我基于某个docker镜像创建一个docker容器,进入容器后,执行ip addr show命令。结果令人失望,容器只有IPv4地址,没有IPv6地址。
  难道是我的docker安装和配置有问题吗?本地尝试了一些办法,没有效果。于是通过google搜索,看了一些文章之后,发现一个重要线索,那就是docker默认只支持IPv4,如果要支持IPv6,需要进行手动配置。
  果真如此吗?如何通过命令查看docker是支持IPv4还是IPv6呢?进一步了解到,docker安装之后会创建三种名称分别为bridge/host/none的网络。在创建容器时,默认会使用bridge网络。于是,执行命令docker network inspect bridge,可以看到默认创建的bridge网络的IPv6确实处于disable状态。
   root@shelwin:~# docker network inspect bridge
  ......
  "Name": "bridge",
  "EnableIPv6": false,
  .......
  看来,现在我面临的问题非常具体,那就是打开IPv6控制开关,让docker支持IPv6。似乎比较幸运的是,官方文档https://docs.docker.com/config/daemon/ipv6/提供了十分简单的操作指南:编辑docker守护进程配置文件/etc/docker/ daemon.json,将ipv6的值设置为true,然后执行命令service docker restart重启docker守护进程即可。
   {
  "ipv6": true
  }
  没想到的是,按照官方指南一步步操作之后,问题不仅没有解决,反而变得更糟:docker直接就启动失败了。查看docker启动日志,发现docker在启动守护进程时创建默认bridge网络阶段失败了,原因是"could not find an available, non-overlapping IPv6 address pool among the defaults to assign to the network"。意思是说,无法为bridge网络找到一个可用的IPv6地址。
  怎么办呢?只能再次求助于google。在排除了一些无关信息之后,最后找到一个github issue: https:// github.com/moby/moby/issues/36954,报的是同样的问题。阅读大家的讨论,可以看到官方文档提供的使能IPv6的操作指南是错误的,文档竟然存在bug。许多人都遇到了这个问题,而我也不幸中枪。
  正确的配置方法是为配置文件/etc/docker /daemon.json增加一个参数fixed-cidr-v6,为容器指定一个可以选择全局IPv6地址的IPv6子网。然后,重启docker守护进程。docker成功启动,并且宿主机的IPv6地址和docker容器的IPv6地址都是正常的,问题解决。
   {
  "ipv6": true,
  "fixed-cidr-v6": "fe80::42:e0ff:fe36:174c/64"
  }
  为什么docker在配置IPv6时,一定要指定参数fixed-cidr-v6呢?有人认为这是docker的一个bug,吐槽都9102年,docker还不能完美支持IPv6。当然,这是另外一个话题。在docker已经存在这个限制的情况下,官方文档确实没有反映实际情况。所幸的是,修复文档的提交已经准备好了: https://github.com/docker/ docker.github.io/pull/8292。相信在不久的将来,正确的docker文档能够跟开发者见面。
  为docker容器配置IPv6地址,这看起来是一个很小的需求,却一波三折,甚至花费了我差不多半天的工作时间。这个过程,有什么值得总结的呢?通过复盘,我有三点体会。
  一是要高度重视文档质量。代码是写给机器执行的,而文档是写给读者阅读的。技术文档直接面向广大开发者,并且开发者对文档的依赖性强,信任度高。一个有bug的文档,会给开发者带来很大麻烦。
  那么,如何提升文档质量呢?文档不像代码,可以设计和实现各种各样的测试用例去发现潜在的bug。在我看来,提升文档质量主要的手段是评审(review),尤其是熟悉同一领域的同事或同行的评审。在学术界,所有论文都要经过一轮甚至几轮的同行评议(peer review),技术文档应该采取类似的方法。
  二是针对不同的技术问题,要采用不同的搜索策略。解决任何技术问题,总是离不开搜索引擎的。对于操作指南,例如如何为docker容器配置IPv6,搜索对象应该是关键词的组合,例如docker + ipv6;对于具体的报错,搜索对象应该是最底层异常所提示的错误消息。
  例如上文中docker启动失败时,抛出了docker守护进程启动错误->网络控制器初始化错误->创建默认bridge网络错误->无法为bridge网络找到一个可用的IPv6地址等4个异常,显然最后一个异常是最底层也是最具体的,应该是我们首选的搜索对象。
  三是在解决技术问题时要聚焦,而不要发散。在解决docker配置IPv6问题的过程中,我脑中产生了许多疑问,什么是IPv6地址?什么是docker守护进程?什么是IPv6子网?什么是docker网络?这些抽象的概念非常重要,也与要解决的问题密切相关。
  但是,学习它们需要耗费时间,而我的当务之急是解决问题。因此,应该把这些疑问先搁置,聚焦在如何打开docker的IPv6开关上,并寻找行之有效的具体操作方法。先把问题解决,然后在有时间和余力前提下,再去学习背后的原理。

      本文内容不用于商业目的,如涉及知识产权问题,请权利人联系博为峰小编(021-64471599-8017),我们将立即处理

评 论

论坛新帖

顶部 底部


建议使用IE 6.0以上浏览器,800×600以上分辨率,法律顾问:上海瀛东律师事务所 张楠律师
版权所有 上海博为峰软件技术股份有限公司 Copyright©51testing.com 2003-2020, 沪ICP备05003035号
投诉及意见反馈:webmaster@51testing.com; 业务联系:service@51testing.com 021-64471599-8017

沪公网安备 31010102002173号

51Testing官方微信

51Testing官方微博

扫一扫 测试知识全知道