diff --git a/content/zh/docs/concepts/containers/container-environment.md b/content/zh/docs/concepts/containers/container-environment.md index 79170508e6..7e9a12be1b 100644 --- a/content/zh/docs/concepts/containers/container-environment.md +++ b/content/zh/docs/concepts/containers/container-environment.md @@ -89,10 +89,10 @@ FOO_SERVICE_PORT= 服务具有专用的 IP 地址。如果启用了 -[DNS插件](https://releases.k8s.io/{{< param "githubbranch" >}}/cluster/addons/dns/), +[DNS 插件](https://releases.k8s.io/{{< param "fullversion" >}}/cluster/addons/dns/), 可以在容器中通过 DNS 来访问服务。 ## {{% heading "whatsnext" %}} diff --git a/content/zh/docs/concepts/containers/images.md b/content/zh/docs/concepts/containers/images.md index 0a629be864..1360faab32 100644 --- a/content/zh/docs/concepts/containers/images.md +++ b/content/zh/docs/concepts/containers/images.md @@ -29,7 +29,7 @@ This page provides an outline of the container image concept. 容器镜像是可执行的软件包,可以单独运行;该软件包对所处的运行时环境具有 良定(Well Defined)的假定。 -你通常会创建应用的容器镜像并将其推送到某仓库,然后在 +你通常会创建应用的容器镜像并将其推送到某仓库(Registry),然后在 {{< glossary_tooltip text="Pod" term_id="pod" >}} 中引用它。 本页概要介绍容器镜像的概念。 @@ -41,7 +41,7 @@ This page provides an outline of the container image concept. Container images are usually given a name such as `pause`, `example/mycontainer`, or `kube-apiserver`. Images can also include a registry hostname; for example: `fictional.registry.example/imagename`, -and possible a port number as well; for example: `fictional.registry.example:10443/imagename`. +and possibly a port number as well; for example: `fictional.registry.example:10443/imagename`. If you don't specify a registry hostname, Kubernetes assumes that you mean the Docker public registry. @@ -72,20 +72,6 @@ If you don't specify a tag, Kubernetes assumes you mean the tag `latest`. 关于在镜像标签中何处可以使用分隔字符(`_`、`-` 和 `.`)还有一些额外的规则。 如果你不指定标签,Kubernetes 认为你想使用标签 `latest`。 - -{{< caution >}} -你要避免在生产环境中使用 `latest` 标签,因为这会使得跟踪所运行的镜像版本变得 -非常困难,同时也很难回滚到之前运行良好的版本。 - -正确的做法恰恰相反,你应该指定一个有意义的标签,如 `v1.42.0`。 -{{< /caution >}} - -如果你希望强制总是拉取镜像,你可以执行以下操作之一: +### 镜像拉取策略 {#image-pull-policy} -- 设置容器的 `imagePullPolicy` 为 `Always`。 -- 省略 `imagePullPolicy`,并使用 `:latest` 作为要使用的镜像的标签; - Kubernetes 会将策略设置为 `Always`。 -- 省略 `imagePullPolicy` 和要使用的镜像标签。 -- 启用 [AlwaysPullImages](/zh/docs/reference/access-authn-authz/admission-controllers/#alwayspullimages) - 准入控制器(Admission Controller)。 +容器的 `imagePullPolicy` 和镜像的标签会影响 [kubelet](/zh/docs/reference/command-line-tools-reference/kubelet/) 尝试拉取(下载)指定的镜像。 + +以下列表包含了 `imagePullPolicy` 可以设置的值,以及这些值的效果: + + +`IfNotPresent` +: 只有当镜像在本地不存在时才会拉取。 + +`Always` +: 每当 kubelet 启动一个容器时,kubelet 会查询容器的镜像仓库, + 将名称解析为一个镜像[摘要](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier)。 + 如果 kubelet 有一个容器镜像,并且对应的摘要已在本地缓存,kubelet 就会使用其缓存的镜像; + 否则,kubelet 就会使用解析后的摘要拉取镜像,并使用该镜像来启动容器。 + +`Never` +: Kubelet 不会尝试获取镜像。如果镜像已经以某种方式存在本地, + kubelet 会尝试启动容器;否则,会启动失败。 + 更多细节见[提前拉取镜像](#pre-pulled-images)。 + + +只要能够可靠地访问镜像仓库,底层镜像提供者的缓存语义甚至可以使 `imagePullPolicy: Always` 高效。 +你的容器运行时可以注意到节点上已经存在的镜像层,这样就不需要再次下载。 + + +{{< note >}} +在生产环境中部署容器时,你应该避免使用 `:latest` 标签,因为这使得正在运行的镜像的版本难以追踪,并且难以正确地回滚。 + +相反,应指定一个有意义的标签,如 `v1.42.0`。 +{{< /note >}} + +为了确保 Pod 总是使用相同版本的容器镜像,你可以指定镜像的摘要; +将 `:` 替换为 `@`,例如 `image@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2`。 + + +当使用镜像标签时,如果镜像仓库修改了代码所对应的镜像标签,可能会出现新旧代码混杂在 Pod 中运行的情况。 +镜像摘要唯一标识了镜像的特定版本,因此 Kubernetes 每次启动具有指定镜像名称和摘要的容器时,都会运行相同的代码。 +指定一个镜像可以固定你所运行的代码,这样镜像仓库的变化就不会导致版本的混杂。 + +有一些第三方的[准入控制器](/zh/docs/reference/access-authn-authz/admission-controllers/) +在创建 Pod(和 Pod 模板)时产生变更,这样运行的工作负载就是根据镜像摘要,而不是标签来定义的。 +无论镜像仓库上的标签发生什么变化,你都想确保你所有的工作负载都运行相同的代码,那么指定镜像摘要会很有用。 + + +#### 默认镜像拉取策略 {#imagepullpolicy-defaulting} + +当你(或控制器)向 API 服务器提交一个新的 Pod 时,你的集群会在满足特定条件时设置 `imagePullPolicy `字段: + + +- 如果你省略了 `imagePullPolicy` 字段,并且容器镜像的标签是 `:latest`, + `imagePullPolicy` 会自动设置为 `Always`。 +- 如果你省略了 `imagePullPolicy` 字段,并且没有指定容器镜像的标签, + `imagePullPolicy` 会自动设置为 `Always`。 +- 如果你省略了 `imagePullPolicy` 字段,并且为容器镜像指定了非 `:latest` 的标签, + `imagePullPolicy` 就会自动设置为 `IfNotPresent`。 {{< note >}} -对象被 *创建* 时,容器的 `imagePullPolicy` 总是被设置为某值,如果镜像的标签 -后来发生改变,镜像拉取策略也不会被改变。 +容器的 `imagePullPolicy` 的值总是在对象初次 _创建_ 时设置的,如果后来镜像的标签发生变化,则不会更新。 -例如,如果你创建了一个 Deployment 对象,其中的镜像标签不是 `:latest`, -后来 Deployment 的镜像被改为 `:latest`,则 `imagePullPolicy` 不会被改变为 -`Always`。你必须在对象被初始创建之后手动改变拉取策略。 +例如,如果你用一个 _非_ `:latest` 的镜像标签创建一个 Deployment, +并在随后更新该 Deployment 的镜像标签为 `:latest`,则 `imagePullPolicy` 字段 _不会_ 变成 `Always`。 +你必须手动更改已经创建的资源的拉取策略。 {{< /note >}} -如果 `imagePullPolicy` 未被定义为特定的值,也会被设置为 `Always`。 +#### 必要的镜像拉取 {#required-image-pull} + +如果你想总是强制执行拉取,你可以使用下述的一中方式: + +- 设置容器的 `imagePullPolicy` 为 `Always`。 +- 省略 `imagePullPolicy`,并使用 `:latest` 作为镜像标签; + 当你提交 Pod 时,Kubernetes 会将策略设置为 `Always`。 +- 省略 `imagePullPolicy` 和镜像的标签; + 当你提交 Pod 时,Kubernetes 会将策略设置为 `Always`。 +- 启用准入控制器 [AlwaysPullImages](/zh/docs/reference/access-authn-authz/admission-controllers/#alwayspullimages)。 + + + +### ImagePullBackOff + +当 kubelet 使用容器运行时创建 Pod 时,容器可能因为 `ImagePullBackOff` 导致状态为 +[Waiting](/zh/docs/concepts/workloads/pods/pod-lifecycle/#container-state-waiting)。 + + +`ImagePullBackOff` 状态意味着容器无法启动, +因为 Kubernetes 无法拉取容器镜像(原因包括无效的镜像名称,或从私有仓库拉取而没有 `imagePullSecret`)。 + `BackOff` 部分表示 Kubernetes 将继续尝试拉取镜像,并增加回退延迟。 + +Kubernetes 会增加每次尝试之间的延迟,直到达到编译限制,即 300 秒(5 分钟)。 -* 阅读 [OCI Image Manifest 规范](https://github.com/opencontainers/image-spec/blob/master/manifest.md) - +* 阅读 [OCI Image Manifest 规范](https://github.com/opencontainers/image-spec/blob/master/manifest.md)。 +* 了解[容器镜像垃圾收集](/zh/docs/concepts/architecture/garbage-collection/#container-image-garbage-collection)。 diff --git a/content/zh/docs/concepts/containers/runtime-class.md b/content/zh/docs/concepts/containers/runtime-class.md index d1ed733804..a2cee358c1 100644 --- a/content/zh/docs/concepts/containers/runtime-class.md +++ b/content/zh/docs/concepts/containers/runtime-class.md @@ -89,10 +89,10 @@ RuntimeClass 假设集群中的节点配置是同构的(换言之,所有的 所有这些配置都具有相应的 `handler` 名,并被 RuntimeClass 引用。 -handler 必须符合 DNS-1123 命名规范(字母、数字、或 `-`)。 +handler 必须是有效的 [DNS 标签名](/zh/docs/concepts/overview/working-with-objects/names/#dns-label-names)。 -更详细信息,请查阅 CRI-O [配置文档](https://raw.githubusercontent.com/cri-o/cri-o/9f11d1d/docs/crio.conf.5.md)。 +更详细信息,请查阅 CRI-O [配置文档](https://github.com/cri-o/cri-o/blob/master/docs/crio.conf.5.md)。 - [RuntimeClass 设计](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/585-runtime-class/README.md) - [RuntimeClass 调度设计](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/585-runtime-class/README.md#runtimeclass-scheduling) diff --git a/content/zh/docs/concepts/overview/components.md b/content/zh/docs/concepts/overview/components.md index 8e76e91fd7..26535842ab 100644 --- a/content/zh/docs/concepts/overview/components.md +++ b/content/zh/docs/concepts/overview/components.md @@ -26,7 +26,7 @@ card: When you deploy Kubernetes, you get a cluster. {{}} -This document outlines the various components you need to have +This document outlines the various components you need to have for a complete and working Kubernetes cluster. Here's the diagram of a Kubernetes cluster with all the components tied together. diff --git a/content/zh/docs/concepts/overview/working-with-objects/annotations.md b/content/zh/docs/concepts/overview/working-with-objects/annotations.md index 5239861124..053fbbc341 100644 --- a/content/zh/docs/concepts/overview/working-with-objects/annotations.md +++ b/content/zh/docs/concepts/overview/working-with-objects/annotations.md @@ -48,6 +48,15 @@ Annotations, like labels, are key/value maps: } ``` +{{}} + +Map 中的键和值必须是字符串。 +换句话说,你不能使用数字、布尔值、列表或其他类型的键或值。 +{{}} + diff --git a/content/zh/docs/concepts/overview/working-with-objects/field-selectors.md b/content/zh/docs/concepts/overview/working-with-objects/field-selectors.md index 5184fb0b38..58a4b65163 100644 --- a/content/zh/docs/concepts/overview/working-with-objects/field-selectors.md +++ b/content/zh/docs/concepts/overview/working-with-objects/field-selectors.md @@ -93,7 +93,7 @@ kubectl get pods --field-selector=status.phase!=Running,spec.restartPolicy=Alway ## 多种资源类型 {#multiple-resource-types} diff --git a/content/zh/docs/concepts/overview/working-with-objects/kubernetes-objects.md b/content/zh/docs/concepts/overview/working-with-objects/kubernetes-objects.md index 96a863cfa0..6c8ce5873e 100644 --- a/content/zh/docs/concepts/overview/working-with-objects/kubernetes-objects.md +++ b/content/zh/docs/concepts/overview/working-with-objects/kubernetes-objects.md @@ -160,6 +160,7 @@ In the `.yaml` file for the Kubernetes object you want to create, you'll need to * `apiVersion` - Which version of the Kubernetes API you're using to create this object * `kind` - What kind of object you want to create * `metadata` - Data that helps uniquely identify the object, including a `name` string, `UID`, and optional `namespace` +* `spec` - What state you desire for the object --> ### 必需字段 {#required-fields} @@ -168,25 +169,23 @@ In the `.yaml` file for the Kubernetes object you want to create, you'll need to * `apiVersion` - 创建该对象所使用的 Kubernetes API 的版本 * `kind` - 想要创建的对象的类别 * `metadata` - 帮助唯一性标识对象的一些数据,包括一个 `name` 字符串、UID 和可选的 `namespace` +* `spec` - 你所期望的该对象的状态 -你也需要提供对象的 `spec` 字段。 -对象 `spec` 的精确格式对每个 Kubernetes 对象来说是不同的,包含了特定于该对象的嵌套字段。 -[Kubernetes API 参考](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/) -能够帮助我们找到任何我们想创建的对象的 spec 格式。 -例如,可以从 -[core/v1 PodSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core) -查看 `Pod` 的 `spec` 格式, -并且可以从 -[apps/v1 DeploymentSpec](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#deploymentspec-v1-apps) -查看 `Deployment` 的 `spec` 格式。 +The precise format of the object `spec` is different for every Kubernetes object, and contains nested fields specific to that object. The [Kubernetes API Reference](https://kubernetes.io/docs/reference/kubernetes-api/) can help you find the spec format for all of the objects you can create using Kubernetes. +For example, the reference for Pod details the [`spec` field](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec) +for a Pod in the API, and the reference for Deployment details the [`spec` field](/docs/reference/kubernetes-api/workload-resources/deployment-v1/#DeploymentSpec) for Deployments. +In those API reference pages you'll see mention of PodSpec and DeploymentSpec. These names are implementation details of the Golang code that Kubernetes uses to implement its API. +--> +对象 `spec` 的精确格式对每个 Kubernetes 对象来说是不同的,包含了特定于该对象的嵌套字段。 +[Kubernetes API 参考](https://kubernetes.io/docs/reference/kubernetes-api/) +能够帮助我们找到任何我们想创建的对象的规约格式。 + +例如,Pod 参考文档详细说明了 API 中 Pod 的 [`spec` 字段](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec), +Deployment 的参考文档则详细说明了 Deployment 的 [`spec` 字段](/docs/reference/kubernetes-api/workload-resources/deployment-v1/#DeploymentSpec)。 +在这些 API 参考页面中,你将看到提到的 PodSpec 和 DeploymentSpec。 +这些名字是 Kubernetes 用来实现其 API 的 Golang 代码的实现细节。 ## {{% heading "whatsnext" %}} diff --git a/content/zh/docs/concepts/overview/working-with-objects/labels.md b/content/zh/docs/concepts/overview/working-with-objects/labels.md index 2714cb3f7b..34b9fe0f6b 100644 --- a/content/zh/docs/concepts/overview/working-with-objects/labels.md +++ b/content/zh/docs/concepts/overview/working-with-objects/labels.md @@ -70,11 +70,10 @@ Example labels: * `"track" : "daily"`, `"track" : "weekly"` -这些只是常用标签的例子; 你可以任意制定自己的约定。请记住,对于给定对象标签的键必须是唯一的。 +有一些[常用标签](/zh/docs/concepts/overview/working-with-objects/common-labels/)的例子; 你可以任意制定自己的约定。 +请记住,标签的 Key 对于给定对象必须是唯一的。 ## 语法和字符集 @@ -97,7 +96,7 @@ _标签_ 是键值对。有效的标签键有两个段:可选的前缀和名 向最终用户对象添加标签的自动系统组件(例如 `kube-scheduler`、`kube-controller-manager`、 `kube-apiserver`、`kubectl` 或其他第三方自动化工具)必须指定前缀。 -`kubernetes.io/` 前缀是为 Kubernetes 核心组件保留的。 +`kubernetes.io/` 和 `k8s.io/` 前缀是为 Kubernetes 核心组件[保留的](/zh/docs/reference/labels-annotations-taints/)。 -以下是比较常见的三种资源命名约束。 +以下是比较常见的四种资源命名约束。 -### DNS 标签名 {#dns-label-names} +### RFC 1123 标签名 {#dns-label-names} 某些资源类型需要其名称遵循 [RFC 1123](https://tools.ietf.org/html/rfc1123) 所定义的 DNS 标签标准。也就是命名必须满足如下规则: -- 最多63个字符 -- 只能包含小写字母、数字,以及'-' +- 最多 63 个字符 +- 只能包含小写字母、数字,以及 '-' - 须以字母数字开头 - 须以字母数字结尾 + + +### RFC 1035 标签名 {#rfc-1035-label-names} + +某些资源类型需要其名称遵循 [RFC 1035](https://tools.ietf.org/html/rfc1035) +所定义的 DNS 标签标准。也就是命名必须满足如下规则: + +- 最多 63 个字符 +- 只能包含小写字母、数字,以及 '-' +- 须以字母开头 +- 须以字母数字结尾 + Kubernetes 会创建四个初始名字空间: -* `default` 没有指明使用其它名字空间的对象所使用的默认名字空间 -* `kube-system` Kubernetes 系统创建对象所使用的名字空间 -* `kube-public` 这个名字空间是自动创建的,所有用户(包括未经过身份验证的用户)都可以读取它。 - 这个名字空间主要用于集群使用,以防某些资源在整个集群中应该是可见和可读的。 - 这个名字空间的公共方面只是一种约定,而不是要求。 -* `kube-node-lease` 此名字空间用于与各个节点相关的租期(Lease)对象; - 此对象的设计使得集群规模很大时节点心跳检测性能得到提升。 + * `default` 没有指明使用其它名字空间的对象所使用的默认名字空间 + * `kube-system` Kubernetes 系统创建对象所使用的名字空间 + * `kube-public` 这个名字空间是自动创建的,所有用户(包括未经过身份验证的用户)都可以读取它。 + 这个名字空间主要用于集群使用,以防某些资源在整个集群中应该是可见和可读的。 + 这个名字空间的公共方面只是一种约定,而不是要求。 + * `kube-node-lease` 此名字空间用于与各个节点相关的 + [租约(Lease)](/docs/reference/kubernetes-api/cluster-resources/lease-v1/)对象。 + 节点租期允许 kubelet 发送[心跳](/zh/docs/concepts/architecture/nodes/#heartbeats),由此控制面能够检测到节点故障。