diff --git a/docs/reference/kubectl/conventions.md b/docs/reference/kubectl/conventions.md index 91856a73cb6ef..a2ff5772fa31f 100644 --- a/docs/reference/kubectl/conventions.md +++ b/docs/reference/kubectl/conventions.md @@ -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 | |:----------------------:|------------------------|-----------------------|--------------------------------------------|--------------------------------------------| @@ -53,21 +51,19 @@ depending on your cluster version: | Job | `--restart=OnFailure` | `--restart=OnFailure` | `--restart=OnFailure` OR `--restart=Never` | N/A | | Cron Job | `--schedule=` | 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.