website/content/zh/docs/reference/kubectl/conventions.md

title, reviewers, content_template

title	reviewers	content_template
kubectl 的用法约定	bgrant0607 janetkuo	templates/concept

{{% capture overview %}}

kubectl 的推荐用法约定 {{% /capture %}}

{{% capture body %}}

在可重用脚本中使用 kubectl

对于脚本中的稳定输出：

• 请求一个面向机器的输出格式，例如 -o name、-o json、-o yaml、-o go template 或 -o jsonpath。
• 完全限定版本。例如 jobs.v1.batch/myjob。这将确保 kubectl 不会使用其默认版本，该版本会随着时间的推移而更改。
• 在使用基于生成器的命令（例如 kubectl run 或者 kubectl expose）时，指定 --generator 参数以固定到特定行为。
• 不要依赖上下文、首选项或其他隐式状态。

最佳实践

kubectl run

若希望 kubectl run 满足"基础设施即代码（infrastructure as code）"的要求：

• 使用特定版本的标签标记镜像，不要将该标签移动到新版本。例如，使用 :v1234、v1.2.3、r03062016-1-4，而不是 :latest（有关详细信息，请参阅配置的最佳实践)。
• 使用基于版本控制的脚本来记录所使用的参数，或者至少使用 --record 参数以便为所创建的对象添加注解，在使用轻度参数化的镜像时，记录下所使用的命令行。
• 使用基于版本控制的脚本来运行包含大量参数的镜像。
• 对于无法通过 kubectl run 参数来表示的功能特性，使用基于源码控制的配置文件，以记录要使用的功能特性。
• 固定到特定的生成器版本，例如 kubectl run --generator=deployment/v1beta1。

生成器

您可以使用带有 --generator 参数的 kubectl run 命令创建如下资源：

资源	kubectl 命令
Pod	kubectl run --generator=run-pod/v1
Replication controller	kubectl run --generator=run/v1
Deployment	kubectl run --generator=extensions/v1beta1
-同时获得端点（默认）	kubectl run --generator=deployment/v1beta1
Deployment	kubectl run --generator=apps/v1beta1
-端点（推荐）	kubectl run --generator=deployment/apps.v1beta1
Job	kubectl run --generator=job/v1
CronJob	kubectl run --generator=batch/v1beta1
-端点（默认）	kubectl run --generator=cronjob/v1beta1
CronJob	kubectl run --generator=batch/v2alpha1
-端点（废弃）	kubectl run --generator=cronjob/v2alpha1

如果不指定 generator 参数，其他参数将提示您使用特定的生成器。下表列出了强制您使用特定生成器的参数，具体取决于集群的版本：

生成的资源	集群版本 v1.4 及以后版本	集群版本 v1.3	集群版本 v1.2	集群版本 v1.1 及更早
Pod	--restart=Never	--restart=Never	--generator=run-pod/v1	--restart=OnFailure 或 --restart=Never
Replication Controller	--generator=run/v1	--generator=run/v1	--generator=run/v1	--restart=Always
Deployment	--restart=Always	--restart=Always	--restart=Always	N/A
Job	--restart=OnFailure	--restart=OnFailure	--restart=OnFailure 或 --restart=Never	N/A
Cron Job	--schedule=<cron>	N/A	N/A	N/A

{{< note >}}

只有在未指定任何参数时，这些参数才使用默认生成器。 这意味着，当您将 --generator 与其他参数组合时，随后指定的生成器不会更改。 例如，在集群版本 v1.4 中，如果最初指定了 --restart=always，则会创建 Deployment；如果后来指定了 --restart=always 和 --generator=run/v1，则会创建 Replication Controller。 这使您能够将生成器固定到特定的行为，即使在以后更改默认生成器时也是如此。 {{< /note >}}

这些参数按以下顺序设置生成器：首先是 --schedule 参数，然后是 --restart 策略参数，最后是 --generator 参数。

要检查最终所创建的资源，请使用 --dry run 参数；该参数可以提供将要提交到集群的对象。

kubectl apply

• 您可以使用 kubectl apply 命令创建或更新资源。但是，要更新资源，您应该使用 kubectl apply 或者 kubectl create --save-config 创建该资源。有关使用 kubectl apply 更新资源的详细信息，请参阅 管理资源。

{{% /capture %}}