75 lines
4.4 KiB
Markdown
75 lines
4.4 KiB
Markdown
---
|
|
assignees:
|
|
- bgrant0607
|
|
- janetkuo
|
|
title: kubectl Usage Conventions
|
|
---
|
|
|
|
* 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](/docs/user-guide/config-best-practices/#container-images) 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](#generators) 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](/docs/user-guide/managing-deployments/#kubectl-apply) for the reason behind it.
|