记编译部署k8s官方离线文档

记编译/部署k8s官方离线文档

在线查看文档实在是太慢了，文档之间往往有相互链接引用，有时候看到一个术语链接，跳过去等半天，以至于内容加载完后都忘了想看什么了。正好看到k8s提供离线文档，也给出了本地运行网站的说明，索性就部署一个本地网站

部署

按照官方文档，使用容器方式运行，确保本地安装了docker desktop，并启动

git clone https://github.com/kubernetes/website.git
cd website
git submodule update --init --recursive --depth 1
# 生成docker镜像
make container-image
# 启动容器，容器内hugo编译并发布网站
make container-serve

问题排查

前面四步除了make container-image需要编译容器镜像，执行时间会比较长外，没有出现任何状况，最后一步开始出现问题。

超时

执行make container-serve出现了如下报错

$ make container-serve
docker run --rm --interactive --tty --volume /Users/myusername/code/web/kubernetes:/src --cap-drop=ALL --cap-add=AUDIT_WRITE --read-only --mount type=tmpfs,destination=/tmp,tmpfs-mode=01777 -p 1313:1313 gcr.io/k8s-staging-sig-docs/k8s-website-hugo:v0.87.0-5a5aca60359e hugo server --buildFuture --bind 0.0.0.0 --destination /tmp/hugo --cleanDestinationDir
Start building sites …
hugo v0.87.0-B0C541E4+extended linux/amd64 BuildDate=2021-08-03T10:57:28Z VendorInfo=gohugoio
WARN 2021/10/26 13:05:10 Page.URL is deprecated and will be removed in a future release. Use .Permalink or .RelPermalink. If what you want is the front matter URL value, use .Params.url
Error: Error building site: "/src/content/fr/docs/concepts/cluster-administration/logging.md:1:1": timed out initializing value. You may have a circular loop in a shortcode, or your site may have resources that take longer to build than the `timeout` limit in your Hugo config file.
Built in 385321 ms
make: *** [container-serve] Error 255

原因

这个是由于hugo的配置中，指定的超时时间太短导致的。k8s网站较大，编译耗费的时间较长，所以触发了超时。

解法

到website目录下，打开config.toml，把timeout时间修改为60000或更大并保存。

空间不足

再次执行make container-serve，报如下错误

$ make container-serve
docker run --rm --interactive --tty --volume /Users/myusername/code/web/kubernetes:/src --cap-drop=ALL --cap-add=AUDIT_WRITE --read-only --mount type=tmpfs,destination=/tmp,tmpfs-mode=01777 -p 1313:1313 gcr.io/k8s-staging-sig-docs/k8s-website-hugo:v0.87.0-5a5aca60359e hugo server --buildFuture --bind 0.0.0.0 --destination /tmp/hugo --cleanDestinationDir
Start building sites …
hugo v0.87.0-B0C541E4+extended linux/amd64 BuildDate=2021-08-03T10:57:28Z VendorInfo=gohugoio
WARN 2021/10/27 05:57:56 Page.URL is deprecated and will be removed in a future release. Use .Permalink or .RelPermalink. If what you want is the front matter URL value, use .Params.url
ERROR 2021/10/27 06:12:10 write /tmp/hugo/es/docs/concepts/workloads/controllers/_print/index.html: no space left on device
ERROR 2021/10/27 06:12:10 write /tmp/hugo/es/docs/concepts/workloads/pods/_print/index.html: no space left on device
ERROR 2021/10/27 06:12:10 write /tmp/hugo/es/docs/contribute/_print/index.html: no space left on device
ERROR 2021/10/27 06:12:10 write /tmp/hugo/es/docs/contribute/style/_print/index.html: no space left on device
Error: Error building site: failed to render pages: write /tmp/hugo/es/docs/concepts/workloads/_print/index.html: no space left on device
Built in 915380 ms
make: *** [container-serve] Error 255

提示空间不足

原因

查看报错中的docker命令，hugo编译的生成内容保存在容器内的/tmp/hugo目录，而这个目录的mount类型是内存文件系统（type=tmpfs），根据Use tmpfs mounts这个文档的描述，当指定mount类型为tmpfs时，容器会将内存当做磁盘来使用的。
所以可以推断，上面的报错是由于内存空间不足导致的。

解法

打开docker desktop dashboard，找到配置中Resource页面，默认情况下Memory是2GB，我调整到了4GB，随后应用并重启docker deamon。

再次执行make container-serve，网站编译启动正常，可以访问localhost:1313查看文档了。

后台执行

默认情况下make container-serve执行完毕后，会一只停留在terminal上，因为docker不是以守护状态执行的。可以ctrl+c停止当前容器，由于在Makefile中docker命令制定了–rm参数，所以容器直接被销毁。
若要以后台服务方式运行，拷贝上面示例中的docker命令，增加-d参数即可。

$ docker run -d --rm --interactive --tty --volume /Users/myusername/code/web/kubernetes:/src --cap-drop=ALL --cap-add=AUDIT_WRITE --read-only --mount type=tmpfs,destination=/tmp,tmpfs-mode=01777 -p 1313:1313 gcr.io/k8s-staging-sig-docs/k8s-website-hugo:v0.87.0-5a5aca60359e hugo server --buildFuture --bind 0.0.0.0 --destination /tmp/hugo --cleanDestinationDir

执行后使用docker logs -f查看日志，直到出现

Web Server is available at http://localhost:1313/ (bind address 0.0.0.0)

就可以正常访问网站了。

结尾

部署了离线文档后，查文档速度直接起飞，所以又把docker网站也部署了，真香