Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update conventions.md #7668

Merged
merged 3 commits into from
Mar 23, 2018
Merged

Update conventions.md #7668

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7f38505
Update conventions.md
Rajakavitha1 Mar 7, 2018
9ceaf3b
Update conventions.md
Rajakavitha1 Mar 20, 2018
88289a8
minor grammar fix
heckj Mar 23, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 25 additions & 29 deletions docs/reference/kubectl/conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,40 +10,38 @@ title: kubectl Usage Conventions

## Using `kubectl` in Reusable Scripts

If you need stable output in a script, you should:
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`, 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
* Specify `--output-version`, because the output forms use a particular API version to output the resource with the exception of `-o name` output form
* Specify `--generator` to pin to a specific behavior forever when you use generator-based commands such as `kubectl run` or `kubectl expose`
* Don't rely on context, preferences, or other implicit states.

## Best Practices

### `kubectl run`

In order for `kubectl run` to satisfy infrastructure as code:
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/concepts/configuration/overview/#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.
* 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](/docs/concepts/configuration/overview/#container-images)).
* 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.
* 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.
* 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):
You can generate the following resources in `kubectl run`using `--generator` flag:

* Pod - use `run-pod/v1`.
* Replication controller - use `run/v1`.
* Deployment, using `extensions/v1beta1` endpoint - use `deployment/v1beta1` (default).
* Deployment, using `apps/v1beta1` endpoint - use `deployment/apps.v1beta1` (recommended).
* Deployment - use `extensions/v1beta1` and for an endpoint - use `deployment/v1beta1` (default).
* Deployment - use `apps/v1beta1` and for an endpoint - use `deployment/apps.v1beta1` (recommended).
* Job - use `job/v1`.
* CronJob - using `batch/v1beta1` endpoint - use `cronjob/v1beta1`(default).
* CronJob - using `batch/v2alpha1` endpoint - use `cronjob/v2alpha1` (deprecated).
* CronJob - use `batch/v1beta1`and for an endpoint - use `cronjob/v1beta1`(default).
* CronJob - use`batch/v2alpha1` and for an endpoint - use `cronjob/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:
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 |
|:----------------------:|------------------------|-----------------------|--------------------------------------------|--------------------------------------------|
Expand All @@ -53,21 +51,19 @@ depending on your cluster version:
| 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.
**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.

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

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.
To check the final resource that was created, use `--dry-run`
flag, which provides 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/concepts/cluster-administration/manage-deployment/#kubectl-apply) for the reason behind it.
* When you use `kubectl apply` to update resources, always create resources initially using `kubectl apply` or using `--save-config`. See [managing resources with kubectl apply](/docs/concepts/cluster-administration/manage-deployment/#kubectl-apply) for more information.