kubectl Usage Conventions
Using kubectl in Reusable Scripts
For a stable output in a script:
- 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, because the output forms use a particular API version to output the resource with the exception of-o nameoutput form - Specify
--generatorto pin to a specific behavior forever when you use generator-based commands such askubectl runorkubectl expose - Don’t rely on context, preferences, or other implicit states.
Best Practices
kubectl run
For kubectl run to satisfy infrastructure as code:
- Tag the 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(For more information, see Best Practices for Configuration). - Capture the parameters in a checked-in script, or at least use
--recordto annotate the created objects with the command line for an image that is lightly parameterized. - Check in the script for an image that is heavily parameterized.
- Switch to configuration files checked into source control for features that are needed, but not expressible via
kubectl runflags. - Pin to a specific generator version, such as
kubectl run --generator=deployment/v1beta1.
Generators
You can generate the following resources in kubectl runusing --generator flag:
- Pod - use
run-pod/v1. - Replication controller - use
run/v1. - Deployment - use
extensions/v1beta1and for an endpoint - usedeployment/v1beta1(default). - Deployment - use
apps/v1beta1and for an endpoint - usedeployment/apps.v1beta1(recommended). - Job - use
job/v1. - CronJob - use
batch/v1beta1and for an endpoint - usecronjob/v1beta1(default). - CronJob - use
batch/v2alpha1and for an endpoint - usecronjob/v2alpha1(deprecated).
If you do not specify a generator flag, other flags prompt you to use a specific generator. The following table lists the flags that force you to use specific generators, depending on the version of the cluster:
| 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: These flags use a default generator only when you have not specified
any flag. This means that when you combine --generator with other flags the generator that you specified later does not change. For example, in a cluster v1.4, if you initially specify
--restart=Always, a Deployment is created; if you later specify --restart=Always
and --generator=run/v1, a Replication Controller is created.
This enables you to pin to a specific behavior with the generator,
even when the default generator is changed later.
The flags set the generator in the following order: first the schedule flag then restart policy and finally the generator.
To check the final resource that was created, use --dry-run
flag, which provides the object to be submitted to the cluster.
kubectl apply
- When you use
kubectl applyto update resources, always create resources initially usingkubectl applyor using--save-config. See managing resources with kubectl apply for more information.