diff --git a/content/en/docs/concepts/cluster-administration/manage-deployment.md b/content/en/docs/concepts/cluster-administration/manage-deployment.md index 4d98cf820c..c09e59f1df 100644 --- a/content/en/docs/concepts/cluster-administration/manage-deployment.md +++ b/content/en/docs/concepts/cluster-administration/manage-deployment.md @@ -154,7 +154,7 @@ deployment.apps/my-deployment created persistentvolumeclaim/my-pvc created ``` -If you're interested in learning more about `kubectl`, go ahead and read [kubectl Overview](/docs/reference/kubectl/overview/). +If you're interested in learning more about `kubectl`, go ahead and read [Command line tool (kubectl)](/docs/reference/kubectl/). ## Using labels effectively diff --git a/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md b/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md index 365590e657..258014a432 100644 --- a/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md +++ b/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md @@ -26,7 +26,7 @@ many core Kubernetes functions are now built using custom resources, making Kube Custom resources can appear and disappear in a running cluster through dynamic registration, and cluster admins can update custom resources independently of the cluster itself. Once a custom resource is installed, users can create and access its objects using -[kubectl](/docs/reference/kubectl/overview/), just as they do for built-in resources like +[kubectl](/docs/reference/kubectl/), just as they do for built-in resources like *Pods*. ## Custom controllers diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index e1ddda4267..ed873bf352 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -23,7 +23,7 @@ The Kubernetes API lets you query and manipulate the state of API objects in Kub (for example: Pods, Namespaces, ConfigMaps, and Events). Most operations can be performed through the -[kubectl](/docs/reference/kubectl/overview/) command-line interface or other +[kubectl](/docs/reference/kubectl/) command-line interface or other command-line tools, such as [kubeadm](/docs/reference/setup-tools/kubeadm/), which in turn use the API. However, you can also access the API directly using REST calls. diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md index 021d2f840d..c41d20bdbb 100644 --- a/content/en/docs/reference/_index.md +++ b/content/en/docs/reference/_index.md @@ -43,7 +43,7 @@ client libraries: ## CLI -* [kubectl](/docs/reference/kubectl/overview/) - Main CLI tool for running commands and managing Kubernetes clusters. +* [kubectl](/docs/reference/kubectl/) - Main CLI tool for running commands and managing Kubernetes clusters. * [JSONPath](/docs/reference/kubectl/jsonpath/) - Syntax guide for using [JSONPath expressions](https://goessner.net/articles/JsonPath/) with kubectl. * [kubeadm](/docs/reference/setup-tools/kubeadm/) - CLI tool to easily provision a secure Kubernetes cluster. diff --git a/content/en/docs/reference/glossary/kubectl.md b/content/en/docs/reference/glossary/kubectl.md index 665fffcf98..61f93b9cf6 100644 --- a/content/en/docs/reference/glossary/kubectl.md +++ b/content/en/docs/reference/glossary/kubectl.md @@ -4,16 +4,19 @@ id: kubectl date: 2018-04-12 full_link: /docs/user-guide/kubectl-overview/ short_description: > - A command line tool for communicating with a Kubernetes API server. + A command line tool for communicating with a Kubernetes cluster. -aka: +aka: +- kubectl tags: - tool - fundamental --- - A command line tool for communicating with a {{< glossary_tooltip text="Kubernetes API" term_id="kubernetes-api" >}} server. +Command line tool for communicating with a Kubernetes cluster's +{{< glossary_tooltip text="control plane" term_id="control-plane" >}}, +using the Kubernetes API. -You can use kubectl to create, inspect, update, and delete Kubernetes objects. +You can use `kubectl` to create, inspect, update, and delete Kubernetes objects. diff --git a/content/en/docs/reference/kubectl/_index.md b/content/en/docs/reference/kubectl/_index.md index 765adb6fe8..ba53c66598 100644 --- a/content/en/docs/reference/kubectl/_index.md +++ b/content/en/docs/reference/kubectl/_index.md @@ -1,5 +1,550 @@ --- -title: "kubectl" +title: Command line tool (kubectl) +content_type: reference weight: 60 +card: + name: reference + weight: 20 --- + +{{< glossary_definition prepend="Kubernetes provides a" term_id="kubectl" length="short" >}} + +This tool is named `kubectl`. + +For configuration, `kubectl` looks for a file named `config` in the `$HOME/.kube` directory. +You can specify other [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) +files by setting the `KUBECONFIG` environment variable or by setting the +[`--kubeconfig`](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) flag. + +This overview covers `kubectl` syntax, describes the command operations, and provides common examples. +For details about each command, including all the supported flags and subcommands, see the +[kubectl](/docs/reference/generated/kubectl/kubectl-commands/) reference documentation. + +For installation instructions, see [Installing kubectl](/docs/tasks/tools/#kubectl). + + + +## Syntax + +Use the following syntax to run `kubectl` commands from your terminal window: + +```shell +kubectl [command] [TYPE] [NAME] [flags] +``` + +where `command`, `TYPE`, `NAME`, and `flags` are: + +* `command`: Specifies the operation that you want to perform on one or more resources, +for example `create`, `get`, `describe`, `delete`. + +* `TYPE`: Specifies the [resource type](#resource-types). Resource types are case-insensitive and + you can specify the singular, plural, or abbreviated forms. + For example, the following commands produce the same output: + + ```shell + kubectl get pod pod1 + kubectl get pods pod1 + kubectl get po pod1 + ``` + +* `NAME`: Specifies the name of the resource. Names are case-sensitive. If the name is omitted, details for all resources are displayed, for example `kubectl get pods`. + + When performing an operation on multiple resources, you can specify each resource by type and name or specify one or more files: + + * To specify resources by type and name: + + * To group resources if they are all the same type: `TYPE1 name1 name2 name<#>`.
+ Example: `kubectl get pod example-pod1 example-pod2` + + * To specify multiple resource types individually: `TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>`.
+ Example: `kubectl get pod/example-pod1 replicationcontroller/example-rc1` + + * To specify resources with one or more files: `-f file1 -f file2 -f file<#>` + + * [Use YAML rather than JSON](/docs/concepts/configuration/overview/#general-configuration-tips) since YAML tends to be more user-friendly, especially for configuration files.
+ Example: `kubectl get -f ./pod.yaml` + +* `flags`: Specifies optional flags. For example, you can use the `-s` or `--server` flags to specify the address and port of the Kubernetes API server.
+ +{{< caution >}} +Flags that you specify from the command line override default values and any corresponding environment variables. +{{< /caution >}} + +If you need help, run `kubectl help` from the terminal window. + +## In-cluster authentication and namespace overrides + +By default `kubectl` will first determine if it is running within a pod, and thus in a cluster. It starts by checking for the `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT` environment variables and the existence of a service account token file at `/var/run/secrets/kubernetes.io/serviceaccount/token`. If all three are found in-cluster authentication is assumed. + +To maintain backwards compatibility, if the `POD_NAMESPACE` environment variable is set during in-cluster authentication it will override the default namespace from the service account token. Any manifests or tools relying on namespace defaulting will be affected by this. + +**`POD_NAMESPACE` environment variable** + +If the `POD_NAMESPACE` environment variable is set, cli operations on namespaced resources will default to the variable value. For example, if the variable is set to `seattle`, `kubectl get pods` would return pods in the `seattle` namespace. This is because pods are a namespaced resource, and no namespace was provided in the command. Review the output of `kubectl api-resources` to determine if a resource is namespaced. + +Explicit use of `--namespace ` overrides this behavior. + +**How kubectl handles ServiceAccount tokens** + +If: +* there is Kubernetes service account token file mounted at + `/var/run/secrets/kubernetes.io/serviceaccount/token`, and +* the `KUBERNETES_SERVICE_HOST` environment variable is set, and +* the `KUBERNETES_SERVICE_PORT` environment variable is set, and +* you don't explicitly specify a namespace on the kubectl command line + +then kubectl assumes it is running in your cluster. The kubectl tool looks up the +namespace of that ServiceAccount (this is the same as the namespace of the Pod) +and acts against that namespace. This is different from what happens outside of a +cluster; when kubectl runs outside a cluster and you don't specify a namespace, +the kubectl command acts against the `default` namespace. + +## Operations + +The following table includes short descriptions and the general syntax for all of the `kubectl` operations: + +Operation | Syntax | Description +-------------------- | -------------------- | -------------------- +`alpha` | `kubectl alpha SUBCOMMAND [flags]` | List the available commands that correspond to alpha features, which are not enabled in Kubernetes clusters by default. +`annotate` | kubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] | Add or update the annotations of one or more resources. +`api-resources` | `kubectl api-resources [flags]` | List the API resources that are available. +`api-versions` | `kubectl api-versions [flags]` | List the API versions that are available. +`apply` | `kubectl apply -f FILENAME [flags]`| Apply a configuration change to a resource from a file or stdin. +`attach` | `kubectl attach POD -c CONTAINER [-i] [-t] [flags]` | Attach to a running container either to view the output stream or interact with the container (stdin). +`auth` | `kubectl auth [flags] [options]` | Inspect authorization. +`autoscale` | kubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags] | Automatically scale the set of pods that are managed by a replication controller. +`certificate` | `kubectl certificate SUBCOMMAND [options]` | Modify certificate resources. +`cluster-info` | `kubectl cluster-info [flags]` | Display endpoint information about the master and services in the cluster. +`completion` | `kubectl completion SHELL [options]` | Output shell completion code for the specified shell (bash or zsh). +`config` | `kubectl config SUBCOMMAND [flags]` | Modifies kubeconfig files. See the individual subcommands for details. +`convert` | `kubectl convert -f FILENAME [options]` | Convert config files between different API versions. Both YAML and JSON formats are accepted. Note - requires `kubectl-convert` plugin to be installed. +`cordon` | `kubectl cordon NODE [options]` | Mark node as unschedulable. +`cp` | `kubectl cp [options]` | Copy files and directories to and from containers. +`create` | `kubectl create -f FILENAME [flags]` | Create one or more resources from a file or stdin. +`delete` | kubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags] | Delete resources either from a file, stdin, or specifying label selectors, names, resource selectors, or resources. +`describe` | kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags] | Display the detailed state of one or more resources. +`diff` | `kubectl diff -f FILENAME [flags]`| Diff file or stdin against live configuration. +`drain` | `kubectl drain NODE [options]` | Drain node in preparation for maintenance. +`edit` | kubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags] | Edit and update the definition of one or more resources on the server by using the default editor. +`exec` | `kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]` | Execute a command against a container in a pod. +`explain` | `kubectl explain [--recursive=false] [flags]` | Get documentation of various resources. For instance pods, nodes, services, etc. +`expose` | kubectl expose (-f FILENAME | TYPE NAME | TYPE/NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--external-ip=external-ip-of-service] [--type=type] [flags] | Expose a replication controller, service, or pod as a new Kubernetes service. +`get` | kubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags] | List one or more resources. +`kustomize` | `kubectl kustomize [flags] [options]` | List a set of API resources generated from instructions in a kustomization.yaml file. The argument must be the path to the directory containing the file, or a git repository URL with a path suffix specifying same with respect to the repository root. +`label` | kubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] | Add or update the labels of one or more resources. +`logs` | `kubectl logs POD [-c CONTAINER] [--follow] [flags]` | Print the logs for a container in a pod. +`options` | `kubectl options` | List of global command-line options, which apply to all commands. +`patch` | kubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags] | Update one or more fields of a resource by using the strategic merge patch process. +`plugin` | `kubectl plugin [flags] [options]` | Provides utilities for interacting with plugins. +`port-forward` | `kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags]` | Forward one or more local ports to a pod. +`proxy` | `kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags]` | Run a proxy to the Kubernetes API server. +`replace` | `kubectl replace -f FILENAME` | Replace a resource from a file or stdin. +`rollout` | `kubectl rollout SUBCOMMAND [options]` | Manage the rollout of a resource. Valid resource types include: deployments, daemonsets and statefulsets. +`run` | kubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags] | Run a specified image on the cluster. +`scale` | kubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags] | Update the size of the specified replication controller. +`set` | `kubectl set SUBCOMMAND [options]` | Configure application resources. +`taint` | `kubectl taint NODE NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N [options]` | Update the taints on one or more nodes. +`top` | `kubectl top [flags] [options]` | Display Resource (CPU/Memory/Storage) usage. +`uncordon` | `kubectl uncordon NODE [options]` | Mark node as schedulable. +`version` | `kubectl version [--client] [flags]` | Display the Kubernetes version running on the client and server. +`wait` | kubectl wait ([-f FILENAME] | resource.group/resource.name | resource.group [(-l label | --all)]) [--for=delete|--for condition=available] [options] | Experimental: Wait for a specific condition on one or many resources. + +To learn more about command operations, see the [kubectl](/docs/reference/kubectl/kubectl/) reference documentation. + +## Resource types + +The following table includes a list of all the supported resource types and their abbreviated aliases. + +(This output can be retrieved from `kubectl api-resources`, and was accurate as of Kubernetes 1.19.1.) + +| NAME | SHORTNAMES | APIGROUP | NAMESPACED | KIND | +|---|---|---|---|---| +| `bindings` | | | true | Binding | +| `componentstatuses` | `cs` | | false | ComponentStatus | +| `configmaps` | `cm` | | true | ConfigMap | +| `endpoints` | `ep` | | true | Endpoints | +| `events` | `ev` | | true | Event | +| `limitranges` | `limits` | | true | LimitRange | +| `namespaces` | `ns` | | false | Namespace | +| `nodes` | `no` | | false | Node | +| `persistentvolumeclaims` | `pvc` | | true | PersistentVolumeClaim | +| `persistentvolumes` | `pv` | | false | PersistentVolume | +| `pods` | `po` | | true | Pod | +| `podtemplates` | | | true | PodTemplate | +| `replicationcontrollers` | `rc` | | true | ReplicationController | +| `resourcequotas` | `quota` | | true | ResourceQuota | +| `secrets` | | | true | Secret | +| `serviceaccounts` | `sa` | | true | ServiceAccount | +| `services` | `svc` | | true | Service | +| `mutatingwebhookconfigurations` | | admissionregistration.k8s.io | false | MutatingWebhookConfiguration | +| `validatingwebhookconfigurations` | | admissionregistration.k8s.io | false | ValidatingWebhookConfiguration | +| `customresourcedefinitions` | `crd,crds` | apiextensions.k8s.io | false | CustomResourceDefinition | +| `apiservices` | | apiregistration.k8s.io | false | APIService | +| `controllerrevisions` | | apps | true | ControllerRevision | +| `daemonsets` | `ds` | apps | true | DaemonSet | +| `deployments` | `deploy` | apps | true | Deployment | +| `replicasets` | `rs` | apps | true | ReplicaSet | +| `statefulsets` | `sts` | apps | true | StatefulSet | +| `tokenreviews` | | authentication.k8s.io | false | TokenReview | +| `localsubjectaccessreviews` | | authorization.k8s.io | true | LocalSubjectAccessReview | +| `selfsubjectaccessreviews` | | authorization.k8s.io | false | SelfSubjectAccessReview | +| `selfsubjectrulesreviews` | | authorization.k8s.io | false | SelfSubjectRulesReview | +| `subjectaccessreviews` | | authorization.k8s.io | false | SubjectAccessReview | +| `horizontalpodautoscalers` | `hpa` | autoscaling | true | HorizontalPodAutoscaler | +| `cronjobs` | `cj` | batch | true | CronJob | +| `jobs` | | batch | true | Job | +| `certificatesigningrequests` | `csr` | certificates.k8s.io | false | CertificateSigningRequest | +| `leases` | | coordination.k8s.io | true | Lease | +| `endpointslices` | | discovery.k8s.io | true | EndpointSlice | +| `events` | `ev` | events.k8s.io | true | Event | +| `ingresses` | `ing` | extensions | true | Ingress | +| `flowschemas` | | flowcontrol.apiserver.k8s.io | false | FlowSchema | +| `prioritylevelconfigurations` | | flowcontrol.apiserver.k8s.io | false | PriorityLevelConfiguration | +| `ingressclasses` | | networking.k8s.io | false | IngressClass | +| `ingresses` | `ing` | networking.k8s.io | true | Ingress | +| `networkpolicies` | `netpol` | networking.k8s.io | true | NetworkPolicy | +| `runtimeclasses` | | node.k8s.io | false | RuntimeClass | +| `poddisruptionbudgets` | `pdb` | policy | true | PodDisruptionBudget | +| `podsecuritypolicies` | `psp` | policy | false | PodSecurityPolicy | +| `clusterrolebindings` | | rbac.authorization.k8s.io | false | ClusterRoleBinding | +| `clusterroles` | | rbac.authorization.k8s.io | false | ClusterRole | +| `rolebindings` | | rbac.authorization.k8s.io | true | RoleBinding | +| `roles` | | rbac.authorization.k8s.io | true | Role | +| `priorityclasses` | `pc` | scheduling.k8s.io | false | PriorityClass | +| `csidrivers` | | storage.k8s.io | false | CSIDriver | +| `csinodes` | | storage.k8s.io | false | CSINode | +| `storageclasses` | `sc` | storage.k8s.io | false | StorageClass | +| `volumeattachments` | | storage.k8s.io | false | VolumeAttachment | + +## Output options + +Use the following sections for information about how you can format or sort the output of certain commands. For details about which commands support the various output options, see the [kubectl](/docs/reference/kubectl/kubectl/) reference documentation. + +### Formatting output + +The default output format for all `kubectl` commands is the human readable plain-text format. To output details to your terminal window in a specific format, you can add either the `-o` or `--output` flags to a supported `kubectl` command. + +#### Syntax + +```shell +kubectl [command] [TYPE] [NAME] -o +``` + +Depending on the `kubectl` operation, the following output formats are supported: + +Output format | Description +--------------| ----------- +`-o custom-columns=` | Print a table using a comma separated list of [custom columns](#custom-columns). +`-o custom-columns-file=` | Print a table using the [custom columns](#custom-columns) template in the `` file. +`-o json` | Output a JSON formatted API object. +`-o jsonpath=