kubectl Usage Conventions
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
--generatorto pin to a specific behavior forever, if using generator-based commands (such askubectl runorkubectl 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
--recordto 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 runflags, 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, using
extensions/v1beta1endpoint - usedeployment/v1beta1(default). - Deployment, using
apps/v1beta1endpoint - usedeployment/apps.v1beta1(recommended). - Job - use
job/v1. - CronJob - using
batch/v1beta1endpoint - usecronjob/v1beta1(default). - CronJob - using
batch/v2alpha1endpoint - usecronjob/v2alpha1(deprecated).
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 and later | Cluster v1.3 | Cluster v1.2 | Cluster v1.1 and earlier |
|---|---|---|---|---|
| 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 applyto update resources, always create resources initially withkubectl applyor with--save-config. See managing resources with kubectl apply for the reason behind it.