website/docs/user-guide/kubectl-conventions.md

assignees
bgrant0607 janetkuo

• TOC {:toc}

Using kubectl in Reusable Scripts

If you need stable output in a script, you should:

• Request one of the machine-oriented output forms, such as -o name, -o json, -o yaml, -o go-template, or -o jsonpath
• Specify --output-version, since those output forms (other than -o name) output the resource using a particular API version
• Specify --generator to pin to a specific behavior forever, if using generator-based commands (such as kubectl run or kubectl expose)
• Don't rely on context, preferences, or other implicit state

Best Practices

kubectl run

In order for kubectl run to satisfy infrastructure as code:

• Always tag your image with a version-specific tag and don't move that tag to a new version. For example, use :v1234, v1.2.3, r03062016-1-4, rather than :latest (see Best Practices for Configuration for more information.)
• If the image is lightly parameterized, capture the parameters in a checked-in script, or at least use --record, to annotate the created objects with the command line.
• If the image is heavily parameterized, definitely check in the script.
• If features are needed that are not expressible via kubectl run flags, switch to configuration files checked into source control.
• Pin to a specific generator version, such as kubectl run --generator=deployment/v1beta1

Generators

kubectl run allows you to generate the following resources (using --generator flag):

• Pod - use run-pod/v1.
• Replication controller - use run/v1.
• Deployment - use deployment/v1beta1.
• Job (using extension/v1beta1 endpoint) - use job/v1beta1. Starting from version 1.5 of kuberentes this generator is deprecated, with a plan to be removed in 1.6. Please use job/v1 instead.
• Job - use job/v1.
• CronJob - use cronjob/v2alpha1.

Additionally, if you didn't specify a generator flag, other flags will suggest using a specific generator. Below table shows which flags force using specific generators, depending on your cluster version:

Generated Resource	Cluster v1.4	Cluster v1.3	Cluster v1.2	Cluster v1.1 and eariler
Pod	--restart=Never	--restart=Never	--generator=run-pod/v1	--restart=OnFailure OR --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 OR --restart=Never	N/A
Cron Job	--schedule=<cron>	N/A	N/A	N/A

Note that these flags will use a default generator only when you have not specified any flag. This also means that combining --generator with other flags won't change the generator you specified. For example, in a 1.4 cluster, if you specify --restart=Always, a Deployment will be created; if you specify --restart=Always and --generator=run/v1, a Replication Controller will be created instead. This becomes handy if you want to pin to a specific behavior with the generator, even when the defaulted generator is changed in the future.

Finally, the order in which flags set the generator is: schedule flag has the highest priority, then restart policy and finally the generator itself.

If in doubt about the final resource being created, you can always use --dry-run flag, which will provide the object to be submitted to the cluster.

kubectl apply

• To use kubectl apply to update resources, always create resources initially with kubectl apply or with --save-config. See managing resources with kubectl apply for the reason behind it.