resolving conflicts
This commit is contained in:
Savitha Raghunathan
@@ -0,0 +1,181 @@
|
||||
---
|
||||
title: 控制面到节点通信
|
||||
content_type: concept
|
||||
weight: 20
|
||||
---
|
||||
|
||||
<!--
|
||||
reviewers:
|
||||
- dchen1107
|
||||
- liggitt
|
||||
title: Control Plane-Node Communication
|
||||
content_type: concept
|
||||
weight: 20
|
||||
aliases:
|
||||
- master-node-communication
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This document catalogs the communication paths between the control plane (really the apiserver) and the Kubernetes cluster. The intent is to allow users to customize their installation to harden the network configuration such that the cluster can be run on an untrusted network (or on fully public IPs on a cloud provider).
|
||||
-->
|
||||
|
||||
本文对控制面节点（确切说是 apiserver）和 Kubernetes 集群之间的通信路径进行了分类。
|
||||
目的是为了让用户能够自定义他们的安装，以实现对网络配置的加固，使得集群能够在不可信的网络上
|
||||
（或者在一个云服务商完全公开的 IP 上）运行。
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
## Node to Control Plane
|
||||
Kubernetes has a "hub-and-spoke" API pattern. All API usage from nodes (or the pods they run) terminate at the apiserver (none of the other control plane components are designed to expose remote services). The apiserver is configured to listen for remote connections on a secure HTTPS port (typically 443) with one or more forms of client [authentication](/docs/reference/access-authn-authz/authentication/) enabled.
|
||||
One or more forms of [authorization](/docs/reference/access-authn-authz/authorization/) should be enabled, especially if [anonymous requests](/docs/reference/access-authn-authz/authentication/#anonymous-requests) or [service account tokens](/docs/reference/access-authn-authz/authentication/#service-account-tokens) are allowed.
|
||||
-->
|
||||
|
||||
## 节点到控制面
|
||||
|
||||
Kubernetes 采用的是中心辐射型（Hub-and-Spoke）API 模式。
|
||||
所有从集群（或所运行的 Pods）发出的 API 调用都终止于 apiserver（其它控制面组件都没有被设计为可暴露远程服务）。
|
||||
apiserver 被配置为在一个安全的 HTTPS 端口（443）上监听远程连接请求，
|
||||
并启用一种或多种形式的客户端[身份认证](/docs/reference/access-authn-authz/authentication/)机制。
|
||||
一种或多种客户端[鉴权机制](/docs/reference/access-authn-authz/authorization/)应该被启用，
|
||||
特别是在允许使用[匿名请求](/docs/reference/access-authn-autha/authentication/#anonymous-requests)
|
||||
或[服务账号令牌](/docs/reference/access-authn-authz/authentication/#service-account-tokens)的时候。
|
||||
|
||||
<!--
|
||||
Nodes should be provisioned with the public root certificate for the cluster such that they can connect securely to the apiserver along with valid client credentials. For example, on a default GKE deployment, the client credentials provided to the kubelet are in the form of a client certificate. See [kubelet TLS bootstrapping](/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/) for automated provisioning of kubelet client certificates.
|
||||
-->
|
||||
|
||||
应该使用集群的公共根证书开通节点，这样它们就能够基于有效的客户端凭据安全地连接 apiserver。
|
||||
例如：在一个默认的 GCE 部署中，客户端凭据以客户端证书的形式提供给 kubelet。
|
||||
请查看 [kubelet TLS 启动引导](/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/)
|
||||
以了解如何自动提供 kubelet 客户端证书。
|
||||
|
||||
<!--
|
||||
Pods that wish to connect to the apiserver can do so securely by leveraging a service account so that Kubernetes will automatically inject the public root certificate and a valid bearer token into the pod when it is instantiated.
|
||||
The `kubernetes` service (in all namespaces) is configured with a virtual IP address that is redirected (via kube-proxy) to the HTTPS endpoint on the apiserver.
|
||||
|
||||
The control plane components also communicate with the cluster apiserver over the secure port.
|
||||
-->
|
||||
|
||||
想要连接到 apiserver 的 Pod 可以使用服务账号安全地进行连接。
|
||||
当 Pod 被实例化时，Kubernetes 自动把公共根证书和一个有效的持有者令牌注入到 Pod 里。
|
||||
`kubernetes` 服务（位于所有名字空间中）配置了一个虚拟 IP 地址，用于（通过 kube-proxy）转发
|
||||
请求到 apiserver 的 HTTPS 末端。
|
||||
|
||||
控制面组件也通过安全端口与集群的 apiserver 通信。
|
||||
|
||||
<!--
|
||||
As a result, the default operating mode for connections from the nodes and pods running on the nodes to the control plane is secured by default and can run over untrusted and/or public networks.
|
||||
-->
|
||||
|
||||
这样，从集群节点和节点上运行的 Pod 到控制面的连接的缺省操作模式即是安全的，能够在不可信的网络或公网上运行。
|
||||
|
||||
<!--
|
||||
## Control Plane to node
|
||||
|
||||
There are two primary communication paths from the control plane (apiserver) to the nodes. The first is from the apiserver to the kubelet process which runs on each node in the cluster. The second is from the apiserver to any node, pod, or service through the apiserver's proxy functionality.
|
||||
-->
|
||||
|
||||
## 控制面到节点
|
||||
|
||||
从控制面（apiserver）到节点有两种主要的通信路径。
|
||||
第一种是从 apiserver 到集群中每个节点上运行的 kubelet 进程。
|
||||
第二种是从 apiserver 通过它的代理功能连接到任何节点、Pod 或者服务。
|
||||
|
||||
<!--
|
||||
### apiserver to kubelet
|
||||
|
||||
The connections from the apiserver to the kubelet are used for:
|
||||
|
||||
* Fetching logs for pods.
|
||||
* Attaching (through kubectl) to running pods.
|
||||
* Providing the kubelet's port-forwarding functionality.
|
||||
|
||||
These connections terminate at the kubelet's HTTPS endpoint. By default, the apiserver does not verify the kubelet's serving certificate, which makes the connection subject to man-in-the-middle attacks, and **unsafe** to run over untrusted and/or public networks.
|
||||
-->
|
||||
|
||||
### apiserver 到 kubelet
|
||||
|
||||
从 apiserver 到 kubelet 的连接用于：
|
||||
|
||||
* 获取 Pod 日志
|
||||
* 挂接（通过 kubectl）到运行中的 Pod
|
||||
* 提供 kubelet 的端口转发功能。
|
||||
|
||||
这些连接终止于 kubelet 的 HTTPS 末端。
|
||||
默认情况下，apiserver 不检查 kubelet 的服务证书。这使得此类连接容易受到中间人攻击，
|
||||
在非受信网络或公开网络上运行也是 **不安全的**。
|
||||
|
||||
<!--
|
||||
To verify this connection, use the `--kubelet-certificate-authority` flag to provide the apiserver with a root certificate bundle to use to verify the kubelet's serving certificate.
|
||||
|
||||
If that is not possible, use [SSH tunneling](/docs/concepts/architecture/master-node-communication/#ssh-tunnels) between the apiserver and kubelet if required to avoid connecting over an
|
||||
untrusted or public network.
|
||||
|
||||
Finally, [Kubelet authentication and/or authorization](/docs/admin/kubelet-authentication-authorization/) should be enabled to secure the kubelet API.
|
||||
-->
|
||||
|
||||
为了对这个连接进行认证，使用 `--kubelet-certificate-authority` 标志给 apiserver
|
||||
提供一个根证书包，用于 kubelet 的服务证书。
|
||||
|
||||
如果无法实现这点，又要求避免在非受信网络或公共网络上进行连接，可在 apiserver 和
|
||||
kubelet 之间使用 [SSH 隧道](#ssh-tunnels)。
|
||||
|
||||
最后，应该启用 [Kubelet 用户认证和/或鉴权](/docs/admin/kubelet-authentication-authorization/)来保护 kubelet API。
|
||||
|
||||
<!--
|
||||
### apiserver to nodes, pods, and services
|
||||
|
||||
The connections from the apiserver to a node, pod, or service default to plain HTTP connections and are therefore neither authenticated nor encrypted. They can be run over a secure HTTPS connection by prefixing `https:` to the node, pod, or service name in the API URL, but they will not validate the certificate provided by the HTTPS endpoint nor provide client credentials so while the connection will be encrypted, it will not provide any guarantees of integrity. These connections **are not currently safe** to run over untrusted and/or public networks.
|
||||
-->
|
||||
|
||||
### apiserver 到节点、Pod 和服务
|
||||
|
||||
从 apiserver 到节点、Pod 或服务的连接默认为纯 HTTP 方式，因此既没有认证，也没有加密。
|
||||
这些连接可通过给 API URL 中的节点、Pod 或服务名称添加前缀 `https:` 来运行在安全的 HTTPS 连接上。
|
||||
不过这些连接既不会验证 HTTPS 末端提供的证书，也不会提供客户端证书。
|
||||
因此，虽然连接是加密的，仍无法提供任何完整性保证。
|
||||
这些连接 **目前还不能安全地** 在非受信网络或公共网络上运行。
|
||||
|
||||
<!--
|
||||
### SSH tunnels
|
||||
|
||||
Kubernetes supports SSH tunnels to protect the control plane to nodes communication paths. In this configuration, the apiserver initiates an SSH tunnel to each node in the cluster (connecting to the ssh server listening on port 22) and passes all traffic destined for a kubelet, node, pod, or service through the tunnel.
|
||||
This tunnel ensures that the traffic is not exposed outside of the network in which the nodes are running.
|
||||
|
||||
SSH tunnels are currently deprecated so you shouldn't opt to use them unless you know what you are doing. The Konnectivity service is a replacement for this communication channel.
|
||||
-->
|
||||
|
||||
### SSH 隧道 {#ssh-tunnels}
|
||||
|
||||
Kubernetes 支持使用 SSH 隧道来保护从控制面到节点的通信路径。在这种配置下，apiserver
|
||||
建立一个到集群中各节点的 SSH 隧道（连接到在 22 端口监听的 SSH 服务）
|
||||
并通过这个隧道传输所有到 kubelet、节点、Pod 或服务的请求。
|
||||
这一隧道保证通信不会被暴露到集群节点所运行的网络之外。
|
||||
|
||||
SSH 隧道目前已被废弃。除非你了解个中细节，否则不应使用。
|
||||
Konnectivity 服务是对此通信通道的替代品。
|
||||
|
||||
<!--
|
||||
### Konnectivity service
|
||||
|
||||
{{< feature-state for_k8s_version="v1.18" state="beta" >}}
|
||||
|
||||
As a replacement to the SSH tunnels, the Konnectivity service provides TCP level proxy for the control plane to cluster communication. The Konnectivity service consists of two parts: the Konnectivity server and the Konnectivity agents, running in the control plane network and the nodes network respectively. The Konnectivity agents initiate connections to the Konnectivity server and maintain the network connections.
|
||||
After enabling the Konnectivity service, all control plane to nodes traffic goes through these connections.
|
||||
|
||||
Follow the [Konnectivity service task](/docs/tasks/extend-kubernetes/setup-konnectivity/) to set up the Konnectivity service in your cluster.
|
||||
-->
|
||||
|
||||
### Konnectivity 服务
|
||||
|
||||
{{< feature-state for_k8s_version="v1.18" state="beta" >}}
|
||||
|
||||
作为 SSH 隧道的替代方案，Konnectivity 服务提供 TCP 层的代理，以便支持从控制面到集群的通信。
|
||||
Konnectivity 服务包含两个部分：Konnectivity 服务器和 Konnectivity 代理，分别运行在
|
||||
控制面网络和节点网络中。Konnectivity 代理建立并维持到 Konnectivity 服务器的网络连接。
|
||||
启用 Konnectivity 服务之后，所有控制面到节点的通信都通过这些连接传输。
|
||||
|
||||
请浏览 [Konnectivity 服务任务](/docs/tasks/extend-kubernetes/setup-konnectivity/)
|
||||
在你的集群中配置 Konnectivity 服务。
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
approvers:
|
||||
- dchen1107
|
||||
- liggitt
|
||||
|
||||
title: Master 节点通信
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
|
||||
## 概览
|
||||
|
||||
|
||||
本文对 Master 节点（确切说是 apiserver）和 Kubernetes 集群之间的通信路径进行了分类。目的是为了让用户能够自定义他们的安装，对网络配置进行加固，使得集群能够在不可信的网络上（或者在一个云服务商完全公共的 IP 上）运行。
|
||||
|
||||
|
||||
## Cluster -> Master
|
||||
|
||||
|
||||
所有从集群到 master 的通信路径都终止于 apiserver（其它 master 组件没有被设计为可暴露远程服务）。在一个典型的部署中，apiserver 被配置为在一个安全的 HTTPS 端口（443）上监听远程连接并启用一种或多种形式的客户端[身份认证](/docs/admin/authentication/)机制。一种或多种客户端[身份认证](/docs/admin/authentication/)机制应该被启用，特别是在允许使用 [匿名请求](/docs/admin/authentication/#anonymous-requests) 或 [service account tokens](/docs/admin/authentication/#service-account-tokens) 的时候。
|
||||
|
||||
|
||||
应该使用集群的公共根证书开通节点，如此它们就能够基于有效的客户端凭据安全的连接 apiserver。例如：在一个默认的 GCE 部署中，客户端凭据以客户端证书的形式提供给 kubelet。请查看 [kubelet TLS bootstrapping](/docs/admin/kubelet-tls-bootstrapping/) 获取如何自动提供 kubelet 客户端证书。
|
||||
|
||||
|
||||
想要连接到 apiserver 的 Pods 可以使用一个 service account 安全的进行连接。这种情况下，当 Pods 被实例化时 Kubernetes 将自动的把公共根证书和一个有效的不记名令牌注入到 pod 里。`kubernetes` service （所有 namespaces 中）都配置了一个虚拟 IP 地址，用于转发（通过 kube-proxy）请求到 apiserver 的 HTTPS endpoint。
|
||||
|
||||
|
||||
Master 组件通过非安全（没有加密或认证）端口和集群的 apiserver 通信。这个端口通常只在 master 节点的 localhost 接口暴露，这样，所有在相同机器上运行的 master 组件就能和集群的 apiserver 通信。一段时间以后，master 组件将变为使用带身份认证和权限验证的安全端口（查看[#13598](https://github.com/kubernetes/kubernetes/issues/13598)）。
|
||||
|
||||
|
||||
这样的结果使得从集群（在节点上运行的 nodes 和 pods）到 master 的缺省连接操作模式默认被保护，能够在不可信或公网中运行。
|
||||
|
||||
|
||||
## Master -> Cluster
|
||||
|
||||
|
||||
从 master（apiserver）到集群有两种主要的通信路径。第一种是从 apiserver 到集群中每个节点上运行的 kubelet 进程。第二种是从 apiserver 通过它的代理功能到任何 node、pod 或者 service。
|
||||
|
||||
|
||||
## apiserver -> kubelet
|
||||
|
||||
|
||||
从 apiserver 到 kubelet 的连接用于获取 pods 日志、连接（通过 kubectl）运行中的 pods，以及使用 kubelet 的端口转发功能。这些连接终止于 kubelet 的 HTTPS endpoint。
|
||||
|
||||
|
||||
默认的，apiserver 不会验证 kubelet 的服务证书，这会导致连接遭到中间人攻击，因而在不可信或公共网络上是不安全的。
|
||||
|
||||
|
||||
为了对这个连接进行认证，请使用 `--kubelet-certificate-authority` 标记给 apiserver 提供一个根证书捆绑，用于 kubelet 的服务证书。
|
||||
|
||||
|
||||
如果这样不可能，又要求避免在不可信的或公共的网络上进行连接，请在 apiserver 和 kubelet 之间使用 [SSH 隧道](/docs/tasks/access-application-cluster/port-forward-access-application-cluster/)。
|
||||
|
||||
|
||||
最后，应该启用 [Kubelet 用户认证和/或权限认证](/docs/admin/kubelet-authentication-authorization/)来保护 kubelet API。
|
||||
|
||||
|
||||
## apiserver -> nodes, pods, and services
|
||||
|
||||
|
||||
从 apiserver 到 node、pod 或者 service 的连接默认为纯 HTTP 方式，因此既没有认证，也没有加密。他们能够通过给 API URL 中的 node、pod 或 service 名称添加前缀 `https:` 来运行在安全的 HTTPS 连接上。但他们即不会认证 HTTPS endpoint 提供的证书，也不会提供客户端证书。这样虽然连接是加密的，但它不会提供任何完整性保证。这些连接**目前还不能安全的**在不可信的或公共的网络上运行。
|
||||
|
||||
|
||||
## SSH 隧道
|
||||
|
||||
|
||||
[Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/) 使用 SSH 隧道保护 Master -> Cluster 通信路径。在这种配置下，apiserver 发起一个到集群中每个节点的 SSH 隧道（连接到在 22 端口监听的 ssh 服务）并通过这个隧道传输所有到 kubelet、node、pod 或者 service 的流量。这个隧道保证流量不会在集群运行的私有 GCE 网络之外暴露。
|
||||
@@ -14,9 +14,9 @@ weight: 10
|
||||
|
||||
{{< feature-state state="alpha" >}}
|
||||
<!--
|
||||
{{< warning >}}Alpha features change rapidly. {{< /warning >}}
|
||||
{{< caution >}}Alpha features can change rapidly. {{< /caution >}}
|
||||
-->
|
||||
{{< warning >}}Alpha 特性迅速变化。{{< /warning >}}
|
||||
{{< caution >}}Alpha 特性可能很快会变化。{{< /caution >}}
|
||||
|
||||
<!--
|
||||
Network plugins in Kubernetes come in a few flavors:
|
||||
@@ -36,7 +36,7 @@ Kubernetes中的网络插件有几种类型：
|
||||
<!--
|
||||
## Installation
|
||||
|
||||
The kubelet has a single default network plugin, and a default network common to the entire cluster. It probes for plugins when it starts up, remembers what it found, and executes the selected plugin at appropriate times in the pod lifecycle (this is only true for Docker, as rkt manages its own CNI plugins). There are two Kubelet command line parameters to keep in mind when using plugins:
|
||||
The kubelet has a single default network plugin, and a default network common to the entire cluster. It probes for plugins when it starts up, remembers what it finds, and executes the selected plugin at appropriate times in the pod lifecycle (this is only true for Docker, as rkt manages its own CNI plugins). There are two Kubelet command line parameters to keep in mind when using plugins:
|
||||
|
||||
* `cni-bin-dir`: Kubelet probes this directory for plugins on startup
|
||||
* `network-plugin`: The network plugin to use from `cni-bin-dir`. It must match the name reported by a plugin probed from the plugin directory. For CNI plugins, this is simply "cni".
|
||||
@@ -71,7 +71,7 @@ iptables 代理显然依赖于 iptables，插件可能需要确保 iptables 能
|
||||
|
||||
The CNI plugin is selected by passing Kubelet the `--network-plugin=cni` command-line option. Kubelet reads a file from `--cni-conf-dir` (default `/etc/cni/net.d`) and uses the CNI configuration from that file to set up each pod's network. The CNI configuration file must match the [CNI specification](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration), and any required CNI plugins referenced by the configuration must be present in `--cni-bin-dir` (default `/opt/cni/bin`).
|
||||
|
||||
If there are multiple CNI configuration files in the directory, the first one in lexicographic order of file name is used.
|
||||
If there are multiple CNI configuration files in the directory, the kubelet uses the configuration file that comes first by name in lexicographic order.
|
||||
|
||||
In addition to the CNI plugin specified by the configuration file, Kubernetes requires the standard CNI [`lo`](https://github.com/containernetworking/plugins/blob/master/plugins/main/loopback/loopback.go) plugin, at minimum version 0.2.0
|
||||
-->
|
||||
@@ -81,7 +81,7 @@ In addition to the CNI plugin specified by the configuration file, Kubernetes re
|
||||
Kubelet 从 `--cni-conf-dir` （默认是 `/etc/cni/net.d`） 读取文件并使用该文件中的 CNI 配置来设置每个 pod 的网络。
|
||||
CNI 配置文件必须与 [CNI 规约](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration)匹配，并且配置引用的任何所需的 CNI 插件都必须存在于 `--cni-bin-dir`（默认是 `/opt/cni/bin`）。
|
||||
|
||||
如果这个目录中有多个 CNI 配置文件，则使用按文件名的字典顺序排列的第一个配置文件。
|
||||
如果这个目录中有多个 CNI 配置文件，kubelet 将会使用按文件名的字典顺序排列的第一个作为配置文件。
|
||||
|
||||
除了配置文件指定的 CNI 插件外，Kubernetes 还需要标准的 CNI [`lo`](https://github.com/containernetworking/plugins/blob/master/plugins/main/loopback/loopback.go) 插件，最低版本是0.2.0。
|
||||
|
||||
@@ -134,20 +134,24 @@ CNI 网络插件支持 `hostPort`。 您可以使用官方 [portmap](https://git
|
||||
<!--
|
||||
#### Support traffic shaping
|
||||
|
||||
**Experimental Feature**
|
||||
|
||||
The CNI networking plugin also supports pod ingress and egress traffic shaping. You can use the official [bandwidth](https://github.com/containernetworking/plugins/tree/master/plugins/meta/bandwidth)
|
||||
plugin offered by the CNI plugin team or use your own plugin with bandwidth control functionality.
|
||||
|
||||
If you want to enable traffic shaping support, you must add a `bandwidth` plugin to your CNI configuration file
|
||||
(default `/etc/cni/net.d`).
|
||||
If you want to enable traffic shaping support, you must add the `bandwidth` plugin to your CNI configuration file
|
||||
(default `/etc/cni/net.d`) and ensure that the binary is included in your CNI bin dir (default `/opt/cni/bin`).
|
||||
-->
|
||||
#### 支持流量整形
|
||||
|
||||
**实验功能**
|
||||
|
||||
CNI 网络插件还支持 pod 入口和出口流量整形。
|
||||
您可以使用 CNI 插件团队提供的 [bandwidth](https://github.com/containernetworking/plugins/tree/master/plugins/meta/bandwidth) 插件，
|
||||
也可以使用您自己的具有带宽控制功能的插件。
|
||||
|
||||
如果您想要启用流量整形支持，你必须将 `bandwidth` 插件添加到 CNI 配置文件
|
||||
（默认是 `/etc/cni/net.d`）。
|
||||
（默认是 `/etc/cni/net.d`）并保证该可执行文件包含在您的 CNI 的 bin 文件夹内 (默认为 `/opt/cni/bin`)。
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@@ -1040,7 +1040,7 @@ provisioner: kubernetes.io/portworx-volume
|
||||
parameters:
|
||||
repl: "1"
|
||||
snap_interval: "70"
|
||||
io_priority: "high"
|
||||
priority_io: "high"
|
||||
|
||||
```
|
||||
|
||||
@@ -1050,7 +1050,7 @@ parameters:
|
||||
* `repl`: number of synchronous replicas to be provided in the form of
|
||||
replication factor `1..3` (default: `1`) A string is expected here i.e.
|
||||
`"1"` and not `1`.
|
||||
* `io_priority`: determines whether the volume will be created from higher
|
||||
* `priority_io`: determines whether the volume will be created from higher
|
||||
performance or a lower priority storage `high/medium/low` (default: `low`).
|
||||
* `snap_interval`: clock/time interval in minutes for when to trigger snapshots.
|
||||
Snapshots are incremental based on difference with the prior snapshot, 0
|
||||
|
||||
@@ -59,7 +59,7 @@ maximum length of a Job name is no more than 63 characters.
|
||||
For instructions on creating and working with cron jobs, and for an example of a spec file for a cron job, see [Running automated tasks with cron jobs](/docs/tasks/job/automated-tasks-with-cron-jobs).
|
||||
-->
|
||||
|
||||
有关创建和使用 CronJob 的说明及规范文件的示例，请参见[使用 CronJob 运行自动化任务](/docs/tasks/job/automated-tasks-with-cron-jobs)。
|
||||
有关创建和使用 CronJob 的说明及规范文件的示例，请参见[使用 CronJob 运行自动化任务](/zh/docs/tasks/job/automated-tasks-with-cron-jobs/)。
|
||||
|
||||
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -66,7 +66,7 @@ Init 容器的状态在 `status.initContainerStatuses` 字段中以容器状态
|
||||
<!--
|
||||
### Differences from regular containers
|
||||
Init containers support all the fields and features of app containers, including resource limits, volumes, and security settings. However, the resource requests and limits for an init container are handled differently, as documented in [Resources](#resources).
|
||||
Also, init containers do not support readiness probes because they must run to completion before the Pod can be ready.
|
||||
Also, init containers do not support `lifecycle`, `livenessProbe`, `readinessProbe`, or `startupProbe` because they must run to completion before the Pod can be ready.
|
||||
If you specify multiple init containers for a Pod, Kubelet runs each init container sequentially. Each init container must succeed before the next can run. When all of the init containers have run to completion, Kubelet initializes the application containers for the Pod and runs them as usual.
|
||||
-->
|
||||
|
||||
@@ -74,7 +74,7 @@ If you specify multiple init containers for a Pod, Kubelet runs each init contai
|
||||
|
||||
Init 容器支持应用容器的全部字段和特性，包括资源限制、数据卷和安全设置。 然而，Init 容器对资源请求和限制的处理稍有不同，在下面 [资源](#资源) 处有说明。
|
||||
|
||||
同时 Init 容器不支持 Readiness Probe，因为它们必须在 Pod 就绪之前运行完成。
|
||||
同时 Init 容器不支持 `lifecycle`、`livenessProbe`、`readinessProbe` 和 `startupProbe`，因为它们必须在 Pod 就绪之前运行完成。
|
||||
|
||||
如果为一个 Pod 指定了多个 Init 容器，这些容器会按顺序逐个运行。每个 Init 容器必须运行成功，下一个才能够运行。当所有的 Init 容器运行完成时，Kubernetes 才会为 Pod 初始化应用容器并像平常一样运行。
|
||||
|
||||
@@ -135,7 +135,7 @@ Here are some ideas for how to use init containers:
|
||||
|
||||
* 在启动应用容器之前等一段时间，使用类似命令：
|
||||
|
||||
sleep 60
|
||||
sleep 60
|
||||
|
||||
* 克隆 Git 仓库到 {{< glossary_tooltip text="Volume" term_id="volume" >}}。
|
||||
* 将配置值放到配置文件中，运行模板工具为主应用容器动态地生成配置文件。例如，在配置文件中存放 POD_IP 值，并使用 Jinja 生成主应用配置文件。
|
||||
@@ -351,7 +351,7 @@ During the startup of a Pod, each init container starts in order, after the netw
|
||||
A Pod cannot be `Ready` until all init containers have succeeded. The ports on an init container are not aggregated under a Service. A Pod that is initializing
|
||||
is in the `Pending` state but should have a condition `Initializing` set to true.
|
||||
|
||||
If the Pod [restarts](#pod-restart-reasons), or is restarted, all init containers must execute again.
|
||||
If the Pod [restarts](#pod-restart-reasons), or is restarted, all init containers must execute again.
|
||||
|
||||
Changes to the init container spec are limited to the container image field. Altering an init container image field is equivalent to restarting the Pod.
|
||||
|
||||
@@ -445,4 +445,3 @@ Pod重启导致 Init 容器重新执行，主要有如下几个原因：
|
||||
|
||||
* 阅读[创建包含 Init 容器的 Pod](/docs/tasks/configure-pod-container/configure-pod-initialization/#create-a-pod-that-has-an-init-container)
|
||||
* 学习如何[调测 Init 容器](/docs/tasks/debug-application-cluster/debug-init-containers/)
|
||||
|
||||
|
||||
@@ -5,17 +5,22 @@ weight: 80
|
||||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Reference docs overview
|
||||
main_menu: true
|
||||
weight: 80
|
||||
---
|
||||
-->
|
||||
|
||||
<!--
|
||||
Much of the Kubernetes reference documentation is generated from Kubernetes
|
||||
source code, using scripts. The topics in this section document how to generate
|
||||
this type of content.
|
||||
The topics in this section document how to generate the Kubernetes
|
||||
reference guides.
|
||||
|
||||
To build the reference documentation, see the following guide:
|
||||
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
-->
|
||||
|
||||
许多 Kubernetes 参考文档都是使用脚本从 Kubernetes 源代码生成的。本节的主题是如何生成这种类型的文档。
|
||||
本节的主题是描述如何生成 Kubernetes 参考指南。
|
||||
要生成参考文档，请参考下面的指南：
|
||||
|
||||
* [生成参考文档快速入门](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: 为上游 Kubernetes 代码库做出贡献
|
||||
content_type: task
|
||||
weight: 20
|
||||
---
|
||||
<!--
|
||||
---
|
||||
title: Contributing to the Upstream Kubernetes Code
|
||||
content_type: task
|
||||
---
|
||||
weight: 20
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
@@ -16,93 +16,83 @@ This page shows how to contribute to the upstream kubernetes/kubernetes project
|
||||
to fix bugs found in the Kubernetes API documentation or the `kube-*`
|
||||
components such as `kube-apiserver`, `kube-controller-manager`, etc.
|
||||
-->
|
||||
此页面描述如何为上游 kubernetes/kubernetes 项目做出贡献，如修复 Kubernetes API 文档或 `kube-*` 组件（例如 kube-apiserver、kube-controller-manager 等）中发现的错误。
|
||||
此页面描述如何为上游 `kubernetes/kubernetes` 项目做出贡献，如修复 Kubernetes API
|
||||
文档或 Kubernetes 组件（例如 `kubeadm`、`kube-apiserver`、`kube-controller-manager` 等）
|
||||
中发现的错误。
|
||||
|
||||
<!--
|
||||
If you instead want to regenerate the reference documentation for the Kubernetes
|
||||
API or the `kube-*` components from the upstream code, see the following instructions:
|
||||
-->
|
||||
相反，如果您想从上游代码重新生成 Kubernetes API 或 `kube-*` 组件的参考文档。请参考以下说明：
|
||||
|
||||
<!--
|
||||
- [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
- [Generating Reference Documentation for the Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
-->
|
||||
如果您仅想从上游代码重新生成 Kubernetes API 或 `kube-*` 组件的参考文档。请参考以下说明：
|
||||
|
||||
- [生成 Kubernetes API 的参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
- [生成 Kubernetes 组件和工具的参考文档](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
|
||||
|
||||
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
|
||||
<!--
|
||||
You need to have these tools installed:
|
||||
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [Golang](https://golang.org/doc/install) version 1.13+
|
||||
- [Docker](https://docs.docker.com/engine/installation/)
|
||||
- [etcd](https://github.com/coreos/etcd/)
|
||||
-->
|
||||
您需要安装以下工具：
|
||||
- 你需要安装以下工具：
|
||||
|
||||
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [Golang](https://golang.org/doc/install) 的 1.13 版本或更高
|
||||
- [Docker](https://docs.docker.com/engine/installation/)
|
||||
- [etcd](https://github.com/coreos/etcd/)
|
||||
|
||||
<!--
|
||||
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
* [Golang](https://golang.org/doc/install) version 1.9.1 or later
|
||||
* [Docker](https://docs.docker.com/engine/installation/)
|
||||
* [etcd](https://github.com/coreos/etcd/)
|
||||
- Your $GOPATH environment variable must be set, and the location of `etcd`
|
||||
must be in your $PATH environment variable.
|
||||
-->
|
||||
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
* [Golang](https://golang.org/doc/install) Go 版本大于 1.9.1
|
||||
* [Docker](https://docs.docker.com/engine/installation/)
|
||||
* [etcd](https://github.com/coreos/etcd/)
|
||||
- 你必须设置 `GOPATH` 环境变量，并且 `etcd` 的位置必须在 `PATH` 环境变量中。
|
||||
|
||||
<!--
|
||||
Your $GOPATH environment variable must be set, and the location of `etcd`
|
||||
must be in your $PATH environment variable.
|
||||
- You need to know how to create a pull request to a GitHub repository.
|
||||
Typically, this involves creating a fork of the repository.
|
||||
For more information, see
|
||||
[Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/) and
|
||||
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
|
||||
-->
|
||||
必须设置 $GOPATH 环境变量，并且 `etcd` 的位置必须在 $PATH 环境变量中。
|
||||
|
||||
<!--
|
||||
You need to know how to create a pull request to a GitHub repository.
|
||||
Typically, this involves creating a fork of the repository. For more
|
||||
information, see
|
||||
[Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/) and
|
||||
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
|
||||
-->
|
||||
您需要知道如何创建对 GitHub 代码仓库的拉取请求（Pull Request）。
|
||||
通常，这涉及创建代码仓库的分支。要获取更多的信息请参考[创建 PR](https://help.github.com/articles/creating-a-pull-request/) 和
|
||||
[GitHub 标准 Fork 和 PR 工作流程](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。
|
||||
|
||||
|
||||
|
||||
|
||||
- 您需要知道如何创建对 GitHub 代码仓库的拉取请求（Pull Request）。
|
||||
通常，这涉及创建代码仓库的派生副本。
|
||||
要获取更多的信息请参考[创建 PR](https://help.github.com/articles/creating-a-pull-request/) 和
|
||||
[GitHub 标准派生和 PR 工作流程](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## The big picture
|
||||
-->
|
||||
## 基本原则
|
||||
|
||||
<!--
|
||||
The reference documentation for the Kubernetes API and the `kube-*` components
|
||||
such as `kube-apiserver`, `kube-controller-manager` are automatically generated
|
||||
from the source code in the [upstream Kubernetes](https://github.com/kubernetes/kubernetes/).
|
||||
-->
|
||||
Kubernetes API 和 `kube-*` 组件（例如 `kube-apiserver`、`kube-controller-manager`）的参考文档是根据[上游 Kubernetes](https://github.com/kubernetes/kubernetes/) 中的源代码自动生成的。
|
||||
|
||||
<!--
|
||||
When you see bugs in the generated documentation, you may want to consider
|
||||
creating a patch to fix it in the upstream project.
|
||||
-->
|
||||
## 基本说明
|
||||
|
||||
Kubernetes API 和 `kube-*` 组件（例如 `kube-apiserver`、`kube-controller-manager`）的参考文档
|
||||
是根据[上游 Kubernetes](https://github.com/kubernetes/kubernetes/) 中的源代码自动生成的。
|
||||
|
||||
当您在生成的文档中看到错误时，您可能需要考虑创建一个 PR 用来在上游项目中对其进行修复。
|
||||
|
||||
<!--
|
||||
## Cloning the Kubernetes repository
|
||||
|
||||
If you don't already have the kubernetes/kubernetes repository, get it now:
|
||||
-->
|
||||
## 克隆 Kubernetes 代码仓库
|
||||
|
||||
<!--
|
||||
If you don't already have the kubernetes/kubernetes repository, get it now:
|
||||
-->
|
||||
如果您还没有 kubernetes/kubernetes 代码仓库，请立即参照下列命令获取：
|
||||
如果您还没有 kubernetes/kubernetes 代码仓库，请参照下列命令获取：
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
@@ -117,9 +107,10 @@ For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
-->
|
||||
确定您的 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库克隆的基本目录。
|
||||
例如，如果按照前面的步骤获取代码仓库，则您的基本目录为 `$GOPATH/src/github.com/kubernetes/kubernetes`。
|
||||
接下来其余步骤将您的基本目录称为 `<k8s-base>`。
|
||||
确定您的 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库克隆的根目录。
|
||||
例如，如果按照前面的步骤获取代码仓库，则你的根目录为 `$GOPATH/src/github.com/kubernetes/kubernetes`。
|
||||
接下来其余步骤将你的根目录称为 `<k8s-base>`。
|
||||
|
||||
<!--
|
||||
Determine the base directory of your clone of the
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
|
||||
@@ -127,22 +118,24 @@ For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
-->
|
||||
确定您的 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) 代码仓库克隆的基本目录。
|
||||
例如，如果按照前面的步骤获取代码仓库，则您的基本目录为 `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
|
||||
接下来其余步骤将您的基本目录称为 `<rdocs-base>`。
|
||||
确定您的 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
代码仓库克隆的根目录。
|
||||
例如，如果按照前面的步骤获取代码仓库，则你的根目录为
|
||||
`$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
|
||||
接下来其余步骤将你的根目录称为 `<rdocs-base>`。
|
||||
|
||||
<!--
|
||||
## Editing the Kubernetes source code
|
||||
-->
|
||||
## 编辑 Kubernetes 源代码
|
||||
|
||||
<!--
|
||||
The Kubernetes API reference documentation is automatically generated from
|
||||
an OpenAPI spec, which is generated from the Kubernetes source code. If you
|
||||
want to change the API reference documentation, the first step is to change one
|
||||
or more comments in the Kubernetes source code.
|
||||
-->
|
||||
Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。
|
||||
## 编辑 Kubernetes 源代码
|
||||
|
||||
Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。
|
||||
如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。
|
||||
|
||||
<!--
|
||||
The documentation for the `kube-*` components is also generated from the upstream
|
||||
@@ -153,27 +146,25 @@ you want to fix in order to fix the generated documentation.
|
||||
|
||||
<!--
|
||||
### Making changes to the upstream source code
|
||||
-->
|
||||
### 更改上游 Kubernetes 源代码
|
||||
|
||||
<!--
|
||||
The following steps are an example, not a general procedure. Details
|
||||
will be different in your situation.
|
||||
-->
|
||||
### 更改上游 Kubernetes 源代码
|
||||
|
||||
{{< note >}}
|
||||
以下步骤仅作为示例，不是一般步骤，具体情况因您而异。
|
||||
以下步骤仅作为示例，不是通用步骤，具体情况因环境而异。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
Here's an example of editing a comment in the Kubernetes source code.
|
||||
-->
|
||||
以下在 Kubernetes 源代码中编辑注释的示例。
|
||||
|
||||
<!--
|
||||
In your local kubernetes/kubernetes repository, check out the master branch,
|
||||
and make sure it is up to date:
|
||||
-->
|
||||
在您本地的 kubernetes/kubernetes 代码仓库中，切换出本地 master 分支，并确保它是最新的：
|
||||
以下在 Kubernetes 源代码中编辑注释的示例。
|
||||
|
||||
在您本地的 kubernetes/kubernetes 代码仓库中，检出 master 分支，并确保它是最新的：
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
@@ -184,19 +175,18 @@ git pull https://github.com/kubernetes/kubernetes master
|
||||
<!--
|
||||
Suppose this source file in the master branch has the typo "atmost":
|
||||
-->
|
||||
假设 master 分支中的此源文件的拼写错误为 "atmost"：
|
||||
假设 master 分支中的下面源文件中包含拼写错误 "atmost"：
|
||||
|
||||
[kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/apps/v1/types.go)
|
||||
|
||||
<!--
|
||||
In your local environment, open `types.go`, and change "atmost" to "at most".
|
||||
-->
|
||||
在您的本地环境中，打开 `types.go` 文件，然后将 "atmost" 更改为 "at most"。
|
||||
|
||||
<!--
|
||||
Verify that you have changed the file:
|
||||
-->
|
||||
以下命令查看您已更改的文件：
|
||||
在你的本地环境中，打开 `types.go` 文件，然后将 "atmost" 更改为 "at most"。
|
||||
|
||||
以下命令验证你已经更改了文件：
|
||||
|
||||
```shell
|
||||
git status
|
||||
@@ -216,23 +206,22 @@ On branch master
|
||||
|
||||
<!--
|
||||
### Committing your edited file
|
||||
-->
|
||||
### 提交已编辑的文件
|
||||
|
||||
<!--
|
||||
Run `git add` and `git commit` to commit the changes you have made so far. In the next step,
|
||||
you will do a second commit. It is important to keep your changes separated into two commits.
|
||||
-->
|
||||
运行 `git add` 和 `git commit` 命令提交到目前为止所做的更改。在下一步中，您将进行第二次提交，将更改分成两个提交很重要。
|
||||
### 提交已编辑的文件
|
||||
|
||||
运行 `git add` 和 `git commit` 命令提交到目前为止所做的更改。
|
||||
在下一步中，您将进行第二次提交，将更改分成两个提交很重要。
|
||||
|
||||
<!--
|
||||
### Generating the OpenAPI spec and related files
|
||||
|
||||
Go to `<k8s-base>` and run these scripts:
|
||||
-->
|
||||
### 生成 OpenAPI 规范和相关文件
|
||||
|
||||
<!--
|
||||
Go to `<k8s-base>` and run these scripts:
|
||||
-->
|
||||
进入 `<k8s-base>` 目录并运行以下脚本：
|
||||
|
||||
```shell
|
||||
@@ -242,12 +231,10 @@ hack/update-generated-protobuf.sh
|
||||
hack/update-api-reference-docs.sh
|
||||
```
|
||||
|
||||
<!--
|
||||
Run `git status` to see what was generated.
|
||||
-->
|
||||
运行 `git status` 命令查看生成的东西。
|
||||
<!-- Run `git status` to see what was generated. -->
|
||||
运行 `git status` 命令查看生成的文件。
|
||||
|
||||
```shell
|
||||
```none
|
||||
On branch master
|
||||
...
|
||||
modified: api/openapi-spec/swagger.json
|
||||
@@ -264,14 +251,16 @@ For example, you could run `git diff -a api/openapi-spec/swagger.json`.
|
||||
This is important, because `swagger.json` is the input to the second stage of
|
||||
the doc generation process.
|
||||
-->
|
||||
查看 `api/openapi-spec/swagger.json` 的内容，以确保 typo 已经被修正。例如，您可以运行 `git diff -a api/openapi-spec/swagger.json` 命令。这很重要，因为 `swagger.json` 是文档生成过程中第二阶段的输入。
|
||||
查看 `api/openapi-spec/swagger.json` 的内容，以确保拼写错误已经被修正。
|
||||
例如，您可以运行 `git diff -a api/openapi-spec/swagger.json` 命令。
|
||||
这很重要，因为 `swagger.json` 是文档生成过程中第二阶段的输入。
|
||||
|
||||
<!--
|
||||
Run `git add` and `git commit` to commit your changes. Now you have two commits:
|
||||
one that contains the edited `types.go` file, and one that contains the generated OpenAPI spec
|
||||
and related files. Keep these two commits separate. That is, do not squash your commits.
|
||||
-->
|
||||
运行 `git add` 和 `git commit` 命令来提交您的更改。现在您有两个提交：
|
||||
运行 `git add` 和 `git commit` 命令来提交您的更改。现在您有两个提交（commits）：
|
||||
一种包含编辑的 `types.go` 文件，另一种包含生成的 OpenAPI 规范和相关文件。
|
||||
将这两个提交分开独立。也就是说，不要 squash 您的提交。
|
||||
|
||||
@@ -283,13 +272,16 @@ master branch of the
|
||||
Monitor your pull request, and respond to reviewer comments as needed. Continue
|
||||
to monitor your pull request until it is merged.
|
||||
-->
|
||||
将您的更改作为 [PR](https://help.github.com/articles/creating-a-pull-request/) 提交到 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库的 master 分支。关注您的 PR，并根据需要回复 reviewer 的评论。继续关注您的 PR，直到 PR 被合并为止。
|
||||
将您的更改作为 [PR](https://help.github.com/articles/creating-a-pull-request/)
|
||||
提交到 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库的 master 分支。
|
||||
关注您的 PR，并根据需要回复 reviewer 的评论。继续关注您的 PR，直到 PR 被合并为止。
|
||||
|
||||
<!--
|
||||
[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758)
|
||||
is an example of a pull request that fixes a typo in the Kubernetes source code.
|
||||
-->
|
||||
[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) 是修复 Kubernetes 源代码中的拼写错误的拉取请求的示例。
|
||||
[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) 是修复 Kubernetes
|
||||
源代码中的拼写错误的拉取请求的示例。
|
||||
|
||||
<!--
|
||||
It can be tricky to determine the correct source file to be changed. In the
|
||||
@@ -302,22 +294,30 @@ repository and in related repositories, such as
|
||||
[kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md).
|
||||
-->
|
||||
{{< note >}}
|
||||
确定要更改的正确源文件可能很棘手。在前面的示例中，官方的源文件位于 `kubernetes/kubernetes` 代码仓库的 `staging` 目录中。但是根据您的情况，`staging` 目录可能不是找到官方源文件的地方。根据指导原则，请检查 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging) 代码仓库和相关代码仓库（例如 [kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md)）中的 `README` 文件。
|
||||
确定要更改的正确源文件可能很棘手。在前面的示例中，官方的源文件位于 `kubernetes/kubernetes`
|
||||
代码仓库的 `staging` 目录中。但是根据您的情况，`staging` 目录可能不是找到官方源文件的地方。
|
||||
如果需要帮助，请阅读
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging)
|
||||
代码仓库和相关代码仓库
|
||||
（例如 [kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md)）
|
||||
中的 `README` 文件。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Cherry picking your commit into a release branch
|
||||
-->
|
||||
### Cherry Pick 将您的提交纳入发布分支
|
||||
|
||||
<!--
|
||||
In the preceding section, you edited a file in the master branch and then ran scripts
|
||||
to generate an OpenAPI spec and related files. Then you submitted your changes in a pull request
|
||||
to the master branch of the kubernetes/kubernetes repository. Now suppose you want to backport
|
||||
your change into a release branch. For example, suppose the master branch is being used to develop
|
||||
Kubernetes version 1.10, and you want to backport your change into the release-1.9 branch.
|
||||
-->
|
||||
在上一节中，您在 master 分支中编辑了一个文件，然后运行了脚本用来生成 OpenAPI 规范和相关文件。然后将您的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支的 pull request 中。 现在，需要将您的更改反向移植到已经 release 的分支。例如，假设使用 master 分支来开发 Kubernetes 1.10 版，并且您想将更改反向移植到 release-1.9 分支。
|
||||
### 将你的提交 Cherrypick 到发布分支
|
||||
|
||||
在上一节中，你在 master 分支中编辑了一个文件，然后运行了脚本用来生成 OpenAPI 规范和相关文件。
|
||||
然后用 PR 将你的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支中。
|
||||
现在，需要将你的更改反向移植到已经发布的分支。
|
||||
例如，假设 master 分支被用来开发 Kubernetes 1.10 版，并且你想将更改反向移植到 release-1.9 分支。
|
||||
|
||||
<!--
|
||||
Recall that your pull request has two commits: one for editing `types.go`
|
||||
@@ -326,7 +326,10 @@ commit into the release-1.9 branch. The idea is to cherry pick the commit that e
|
||||
the commit that has the results of running the scripts. For instructions, see
|
||||
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
|
||||
-->
|
||||
回想一下，您的 pull request 有两个提交：一个用于编辑 `types.go`，一个用于由脚本生成的文件。下一步的目的是对您的第一次提交 cherry pick 到 release-1.9 分支。这个想法是 cherry pick 编辑了 types.go 的提交，但不是具有运行脚本结果的提交。有关说明，请参见[提出 Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
|
||||
回想一下，您的 PR 有两个提交：一个用于编辑 `types.go`，一个用于由脚本生成的文件。
|
||||
下一步是将你的第一次提交 cherrypick 到 release-1.9 分支。这样做的原因是仅 cherrypick 编辑了 types.go 的提交，
|
||||
而不是具有脚本运行结果的提交。
|
||||
有关说明，请参见[提出 Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
|
||||
|
||||
<!--
|
||||
Proposing a cherry pick requires that you have permission to set a label and a milestone in your
|
||||
@@ -334,14 +337,16 @@ pull request. If you don't have those permissions, you will need to work with so
|
||||
and milestone for you.
|
||||
-->
|
||||
{{< note >}}
|
||||
提出 cherry pick 要求您有权在 pull request 中设置标签和里程碑。如果您没有这些权限，则需要与可以为您设置标签和里程碑的人员合作。
|
||||
提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果您没有这些权限，
|
||||
则需要与可以为你设置标签和里程碑的人员合作。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
When you have a pull request in place for cherry picking your one commit into the release-1.9 branch,
|
||||
the next step is to run these scripts in the release-1.9 branch of your local environment.
|
||||
-->
|
||||
当您提出一个 pull request，希望将您的一个提交 cherry pick 到 release-1.9 分支中时，下一步是在本地环境的 release-1.9 分支中运行这些脚本。
|
||||
当你发起 PR 将你的一个提交 cherry pick 到 release-1.9 分支中时，下一步是在本地环境的 release-1.9
|
||||
分支中运行如下脚本。
|
||||
|
||||
```shell
|
||||
hack/update-generated-swagger-docs.sh
|
||||
@@ -354,7 +359,8 @@ hack/update-api-reference-docs.sh
|
||||
Now add a commit to your cherry-pick pull request that has the recently generated OpenAPI spec
|
||||
and related files. Monitor your pull request until it gets merged into the release-1.9 branch.
|
||||
-->
|
||||
现在将提交添加到您的 Cherry-pick pull request 中，该请求具有最近生成的 OpenAPI 规范和相关文件。关注您的 pull request 请求，直到其合并到 release-1.9 分支中为止。
|
||||
现在将提交添加到您的 Cherry-Pick PR 中，该 PR 中包含最新生成的 OpenAPI 规范和相关文件。
|
||||
关注你的 PR，直到其合并到 release-1.9 分支中为止。
|
||||
|
||||
<!--
|
||||
At this point, both the master branch and the release-1.9 branch have your updated `types.go`
|
||||
@@ -364,36 +370,37 @@ the same as the generated files in the master branch. The generated files in the
|
||||
contain API elements only from Kubernetes 1.9. The generated files in the master branch might contain
|
||||
API elements that are not in 1.9, but are under development for 1.10.
|
||||
-->
|
||||
此时，master 分支和 release-1.9 分支都具有更新的 `types.go` 文件和一组生成的文件，这些文件反映了您对 `types.go` 所做的更改。请注意，生成的 OpenAPI 规范和其他 release-1.9 分支中生成的文件不一定与 master 分支中生成的文件相同。release-1.9 分支中生成的文件仅包含来自 Kubernetes 1.9 的 API 元素。master 分支中生成的文件可能包含不在 1.9 中但正在为 1.10 开发的 API 元素。
|
||||
|
||||
此时，master 分支和 release-1.9 分支都具有更新的 `types.go` 文件和一组生成的文件，
|
||||
这些文件反映了对 `types.go` 所做的更改。
|
||||
请注意，生成的 OpenAPI 规范和其他 release-1.9 分支中生成的文件不一定与 master 分支中生成的文件相同。
|
||||
release-1.9 分支中生成的文件仅包含来自 Kubernetes 1.9 的 API 元素。
|
||||
master 分支中生成的文件可能包含不在 1.9 中但正在为 1.10 开发的 API 元素。
|
||||
|
||||
<!--
|
||||
## Generating the published reference docs
|
||||
-->
|
||||
## 生成已发布的参考文档
|
||||
|
||||
<!--
|
||||
The preceding section showed how to edit a source file and then generate
|
||||
several files, including `api/openapi-spec/swagger.json` in the
|
||||
`kubernetes/kubernetes` repository.
|
||||
The `swagger.json` file is the OpenAPI definition file to use for generating
|
||||
the API reference documentation.
|
||||
-->
|
||||
上一节显示了如何编辑源文件然后生成多个文件，包括在 `kubernetes/kubernetes` 代码仓库中的 `api/openapi-spec/swagger.json`。
|
||||
`swagger.json` 文件是 OpenAPI 定义文件，可用于生成 API 参考文档。
|
||||
## 生成已发布的参考文档
|
||||
|
||||
上一节显示了如何编辑源文件然后生成多个文件，包括在 `kubernetes/kubernetes` 代码仓库中的
|
||||
`api/openapi-spec/swagger.json`。`swagger.json` 文件是 OpenAPI 定义文件，可用于生成 API 参考文档。
|
||||
|
||||
<!--
|
||||
You are now ready to follow the [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/) guide to generate the
|
||||
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
-->
|
||||
现在，您可以按照[生成 Kubernetes API 的参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/)指南来生成
|
||||
现在，您可以按照
|
||||
[生成 Kubernetes API 的参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
指南来生成
|
||||
[已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。
|
||||
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
<!--
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
|
||||
@@ -403,5 +410,3 @@ You are now ready to follow the [Generating Reference Documentation for the Kube
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generated-reference/kubernetes-components/)
|
||||
* [生成 kubectl 命令的参考文档](/docs/home/contribute/generated-reference/kubectl/)
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,106 +1,65 @@
|
||||
---
|
||||
title: 为 kubectl 命令集生成参考文档
|
||||
content_type: task
|
||||
weight: 90
|
||||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Generating Reference Documentation for kubectl Commands
|
||||
content_type: task
|
||||
---
|
||||
weight: 90
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to automatically generate reference pages for the
|
||||
commands provided by the `kubectl` tool.
|
||||
This page shows how to generate the `kubectl` command reference.
|
||||
-->
|
||||
|
||||
该页面显示了如何自动生成 `kubectl` 工具提供的命令的参考页面。
|
||||
本页面描述了如何生成 `kubectl` 命令参考。
|
||||
|
||||
{{< note >}}
|
||||
<!--
|
||||
This topic shows how to generate reference documentation for
|
||||
[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands)
|
||||
like
|
||||
[kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and
|
||||
[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint).
|
||||
-->
|
||||
本主题展示了如何为 [kubectl 命令集](/docs/reference/generated/kubectl/kubectl-commands) 生成参考文档，如 [kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) 和 [kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint)。
|
||||
<!--
|
||||
This topic does not show how to generate the
|
||||
[kubectl](/docs/reference/generated/kubectl/kubectl/)
|
||||
options reference page. For instructions on how to generate the kubectl options
|
||||
reference page, see
|
||||
[Generating Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/).
|
||||
-->
|
||||
本主题没有展示如何生成 [kubectl](/docs/reference/generated/kubectl/kubectl/) 组件的参考页面。相关说明请参见[为 Kubernetes 组件和工具生成参考页面](/docs/home/contribute/generated-reference/kubernetes-components/)。
|
||||
|
||||
{{< note >}}
|
||||
本主题描述了如何为 [kubectl 命令](/docs/reference/generated/kubectl/kubectl-commands)
|
||||
生成参考文档，如 [kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) 和
|
||||
[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint)。
|
||||
本主题没有讨论如何生成 [kubectl](/docs/reference/generated/kubectl/kubectl/) 组件选项的参考页面。
|
||||
相关说明请参见[为 Kubernetes 组件和工具生成参考页面](/docs/home/contribute/generated-reference/kubernetes-components/)。
|
||||
{{< /note >}}
|
||||
|
||||
|
||||
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
|
||||
<!--
|
||||
* You need to have
|
||||
[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
installed.
|
||||
-->
|
||||
|
||||
* 你需要安装 [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)。
|
||||
|
||||
<!--
|
||||
* You need to have
|
||||
[Golang](https://golang.org/doc/install) version 1.9.1 or later installed,
|
||||
and your `$GOPATH` environment variable must be set.
|
||||
-->
|
||||
|
||||
* 你需要安装 1.9.1 或更高版本的 [Golang](https://golang.org/doc/install), 并在环境变量中设置 `$GOPATH`。
|
||||
|
||||
<!--
|
||||
* You need to have
|
||||
[Docker](https://docs.docker.com/engine/installation/) installed.
|
||||
-->
|
||||
|
||||
* 你需要安装 [Docker](https://docs.docker.com/engine/installation/)。
|
||||
|
||||
<!--
|
||||
* You need to know how to create a pull request to a GitHub repository.
|
||||
Typically, this involves creating a fork of the repository. For more
|
||||
information, see
|
||||
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/) and
|
||||
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
|
||||
-->
|
||||
|
||||
* 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的一个分支。想了解更多信息，请参见[创建一个文档 PR](/docs/home/contribute/create-pull-request/) 和 [GitHub 标准 Fork & PR 工作流](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。
|
||||
|
||||
|
||||
|
||||
{{< include "prerequisites-ref-docs.md" >}}
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## Setting up the local repositories
|
||||
-->
|
||||
## 设置本地仓库
|
||||
|
||||
<!--
|
||||
Create a local workspace and set your `GOPATH`.
|
||||
-->
|
||||
创建本地工作区并设置您的 `GOPATH`。
|
||||
## 配置本地仓库
|
||||
|
||||
创建本地工作区并设置你的 `GOPATH`。
|
||||
|
||||
```shell
|
||||
mkdir -p $HOME/<workspace>
|
||||
|
||||
export GOPATH=$HOME/<workspace>
|
||||
```
|
||||
|
||||
<!--
|
||||
Get a local clone of the following repositories:
|
||||
-->
|
||||
<!-- Get a local clone of the following repositories: -->
|
||||
获取以下仓库的本地克隆：
|
||||
|
||||
```shell
|
||||
@@ -113,16 +72,14 @@ go get -u kubernetes-incubator/reference-docs
|
||||
<!--
|
||||
If you don't already have the kubernetes/website repository, get it now:
|
||||
-->
|
||||
如果您还没有下载过 `kubernetes/website` 仓库，现在下载：
|
||||
如果您还没有获取过 `kubernetes/website` 仓库，现在获取之：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
|
||||
```
|
||||
|
||||
<!--
|
||||
Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
|
||||
-->
|
||||
克隆下载 kubernetes/kubernetes 仓库，并作为 k8s.io/kubernetes：
|
||||
<!-- Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes: -->
|
||||
克隆 kubernetes/kubernetes 仓库作为 k8s.io/kubernetes：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
|
||||
@@ -131,18 +88,15 @@ git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
|
||||
<!--
|
||||
Remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`.
|
||||
-->
|
||||
从 `$GOPATH/src/k8s.io/kubernetes/vendor/github.com` 中卸载 spf13 软件包。
|
||||
从 `$GOPATH/src/k8s.io/kubernetes/vendor/github.com` 中移除 spf13 软件包。
|
||||
|
||||
```shell
|
||||
rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13
|
||||
```
|
||||
|
||||
<!--
|
||||
The kubernetes/kubernetes repository provides access to the kubectl and kustomize source code.
|
||||
-->
|
||||
<!-- The kubernetes/kubernetes repository provides access to the kubectl and kustomize source code. -->
|
||||
kubernetes/kubernetes 仓库提供对 kubectl 和 kustomize 源代码的访问。
|
||||
|
||||
|
||||
<!--
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
@@ -150,7 +104,9 @@ For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/k8s.io/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
-->
|
||||
确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/k8s.io/kubernetes.`。下文将该目录称为 `<k8s-base>`。
|
||||
* 确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。
|
||||
例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/k8s.io/kubernetes.`。
|
||||
下文将该目录称为 `<k8s-base>`。
|
||||
|
||||
<!--
|
||||
* Determine the base directory of your clone of the
|
||||
@@ -159,198 +115,197 @@ For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/<your-username>/website.`
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
-->
|
||||
确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/<your-username>/website`。下文将该目录称为 `<web-base>`。
|
||||
* 确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。
|
||||
例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/<your-username>/website`。
|
||||
下文将该目录称为 `<web-base>`。
|
||||
|
||||
<!--
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) repository.
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`. -->
|
||||
确定 [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/kubernetes-incubator/reference-docs`。下文将该目录称为 `<rdocs-base>`。
|
||||
* 确定 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是
|
||||
`$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
|
||||
下文将该目录称为 `<rdocs-base>`。
|
||||
|
||||
<!--
|
||||
In your local k8s.io/kubernetes repository, check out the branch of interest,
|
||||
and make sure it is up to date. For example, if you want to generate docs for
|
||||
Kubernetes 1.15, you could use these commands:
|
||||
Kubernetes 1.17, you could use these commands:
|
||||
-->
|
||||
在您当地的 k8s.io/kubernetes 仓库中，检查感兴趣的分支并确保它是最新的。例如，如果您想要生成 Kubernetes 1.15 的文档，您可以使用以下命令：
|
||||
在本地的 k8s.io/kubernetes 仓库中，检出感兴趣的分支并确保它是最新的。例如，
|
||||
如果你想要生成 Kubernetes 1.17 的文档，可以使用以下命令：
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
git checkout release-1.15
|
||||
git pull https://github.com/kubernetes/kubernetes release-1.15
|
||||
git checkout v1.17.0
|
||||
git pull https://github.com/kubernetes/kubernetes v1.17.0
|
||||
```
|
||||
|
||||
<!--
|
||||
If you do not need to edit the kubectl source code, follow the instructions to [Edit the Makefile](#editing-makefile).
|
||||
If you do not need to edit the kubectl source code, follow the instructions to
|
||||
[Setting build variables](#setting-build-variables).
|
||||
-->
|
||||
如果不需要编辑 kubectl 源码，请按照说明[编辑 Makefile](#editing-makefile)。
|
||||
如果不需要编辑 `kubectl`
|
||||
源码，请按照说明[配置构建变量](#setting-build-variables)。
|
||||
|
||||
<!--
|
||||
## Editing the kubectl source code
|
||||
-->
|
||||
|
||||
## 编辑 kubectl 源码
|
||||
|
||||
<!--
|
||||
The kubectl command reference documentation is automatically generated from
|
||||
the kubectl source code. If you want to change the reference documentation, the first step
|
||||
is to change one or more comments in the kubectl source code. Make the change in your
|
||||
local kubernetes/kubernetes repository, and then submit a pull request to the master branch of
|
||||
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
|
||||
-->
|
||||
## 编辑 kubectl 源码
|
||||
|
||||
kubectl 命令集的参考文档是基于 kubectl 源码自动生成的。如果想要修改参考文档，可以从修改 kubectl 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向 [github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 的 master 分支提交 PR。
|
||||
kubectl 命令的参考文档是基于 kubectl 源码自动生成的。如果想要修改参考文档，可以从修改
|
||||
kubectl 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向
|
||||
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 的 master
|
||||
分支提交 PR。
|
||||
|
||||
<!--
|
||||
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files)
|
||||
is an example of a pull request that fixes a typo in the kubectl source code.
|
||||
-->
|
||||
|
||||
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl 源码中的笔误进行修复的 PR 示例。
|
||||
|
||||
<!--
|
||||
Monitor your pull request, and respond to reviewer comments. Continue to monitor your
|
||||
pull request until it is merged into the master branch of the kubernetes/kubernetes repository.
|
||||
-->
|
||||
|
||||
跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的 master 分支中。
|
||||
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl
|
||||
源码中的笔误进行修复的 PR 示例。
|
||||
|
||||
跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的
|
||||
master 分支中。
|
||||
|
||||
<!--
|
||||
## Cherry picking your change into a release branch
|
||||
-->
|
||||
|
||||
## 以 cherry-pick 方式将你的修改合入已发布分支
|
||||
|
||||
<!--
|
||||
Your change is now in the master branch, which is used for development of the next
|
||||
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
|
||||
version that has already been released, you need to propose that your change be
|
||||
cherry picked into the release branch.
|
||||
-->
|
||||
## 以 cherry-pick 方式将你的修改合入已发布分支
|
||||
|
||||
你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 cherry-pick 方式合入已发布分支。
|
||||
你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。
|
||||
如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以
|
||||
cherry-pick 方式合入已发布分支。
|
||||
|
||||
<!--
|
||||
For example, suppose the master branch is being used to develop Kubernetes 1.10,
|
||||
and you want to backport your change to the release-1.15 branch. For instructions
|
||||
on how to do this, see
|
||||
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
|
||||
-->
|
||||
|
||||
例如，假设 master 分支正用于开发 Kubernetes 1.10 版本，而你希望将修改合入到已发布的 1.15 版本分支。相关的操作指南，请参见 [提议一个 cherry-pick 合入](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
|
||||
|
||||
<!--
|
||||
Monitor your cherry-pick pull request until it is merged into the release branch.
|
||||
-->
|
||||
|
||||
例如，假设 master 分支正用于开发 Kubernetes 1.16 版本，而你希望将修改合入到已发布的 1.15 版本分支。
|
||||
相关的操作指南，请参见
|
||||
[提议一个 cherry-pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
|
||||
|
||||
跟踪你的 cherry-pick PR，直到它合入到已发布分支中。
|
||||
|
||||
{{< note >}}
|
||||
<!--
|
||||
Proposing a cherry pick requires that you have permission to set a label and a
|
||||
milestone in your pull request. If you don’t have those permissions, you will
|
||||
need to work with someone who can set the label and milestone for you.
|
||||
-->
|
||||
|
||||
提议一个 cherry-pick 合入，需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。
|
||||
{{< note >}}
|
||||
提议一个 cherry-pick 需要你有在 PR 中设置标签和里程碑的权限。
|
||||
如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Editing Makefile
|
||||
-->
|
||||
## Setting build variables
|
||||
|
||||
## 编辑 Makefile
|
||||
|
||||
<!--
|
||||
Go to `<rdocs-base>`, and open the `Makefile` for editing:
|
||||
-->
|
||||
## 设置构建变量 {#setting-build-variables}
|
||||
|
||||
进入 `<rdocs-base>` 目录, 打开 `Makefile` 进行编辑：
|
||||
|
||||
<!--
|
||||
* Set `K8SROOT` to `<k8s-base>`.
|
||||
* Set `WEBROOT` to `<web-base>`.
|
||||
* Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
|
||||
if you want to build docs for Kubernetes 1.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`.
|
||||
-->
|
||||
* 设置 `K8SROOT` 为 `<k8s-base>`。
|
||||
* 设置 `WEBROOT` 为 `<web-base>`。
|
||||
* 设置 `MINOR_VERSION` 为要构建的文档的次要版本。例如，如果您想为 Kubernetes 1.15 构建文档，请将 `MINOR_VERSION` 设置为 15。保存并关闭 `Makefile` 文件。
|
||||
* Set `K8S_ROOT` to `<k8s-base>`.
|
||||
* Set `K8S_WEBROOT` to `<web-base>`.
|
||||
* Set `K8S_RELEASE` to the version of the docs you want to build.
|
||||
For example, if you want to build docs for Kubernetes 1.17, set `K8S_RELEASE` to 1.17.
|
||||
|
||||
<!--
|
||||
For example, update the following variables:
|
||||
-->
|
||||
例如，更新以下变量：
|
||||
* 设置 `K8S_ROOT` 为 `<k8s-base>`。
|
||||
* 设置 `K8S_WEBROOT` 为 `<web-base>`。
|
||||
* 设置 `K8S_RELEASE` 为要构建文档的版本。
|
||||
例如，如果您想为 Kubernetes 1.17 构建文档，请将 `K8S_RELEASE` 设置为 1.17。
|
||||
|
||||
例如：
|
||||
|
||||
```
|
||||
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
|
||||
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
|
||||
MINOR_VERSION=15
|
||||
export K8S_WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
|
||||
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
|
||||
export K8S_RELEASE=1.17
|
||||
```
|
||||
|
||||
<!--
|
||||
## Creating a version directory
|
||||
## Creating a versioned directory
|
||||
|
||||
The `createversiondirs` build target creates a versioned directory
|
||||
and copies the kubectl reference configuration files to the versioned directory.
|
||||
The versioned directory name follows the pattern of `v<major>_<minor>`.
|
||||
|
||||
In the `<rdocs-base>` directory, run the following build target:
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
make createversiondirs
|
||||
```
|
||||
-->
|
||||
## 创建版本目录
|
||||
|
||||
<!--
|
||||
The version directory is a staging area for the kubectl command reference build.
|
||||
The YAML files in this directory are used to create the structure and navigation
|
||||
of the kubectl command reference.
|
||||
-->
|
||||
版本目录是 kubectl 命令集构建的临时区域。该目录中的 YAML 文件用于创建 kubectl 命令集参考的结构和导航。
|
||||
构建目标 `createversiondirs` 会生成一个版本目录并将 kubectl 参考配置文件复制到该目录中。
|
||||
版本目录的名字模式为 `v<major>_<minor>`。
|
||||
|
||||
<!--
|
||||
In the `<rdocs-base>/gen-kubectldocs/generators` directory, if you do not already
|
||||
have a directory named `v1_<MINOR_VERSION>`, create one now by copying the directory
|
||||
for the previous version. For example, suppose you want to generate docs for
|
||||
Kubernetes 1.15, but you don't already have a `v1_15` directory. Then you could
|
||||
create and populate a `v1_15` directory by running these commands:
|
||||
-->
|
||||
|
||||
在 `gen-kubectldocs/generators` 目录中，如果你还没有一个名为 `v1_MINOR_VERSION` 的目录，那么现在通过复制前一版本的目录来创建一个。例如，假设你想要为 Kubernetes 1.15 版本生成文档，但是还没有 `v1_15` 目录，这时可以通过运行以下命令来创建并填充 `v1_15` 目录：
|
||||
在 `<rdocs-base>` 目录下，执行下面的命令：
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
git checkout release-1.15
|
||||
git pull https://github.com/kubernetes/kubernetes release-1.15
|
||||
cd <rdocs-base>
|
||||
make createversiondirs
|
||||
```
|
||||
|
||||
<!--
|
||||
## Checking out a branch in k8s.io/kubernetes
|
||||
-->
|
||||
|
||||
## 从 kubernetes/kubernetes 检出一个分支
|
||||
|
||||
<!--
|
||||
In your local <k8s-base> repository, checkout the branch that has
|
||||
the version of Kubernetes that you want to document. For example, if you want
|
||||
to generate docs for Kubernetes 1.15, checkout the release-1.15 branch. Make sure
|
||||
you local branch is up to date.
|
||||
-->
|
||||
## 从 kubernetes/kubernetes 检出一个分支
|
||||
|
||||
在本地 <k8s-base> 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。例如，如果希望为 Kubernetes 1.15 版本生成文档，请检出 1.15 分支。确保本地分支是最新的。
|
||||
在本地 `<k8s-base>` 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。
|
||||
例如，如果希望为 Kubernetes 1.17 版本生成文档，请检出 `v1.17.0` 标记。
|
||||
确保本地分支是最新的。
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
git checkout release-1.15
|
||||
git pull https://github.com/kubernetes/kubernetes release-1.15
|
||||
git checkout v1.17.0
|
||||
git pull https://github.com/kubernetes/kubernetes v1.17.0
|
||||
```
|
||||
|
||||
<!--
|
||||
## Running the doc generation code
|
||||
-->
|
||||
|
||||
## 运行文档生成代码
|
||||
|
||||
<!--
|
||||
In your local kubernetes-incubator/reference-docs repository, build and run the
|
||||
kubectl command reference generation code. You might need to run the command as root:
|
||||
-->
|
||||
## 运行文档生成代码
|
||||
|
||||
在 kubernetes-incubator/reference-docs 仓库的本地目录中，构建并运行 kubectl 命令集参数生成代码。你可能需要以 root 用户运行命令：
|
||||
在本地的 `<rdocs-base>` 目录下，运行 `copycli` 构建目标。此命令以 `root` 账号运行：
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
@@ -361,16 +316,16 @@ make copycli
|
||||
The `copycli` command will clean the staging directories, generate the kubectl command files,
|
||||
and copy the collated kubectl reference HTML page and assets to `<web-base>`.
|
||||
-->
|
||||
`copycli` 命令将清理暂存目录，生成 kubectl 命令集文件，并将整理后的 kubectl 参考 HTML 页面和文件复制到 `<web-base>`。
|
||||
`copycli` 命令将清理暂存目录，生成 kubectl 命令文件，并将整理后的 kubectl 参考 HTML 页面和
|
||||
文件复制到 `<web-base>`。
|
||||
|
||||
<!--
|
||||
## Locate the generated files
|
||||
|
||||
Verify that these two files have been generated:
|
||||
-->
|
||||
## 找到生成的文件
|
||||
|
||||
<!--
|
||||
Verify that these two files have been generated:
|
||||
-->
|
||||
验证是否已生成以下两个文件：
|
||||
|
||||
```shell
|
||||
@@ -380,22 +335,19 @@ Verify that these two files have been generated:
|
||||
|
||||
<!--
|
||||
## Locate the copied files
|
||||
|
||||
Verify that all generated files have been copied to your `<web-base>`:
|
||||
-->
|
||||
## 找到复制的文件
|
||||
|
||||
<!--
|
||||
Verify that all generated files have been copied to your `<web-base>`:
|
||||
-->
|
||||
确认所有生成的文件都已复制到您的 `<web-base>`：
|
||||
确认所有生成的文件都已复制到你的 `<web-base>`：
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git status
|
||||
```
|
||||
|
||||
<!--
|
||||
The output should include the modified files:
|
||||
-->
|
||||
<!-- The output should include the modified files: -->
|
||||
输出应包括修改后的文件：
|
||||
|
||||
```
|
||||
@@ -403,10 +355,9 @@ static/docs/reference/generated/kubectl/kubectl-commands.html
|
||||
static/docs/reference/generated/kubectl/navData.js
|
||||
```
|
||||
|
||||
<!--
|
||||
Additionally, the output might show the modified files:
|
||||
-->
|
||||
此外，输出可能显示修改后的文件：
|
||||
<!-- Additionally, the output might show the modified files: -->
|
||||
|
||||
此外，输出可能还包含：
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubectl/scroll.js
|
||||
@@ -421,12 +372,11 @@ static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-aweso
|
||||
|
||||
<!--
|
||||
## Locally test the documentation
|
||||
|
||||
Build the Kubernetes documentation in your local `<web-base>`.
|
||||
-->
|
||||
## 在本地测试文档
|
||||
|
||||
<!--
|
||||
Build the Kubernetes documentation in your local `<web-base>`.
|
||||
-->
|
||||
在本地 `<web-base>` 中构建 Kubernetes 文档。
|
||||
|
||||
```shell
|
||||
@@ -434,55 +384,44 @@ cd <web-base>
|
||||
make docker-serve
|
||||
```
|
||||
|
||||
<!--
|
||||
View the [local preview](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/).
|
||||
-->
|
||||
<!-- View the [local preview](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/). -->
|
||||
查看[本地预览](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/)。
|
||||
|
||||
<!--
|
||||
## Adding and committing changes in kubernetes/website
|
||||
|
||||
Run `git add` and `git commit` to commit the files.
|
||||
-->
|
||||
## 在 kubernetes/website 中添加和提交更改
|
||||
|
||||
<!--
|
||||
Run `git add` and `git commit` to commit the files.
|
||||
-->
|
||||
运行 `git add` 和 `git commit` 提交修改文件。
|
||||
|
||||
<!--
|
||||
## Creating a pull request
|
||||
-->
|
||||
## 创建 PR
|
||||
|
||||
<!--
|
||||
Create a pull request to the `kubernetes/website` repository. Monitor your
|
||||
pull request, and respond to review comments as needed. Continue to monitor
|
||||
your pull request until it is merged.
|
||||
-->
|
||||
|
||||
对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。
|
||||
|
||||
<!--
|
||||
A few minutes after your pull request is merged, your updated reference
|
||||
topics will be visible in the
|
||||
[published documentation](/docs/home).
|
||||
-->
|
||||
## 创建 PR
|
||||
|
||||
对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。
|
||||
继续跟踪你的 PR，直到它被合入。
|
||||
|
||||
在 PR 合入的几分钟后，你更新的参考主题将出现在[已发布文档](/docs/home/)中。
|
||||
|
||||
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
<!--
|
||||
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
|
||||
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
-->
|
||||
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generated-reference/kubernetes-components/)
|
||||
* [为 Kubernetes API 生成参考文档](/docs/home/contribute/generated-reference/kubernetes-api/)
|
||||
* [为 Kubernetes 联邦 API 生成参考文档](/docs/home/contribute/generated-reference/federation-api/)
|
||||
* [生成参考文档快速入门](/docs/home/contribute/generate-ref-docs/quickstart/)
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [为 Kubernetes API 生成参考文档](/docs/home/contribute/generate-ref-docs/kubernetes-api/)
|
||||
|
||||
|
||||
@@ -1,21 +1,22 @@
|
||||
---
|
||||
title: 为 Kubernetes API 生成参考文档
|
||||
content_type: task
|
||||
weight: 50
|
||||
---
|
||||
<!--
|
||||
---
|
||||
title: Generating Reference Documentation for the Kubernetes API
|
||||
content_type: task
|
||||
---
|
||||
weight: 50
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to update the generated reference docs for the Kubernetes API.
|
||||
|
||||
The Kubernetes API reference documentation is built from the
|
||||
[Kubernetes OpenAPI spec](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)
|
||||
and tools from [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs).
|
||||
and tools from [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs).
|
||||
|
||||
If you find bugs in the generated documentation, you need to
|
||||
[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).
|
||||
@@ -24,86 +25,54 @@ If you need only to regenerate the reference documentation from the [OpenAPI](ht
|
||||
spec, continue reading this page.
|
||||
-->
|
||||
本页面展示了如何为 Kubernetes API 更新自动生成的参考文档。
|
||||
Kubernetes API 参考文档是从 [Kubernetes OpenAPI 规范](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)构建的，而工具是从 [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 构建的。
|
||||
|
||||
如果您在生成的文档中发现错误，则需要[将其上游修复](/docs/contribute/generate-ref-docs/contribute-upstream/)。
|
||||
|
||||
如果您只需要从 [OpenAPI](https://github.com/OAI/OpenAPI-Specification) 规范中重新生成参考文档，请继续阅读此页面。
|
||||
|
||||
Kubernetes API 参考文档是从
|
||||
[Kubernetes OpenAPI 规范](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)
|
||||
构建的，而工具是从
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) 构建的。
|
||||
|
||||
如果您在生成的文档中发现错误，则需要[在上游修复](/docs/contribute/generate-ref-docs/contribute-upstream/)。
|
||||
|
||||
如果您只需要从 [OpenAPI](https://github.com/OAI/OpenAPI-Specification) 规范中重新生成参考文档，请继续阅读此页。
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
|
||||
<!--
|
||||
You need to have these tools installed:
|
||||
-->
|
||||
|
||||
你需要安装以下软件：
|
||||
|
||||
<!--
|
||||
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
* [Golang](https://golang.org/doc/install) version 1.9.1 or later
|
||||
-->
|
||||
|
||||
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
* 1.9.1 或更高版本的 [Golang](https://golang.org/doc/install)
|
||||
|
||||
<!--
|
||||
You need to know how to create a pull request (PR) to a GitHub repository.
|
||||
Typically, this involves creating a fork of the repository. For more
|
||||
information, see
|
||||
[Creating a Documentation Pull Request](/docs/contribute/start/) and
|
||||
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
|
||||
-->
|
||||
你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的 fork 分支。想了解更多信息，请参见[创建一个文档 PR](/docs/contribute/start/) 和 [GitHub 标准 Fork & PR 工作流](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。
|
||||
|
||||
|
||||
|
||||
{{< include "prerequisites-ref-docs.md" >}}
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## Setting up the local repositories
|
||||
-->
|
||||
## 设置本地仓库
|
||||
|
||||
<!--
|
||||
Create a local workspace and set your `GOPATH`.
|
||||
-->
|
||||
创建本地工作区并设置您的 `GOPATH`。
|
||||
## 配置本地仓库
|
||||
|
||||
创建本地工作区并设置你的 `GOPATH`。
|
||||
|
||||
```shell
|
||||
mkdir -p $HOME/<workspace>
|
||||
|
||||
export GOPATH=$HOME/<workspace>
|
||||
```
|
||||
|
||||
<!--
|
||||
Get a local clone of the following repositories:
|
||||
-->
|
||||
<!-- Get a local clone of the following repositories: -->
|
||||
获取以下仓库的本地克隆：
|
||||
|
||||
```shell
|
||||
go get -u github.com/kubernetes-incubator/reference-docs
|
||||
|
||||
go get -u github.com/go-openapi/loads
|
||||
go get -u github.com/go-openapi/spec
|
||||
```
|
||||
|
||||
<!--
|
||||
If you don't already have the kubernetes/website repository, get it now: -->
|
||||
如果您还没有下载过 `kubernetes/website` 仓库，现在下载：
|
||||
<!-- If you don't already have the kubernetes/website repository, get it now: -->
|
||||
如果你还没有下载过 `kubernetes/website` 仓库，现在下载：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
|
||||
```
|
||||
|
||||
<!--
|
||||
Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
|
||||
-->
|
||||
克隆下载 kubernetes/kubernetes 仓库，并作为 k8s.io/kubernetes：
|
||||
<!-- Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes: -->
|
||||
克隆 kubernetes/kubernetes 仓库作为 k8s.io/kubernetes：
|
||||
|
||||
```shell
|
||||
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
|
||||
@@ -125,97 +94,91 @@ The remaining steps refer to your base directory as `<web-base>`.
|
||||
repository is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
-->
|
||||
* [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库克隆后的基本目录为 `$GOPATH/src/k8s.io/kubernetes`。
|
||||
其余后续步骤将您的基本目录称为 `<k8s-base>`。
|
||||
|
||||
* [kubernetes/website](https://github.com/kubernetes/website) 仓库克隆后的基本目录为 `$GOPATH/src/github.com/<your username>/website`。
|
||||
其余后续步骤将您的基本目录称为 `<web-base>`。
|
||||
|
||||
* [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 仓库克隆后的基本目录为 `$GOPATH/src/github.com/kubernetes-incubator/reference-docs`。
|
||||
其余后续步骤将您的基本目录称为 `<rdocs-base>`。
|
||||
* [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库克隆后的根目录为
|
||||
`$GOPATH/src/k8s.io/kubernetes`。 后续步骤将此目录称为 `<k8s-base>`。
|
||||
* [kubernetes/website](https://github.com/kubernetes/website) 仓库克隆后的根目录为
|
||||
`$GOPATH/src/github.com/<your username>/website`。后续步骤将此目录称为 `<web-base>`。
|
||||
* [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
仓库克隆后的基本目录为 `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
|
||||
后续步骤将此目录称为 `<rdocs-base>`。
|
||||
|
||||
<!--
|
||||
## Generating the API reference docs
|
||||
-->
|
||||
## 生成 API 参考文档
|
||||
|
||||
<!--
|
||||
This section shows how to generate the
|
||||
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
-->
|
||||
## 生成 API 参考文档
|
||||
|
||||
本节说明如何生成[已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。
|
||||
|
||||
<!--
|
||||
### Modifying the Makefile
|
||||
-->
|
||||
### 修改 Makefile 文件
|
||||
### Setting build variables
|
||||
|
||||
<!--
|
||||
Go to `<rdocs-base>`, and open the `Makefile` for editing:
|
||||
-->
|
||||
进入 `<rdocs-base>` 目录，然后编辑 `Makefile` 文件：
|
||||
### 设置构建变量 {#setting-build-variables}
|
||||
|
||||
<!--
|
||||
* Set `K8SROOT` to `<k8s-base>`.
|
||||
* Set `WEBROOT` to `<web-base>`.
|
||||
* Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
|
||||
if you want to build docs for Kubernetes 1.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`.
|
||||
* Set `K8S_ROOT` to `<k8s-base>`.
|
||||
* Set `K8S_WEBROOT` to `<web-base>`.
|
||||
* Set `K8S_RELEASE` to the minor version of the docs you want to build.
|
||||
For example, if you want to build docs for Kubernetes 1.17, set `K8S_RELEASE` to 1.17.
|
||||
-->
|
||||
* 设置 `K8SROOT` 为 `<k8s-base>`.
|
||||
* 设置 `WEBROOT` 为 `<web-base>`.
|
||||
* 设置 `MINOR_VERSION` 为要构建的文档的次要版本。例如，如果您想为 Kubernetes 1.15 构建文档，请将 `MINOR_VERSION` 设置为 15。保存并关闭 `Makefile` 文件。
|
||||
* 设置 `K8S_ROOT` 为 `<k8s-base>`.
|
||||
* 设置 `K8S_WEBROOT` 为 `<web-base>`.
|
||||
* 设置 `K8S_RELEASE` 为要构建的文档的版本。
|
||||
例如，如果您想为 Kubernetes 1.17 构建文档，请将 `K8S_RELEASE` 设置为 1.17。
|
||||
|
||||
<!--
|
||||
For example, update the following variables:
|
||||
-->
|
||||
例如，更新以下变量：
|
||||
<!-- For example, update the following variables: -->
|
||||
例如：
|
||||
|
||||
```
|
||||
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
|
||||
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
|
||||
MINOR_VERSION=15
|
||||
export K8S_WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
|
||||
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
|
||||
export K8S_RELEASE=1.17
|
||||
```
|
||||
|
||||
<!--
|
||||
### Copying the OpenAPI spec
|
||||
-->
|
||||
### 复制 OpenAPI 规范
|
||||
### Creating versioned directory and fetching Open API spec
|
||||
|
||||
<!--
|
||||
Run the following command in `<rdocs-base>`:
|
||||
The `updateapispec` build target creates the versioned build directory.
|
||||
After the directory is created, the Open API spec is fetched from the
|
||||
`<k8s-base>` repository. These steps ensure that the version
|
||||
of the configuration files and Kubernetes Open API spec match the release version.
|
||||
The versioned directory name follows the pattern of `v<major>_<minor>`.
|
||||
-->
|
||||
在 `<rdocs-base>` 目录中运行以下命令：
|
||||
### 创建版本目录并复制 OpenAPI 规范
|
||||
|
||||
构建目标 `updateapispec` 负责创建版本化的构建目录。
|
||||
目录创建了之后，从 `<k8s-base>` 仓库取回 OpenAPI 规范文件。
|
||||
这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。
|
||||
版本化目录的名称形式为 `v<major>_<minor>`。
|
||||
|
||||
```shell
|
||||
make updateapispec
|
||||
```
|
||||
|
||||
<!--
|
||||
The output shows that the file was copied:
|
||||
-->
|
||||
输出显示文件已被复制：
|
||||
|
||||
```shell
|
||||
cp ~/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
|
||||
```
|
||||
|
||||
<!--
|
||||
### Building the API reference docs
|
||||
|
||||
The `copyapi` target builds the API reference and
|
||||
copies the generated files to directories in `<web-base>`.
|
||||
Run the following command in `<rdocs-base>`:
|
||||
|
||||
-->
|
||||
### 构建 API 参考文档
|
||||
|
||||
<!--
|
||||
Run the following command in `<rdocs-base>`:
|
||||
-->
|
||||
构建目标 `copyapi` 会生成 API 参考文档并将所生成文件复制到
|
||||
`<web-base` 中的目录下。
|
||||
在 `<rdocs-base>` 目录中运行以下命令：
|
||||
|
||||
```shell
|
||||
make api
|
||||
cd <rdocs-base>
|
||||
make copyapi
|
||||
```
|
||||
|
||||
<!--
|
||||
Verify that these two files have been generated:
|
||||
-->
|
||||
<!-- Verify that these two files have been generated: -->
|
||||
验证是否已生成这两个文件：
|
||||
|
||||
```shell
|
||||
@@ -223,108 +186,83 @@ Verify that these two files have been generated:
|
||||
[ -e "<rdocs-base>/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
|
||||
```
|
||||
|
||||
<!--
|
||||
### Creating directories for published docs
|
||||
<!--
|
||||
Go to the base of your local `<web-base>`, and
|
||||
view which files have been modified:
|
||||
-->
|
||||
### 创建发布文档的目录
|
||||
|
||||
<!--
|
||||
Create the directories in `<web-base>` for the generated API reference files:
|
||||
-->
|
||||
在 `<web-base>` 目录中为生成的 API 参考文件创建目录：
|
||||
|
||||
```shell
|
||||
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>
|
||||
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/css
|
||||
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/fonts
|
||||
```
|
||||
|
||||
<!--
|
||||
## Copying the generated docs to the kubernetes/website repository
|
||||
-->
|
||||
## 将生成的文档复制到 kubernetes/website 仓库
|
||||
|
||||
<!--
|
||||
Run the following command in `<rdocs-base>` to copy the generated files to
|
||||
your local kubernetes/website repository:
|
||||
-->
|
||||
在 `<rdocs-base>` 目录中运行以下命令，将生成的文件复制到本地 kubernetes/website 仓库。
|
||||
|
||||
```shell
|
||||
make copyapi
|
||||
```
|
||||
|
||||
<!--
|
||||
Go to the base of your local kubernetes/website repository, and
|
||||
see which files have been modified:
|
||||
-->
|
||||
进入 kubernetes/website 仓库的本地主目录，并查看已修改的文件：
|
||||
进入本地 `<web-base>` 目录，检查哪些文件被更改：
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git status
|
||||
```
|
||||
|
||||
<!--
|
||||
The output shows the modified files:
|
||||
-->
|
||||
输出显示修改后的文件：
|
||||
<!-- The output is similar to: -->
|
||||
输出类似于：
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/css/font-awesome.min.css
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/css/stylesheet.css
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/fonts/FontAwesome.otf
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.eot
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.svg
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.ttf
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff2
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/index.html
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/jquery.scrollTo.min.js
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/navData.js
|
||||
static/docs/reference/generated/kubernetes-api/v1.15/scroll.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/jquery.scrollTo.min.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js
|
||||
```
|
||||
|
||||
<!--
|
||||
## Updating the API reference index pages
|
||||
|
||||
When generating reference documentation for a new release, update the file,
|
||||
`<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` with the new
|
||||
version number.
|
||||
-->
|
||||
## 更新 API 参考索引页面
|
||||
|
||||
在为新发行版本生成参考文档时，需要更新下面的文件，使之包含新的版本号：
|
||||
`<web-base>/content/en/docs/reference/kubernetes-api/api-index.md`。
|
||||
|
||||
<!--
|
||||
* Open `<web-base>/content/en/docs/reference/kubernetes-api/index.md` for editing, and update the API reference
|
||||
version number. For example:
|
||||
<!--
|
||||
* Open `<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` for editing,
|
||||
and update the API reference version number. For example:
|
||||
|
||||
```
|
||||
title: v1.17
|
||||
[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
|
||||
```
|
||||
-->
|
||||
* 打开 `<web-base>/content/en/docs/reference/kubernetes-api/index.md` 文件进行编辑，并且更新 API 参考版本号。例如：
|
||||
* 打开并编辑 `<web-base>/content/en/docs/reference/kubernetes-api/api-index.md`，
|
||||
API 参考的版本号。例如：
|
||||
|
||||
```
|
||||
---
|
||||
title: v1.15
|
||||
---
|
||||
|
||||
[Kubernetes API v1.15](/docs/reference/generated/kubernetes-api/v1.15/)
|
||||
title: v1.17
|
||||
[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
|
||||
```
|
||||
|
||||
<!--
|
||||
<!--
|
||||
* Open `<web-base>/content/en/docs/reference/_index.md` for editing, and add a
|
||||
new link for the latest API reference. Remove the oldest API reference version.
|
||||
There should be five links to the most recent API references.
|
||||
new link for the latest API reference. Remove the oldest API reference version.
|
||||
There should be five links to the most recent API references.
|
||||
-->
|
||||
* 打开 `<web-base>/content/en/docs/reference/_index.md` 文件进行编辑，并添加新链接以获取最新的 API 参考。移除最旧的 API 参考版本。应该有五个指向最新 API 参考的链接。
|
||||
|
||||
* 打开编辑 `<web-base>/content/en/docs/reference/_index.md`，添加指向最新 API 参考
|
||||
的链接，删除最老的 API 版本。
|
||||
通常保留最近的五个版本的 API 参考的链接。
|
||||
|
||||
<!--
|
||||
## Locally test the API reference
|
||||
-->
|
||||
## 在本地测试 API 参考
|
||||
|
||||
<!--
|
||||
Publish a local version of the API reference.
|
||||
Verify the [local preview](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/).
|
||||
-->
|
||||
## 在本地测试 API 参考
|
||||
|
||||
发布 API 参考的本地版本。
|
||||
验证 [本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/)。
|
||||
检查[本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/)。
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
@@ -333,11 +271,11 @@ make docker-serve
|
||||
|
||||
<!--
|
||||
## Commit the changes
|
||||
|
||||
In `<web-base>` run `git add` and `git commit` to commit the change.
|
||||
-->
|
||||
## 提交更改
|
||||
|
||||
<!--
|
||||
In `<web-base>` run `git add` and `git commit` to commit the change. -->
|
||||
在 `<web-base>` 中运行 `git add` 和 `git commit` 来提交更改。
|
||||
|
||||
<!--
|
||||
@@ -347,19 +285,18 @@ Submit your changes as a
|
||||
Monitor your pull request, and respond to reviewer comments as needed. Continue
|
||||
to monitor your pull request until it has been merged.
|
||||
-->
|
||||
将您的更改[创建 PR](/docs/contribute/start/) 提交到 [kubernetes/website](https://github.com/kubernetes/website) 仓库。监视您提交的 PR，并根据需要回复 reviewer 的评论。继续监视您的 PR，直到合并为止。
|
||||
|
||||
|
||||
基于你所生成的更改[创建 PR](/docs/contribute/start/)，
|
||||
提交到 [kubernetes/website](https://github.com/kubernetes/website) 仓库。
|
||||
监视您提交的 PR，并根据需要回复 reviewer 的评论。继续监视您的 PR，直到合并为止。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
<!--
|
||||
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
|
||||
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
-->
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generated-reference/kubernetes-components/)
|
||||
* [为 kubectl 命令集生成参考文档](/docs/home/contribute/generated-reference/kubectl/)
|
||||
* [为 Kubernetes 联邦 API 生成参考文档](/docs/home/contribute/generated-reference/federation-api/)
|
||||
* [生成参考文档快速入门](/docs/home/contribute/generate-ref-docs/quickstart/)
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [为 kubectl 命令集生成参考文档](/docs/home/contribute/generate-ref-docs/kubectl/)
|
||||
|
||||
|
||||
@@ -1,413 +1,50 @@
|
||||
---
|
||||
title: 为 Kubernetes 组件和工具生成参考页面
|
||||
title: 为 Kubernetes 组件和工具生成参考文档
|
||||
content_type: task
|
||||
weight: 120
|
||||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Generating Reference Pages for Kubernetes Components and Tools
|
||||
content_type: task
|
||||
---
|
||||
weight: 120
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to use the `update-imported-docs` tool to generate
|
||||
reference documentation for tools and components in the
|
||||
[Kubernetes](https://github.com/kubernetes/kubernetes) and
|
||||
[Federation](https://github.com/kubernetes/federation) repositories.
|
||||
This page shows how to build the Kubernetes component and tool reference pages.
|
||||
-->
|
||||
|
||||
本页面展示了如何使用 `update-imported-docs` 工具来为 [Kubernetes](https://github.com/kubernetes/kubernetes) 和 [Federation](https://github.com/kubernetes/federation) 仓库中的工具和组件生成参考文档。
|
||||
|
||||
|
||||
本页面描述如何构造 Kubernetes 组件和工具的参考文档。
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
|
||||
<!--
|
||||
* You need a machine that is running Linux or macOS.
|
||||
Start with the [Prerequisites section](/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)
|
||||
in the Reference Documentation Quickstart guide.
|
||||
-->
|
||||
|
||||
* 你需要一个运行着 Linux 或 macOS 操作系统的机器。
|
||||
|
||||
<!--
|
||||
* You need to have this software installed:
|
||||
|
||||
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
|
||||
* [Golang](https://golang.org/doc/install) version 1.9 or later
|
||||
|
||||
* [make](https://www.gnu.org/software/make/)
|
||||
|
||||
* [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
-->
|
||||
|
||||
* 你需要安装以下软件：
|
||||
|
||||
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
|
||||
* 1.9或更高版本的 [Golang](https://golang.org/doc/install)
|
||||
|
||||
* [make](https://www.gnu.org/software/make/)
|
||||
|
||||
* [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
|
||||
<!--
|
||||
* Your `$GOPATH` environment variable must be set.
|
||||
-->
|
||||
|
||||
* 在环境变量中设置 `$GOPATH`。
|
||||
|
||||
<!--
|
||||
* You need to know how to create a pull request to a GitHub repository.
|
||||
Typically, this involves creating a fork of the repository. For more
|
||||
information, see
|
||||
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/).
|
||||
-->
|
||||
|
||||
* 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的一个分支。想了解更多信息，请参见[创建一个文档 PR](/docs/home/contribute/create-pull-request/)。
|
||||
|
||||
|
||||
阅读参考文档快速入门指南中的[准备工作](/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)节。
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## Getting two repositories
|
||||
Follow the [Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
to generate the Kubernetes component and tool reference pages.
|
||||
-->
|
||||
|
||||
## 下载两个仓库
|
||||
|
||||
<!--
|
||||
If you don't already have the `kubernetes/website` repository, get it now:
|
||||
-->
|
||||
|
||||
如果你还没有下载过 `kubernetes/website` 仓库，现在下载：
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
cd $GOPATH/src
|
||||
go get github.com/kubernetes/website
|
||||
```
|
||||
|
||||
<!--
|
||||
Determine the base directory of your clone of the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
For example, if you followed the preceding step to get the repository,
|
||||
your base directory is `$GOPATH/src/github.com/kubernetes/website.`
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
-->
|
||||
|
||||
确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/kubernetes/website`。下文将该目录称为 `<web-base>`。
|
||||
|
||||
<!--
|
||||
If you plan on making changes to the ref docs, and if you don't already have
|
||||
the `kubernetes/kubernetes` repository, get it now:
|
||||
-->
|
||||
|
||||
如果你想对参考文档进行修改，但是你还没下载过 `kubernetes/kubernetes` 仓库，现在下载：
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
cd $GOPATH/src
|
||||
go get github.com/kubernetes/kubernetes
|
||||
```
|
||||
|
||||
<!--
|
||||
Determine the base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
For example, if you followed the preceding step to get the repository,
|
||||
your base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
-->
|
||||
|
||||
确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/kubernetes/kubernetes`。下文将该目录称为 `<k8s-base>`。
|
||||
|
||||
{{< note >}}
|
||||
<!--
|
||||
If you only need to generate, but not change, the reference docs, you don't need to
|
||||
manually get the `kubernetes/kubernetes` repository. When you run the `update-imported-docs`
|
||||
tool, it automatically clones the `kubernetes/kubernetes` repository.
|
||||
-->
|
||||
|
||||
如果你只想生成参考文档，而不需要修改，则不需要手动下载 `kubernetes/kubernetes` 仓库。当你运行 `update-imported-docs` 工具时，它会自动克隆 `kubernetes/kubernetes` 仓库。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Editing the Kubernetes source code
|
||||
-->
|
||||
|
||||
## 编辑 Kubernetes 源码
|
||||
|
||||
<!--
|
||||
The reference documentation for the Kubernetes components and tools is automatically
|
||||
generated from the Kubernetes source code. If you want to change the reference documentation,
|
||||
the first step is to change one or more comments in the Kubernetes source code. Make the
|
||||
change in your local kubernetes/kubernetes repository, and then submit a pull request to
|
||||
the master branch of
|
||||
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
|
||||
-->
|
||||
|
||||
Kubernetes 组件和工具的参考文档是基于 Kubernetes 源码自动生成的。如果想要修改参考文档，可以从修改 Kubernetes 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向 [github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 的 master 分支提交 PR。
|
||||
|
||||
<!--
|
||||
[PR 56942](https://github.com/kubernetes/kubernetes/pull/56942)
|
||||
is an example of a pull request that makes changes to comments in the Kubernetes
|
||||
source code.
|
||||
-->
|
||||
|
||||
[PR 56942](https://github.com/kubernetes/kubernetes/pull/56942) 是一个对 Kubernetes 源码中的注释进行修改的 PR 示例。
|
||||
|
||||
<!--
|
||||
Monitor your pull request, and respond to reviewer comments. Continue to monitor
|
||||
your pull request until it is merged into the master branch of the
|
||||
`kubernetes/kubernetes` repository.
|
||||
-->
|
||||
|
||||
跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 `kubernetes/kubernetes` 仓库的 master 分支中。
|
||||
|
||||
<!--
|
||||
## Cherry picking your change into a release branch
|
||||
-->
|
||||
|
||||
## 以 cherry-pick 方式将你的修改合入已发布分支
|
||||
|
||||
<!--
|
||||
Your change is now in the master branch, which is used for development of the next
|
||||
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
|
||||
version that has already been released, you need to propose that your change be cherry
|
||||
picked into the release branch.
|
||||
-->
|
||||
|
||||
你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 cherry-pick 方式合入已发布分支。
|
||||
|
||||
<!--
|
||||
For example, suppose the master branch is being used to develop Kubernetes 1.10, and
|
||||
you want to backport your change to the release-1.9 branch. For instructions on how
|
||||
to do this, see
|
||||
[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md).
|
||||
-->
|
||||
|
||||
例如，假设 master 分支正用于开发 Kubernetes 1.10 版本，而你希望将修改合入到已发布的 1.9 版本分支。相关的操作指南，请参见 [提议一个 cherry-pick 合入](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md)。
|
||||
|
||||
<!--
|
||||
Monitor your cherry-pick pull request until it is merged into the release branch.
|
||||
-->
|
||||
|
||||
跟踪你的 cherry-pick PR，直到它合入到已发布分支中。
|
||||
|
||||
{{< note >}}
|
||||
<!--
|
||||
Proposing a cherry pick requires that you have permission to set a label
|
||||
and a milestone in your pull request. If you don’t have those permissions, you will
|
||||
need to work with someone who can set the label and milestone for you.
|
||||
-->
|
||||
|
||||
提议一个 cherry-pick 合入，需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Overview of update-imported-docs
|
||||
-->
|
||||
|
||||
## update-imported-docs 概述
|
||||
|
||||
<!--
|
||||
The `update-imported-docs` tool is located in the `kubernetes/website/update-imported-docs/`
|
||||
directory. The tool performs the following steps:
|
||||
-->
|
||||
|
||||
`update-imported-docs` 工具在 `kubernetes/website/update-imported-docs/` 目录下。它执行以下步骤：
|
||||
|
||||
<!--
|
||||
1. Clones the related repositories specified in a configuration file. For the
|
||||
purpose of generating reference docs, the repositories that are cloned by
|
||||
default are `kubernetes-incubator/reference-docs` and `kubernetes/federation`.
|
||||
1. Runs commands under the cloned repositories to prepare the docs generator and
|
||||
then generates the Markdown files.
|
||||
1. Copies the generated Markdown files to a local clone of the `kubernetes/website`
|
||||
repository under locations specified in the configuration file.
|
||||
-->
|
||||
|
||||
1. 克隆配置文件中指定的相关仓库。为了生成参考文档，默认情况下克隆的仓库是 `kubernetes-incubator/reference-docs` 和 `kubernetes/federation`。
|
||||
1. 在克隆出的仓库下运行命令来准备文档生成器，然后生成 Markdown 文件。
|
||||
1. 将生成的 Markdown 文件复制到配置文件中指定的 `kubernetes/website` 仓库的本地目录中。
|
||||
|
||||
<!--
|
||||
When the Markdown files are in your local clone of the `kubernetes/website`
|
||||
repository, you can submit them in a
|
||||
[pull request](/docs/home/contribute/create-pull-request/)
|
||||
to `kubernetes/website`.
|
||||
-->
|
||||
|
||||
当 Markdown 文件放入 `kubernetes/website` 仓库的本地目录中后，你就可以创建 [PR](/docs/home/contribute/create-pull-request/) 将它们提交到 `kubernetes/website`。
|
||||
|
||||
<!--
|
||||
## Customizing the reference.yml config file
|
||||
-->
|
||||
|
||||
## 自定义 reference.yml 配置文件
|
||||
|
||||
<!--
|
||||
Open `<web-base>/update-imported-docs/reference.yml` for editing.
|
||||
Do not change the content for the `generate-command` entry unless you understand
|
||||
what it is doing and need to change the specified release branch.
|
||||
-->
|
||||
|
||||
打开 `<web-base>/update-imported-docs/reference.yml` 进行编辑。不要修改 `generate-command` 条目的内容，除非你了解它的作用，并且需要修改指定的已发布分支。
|
||||
|
||||
```yaml
|
||||
repos:
|
||||
- name: reference-docs
|
||||
remote: https://github.com/kubernetes-sigs/reference-docs.git
|
||||
# This and the generate-command below needs a change when reference-docs has
|
||||
# branches properly defined
|
||||
branch: master
|
||||
generate-command: |
|
||||
cd $GOPATH
|
||||
git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes
|
||||
cd src/k8s.io/kubernetes
|
||||
git checkout release-1.17
|
||||
make generated_files
|
||||
cp -L -R vendor $GOPATH/src
|
||||
rm -r vendor
|
||||
cd $GOPATH
|
||||
go get -v github.com/kubernetes-sigs/reference-docs/gen-compdocs
|
||||
cd src/github.com/kubernetes-sigs/reference-docs/
|
||||
make comp
|
||||
```
|
||||
|
||||
<!--
|
||||
In reference.yml, the `files` field is a list of `src` and `dst` fields. The `src` field
|
||||
specifies the location of a generated Markdown file, and the `dst` field specifies
|
||||
where to copy this file in the cloned `kubernetes/website` repository.
|
||||
For example:
|
||||
-->
|
||||
|
||||
在 reference.yml 中，`files` 字段是 `src` 和 `dst` 字段的列表。`src` 字段指定生成的 Markdown 文件的位置，而 `dst` 字段指定将此文件复制到 `kubernetes/website` 仓库的本地目录的哪个位置。例如：
|
||||
|
||||
```yaml
|
||||
repos:
|
||||
- name: reference-docs
|
||||
remote: https://github.com/kubernetes-incubator/reference-docs.git
|
||||
files:
|
||||
- src: gen-compdocs/build/kube-apiserver.md
|
||||
dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
|
||||
...
|
||||
```
|
||||
|
||||
<!--
|
||||
Note that when there are many files to be copied from the same source directory
|
||||
to the same destination directory, you can use wildcards in the value given to
|
||||
`src` and you can just provide the directory name as the value for `dst`.
|
||||
For example:
|
||||
-->
|
||||
|
||||
注意，当有许多文件要从同一个源目录复制到同一个目标目录时，可以使用通配符给 `src` 赋值，而使用目录名给 `dst` 赋值。例如：
|
||||
|
||||
```shell
|
||||
files:
|
||||
- src: gen-compdocs/build/kubeadm*.md
|
||||
dst: content/en/docs/reference/setup-tools/kubeadm/generated/
|
||||
```
|
||||
|
||||
<!--
|
||||
## Running the update-imported-docs tool
|
||||
-->
|
||||
|
||||
## 运行 update-imported-docs 工具
|
||||
|
||||
<!--
|
||||
After having reviewed and/or customized the `reference.yaml` file, you can run
|
||||
the `update-imported-docs` tool:
|
||||
-->
|
||||
|
||||
在检查与或自定义 `reference.yaml` 文件后，运行 `update-imported-docs` 工具：
|
||||
|
||||
```shell
|
||||
cd <web-base>/update-imported-docs
|
||||
./update-imported-docs reference.yml
|
||||
```
|
||||
|
||||
<!--
|
||||
## Adding and committing changes in kubernetes/website
|
||||
-->
|
||||
|
||||
## 在 kubernetes/website 中添加和提交修改
|
||||
|
||||
<!--
|
||||
List the files that were generated and copied to the `kubernetes/website`
|
||||
repository:
|
||||
-->
|
||||
|
||||
列出生成并准备合入到 `kubernetes/website` 仓库中的文件：
|
||||
|
||||
```
|
||||
cd <web-base>
|
||||
git status
|
||||
```
|
||||
|
||||
<!--
|
||||
The output shows the new and modified files. For example, the output
|
||||
might look like this:
|
||||
-->
|
||||
|
||||
输出展示了新增和修改的文件。例如，输出可能如下所示：
|
||||
|
||||
```shell
|
||||
...
|
||||
|
||||
modified: content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
|
||||
modified: content/en/docs/reference/command-line-tools-reference/federation-apiserver.md
|
||||
modified: content/en/docs/reference/command-line-tools-reference/federation-controller-manager.md
|
||||
modified: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
|
||||
modified: content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
|
||||
modified: content/en/docs/reference/command-line-tools-reference/kube-proxy.md
|
||||
modified: content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
|
||||
...
|
||||
```
|
||||
|
||||
<!--
|
||||
Run `git add` and `git commit` to commit the files.
|
||||
-->
|
||||
|
||||
运行 `git add` 和 `git commit` 将提交上述文件。
|
||||
|
||||
<!--
|
||||
## Creating a pull request
|
||||
-->
|
||||
|
||||
## 创建 PR
|
||||
|
||||
<!--
|
||||
Create a pull request to the `kubernetes/website` repository. Monitor your
|
||||
pull request, and respond to review comments as needed. Continue to monitor
|
||||
your pull request until it is merged.
|
||||
-->
|
||||
|
||||
对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。
|
||||
|
||||
<!--
|
||||
A few minutes after your pull request is merged, your updated reference
|
||||
topics will be visible in the
|
||||
[published documentation](/docs/home/).
|
||||
-->
|
||||
|
||||
在 PR 合入的几分钟后，你更新的参考主题将出现在[已发布文档](/docs/home/)中。
|
||||
|
||||
|
||||
按照[参考文档快速入门](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
指引，生成 Kubernetes 组件和工具的参考文档。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
<!--
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
|
||||
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
* [Contributing to the Upstream Kubernetes Project for Documentation](/docs/contribute/generate-ref-docs/contribute-upstream/)
|
||||
-->
|
||||
|
||||
* [为 kubectl 命令集生成参考文档](/docs/home/contribute/generated-reference/kubectl/)
|
||||
* [为 Kubernetes API 生成参考文档](/docs/home/contribute/generated-reference/kubernetes-api/)
|
||||
* [为 Kubernetes 联邦 API 生成参考文档](/docs/home/contribute/generated-reference/federation-api/)
|
||||
* [生成参考文档快速入门](/docs/home/contribute/generate-ref-docs/quickstart/)
|
||||
* [为 kubectll 命令生成参考文档](/docs/home/contribute/generate-ref-docs/kubectl/)
|
||||
* [为 Kubernetes API 生成参考文档](/docs/home/contribute/generate-ref-docs/kubernetes-api/)
|
||||
* [为上游 Kubernetes 项目做贡献以改进文档](/docs/contribute/generate-ref-docs/contribute-upstream/)
|
||||
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
<!--
|
||||
### Requirements:
|
||||
|
||||
- You need a machine that is running Linux or macOS.
|
||||
|
||||
- You need to have these tools installed:
|
||||
|
||||
- [Python](https://www.python.org/downloads/) v3.7.x
|
||||
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [Golang](https://golang.org/doc/install) version 1.13+
|
||||
- [Pip](https://pypi.org/project/pip/) used to install PyYAML
|
||||
- [PyYAML](https://pyyaml.org/) v5.1.2
|
||||
- [make](https://www.gnu.org/software/make/)
|
||||
- [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
- [Docker](https://docs.docker.com/engine/installation/) (Required only for `kubectl` command reference)
|
||||
-->
|
||||
|
||||
### 需求 {#requirements}
|
||||
|
||||
- 你需要一台 Linux 或 macOS 机器。
|
||||
|
||||
- 你需要安装以下工具：
|
||||
|
||||
- [Python](https://www.python.org/downloads/) v3.7.x
|
||||
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
- [Golang](https://golang.org/doc/install) 1.13+ 版本
|
||||
- 用来安装 PyYAML 的 [Pip](https://pypi.org/project/pip/)
|
||||
- [PyYAML](https://pyyaml.org/) v5.1.2
|
||||
- [make](https://www.gnu.org/software/make/)
|
||||
- [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
- [Docker](https://docs.docker.com/engine/installation/) （仅用于 `kubectl` 命令参考）
|
||||
|
||||
<!--
|
||||
- Your `PATH` environment variable must include the required build tools, such as the `Go` binary and `python`.
|
||||
|
||||
- You need to know how to create a pull request to a GitHub repository.
|
||||
This involves creating your own fork of the repository. For more
|
||||
information, see [Work from a local clone](/docs/contribute/intermediate/#work_from_a_local_clone).
|
||||
-->
|
||||
- 你的 `PATH` 环境变量必须包含所需要的构建工具，例如 `Go` 程序和 `python`。
|
||||
|
||||
- 你需要知道如何为一个 GitHub 仓库创建拉取请求（PR）。
|
||||
这牵涉到创建仓库的派生（fork）副本。
|
||||
有关信息可进一步查看[基于本地副本开展工作](/docs/contribute/intermediate/#work_from_a_local_clone)。
|
||||
|
||||
@@ -0,0 +1,405 @@
|
||||
---
|
||||
title: 快速入门
|
||||
content_type: task
|
||||
weight: 40
|
||||
---
|
||||
<!--
|
||||
title: Quickstart
|
||||
content_type: task
|
||||
weight: 40
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This page shows how to use the `update-imported-docs` script to generate
|
||||
the Kubernetes reference documentation. The script automates
|
||||
the build setup and generates the reference documentation for a release.
|
||||
-->
|
||||
本页讨论如何使用 `update-imported-docs` 脚本来生成 Kubernetes 参考文档。
|
||||
此脚本将构建的配置过程自动化，并为某个发行版本生成参考文档。
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
{{< include "prerequisites-ref-docs.md" >}}
|
||||
|
||||
<!-- steps -->
|
||||
<!--
|
||||
## Getting the docs repository
|
||||
|
||||
Make sure your `website` fork is up-to-date with the `kubernetes/website` master and clone
|
||||
your `website` fork.
|
||||
-->
|
||||
## 获取文档仓库 {#getting-the-docs-repository}
|
||||
|
||||
确保你的 `website` 派生仓库与 `kubernetes/website` 主分支一致，并克隆
|
||||
你的派生仓库。
|
||||
|
||||
```shell
|
||||
mkdir github.com
|
||||
cd github.com
|
||||
git clone git@github.com:<your_github_username>/website.git
|
||||
```
|
||||
|
||||
<!--
|
||||
Determine the base directory of your clone. For example, if you followed the
|
||||
preceding step to get the repository, your base directory is
|
||||
`github.com/website.` The remaining steps refer to your base directory as
|
||||
`<web-base>`.
|
||||
|
||||
{{< note>}}
|
||||
If you want to change the content of the component tools and API reference,
|
||||
see the [contributing upstream guide](/docs/contribute/generate-ref-docs/contribute-upstream).
|
||||
{{< /note >}}
|
||||
-->
|
||||
确定你的克隆副本的根目录。例如，如果你按照前面的步骤获取了仓库，你的根目录
|
||||
会是 `github.com/website`。接下来的步骤中，`<web-base>` 用来指代你的根目录。
|
||||
|
||||
{{< note>}}
|
||||
如果你希望更改构建工具和 API 参考资料，可以阅读
|
||||
[上游贡献指南](/docs/contribute/generate-ref-docs/contribute-upstream).
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Overview of update-imported-docs
|
||||
|
||||
The `update-imported-docs` script is located in the `<web-base>/update-imported-docs/`
|
||||
directory.
|
||||
|
||||
The script builds the following references:
|
||||
|
||||
* Component and tool reference pages
|
||||
* The `kubectl` command reference
|
||||
* The Kubernetes API reference
|
||||
-->
|
||||
## update-imported-docs 的概述
|
||||
|
||||
脚本 `update-imported-docs` 位于 `<web-base>/update-imported-docs/` 目录下，
|
||||
能够生成以下参考文档：
|
||||
|
||||
* Kubernetes 组件和工具的参考页面
|
||||
* `kubectl` 命令参考文档
|
||||
* Kubernetes API 参考文档
|
||||
|
||||
<!--
|
||||
The `update-imported-docs` script generates the Kubernetes reference documentation
|
||||
from the Kubernetes source code. The script creates a temporary directory
|
||||
under `/tmp` on your machine and clones the required repositories: `kubernetes/kubernetes` and
|
||||
`kubernetes-sigs/reference-docs` into this directory.
|
||||
The script sets your `GOPATH` to this temporary directory.
|
||||
Three additional environment variables are set:
|
||||
|
||||
* `K8S_RELEASE`
|
||||
* `K8S_ROOT`
|
||||
* `K8S_WEBROOT`
|
||||
-->
|
||||
脚本 `update-imported-docs` 基于 Kubernetes 源代码生成参考文档。
|
||||
过程中会在你的机器的 `/tmp` 目录下创建临时目录，克隆所需要的仓库
|
||||
`kubernetes/kubernetes` 和 `kubernetes-sigs/reference-docs` 到此临时目录。
|
||||
脚本会将 `GOPATH` 环境变量设置为指向此临时目录。
|
||||
此外，脚本会设置三个环境变量：
|
||||
|
||||
* `K8S_RELEASE`
|
||||
* `K8S_ROOT`
|
||||
* `K8S_WEBROOT`
|
||||
|
||||
<!--
|
||||
The script requires two arguments to run successfully:
|
||||
|
||||
* A YAML configuration file (`reference.yml`)
|
||||
* A release version, for example:`1.17`
|
||||
|
||||
The configuration file contains a `generate-command` field.
|
||||
The `generate-command` field defines a series of build instructions
|
||||
from `kubernetes-sigs/reference-docs/Makefile`. The `K8S_RELEASE` variable
|
||||
determines the version of the release.
|
||||
-->
|
||||
脚本需要两个参数才能成功运行：
|
||||
|
||||
* 一个 YAML 配置文件（`reference.yml`）
|
||||
* 一个发行版本字符串，例如：`1.17`
|
||||
|
||||
配置文件中包含 `generate-command` 字段，其中定义了一系列来自于
|
||||
`kubernetes-sigs/reference-docs/Makefile` 的构建指令。
|
||||
变量 `K8S_RELEASE` 用来确定所针对的发行版本。
|
||||
|
||||
<!--
|
||||
The `update-imported-docs` script performs the following steps:
|
||||
|
||||
1. Clones the related repositories specified in a configuration file. For the
|
||||
purpose of generating reference docs, the repository that is cloned by
|
||||
default is `kubernetes-sigs/reference-docs`.
|
||||
1. Runs commands under the cloned repositories to prepare the docs generator and
|
||||
then generates the HTML and Markdown files.
|
||||
1. Copies the generated HTML and Markdown files to a local clone of the `<web-base>`
|
||||
repository under locations specified in the configuration file.
|
||||
1. Updates `kubectl` command links from `kubectl`.md to the refer to
|
||||
the sections in the `kubectl` command reference.
|
||||
-->
|
||||
脚本 `update-imported-docs` 执行以下步骤：
|
||||
|
||||
1. 克隆配置文件中所指定的相关仓库。就生成参考文档这一目的而言，要克隆的
|
||||
仓库默认为 `kubernetes-sigs/reference-docs`。
|
||||
1. 在所克隆的仓库下运行命令，准备文档生成器，之后生成 HTML 和 Markdown 文件。
|
||||
1. 将所生成的 HTML 和 Markdown 文件复制到 `<web-base>` 本地克隆副本中，
|
||||
放在配置文件中所指定的目录下。
|
||||
1. 更新 `kubectl.md` 文件中对 `kubectl` 命令文档的链接，使之指向 `kubectl`
|
||||
命令参考中对应的节区。
|
||||
|
||||
<!--
|
||||
When the generated files are in your local clone of the `<web-base>`
|
||||
repository, you can submit them in a [pull request](/docs/contribute/start/)
|
||||
to `<web-base>`.
|
||||
-->
|
||||
当所生成的文件已经被放到 `<web-base>` 目录下，你就可以将其提交到你的派生副本中，
|
||||
并基于所作提交发起[拉取请求（PR）](/docs/contribute/start/)到 k/website 仓库。
|
||||
|
||||
<!--
|
||||
## Configuration file format
|
||||
|
||||
Each configuration file may contain multiple repos that will be imported together. When
|
||||
necessary, you can customize the configuration file by manually editing it. You
|
||||
may create new config files for importing other groups of documents.
|
||||
The following is an example of the YAML configuration file:
|
||||
-->
|
||||
## 配置文件格式 {#configuration-file-format}
|
||||
|
||||
每个配置文件可以包含多个被导入的仓库。当必要时，你可以通过手工编辑此文件进行定制。
|
||||
你也可以通过创建新的配置文件来导入其他文档集合。
|
||||
下面是 YAML 配置文件的一个例子：
|
||||
|
||||
```yaml
|
||||
repos:
|
||||
- name: community
|
||||
remote: https://github.com/kubernetes/community.git
|
||||
branch: master
|
||||
files:
|
||||
- src: contributors/devel/README.md
|
||||
dst: docs/imported/community/devel.md
|
||||
- src: contributors/guide/README.md
|
||||
dst: docs/imported/community/guide.md
|
||||
```
|
||||
|
||||
<!--
|
||||
Single page Markdown documents, imported by the tool, must adhere to
|
||||
the [Documentation Style Guide](/docs/contribute/style/style-guide/).
|
||||
-->
|
||||
通过工具导入的单页面的 Markdown 文档必须遵从
|
||||
[文档样式指南](/docs/contribute/style/style-guide/)。
|
||||
|
||||
<!--
|
||||
## Customizing reference.yml
|
||||
|
||||
Open `<web-base>/update-imported-docs/reference.yml` for editing.
|
||||
Do not change the content for the `generate-command` field unless you understand
|
||||
how the command is used to build the references.
|
||||
You should not need to update `reference.yml`. At times, changes in the
|
||||
upstream source code, may require changes to the configuration file
|
||||
(for example: golang version dependencies and third-party library changes).
|
||||
If you encounter build issues, contact the SIG-Docs team on the
|
||||
[#sig-docs Kubernetes Slack channel](https://kubernetes.slack.com).
|
||||
-->
|
||||
|
||||
## 定制 reference.yml
|
||||
|
||||
打开 `<web-base>/update-imported-docs/reference.yml` 文件进行编辑。
|
||||
在不了解参考文档构造命令的情况下，不要更改 `generate-command` 字段的内容。
|
||||
你一般不需要更新 `reference.yml` 文件。不过也有时候上游的源代码发生变化，
|
||||
导致需要对配置文件进行更改（例如：Golang 版本依赖或者第三方库发生变化）。
|
||||
如果你遇到类似问题，请在 [Kubernetes Slack 的 #sig-docs 频道](https://kubernetes.slack.com)
|
||||
联系 SIG-Docs 团队。
|
||||
|
||||
<!--
|
||||
{{< note >}}
|
||||
The `generate-command` is an optional entry, which can be used to run a
|
||||
given command or a short script to generate the docs from within a repository.
|
||||
{{< /note >}}
|
||||
|
||||
In `reference.yml`, `files` contains a list of `src` and `dst` fields.
|
||||
The `src` field contains the location of a generated Markdown file in the cloned
|
||||
`kubernetes-sigs/reference-docs` build directory, and the `dst` field specifies
|
||||
where to copy this file in the cloned `kubernetes/website` repository.
|
||||
For example:
|
||||
-->
|
||||
|
||||
{{< note >}}
|
||||
注意，`generate-command` 是一个可选项，用来运行指定命令或者短脚本以在仓库
|
||||
内生成文档。
|
||||
{{< /note >}}
|
||||
|
||||
在 `reference.yml` 文件中，`files` 属性包含了一组 `src` 和 `dst` 字段。
|
||||
`src` 字段给出在所克隆的 `kubernetes-sigs/reference-docs` 构造目录中生成的
|
||||
Markdown 文件的位置，而 `dst` 字段则给出了对应文件要复制到的、所克隆的
|
||||
`kubernetes/website` 仓库中的位置。例如：
|
||||
|
||||
```yaml
|
||||
repos:
|
||||
- name: reference-docs
|
||||
remote: https://github.com/kubernetes-sigs/reference-docs.git
|
||||
files:
|
||||
- src: gen-compdocs/build/kube-apiserver.md
|
||||
dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
|
||||
...
|
||||
```
|
||||
|
||||
<!--
|
||||
Note that when there are many files to be copied from the same source directory
|
||||
to the same destination directory, you can use wildcards in the value given to
|
||||
`src`. You must provide the directory name as the value for `dst`.
|
||||
For example:
|
||||
-->
|
||||
注意，如果从同一源目录中有很多文件要复制到目标目录，你可以在为 `src` 所设置的
|
||||
值中使用通配符。这时，为 `dst` 所设置的值必须是目录名称。例如：
|
||||
|
||||
```yaml
|
||||
files:
|
||||
- src: gen-compdocs/build/kubeadm*.md
|
||||
dst: content/en/docs/reference/setup-tools/kubeadm/generated/
|
||||
```
|
||||
|
||||
<!--
|
||||
## Running the update-imported-docs tool
|
||||
|
||||
You can run the `update-imported-docs` tool as follows:
|
||||
-->
|
||||
## 运行 update-imported-docs 工具
|
||||
|
||||
你可以用如下方式运行 `update-imported-docs` 工具：
|
||||
|
||||
```shell
|
||||
cd <web-base>/update-imported-docs
|
||||
./update-imported-docs <configuration-file.yml> <release-version>
|
||||
```
|
||||
|
||||
<!-- For example: -->
|
||||
例如：
|
||||
|
||||
```shell
|
||||
./update-imported-docs reference.yml 1.17
|
||||
```
|
||||
|
||||
<!-- Revisit: is the release configuration used -->
|
||||
<!-- ## Fixing Links
|
||||
|
||||
The `release.yml` configuration file contains instructions to fix relative links.
|
||||
To fix relative links within your imported files, set the`gen-absolute-links`
|
||||
property to `true`. You can find an example of this in
|
||||
[`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml).
|
||||
-->
|
||||
## 修复链接
|
||||
|
||||
配置文件 `release.yml` 中包含用来修复相对链接的指令。
|
||||
若要修复导入文件中的相对链接，将 `gen-absolute-links` 属性设置为 `true`。
|
||||
你可以在 [`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml)
|
||||
文件中找到示例。
|
||||
|
||||
<!--
|
||||
## Adding and committing changes in kubernetes/website
|
||||
|
||||
List the files that were generated and copied to `<web-base>`:
|
||||
-->
|
||||
## 添加并提交 kubernetes/website 中的变更
|
||||
|
||||
枚举新生成并复制到 `<web-base>` 的文件：
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git status
|
||||
```
|
||||
|
||||
<!--
|
||||
The output shows the new and modified files. The generated output varies
|
||||
depending upon changes made to the upstream source code.
|
||||
|
||||
### Generated component tool files
|
||||
-->
|
||||
输出显示新生成和已修改的文件。取决于上游源代码的修改多少，
|
||||
所生成的输出也会不同。
|
||||
|
||||
### 生成的 Kubernetes 组件文档
|
||||
|
||||
```
|
||||
content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
|
||||
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
|
||||
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
|
||||
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
|
||||
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
|
||||
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
|
||||
content/en/docs/reference/kubectl/kubectl.md
|
||||
```
|
||||
|
||||
<!-- ### Generated kubectl command reference files -->
|
||||
### 生成的 kubectl 命令参考文件
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubectl/kubectl-commands.html
|
||||
static/docs/reference/generated/kubectl/navData.js
|
||||
static/docs/reference/generated/kubectl/scroll.js
|
||||
static/docs/reference/generated/kubectl/stylesheet.css
|
||||
static/docs/reference/generated/kubectl/tabvisibility.js
|
||||
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
|
||||
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
|
||||
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
|
||||
static/docs/reference/generated/kubectl/css/font-awesome.min.css
|
||||
```
|
||||
|
||||
<!-- ### Generated Kubernetes API reference directories and files -->
|
||||
### 生成的 Kubernetes API 参考目录与文件
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/query.scrollTo.min.js
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff
|
||||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2
|
||||
```
|
||||
|
||||
<!--
|
||||
Run `git add` and `git commit` to commit the files.
|
||||
|
||||
## Creating a pull request
|
||||
|
||||
Create a pull request to the `kubernetes/website` repository. Monitor your
|
||||
pull request, and respond to review comments as needed. Continue to monitor
|
||||
your pull request until it is merged.
|
||||
|
||||
A few minutes after your pull request is merged, your updated reference
|
||||
topics will be visible in the
|
||||
[published documentation](/docs/home/).
|
||||
-->
|
||||
运行 `git add` 和 `git commit` 提交文件。
|
||||
|
||||
## 创建拉取请求 {#creating-a-pull-request}
|
||||
|
||||
接下来创建一个对 `kubernetes/website` 仓库的拉取请求（PR）。
|
||||
监视所创建的 PR，并根据需要对评阅意见给出反馈。
|
||||
继续监视该 PR 直到其被合并为止。
|
||||
|
||||
当你的 PR 被合并几分钟之后，你所做的对参考文档的变更就会出现
|
||||
[发布的文档](/docs/home/)上。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
To generate the individual reference documentation by manually setting up the required build repositories and
|
||||
running the build targets, see the following guides:
|
||||
|
||||
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
-->
|
||||
要手动设置所需的构造仓库，执行构建目标，以生成各个参考文档，可参考下面的指南：
|
||||
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [为 kubeclt 命令生成参考文档](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
* [为 Kubernetes API 生成参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
|
||||
@@ -271,9 +271,9 @@ To apply:
|
||||
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) file
|
||||
in the `kubernetes/website` repository.
|
||||
|
||||
{{ note }}
|
||||
{{< note >}}
|
||||
If you aren't sure where to add yourself, add yourself to `sig-docs-en-reviews`.
|
||||
{{ /note }}
|
||||
{{< /note >}}
|
||||
|
||||
2. Assign the PR to one or more SIG-Docs approvers (user names listed under `sig-docs-{language}-owners`).
|
||||
|
||||
@@ -283,9 +283,9 @@ If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added
|
||||
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS)
|
||||
文件的特定节。
|
||||
|
||||
{{ note }}
|
||||
{{< note >}}
|
||||
如果你不确定要添加到哪个位置，可以将自己添加到 `sig-docs-en-reviews`。
|
||||
{{ /note }}
|
||||
{{< /note >}}
|
||||
|
||||
2. 将 PR 指派给一个或多个 SIG Docs 批准人（`sig-docs-{language}-owners`
|
||||
下列举的用户名）。
|
||||
@@ -383,9 +383,9 @@ To apply:
|
||||
|
||||
1. Open a pull request adding yourself to a section of the [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS) file in the `kubernetes/website` repository.
|
||||
|
||||
{{ note }}
|
||||
{{< note >}}
|
||||
If you aren't sure where to add yourself, add yourself to `sig-docs-en-owners`.
|
||||
{{ /note }}
|
||||
{{< /note >}}
|
||||
|
||||
2. Assign the PR to one or more current SIG Docs approvers.
|
||||
|
||||
@@ -397,9 +397,9 @@ If approved, a SIG Docs lead adds you to the appropriate GitHub team. Once added
|
||||
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS)
|
||||
文件的对应节区。
|
||||
|
||||
{{ note }}
|
||||
{{< note >}}
|
||||
如果你不确定要添加到哪个位置，可以将自己添加到 `sig-docs-en-owners` 中。
|
||||
{{ /note }}
|
||||
{{< /note >}}
|
||||
|
||||
2. 将 PR 指派给一个或多个 SIG Docs 批准人。
|
||||
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: 评阅变更
|
||||
weight: 30
|
||||
---
|
||||
<!--
|
||||
title: Reviewing changes
|
||||
weight: 30
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
This section describes how to review content.
|
||||
-->
|
||||
本节描述如何对内容进行评阅。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
@@ -0,0 +1,432 @@
|
||||
---
|
||||
title: 评阅人和批准人文档
|
||||
linktitle: 评阅人和批准人
|
||||
slug: for-approvers
|
||||
content_type: concept
|
||||
weight: 20
|
||||
---
|
||||
<!--
|
||||
title: Reviewing for approvers and reviewers
|
||||
linktitle: For approvers and reviewers
|
||||
slug: for-approvers
|
||||
content_type: concept
|
||||
weight: 20
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
SIG Docs [Reviewers](/docs/contribute/participating/#reviewers) and [Approvers](/docs/contribute/participating/#approvers) do a few extra things when reviewing a change.
|
||||
|
||||
Every week a specific docs approver volunteers to triage
|
||||
and review pull requests. This
|
||||
person is the "PR Wrangler" for the week. See the
|
||||
[PR Wrangler scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers) for more information. To become a PR Wrangler, attend the weekly SIG Docs meeting and volunteer. Even if you are not on the schedule for the current week, you can still review pull
|
||||
requests (PRs) that are not already under active review.
|
||||
|
||||
In addition to the rotation, a bot assigns reviewers and approvers
|
||||
for the PR based on the owners for the affected files.
|
||||
-->
|
||||
SIG Docs [评阅人（Reviewers）](/docs/contribute/participating/#reviewers)
|
||||
和[批准人（Approvers）](/docs/contribute/participating/#approvers)
|
||||
在对变更进行评审时需要做一些额外的事情。
|
||||
|
||||
每周都有一个特定的文档批准人自愿负责对 PR 进行分类和评阅。
|
||||
此角色称作该周的“PR 管理者（PR Wrangler）”。
|
||||
相关信息可参考 [PR Wrangler 排班表](https://github.com/kubernetes/website/wiki/PR-Wranglers)。
|
||||
要成为 PR Wangler，需要参加每周的 SIG Docs 例会，并自愿报名。
|
||||
即使当前这周排班没有轮到你，你仍可以评阅那些尚未被积极评阅的 PRs。
|
||||
|
||||
除了上述的轮值安排，后台机器人也会为基于所影响的文件来为 PR
|
||||
指派评阅人和批准人。
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
## Reviewing a PR
|
||||
Kubernetes documentation follows the [Kubernetes code review process](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process).
|
||||
|
||||
Everything described in [Reviewing a pull request](/docs/contribute/review/reviewing-prs) applies, but Reviewers and Approvers should also do the following:
|
||||
-->
|
||||
## 评阅 PR
|
||||
|
||||
Kubernetes 文档遵循 [Kubernetes 代码评阅流程](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process)。
|
||||
|
||||
[评阅 PR](/docs/contribute/review/reviewing-prs) 文档中所描述的所有规程都适用，
|
||||
不过评阅人和批准人还要做以下工作：
|
||||
|
||||
<!--
|
||||
- Using the `/assign` Prow command to assign a specific reviewer to a PR as needed. This is extra important
|
||||
when it comes to requesting technical review from code contributors.
|
||||
|
||||
{{< note >}}
|
||||
Look at the `reviewers` field in the front-matter at the top of a Markdown file to see who can
|
||||
provide technical review.
|
||||
{{< /note >}}
|
||||
|
||||
- Making sure the PR follows the [Content](/docs/contribute/style/content-guide/) and [Style](/docs/contribute/style/style-guide/) guides; link the author to the relevant part of the guide(s) if it doesn't.
|
||||
- Using the GitHub **Request Changes** option when applicable to suggest changes to the PR author.
|
||||
- Changing your review status in GitHub using the `/approve` or `/lgtm` Prow commands, if your suggestions are implemented.
|
||||
-->
|
||||
- 根据需要使用 Prow 命令 `/assign` 指派特定的评阅人。如果某个 PR
|
||||
需要来自代码贡献者的技术审核时，这一点非常重要。
|
||||
|
||||
{{< note >}}
|
||||
你可以查看 Markdown 文件的文件头，其中的 `reviewers` 字段给出了哪些人可以为文档提供技术审核。
|
||||
{{< /note >}}
|
||||
|
||||
- 确保 PR 遵从[内容指南](/docs/contribute/style/content-guide/)和[样式指南](/docs/contribute/style/style-guide/)；
|
||||
如果 PR 没有达到要求，指引作者阅读指南中的相关部分。
|
||||
- 适当的时候使用 GitHub **Request Changes** 选项，建议 PR 作者实施所建议的修改。
|
||||
- 当你所提供的建议被采纳后，在 GitHub 中使用 `/approve` 或 `/lgtm` Prow 命令，改变评审状态。
|
||||
|
||||
<!--
|
||||
## Commit into another person's PR
|
||||
|
||||
Leaving PR comments is helpful, but there might be times when you need to commit
|
||||
into another person's PR instead.
|
||||
|
||||
Do not "take over" for another person unless they explicitly ask
|
||||
you to, or you want to resurrect a long-abandoned PR. While it may be faster
|
||||
in the short term, it deprives the person of the chance to contribute.
|
||||
|
||||
The process you use depends on whether you need to edit a file that is already
|
||||
in the scope of the PR, or a file that the PR has not yet touched.
|
||||
-->
|
||||
## 提交到他人的 PR
|
||||
|
||||
为 PR 留下评语是很有用的，不过有时候你需要向他人的 PR 提交内容。
|
||||
|
||||
除非他人明确请求你的帮助或者你希望重启一个被放弃很久的 PR，不要“接手”他人的工作。
|
||||
尽管短期看来这样做可以提高效率，但是也剥夺了他人提交贡献的机会。
|
||||
|
||||
你所要遵循的流程取决于你需要编辑已经在 PR 范畴的文件，还是 PR 尚未触碰的文件。
|
||||
|
||||
<!--
|
||||
You can't commit into someone else's PR if either of the following things is
|
||||
true:
|
||||
|
||||
- If the PR author pushed their branch directly to the
|
||||
[https://github.com/kubernetes/website/](https://github.com/kubernetes/website/)
|
||||
repository. Only a reviewer with push access can commit to another user's PR.
|
||||
|
||||
{{< note >}}
|
||||
Encourage the author to push their branch to their fork before
|
||||
opening the PR next time.
|
||||
{{< /note >}}
|
||||
|
||||
- The PR author explicitly disallows edits from approvers.
|
||||
-->
|
||||
如果处于下列情况之一，你不可以向别人的 PR 提交内容：
|
||||
|
||||
- 如果 PR 作者是直接将自己的分支提交到
|
||||
[https://github.com/kubernetes/website/](https://github.com/kubernetes/website/)
|
||||
仓库。只有具有推送权限的评阅人才可以向他人的 PR 提交内容。
|
||||
|
||||
{{< note >}}
|
||||
我们应鼓励作者下次将分支推送到自己的克隆副本之后再发起 PR。
|
||||
{{< /note >}}
|
||||
|
||||
- PR 作者明确地禁止批准人编辑他/她的 PR。
|
||||
|
||||
<!--
|
||||
## Prow commands for reviewing
|
||||
|
||||
[Prow](https://github.com/kubernetes/test-infra/blob/master/prow/README.md) is
|
||||
the Kubernetes-based CI/CD system that runs jobs against pull requests (PRs). Prow
|
||||
enables chatbot-style commands to handle GitHub actions across the Kubernetes
|
||||
organization, like [adding and removing labels](#adding-and-removing-issue-labels), closing issues, and assigning an approver. Enter Prow commands as GitHub comments using the `/<command-name>` format.
|
||||
|
||||
The most common prow commands reviewers and approvers use are:
|
||||
-->
|
||||
## 评阅用的 Prow 命令
|
||||
|
||||
[Prow](https://github.com/kubernetes/test-infra/blob/master/prow/README.md)
|
||||
是基于 Kubernetes 的 CI/CD 系统，基于拉取请求（PR）的触发运行不同任务。
|
||||
Prow 使得我们可以使用会话机器人一样的命令跨整个 Kubernetes 组织处理 GitHub
|
||||
动作，例如[添加和删除标签](#adding-and-removing-issue-labels)、关闭 Issues
|
||||
以及指派批准人等等。你可以使用 `/<命令名称>` 的形式以 GitHub 评论的方式输入
|
||||
Prow 命令。
|
||||
|
||||
评阅人和批准人最常用的 Prow 命令有：
|
||||
|
||||
<!--
|
||||
{{< table caption="Prow commands for reviewing" >}}
|
||||
Prow Command | Role Restrictions | Description
|
||||
:------------|:------------------|:-----------
|
||||
`/lgtm` | Anyone, but triggers automation if a Reviewer or Approver uses it | Signals that you've finished reviewing a PR and are satisfied with the changes.
|
||||
`/approve` | Approvers | Approves a PR for merging.
|
||||
`/assign` | Reviewers or Approvers | Assigns a person to review or approve a PR
|
||||
`/close` | Reviewers or Approvers | Closes an issue or PR.
|
||||
`/hold` | Anyone | Adds the `do-not-merge/hold` label, indicating the PR cannot be automatically merged.
|
||||
`/hold cancel` | Anyone | Removes the `do-not-merge/hold` label.
|
||||
{{< /table >}}
|
||||
|
||||
See [the Prow command reference](https://prow.k8s.io/command-help) to see the full list
|
||||
of commands you can use in a PR.
|
||||
-->
|
||||
{{< table caption="评阅用 Prow 命令" >}}
|
||||
Prow 命令 | 角色限制 | 描述
|
||||
:------------|:------------------|:-----------
|
||||
`/lgtm` | 任何人均可使用，但只有评阅人和批准人使用此命令的时候才会触发自动化操作 | 用来表明你已经完成 PR 的评阅并对其所作变更表示满意
|
||||
`/approve` | 批准人 | 批准某 PR 可以合并
|
||||
`/assign` |评阅人或批准人 | 指派某人来评阅或批准某 PR
|
||||
`/close` | 评阅人或批准人 | 关闭 Issue 或 PR
|
||||
`/hold` | 任何人 | 添加 `do-not-merge/hold` 标签，用来表明 PR 不应被自动合并
|
||||
`/hold cancel` | 任何人 | 去掉 `do-not-merge/hold` 标签
|
||||
{{< /table >}}
|
||||
|
||||
请参考 [Prow 命令指南](https://prow.k8s.io/command-help)，了解你可以在 PR
|
||||
中使用的命令的完整列表。
|
||||
|
||||
<!--
|
||||
## Triage and categorize issues
|
||||
|
||||
In general, SIG Docs follows the [Kubernetes issue triage](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md) process and uses the same labels.
|
||||
|
||||
This GitHub Issue [filter](https://github.com/kubernetes/website/issues?q=is%3Aissue+is%3Aopen+-label%3Apriority%2Fbacklog+-label%3Apriority%2Fimportant-longterm+-label%3Apriority%2Fimportant-soon+-label%3Atriage%2Fneeds-information+-label%3Atriage%2Fsupport+sort%3Acreated-asc)
|
||||
finds issues that might need triage.
|
||||
-->
|
||||
## 对 Issue 进行诊断和分类
|
||||
|
||||
一般而言，SIG Docs 遵从 [Kubernetes issue 判定](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md) 流程并使用相同的标签。
|
||||
|
||||
此 GitHub Issue
|
||||
[过滤器](https://github.com/kubernetes/website/issues?q=is%3Aissue+is%3Aopen+-label%3Apriority%2Fbacklog+-label%3Apriority%2Fimportant-longterm+-label%3Apriority%2Fimportant-soon+-label%3Atriage%2Fneeds-information+-label%3Atriage%2Fsupport+sort%3Acreated-asc)
|
||||
可以用来查找需要评判的 Issues。
|
||||
|
||||
<!--
|
||||
### Triaging an issue
|
||||
|
||||
1. Validate the issue
|
||||
- Make sure the issue is about website documentation. Some issues can be closed quickly by
|
||||
answering a question or pointing the reporter to a resource. See the
|
||||
[Support requests or code bug reports](#support-requests-or-code-bug-reports) section for details.
|
||||
- Assess whether the issue has merit.
|
||||
- Add the `triage/needs-information` label if the issue doesn't have enough
|
||||
detail to be actionable or the template is not filled out adequately.
|
||||
- Close the issue if it has both the `lifecycle/stale` and `triage/needs-information` labels.
|
||||
-->
|
||||
|
||||
### 评判 Issue {#triaging-an-issue}
|
||||
|
||||
1. 验证 Issue 的合法性
|
||||
|
||||
- 确保 Issue 是关于网站文档的。某些 Issue 可以通过回答问题或者为报告者提供
|
||||
资源链接来快速关闭。
|
||||
参考[请求支持或代码缺陷报告](#support-requests-or-code-bug-reports)
|
||||
节以了解详细信息。
|
||||
- 评估该 Issue 是否有价值。
|
||||
- 如果 Issue 缺少足够的细节以至于无法采取行动，或者报告者没有通过模版提供
|
||||
足够信息，可以添加 `triage/needs-information` 标签。
|
||||
- 如果 Issue 同时标注了 `lifecycle/stale` 和 `triage/needs-information`
|
||||
标签，可以直接关闭。
|
||||
|
||||
<!--
|
||||
2. Add a priority label (the
|
||||
[Issue Triage Guidelines](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority) define priority labels in detail)
|
||||
|
||||
< table caption="Issue labels" >
|
||||
Label | Description
|
||||
:------------|:------------------
|
||||
`priority/critical-urgent` | Do this right now.
|
||||
`priority/important-soon` | Do this within 3 months.
|
||||
`priority/important-longterm` | Do this within 6 months.
|
||||
`priority/backlog` | Deferrable indefinitely. Do when resources are available.
|
||||
`priority/awaiting-more-evidence` | Placeholder for a potentially good issue so it doesn't get lost.
|
||||
`help` or `good first issue` | Suitable for someone with very little Kubernetes or SIG Docs experience. See [Help Wanted and Good First Issue Labels](https://github.com/kubernetes/community/blob/master/contributors/guide/help-wanted.md) for more information.
|
||||
|
||||
At your discretion, take ownership of an issue and submit a PR for it
|
||||
(especially if it's quick or relates to work you're already doing).
|
||||
|
||||
If you have questions about triaging an issue, ask in `#sig-docs` on Slack or
|
||||
the [kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
|
||||
-->
|
||||
2. 添加优先级标签（
|
||||
[Issue 判定指南](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority)中有优先级标签的详细定义)
|
||||
|
||||
{{< table caption="Issue 标签" >}}
|
||||
标签 | 描述
|
||||
:------------|:------------------
|
||||
`priority/critical-urgent` | 应马上处理
|
||||
`priority/important-soon` | 应在 3 个月内处理
|
||||
`priority/important-longterm` | 应在 6 个月内处理
|
||||
`priority/backlog` | 可无限期地推迟，可在人手充足时处理
|
||||
`priority/awaiting-more-evidence` | 占位符，标示 Issue 可能是一个不错的 Issue，避免该 Issue 被忽略或遗忘
|
||||
`help` or `good first issue` | 适合对 Kubernetes 或 SIG Docs 经验较少的贡献者来处理。更多信息可参考[需要帮助和入门候选 Issue 标签](https://github.com/kubernetes/community/blob/master/contributors/guide/help-wanted.md)。
|
||||
{{< /table >}}
|
||||
|
||||
基于你自己的判断，你可以选择某 Issue 来处理，为之发起 PR
|
||||
（尤其是那些可以很快处理或与你已经在做的工作相关的 Issue）。
|
||||
|
||||
如果你对 Issue 评判有任何问题，可以在 `#sig-docs` Slack 频道或者
|
||||
[kubernetes-sig-docs 邮件列表](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)
|
||||
中提问。
|
||||
|
||||
<!--
|
||||
## Adding and removing issue labels
|
||||
|
||||
To add a label, leave a comment in one of the following formats:
|
||||
|
||||
- `/<label-to-add>` (for example, `/good-first-issue`)
|
||||
- `/<label-category> <label-to-add>` (for example, `/triage needs-information` or `/language ja`)
|
||||
|
||||
To remove a label, leave a comment in one of the following formats:
|
||||
|
||||
- `/remove-<label-to-remove>` (for example, `/remove-help`)
|
||||
- `/remove-<label-category> <label-to-remove>` (for example, `/remove-triage needs-information`)`
|
||||
-->
|
||||
## 添加和删除 Issue 标签 {#adding-and-removing-issue-labels}
|
||||
|
||||
要添加标签，可以用以下形式对 PR 进行评论：
|
||||
|
||||
- `/<要添加的标签>` （例如, `/good-first-issue`）
|
||||
- `/<标签类别> <要添加的标签>` （例如，`/triage needs-information` 或 `/language ja`）
|
||||
|
||||
要移除某个标签，可以用以下形式对 PR 进行评论：
|
||||
|
||||
- `/remove-<要移除的标签>` （例如，`/remove-help`）
|
||||
- `/remove-<标签类别> <要移除的标签>` （例如，`/remove-triage needs-information`）
|
||||
|
||||
<!--
|
||||
In both cases, the label must already exist. If you try to add a label that does not exist, the command is
|
||||
silently ignored.
|
||||
|
||||
For a list of all labels, see the [website repository's Labels section](https://github.com/kubernetes/website/labels). Not all labels are used by SIG Docs.
|
||||
-->
|
||||
在以上两种情况下，标签都必须合法存在。如果你尝试添加一个尚不存在的标签，
|
||||
对应的命令会被悄悄忽略。
|
||||
|
||||
关于所有标签的完整列表，可以参考
|
||||
[Website 仓库的标签节](https://github.com/kubernetes/website/labels)。
|
||||
实际上，SIG Docs 并没有使用全部标签。
|
||||
|
||||
<!--
|
||||
### Issue lifecycle labels
|
||||
|
||||
Issues are generally opened and closed quickly.
|
||||
However, sometimes an issue is inactive after its opened.
|
||||
Other times, an issue may need to remain open for longer than 90 days.
|
||||
|
||||
{{< table caption="Issue lifecycle labels" >}}
|
||||
Label | Description
|
||||
:------------|:------------------
|
||||
`lifecycle/stale` | After 90 days with no activity, an issue is automatically labeled as stale. The issue will be automatically closed if the lifecycle is not manually reverted using the `/remove-lifecycle stale` command.
|
||||
`lifecycle/frozen` | An issue with this label will not become stale after 90 days of inactivity. A user manually adds this label to issues that need to remain open for much longer than 90 days, such as those with a `priority/important-longterm` label.
|
||||
{{< /table >}}
|
||||
-->
|
||||
### Issue 生命周期标签
|
||||
|
||||
Issues 通常都可以快速创建并关闭。
|
||||
不过也有些时候，某个 Issue 被创建之后会长期处于非活跃状态。
|
||||
也有一些时候，即使超过 90 天，某个 Issue 仍应保持打开状态。
|
||||
|
||||
{{< table caption="Issue 生命周期标签" >}}
|
||||
标签 | 描述
|
||||
:------------|:------------------
|
||||
`lifecycle/stale` | 过去 90 天内某 Issue 无人问津，会被自动标记为停滞状态。如果 Issue 没有被 `/remove-lifecycle stale` 命令重置生命期，就会被自动关闭。
|
||||
`lifecycle/frozen` | 对应的 Issue 即使超过 90 天仍无人处理也不会进入停滞状态。用户手动添加此标签给一些需要保持打开状态超过 90 天的 Issue，例如那些带有 `priority/important-longterm` 标签的 Issue。
|
||||
{{< /table >}}
|
||||
|
||||
<!--
|
||||
## Handling special issue types
|
||||
|
||||
SIG Docs encounters the following types of issues often enough to document how
|
||||
to handle them.
|
||||
|
||||
### Duplicate issues
|
||||
|
||||
If a single problem has one or more issues open for it, combine them into a single issue.
|
||||
You should decide which issue to keep open (or
|
||||
open a new issue), then move over all relevant information and link related issues.
|
||||
Finally, label all other issues that describe the same problem with
|
||||
`triage/duplicate` and close them. Only having a single issue to work on reduces confusion
|
||||
and avoids duplicate work on the same problem.
|
||||
-->
|
||||
## 处理特殊的 Issue 类型 {#handling-special-issue-types}
|
||||
|
||||
SIG Docs 常常会遇到以下类型的 Issue，因此对其处理方式描述如下。
|
||||
|
||||
### 重复的 Issue {#duplicate-issues}
|
||||
|
||||
如果针对同一个问题有不止一个打开的 Issue，可以将其合并为一个 Issue。
|
||||
你需要决定保留哪个 Issue 为打开状态（或者重新登记一个新的 Issue），
|
||||
然后将所有相关的信息复制过去并提供对关联 Issues 的链接。
|
||||
最后，将所有其他描述同一问题的 Issue 标记为 `triage/duplicate` 并关闭之。
|
||||
保持只有一个 Issue 待处理有助于减少困惑，避免在同一问题上发生重复劳动。
|
||||
|
||||
<!--
|
||||
### Dead link issues
|
||||
|
||||
If the dead link issue is in the API or `kubectl` documentation, assign them `/priority critical-urgent` until the problem is fully understood. Assign all other dead link issues `/priority important-longterm`, as they must be manually fixed.
|
||||
|
||||
### Blog issues
|
||||
|
||||
We expect [Kubernetes Blog](https://kubernetes.io/blog/) entries to become
|
||||
outdated over time. Therefore, we only maintain blog entries less than a year old.
|
||||
If an issue is related to a blog entry that is more than one year old,
|
||||
close the issue without fixing.
|
||||
-->
|
||||
### 失效链接 Issues {#dead-link-issues}
|
||||
|
||||
如果失效链接是关于 API 或者 `kubectl` 文档的，可以将其标记为
|
||||
`/priority critical-urgent`，直到问题原因被弄清楚为止。
|
||||
对于其他的链接失效问题，可以标记 `/priority important-longterm`，
|
||||
因为这些问题都需要手动处理。
|
||||
|
||||
### 博客问题 {#blog-issues}
|
||||
|
||||
我们预期 [Kubernetes 博客](https://kubernetes.io/blog/)条目随着时间推移都会过期。
|
||||
因此，我们只维护一年内的博客条目。
|
||||
如果某个 Issue 是与某个超过一年的博客条目有关的，可以直接关闭
|
||||
Issue，不必修复。
|
||||
|
||||
<!--
|
||||
### Support requests or code bug reports
|
||||
|
||||
Some docs issues are actually issues with the underlying code, or requests for
|
||||
assistance when something, for example a tutorial, doesn't work.
|
||||
For issues unrelated to docs, close the issue with the `triage/support` label and a comment
|
||||
directing the requester to support venues (Slack, Stack Overflow) and, if
|
||||
relevant, the repository to file an issue for bugs with features (`kubernetes/kubernetes`
|
||||
is a great place to start).
|
||||
|
||||
Sample response to a request for support:
|
||||
-->
|
||||
### 请求支持或代码缺陷报告 {#support-requests-or-code-bug-reports}
|
||||
|
||||
某些文档 Issues 实际上是关于底层代码的 Issue 或者在某方面请求协助的问题，
|
||||
例如某个教程无法正常工作。
|
||||
对于与文档无关的 Issues，关闭它并打上标签 `triage/support`，可以通过评论
|
||||
告知请求者其他支持渠道（Slack、Stack Overflow）。
|
||||
如果有相关的其他仓库，可以告诉请求者应该在哪个仓库登记与功能特性相关的 Issues
|
||||
（通常会是 `kubernetes/kubernetes`）。
|
||||
|
||||
下面是对支持请求的回复示例：
|
||||
|
||||
```none
|
||||
This issue sounds more like a request for support and less
|
||||
like an issue specifically for docs. I encourage you to bring
|
||||
your question to the `#kubernetes-users` channel in
|
||||
[Kubernetes slack](http://slack.k8s.io/). You can also search
|
||||
resources like
|
||||
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)
|
||||
for answers to similar questions.
|
||||
|
||||
You can also open issues for Kubernetes functionality in
|
||||
https://github.com/kubernetes/kubernetes.
|
||||
|
||||
If this is a documentation issue, please re-open this issue.
|
||||
```
|
||||
|
||||
<!--
|
||||
Sample code bug report response:
|
||||
-->
|
||||
对代码缺陷 Issue 的回复示例：
|
||||
|
||||
```none
|
||||
This sounds more like an issue with the code than an issue with
|
||||
the documentation. Please open an issue at
|
||||
https://github.com/kubernetes/kubernetes/issues.
|
||||
|
||||
If this is a documentation issue, please re-open this issue.
|
||||
```
|
||||
|
||||
@@ -0,0 +1,202 @@
|
||||
---
|
||||
title: 评阅 PRs
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 10
|
||||
---
|
||||
<!--
|
||||
title: Reviewing pull requests
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 10
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
Anyone can review a documentation pull request. Visit the [pull requests](https://github.com/kubernetes/website/pulls) section in the Kubernetes website repository to see open pull requests.
|
||||
|
||||
Reviewing documentation pull requests is a
|
||||
great way to introduce yourself to the Kubernetes community.
|
||||
It helps you learn the code base and build trust with other contributors.
|
||||
|
||||
Before reviewing, it's a good idea to:
|
||||
|
||||
- Read the [content guide](/docs/contribute/style/content-guide/) and
|
||||
[style guide](/docs/contribute/style/style-guide/) so you can leave informed comments.
|
||||
- Understand the different [roles and responsibilities](/docs/contribute/participating/#roles-and-responsibilities) in the Kubernetes documentation community.
|
||||
-->
|
||||
任何人均可评阅文档的拉取请求。访问 Kubernetes 网站仓库的
|
||||
[pull requests](https://github.com/kubernetes/website/pulls)
|
||||
部分可以查看所有待处理的拉取请求（PRs）。
|
||||
|
||||
评阅文档 PR 是将你自己介绍给 Kubernetes 社区的一种很好的方式。
|
||||
它将有助于你学习代码库并与其他贡献者之间建立相互信任关系。
|
||||
|
||||
在评阅之前，可以考虑：
|
||||
|
||||
- 阅读[内容指南](/docs/contribute/style/content-guide/)和
|
||||
[样式指南](/docs/contribute/style/style-guide/)以便给出有价值的评论。
|
||||
- 了解 Kubernetes 文档社区中不同的[角色和职责](/docs/contribute/participating/#roles-and-responsibilities)。
|
||||
|
||||
<!-- body -->
|
||||
<!--
|
||||
## Before you begin
|
||||
|
||||
Before you start a review:
|
||||
|
||||
- Read the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) and ensure that you abide by it at all times.
|
||||
- Be polite, considerate, and helpful.
|
||||
- Comment on positive aspects of PRs as well as changes.
|
||||
- Be empathetic and mindful of how your review may be received.
|
||||
- Assume good intent and ask clarifying questions.
|
||||
- Experienced contributors, consider pairing with new contributors whose work requires extensive changes.
|
||||
-->
|
||||
## 准备工作 {#before-you-begin}
|
||||
|
||||
在你开始评阅之前：
|
||||
|
||||
- 阅读 [CNCF 行为准则](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)
|
||||
确保你会始终遵从其中约定；
|
||||
- 保持有礼貌、体谅他人，怀助人为乐初心；
|
||||
- 评论时若给出修改建议，也要兼顾 PR 的积极方面
|
||||
- 保持同理心，多考虑他人收到评阅意见时的可能反应
|
||||
- 假定大家都是好意的，通过问问题澄清意图
|
||||
- 如果你是有经验的贡献者，请考虑和新贡献者一起合作，提高其产出质量
|
||||
|
||||
<!--
|
||||
## Review process
|
||||
|
||||
In general, review pull requests for content and style in English.
|
||||
|
||||
1. Go to
|
||||
[https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).
|
||||
You see a list of every open pull request against the Kubernetes website and
|
||||
docs.
|
||||
|
||||
2. Filter the open PRs using one or all of the following labels:
|
||||
- `cncf-cla: yes` (Recommended): PRs submitted by contributors who have not signed the CLA cannot be merged. See [Sign the CLA](/docs/contribute/new-content/overview/#sign-the-cla) for more information.
|
||||
- `language/en` (Recommended): Filters for english language PRs only.
|
||||
- `size/<size>`: filters for PRs of a certain size. If you're new, start with smaller PRs.
|
||||
|
||||
Additionally, ensure the PR isn't marked as a work in progress. PRs using the `work in progress` label are not ready for review yet.
|
||||
-->
|
||||
## 评阅过程 {#review-process}
|
||||
|
||||
一般而言，应该使用英语来评阅 PR 的内容和样式。
|
||||
|
||||
1. 前往 [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls)，
|
||||
你会看到所有针对 Kubernetes 网站和文档的待处理 PRs。
|
||||
|
||||
2. 使用以下标签（组合）对待处理 PRs 进行过滤：
|
||||
|
||||
- `cncf-cla: yes` （建议）：由尚未签署 CLA 的贡献者所发起的 PRs 不可以合并。
|
||||
参考[签署 CLA](/docs/contribute/new-content/overview/#sign-the-cla) 以了解更多信息。
|
||||
- `language/en` （建议）：仅查看英语语言的 PRs。
|
||||
- `size/<尺寸>`：过滤特定尺寸（规模）的 PRs。如果你刚入门，可以从较小的 PR 开始。
|
||||
|
||||
此外，确保 PR 没有标记为尚未完成（Work in Progress）。
|
||||
包含 `work in progress` 的 PRs 通常还没准备好被评阅。
|
||||
|
||||
<!--
|
||||
3. Once you've selected a PR to review, understand the change by:
|
||||
- Reading the PR description to understand the changes made, and read any linked issues
|
||||
- Reading any comments by other reviewers
|
||||
- Clicking the **Files changed** tab to see the files and lines changed
|
||||
- Previewing the changes in the Netlify preview build by scrolling to the PR's build check section at the bottom of the **Conversation** tab and clicking the **deploy/netlify** line's **Details** link.
|
||||
|
||||
4. Go to the **Files changed** tab to start your review.
|
||||
1. Click on the `+` symbol beside the line you want to comment on.
|
||||
2. Fill in any comments you have about the line and click either **Add single comment** (if you have only one comment to make) or **Start a review** (if you have multiple comments to make).
|
||||
3. When finished, click **Review changes** at the top of the page. Here, you can add
|
||||
add a summary of your review (and leave some positive comments for the contributor!),
|
||||
approve the PR, comment or request changes as needed. New contributors should always
|
||||
choose **Comment**.
|
||||
-->
|
||||
3. 选定 PR 评阅之后，可以通过以下方式理解所作的变更：
|
||||
|
||||
- 阅读 PR 描述以理解所作变更，并且阅读所有关联的 Issues
|
||||
- 阅读其他评阅人给出的评论
|
||||
- 点击 **Files changed** Tab 页面，查看被改变的文件和代码行
|
||||
- 滚动到 **Conversation** Tab 页面下端的 PR 构建检查节区，点击
|
||||
**deploy/netlify** 行的 **Details** 链接，预览 Netlify
|
||||
预览构建所生成的结果
|
||||
|
||||
4. 前往 **Files changed** Tab 页面，开始你的评阅工作
|
||||
|
||||
1. 点击你希望评论的行旁边的 `+` 号
|
||||
2. 填写你对该行的评论，之后或者选择**Add single comment** （如果你只有一条评论）
|
||||
或者 **Start a review** （如果你还有其他评论要添加）
|
||||
3. 评论结束时，点击页面顶部的 **Review changes**。这里你可以添加你的评论结语
|
||||
（记得留下一些正能量的评论！）、根据需要批准 PR、请求作者进一步修改等等。
|
||||
新手应该选择 **Comment**。
|
||||
|
||||
<!--
|
||||
## Reviewing checklist
|
||||
|
||||
When reviewing, use the following as a starting point.
|
||||
|
||||
### Language and grammar
|
||||
|
||||
- Are there any obvious errors in language or grammar? Is there a better way to phrase something?
|
||||
- Are there any complicated or archaic words which could be replaced with a simpler word?
|
||||
- Are there any words, terms or phrases in use which could be replaced with a non-discriminatory alternative?
|
||||
- Does the word choice and its capitalization follow the [style guide](/docs/contribute/style/style-guide/)?
|
||||
- Are there long sentences which could be shorter or less complex?
|
||||
- Are there any long paragraphs which might work better as a list or table?
|
||||
-->
|
||||
## 评阅清单 {#reviewing-checklist}
|
||||
|
||||
评阅 PR 时可以从下面的条目入手。
|
||||
|
||||
### 语言和语法 {#language-and-grammar}
|
||||
|
||||
- 是否存在明显的语言或语法错误？对某事的描述有更好的方式？
|
||||
- 是否存在一些过于复杂晦涩的用词，本可以用简单词汇来代替？
|
||||
- 是否有些用词、术语或短语可以用不带歧视性的表达方式代替？
|
||||
- 用词和大小写方面是否遵从了[样式指南](/docs/contribute/style/style-guide/)？
|
||||
- 是否有些句子太长，可以改得更短、更简单？
|
||||
- 是否某些段落过长，可以考虑使用列表或者表格来表达？
|
||||
|
||||
<!--
|
||||
### Content
|
||||
|
||||
- Does similar content exist elsewhere on the Kubernetes site?
|
||||
- Does the content excessively link to off-site, individual vendor or non-open source documentation?
|
||||
-->
|
||||
### 内容 {#content}
|
||||
|
||||
- Kubernetes 网站上是否别处已经存在类似的内容？
|
||||
- 内容本身是否过度依赖于网站范畴之外、独立供应商或者非开源的文档？
|
||||
|
||||
<!--
|
||||
### Website
|
||||
|
||||
- Did this PR change or remove a page title, slug/alias or anchor link? If so, are there broken links as a result of this PR? Is there another option, like changing the page title without changing the slug?
|
||||
- Does the PR introduce a new page? If so:
|
||||
- Is the page using the right [page content type](/docs/contribute/style/page-content-types/) and associated Hugo shortcodes?
|
||||
- Does the page appear correctly in the section's side navigation (or at all)?
|
||||
- Should the page appear on the [Docs Home](/docs/home/) listing?
|
||||
- Do the changes show up in the Netlify preview? Be particularly vigilant about lists, code blocks, tables, notes and images.
|
||||
|
||||
### Other
|
||||
|
||||
For small issues with a PR, like typos or whitespace, prefix your comments with `nit:`. This lets the author know the issue is non-critical.
|
||||
-->
|
||||
### 网站 {#Website}
|
||||
|
||||
- PR 是否改变或者删除了某页面的标题、slug/别名或者链接锚点？
|
||||
如果是这样，PR 是否会导致出现新的失效链接？
|
||||
是否有其他的办法，比如改变页面标题但不改变其 slug？
|
||||
- PR 是否引入新的页面？如果是：
|
||||
- 该页面是否使用了正确的[页面内容类型](/docs/contribute/style/page-content-types/)
|
||||
及相关联的 Hugo 短代码（shortcodes）？
|
||||
- 该页面能否在对应章节的侧面导航中显示？显示得正确么？
|
||||
- 该页面是否应出现在[网站主页面](/docs/home/)的列表中？
|
||||
- 变更是否正确出现在 Netlify 预览中了？
|
||||
要对列表、代码段、表格、注释和图像等元素格外留心
|
||||
|
||||
### 其他 {#other}
|
||||
|
||||
对于 PR 中的小问题，例如拼写错误或者空格问题，可以在你的评论前面加上 `nit:`。
|
||||
这样做可以让作者知道该问题不是一个不得了的大问题。
|
||||
|
||||
@@ -60,7 +60,7 @@ Minikube 支持以下 Kubernetes 功能：
|
||||
<!--
|
||||
See [Installing Minikube](/docs/tasks/tools/install-minikube/).
|
||||
-->
|
||||
请参阅[安装 Minikube](/docs/tasks/tools/install-minikube/)。
|
||||
请参阅[安装 Minikube](/zh/docs/tasks/tools/install-minikube/)。
|
||||
|
||||
<!--
|
||||
## Quickstart
|
||||
|
||||
@@ -32,7 +32,7 @@ weight: 20
|
||||
</div>
|
||||
<div class="row">
|
||||
<div class="col-md-12">
|
||||
<a class="btn btn-lg btn-success" href="/docs/tutorials/kubernetes-basics/" role="button">回到 Kubernetes 的基础<span class="btn__next">›</span></a>
|
||||
<a class="btn btn-lg btn-success" href="/zh/docs/tutorials/kubernetes-basics/" role="button">回到 Kubernetes 的基础<span class="btn__next">›</span></a>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
Reference in New Issue
Block a user