whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update conventions.md (#7668)

Browse Source 
* Update conventions.md

Edited the content for better readability.

* Update conventions.md

Formatted the {:note} to **Note:**

* minor grammar fix
This commit is contained in:
Rajakavitha1
2018-03-23 22:41:02 +05:30
committed by k8s-ci-robot
parent 9f5b5c5ea9
commit de65320ec5
1 changed files with 25 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/kubectl/conventions.md
+25 -29
View File
@@ -10,40 +10,38 @@ title: kubectl Usage Conventions
## Using `kubectl` in Reusable Scripts ## 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` * 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 `--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, if using generator-based commands (such as `kubectl run` or `kubectl expose`) * 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 state * Don't rely on context, preferences, or other implicit states.
## Best Practices ## Best Practices
### `kubectl run` ### `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). * 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)).
* 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. * 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.
* If the image is heavily parameterized, definitely check in the script. * Check in the script for an image that is heavily parameterized.
* If features are needed that are not expressible via `kubectl run` flags, switch to configuration files checked into source control. * 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`. * Pin to a specific [generator](#generators) version, such as `kubectl run --generator=deployment/v1beta1`.
#### Generators #### 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`. * Pod - use `run-pod/v1`.
* Replication controller - use `run/v1`. * Replication controller - use `run/v1`.
* Deployment, using `extensions/v1beta1` endpoint - use `deployment/v1beta1` (default). * Deployment - use `extensions/v1beta1` and for an endpoint - use `deployment/v1beta1` (default).
* Deployment, using `apps/v1beta1` endpoint - use `deployment/apps.v1beta1` (recommended). * Deployment - use `apps/v1beta1` and for an endpoint - use `deployment/apps.v1beta1` (recommended).
* Job - use `job/v1`. * Job - use `job/v1`.
* CronJob - using `batch/v1beta1` endpoint - use `cronjob/v1beta1`(default). * CronJob - use `batch/v1beta1`and for an endpoint - use `cronjob/v1beta1`(default).
* CronJob - using `batch/v2alpha1` endpoint - use `cronjob/v2alpha1` (deprecated). * 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 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:
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 | | Generated Resource | Cluster v1.4 and later | Cluster v1.3 | Cluster v1.2 | Cluster v1.1 and earlier |
|:----------------------:|------------------------|-----------------------|--------------------------------------------|--------------------------------------------| |:----------------------:|------------------------|-----------------------|--------------------------------------------|--------------------------------------------|
@@ -53,21 +51,19 @@ depending on your cluster version:
| Job | `--restart=OnFailure` | `--restart=OnFailure` | `--restart=OnFailure` OR `--restart=Never` | N/A | | Job | `--restart=OnFailure` | `--restart=OnFailure` | `--restart=OnFailure` OR `--restart=Never` | N/A |
| Cron Job | `--schedule=<cron>` | N/A | N/A | 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 **Note:** These flags use a default generator only when you have not specified
any flag. This also means that combining `--generator` with other flags won't 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
change the generator you specified. For example, in a 1.4 cluster, if you specify `--restart=Always`, a Deployment is created; if you later specify `--restart=Always`
`--restart=Always`, a Deployment will be created; if you specify `--restart=Always` and `--generator=run/v1`, a Replication Controller is created.
and `--generator=run/v1`, a Replication Controller will be created instead. This enables you to pin to a specific behavior with the generator,
This becomes handy if you want to pin to a specific behavior with the generator, even when the default generator is changed later.
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 The flags set the generator in the following order: first the schedule flag then restart policy and finally the generator.
priority, then restart policy and finally the generator itself.
If in doubt about the final resource being created, you can always use `--dry-run` To check the final resource that was created, use `--dry-run`
flag, which will provide the object to be submitted to the cluster. flag, which provides the object to be submitted to the cluster.
### `kubectl apply` ### `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.