kubectl Usage Conventions
Recommended usage conventions for kubectl
.
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
. - Fully-qualify the version. For example,
jobs.v1.batch/myjob
. This will ensure that kubectl does not use its default version that can change over time. - Specify the
--generator
flag to pin to a specific behavior when you use generator-based commands such askubectl run
orkubectl 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
--record
to annotate the created objects with the command line for an image that is lightly parameterized. - Pin to a specific generator version, such as
kubectl run --generator=run-pod/v1
. - 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 run
flags.
Generators
You can create the following resources using kubectl run
with the --generator
flag:
Resource | API group | kubectl command |
---|---|---|
Pod | v1 | kubectl run --generator=run-pod/v1 |
ReplicationController (deprecated) | v1 | kubectl run --generator=run/v1 |
Deployment (deprecated) | extensions/v1beta1 | kubectl run --generator=deployment/v1beta1 |
Deployment (deprecated) | apps/v1beta1 | kubectl run --generator=deployment/apps.v1beta1 |
Job (deprecated) | batch/v1 | kubectl run --generator=job/v1 |
CronJob (deprecated) | batch/v2alpha1 | kubectl run --generator=cronjob/v2alpha1 |
CronJob (deprecated) | batch/v1beta1 | kubectl run --generator=cronjob/v1beta1 |
Note: Generators other thanrun-pod/v1
are deprecated.
If you explicitly set --generator
, kubectl uses the generator you specified. If you invoke kubectl run
and don’t specify a generator, kubectl automatically selects which generator to use based on the other flags you set. The following table lists flags and the generators that are activated if you didn’t specify one yourself:
Flag | Generated Resource |
---|---|
--schedule=<schedule> |
CronJob |
--restart=Always |
Deployment |
--restart=OnFailure |
Job |
--restart=Never |
Pod |
If you don’t specify a generator, kubectl pays attention to other flags in the following order:
--schedule
--restart
You can use the --dry-run
flag to preview the object that would be sent to your cluster, without really submitting it.
kubectl apply
- You can use
kubectl apply
to create or update resources. For more information about using kubectl apply to update resources, see Kubectl Book.
Feedback
Was this page helpful?
Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.