kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
website/content/en/docs/reference/kubectl/conventions.md

5.1 KiB
Raw Blame History

title reviewers content_template
kubectl Usage Conventions
janetkuo
templates/concept

{{% capture overview %}} Recommended usage conventions for kubectl. {{% /capture %}}

{{% capture body %}}

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 as kubectl run or kubectl 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 generate the following resources with a kubectl command, kubectl create --dry-run -o yaml:

  clusterrole         Create a ClusterRole.
  clusterrolebinding  Create a ClusterRoleBinding for a particular ClusterRole.
  configmap           Create a configmap from a local file, directory or literal value.
  cronjob             Create a cronjob with the specified name.
  deployment          Create a deployment with the specified name.
  job                 Create a job with the specified name.
  namespace           Create a namespace with the specified name.
  poddisruptionbudget Create a pod disruption budget with the specified name.
  priorityclass       Create a priorityclass with the specified name.
  quota               Create a quota with the specified name.
  role                Create a role with single rule.
  rolebinding         Create a RoleBinding for a particular Role or ClusterRole.
  secret              Create a secret using specified subcommand.
  service             Create a service using specified subcommand.
  serviceaccount      Create a service account with the specified name.

You can create the following resources using kubectl run with the --generator flag:

{{< table caption="Resources you can create using kubectl run" >}}

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
{{< /table >}}

{{< note >}} Generators other than run-pod/v1 are deprecated. {{< /note >}}

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:

{{< table caption="kubectl run flags and the resource they imply" >}}

Flag Generated Resource
--schedule=<schedule> CronJob
--restart=Always Deployment
--restart=OnFailure Job
--restart=Never Pod
{{< /table >}}

If you don't specify a generator, kubectl pays attention to other flags in the following order:

  1. --schedule
  2. --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.

{{% /capture %}}