Kubernetes 文档

本仓库包含了所有用于构建 Kubernetes 网站和文档的软件资产。我们非常高兴你想要参与贡献！

为文档做贡献
README 本地化

使用这个仓库

可以使用 Hugo（扩展版）在本地运行网站，也可以在容器中运行它。强烈建议使用容器，因为这样可以和在线网站的部署保持一致。

前提条件

使用这个仓库，需要在本地安装以下软件：

npm
Go
Hugo（Extended 版本）
容器运行时，比如 Docker。

开始前，先安装这些依赖。克隆本仓库并进入对应目录：

git clone https://github.com/kubernetes/website.git
cd website

Kubernetes 网站使用的是 Docsy Hugo 主题。即使你打算在容器中运行网站，我们也强烈建议你通过运行以下命令来引入子模块和其他开发依赖项：

Windows

# 获取子模块依赖
git submodule update --init --recursive --depth 1

Linux / 其它 Unix

# 获取子模块依赖
make module-init

在容器中运行网站

要在容器中构建网站，请运行以下命令：

# 你可以将 $CONTAINER_ENGINE 设置为任何 Docker 类容器工具的名称
make container-serve

如果你看到错误，这可能意味着 Hugo 容器没有足够的可用计算资源。要解决这个问题，请增加机器（MacOS 和 Windows）上 Docker 允许的 CPU 和内存使用量。

启动浏览器，打开 http://localhost:1313 来查看网站。当你对源文件作出修改时，Hugo 会更新网站并强制浏览器执行刷新操作。

在本地使用 Hugo 来运行网站

请确保安装的是 netlify.toml 文件中环境变量 HUGO_VERSION 所指定的 Hugo Extended 版本。

若要在本地安装依赖，构建和测试网站，运行以下命令：

对于 macOS 和 Linux
```
npm ci
make serve
```

对于 Windows (PowerShell)

npm ci
hugo.exe server --buildFuture --environment development

上述命令会在端口 1313 上启动本地 Hugo 服务器。启动浏览器，打开 http://localhost:1313 来查看网站。当你对源文件作出修改时，Hugo 会更新网站并强制浏览器执行刷新操作。

构建 API 参考页面

位于 content/en/docs/reference/kubernetes-api 的 API 参考页面是使用 https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs 根据 Swagger 规范（也称为 OpenAPI 规范）构建的。

要更新 Kubernetes 新版本的参考页面，请执行以下步骤：

拉取 api-ref-generator 子模块：

git submodule update --init --recursive --depth 1

更新 Swagger 规范：

curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json

在 api-ref-assets/config/ 中，调整文件 toc.yaml 和 fields.yaml 以反映新版本的变化。

接下来，构建页面：
```
make api-reference
```
你可以通过从容器镜像创建和提供站点来在本地测试结果：
```
make container-image
make container-serve
```
在 Web 浏览器中，打开 http://localhost:1313/docs/reference/kubernetes-api/ 查看 API 参考页面。

当所有新的更改都反映到配置文件 toc.yaml 和 fields.yaml 中时，使用新生成的 API 参考页面创建一个 Pull Request。

故障排除

error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version

由于技术原因，Hugo 会发布两套二进制文件。当前网站仅基于 Hugo Extended 版本运行。在发布页面中查找名称为 extended 的归档。可以运行 hugo version 查看是否有单词 extended 来确认。

对 macOS 上打开太多文件的故障排除

如果在 macOS 上运行 make serve 收到以下错误：

ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files
make: *** [serve] Error 1

试着查看一下当前打开文件数的限制：

launchctl limit maxfiles

然后运行以下命令（参考 https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c）：

#!/bin/sh

# 这些是原始的 gist 链接，现在则会链接到我的 gist
# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist
# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist

curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist
curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist

sudo mv limit.maxfiles.plist /Library/LaunchDaemons
sudo mv limit.maxproc.plist /Library/LaunchDaemons

sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist

sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist

这适用于 Catalina 和 Mojave macOS。

对执行 make container-image 命令部分地区访问超时的故障排除

现象如下：

langs/language.go:23:2: golang.org/x/text@v0.3.7: Get "https://proxy.golang.org/golang.org/x/text/@v/v0.3.7.zip": dial tcp 142.251.43.17:443: i/o timeout
langs/language.go:24:2: golang.org/x/text@v0.3.7: Get "https://proxy.golang.org/golang.org/x/text/@v/v0.3.7.zip": dial tcp 142.251.43.17:443: i/o timeout
common/text/transform.go:21:2: golang.org/x/text@v0.3.7: Get "https://proxy.golang.org/golang.org/x/text/@v/v0.3.7.zip": dial tcp 142.251.43.17:443: i/o timeout
common/text/transform.go:22:2: golang.org/x/text@v0.3.7: Get "https://proxy.golang.org/golang.org/x/text/@v/v0.3.7.zip": dial tcp 142.251.43.17:443: i/o timeout
common/text/transform.go:23:2: golang.org/x/text@v0.3.7: Get "https://proxy.golang.org/golang.org/x/text/@v/v0.3.7.zip": dial tcp 142.251.43.17:443: i/o timeout
hugolib/integrationtest_builder.go:29:2: golang.org/x/tools@v0.1.11: Get "https://proxy.golang.org/golang.org/x/tools/@v/v0.1.11.zip": dial tcp 142.251.42.241:443: i/o timeout
deploy/google.go:24:2: google.golang.org/api@v0.76.0: Get "https://proxy.golang.org/google.golang.org/api/@v/v0.76.0.zip": dial tcp 142.251.43.17:443: i/o timeout
parser/metadecoders/decoder.go:32:2: gopkg.in/yaml.v2@v2.4.0: Get "https://proxy.golang.org/gopkg.in/yaml.v2/@v/v2.4.0.zip": dial tcp 142.251.42.241:443: i/o timeout
The command '/bin/sh -c mkdir $HOME/src &&     cd $HOME/src &&     curl -L https://github.com/gohugoio/hugo/archive/refs/tags/v${HUGO_VERSION}.tar.gz | tar -xz &&     cd "hugo-${HUGO_VERS    ION}" &&     go install --tags extended' returned a non-zero code: 1
make: *** [Makefile:69：container-image] error 1

请修改 Dockerfile 文件，为其添加网络代理。修改内容如下：

...
FROM golang:1.18-alpine

LABEL maintainer="Luc Perkins <lperkins@linuxfoundation.org>"

ENV GO111MODULE=on                            # 需要添加内容1

ENV GOPROXY=https://proxy.golang.org,direct   # 需要添加内容2

RUN apk add --no-cache \
    curl \
    gcc \
    g++ \
    musl-dev \
    build-base \
    libc6-compat

ARG HUGO_VERSION
...

将 "https://proxy.golang.org" 替换为本地可以使用的代理地址。

注意： 此部分仅适用于中国大陆。

参与 SIG Docs 工作

通过社区页面进一步了解 SIG Docs Kubernetes 社区和会议信息。

你也可以通过以下渠道联系本项目的维护人员：

为文档做贡献

你也可以点击屏幕右上方区域的 Fork 按钮，在你自己的 GitHub 账号下创建本仓库的拷贝。此拷贝被称作 fork。你可以在自己的拷贝中任意地修改文档，并在你已准备好将所作修改提交给我们时，在你自己的拷贝下创建一个拉取请求（Pull Request），以便让我们知道。

一旦你创建了拉取请求，某个 Kubernetes 评审人会负责提供明确的、可执行的反馈意见。作为拉取请求的拥有者，修改拉取请求以解决 Kubernetes 评审人所提出的反馈是你的责任。

还要提醒的一点，有时可能会有不止一个 Kubernetes 评审人为你提供反馈意见。有时候，某个评审人的意见和另一个最初被指派的评审人的意见不同。

另外在某些时候，某个评审人可能会在需要的时候请求一名 Kubernetes 技术评审人来执行技术评审。这些评审人会尽力及时地提供反馈意见，不过具体的响应时间可能会因时而异。

有关为 Kubernetes 文档做出贡献的更多信息，请参阅：

新贡献者大使

如果你在贡献时需要帮助，新贡献者大使是一个很好的联系人。这些是 SIG Docs 批准者，其职责包括指导新贡献者并帮助他们完成最初的几个拉取请求。联系新贡献者大使的最佳地点是 Kubernetes Slack。 SIG Docs 的当前新贡献者大使：

姓名	Slack	GitHub
Sreeram Venkitesh	@sreeram.venkitesh	@sreeram-venkitesh

中文本地化

可以通过以下方式联系中文本地化的维护人员：

行为准则

参与 Kubernetes 社区受 CNCF 行为准则约束。

感谢你

Kubernetes 因为社区的参与而蓬勃发展，感谢你对我们网站和文档的贡献！