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

Merge pull request #21160 from sftim/20200524_revise_kubectl_overview

Browse Source 
Revise kubectl overview
This commit is contained in:
Kubernetes Prow Robot
2020-06-12 22:53:57 -07:00
committed by GitHub
parent d0024d7d44 400c98fb5f
commit ffc4df9f2a
1 changed files with 43 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/reference/kubectl/overview.md
+43 -32
View File
@@ -10,7 +10,7 @@ card:
--- ---
<!-- overview --> <!-- overview -->
Kubectl is a command line tool for controlling Kubernetes clusters. `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. The kubectl command line tool lets you control Kubernetes clusters. 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/kubectl/install/). 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/kubectl/install/).
@@ -32,11 +32,11 @@ where `command`, `TYPE`, `NAME`, and `flags` are:
* `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: * `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 ```shell
kubectl get pod pod1 kubectl get pod pod1
kubectl get pods pod1 kubectl get pods pod1
kubectl get po 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`. * `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`.
@@ -113,13 +113,13 @@ Operation | Syntax | Description
`version` | `kubectl version [--client] [flags]` | Display the Kubernetes version running on the client and server. `version` | `kubectl version [--client] [flags]` | Display the Kubernetes version running on the client and server.
`wait` | <code>kubectl wait ([-f FILENAME] &#124; resource.group/resource.name &#124; resource.group [(-l label &#124; --all)]) [--for=delete&#124;--for condition=available] [options]</code> | Experimental: Wait for a specific condition on one or many resources. `wait` | <code>kubectl wait ([-f FILENAME] &#124; resource.group/resource.name &#124; resource.group [(-l label &#124; --all)]) [--for=delete&#124;--for condition=available] [options]</code> | Experimental: Wait for a specific condition on one or many resources.
Remember: For more about command operations, see the [kubectl](/docs/user-guide/kubectl/) reference documentation. To learn more about command operations, see the [kubectl](/docs/reference/kubectl/kubectl/) reference documentation.
## Resource types ## Resource types
The following table includes a list of all the supported resource types and their abbreviated aliases. 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 is accurate as of Kubernetes 1.13.3.) (This output can be retrieved from `kubectl api-resources`, and was accurate as of Kubernetes 1.13.3.)
| Resource Name | Short Names | API Group | Namespaced | Resource Kind | | Resource Name | Short Names | API Group | Namespaced | Resource Kind |
|---|---|---|---|---| |---|---|---|---|---|
@@ -175,7 +175,7 @@ The following table includes a list of all the supported resource types and thei
## Output options ## 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/user-guide/kubectl/) reference documentation. 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 ### Formatting output
@@ -234,9 +234,9 @@ where the `template.txt` file contains:
NAME RSRC NAME RSRC
metadata.name metadata.resourceVersion metadata.name metadata.resourceVersion
``` ```
The result of running either command is: The result of running either command is similar to:
```shell ```
NAME RSRC NAME RSRC
submit-queue 610995 submit-queue 610995
``` ```
@@ -247,7 +247,7 @@ submit-queue 610995
This means that for any given resource, the server will return columns and rows relevant to that resource, for the client to print. This means that for any given resource, the server will return columns and rows relevant to that resource, for the client to print.
This allows for consistent human-readable output across clients used against the same cluster, by having the server encapsulate the details of printing. This allows for consistent human-readable output across clients used against the same cluster, by having the server encapsulate the details of printing.
This feature is enabled by default in `kubectl` 1.11 and higher. To disable it, add the This feature is enabled by default. To disable it, add the
`--server-print=false` flag to the `kubectl get` command. `--server-print=false` flag to the `kubectl get` command.
##### Examples ##### Examples
@@ -258,9 +258,9 @@ To print information about the status of a pod, use a command like the following
kubectl get pods <pod-name> --server-print=false kubectl get pods <pod-name> --server-print=false
``` ```
Output looks like this: The output is similar to:
```shell ```
NAME AGE NAME AGE
pod-name 1m pod-name 1m
``` ```
@@ -405,19 +405,23 @@ Use the following set of examples to help you familiarize yourself with writing
# create a simple plugin in any language and name the resulting executable file # create a simple plugin in any language and name the resulting executable file
# so that it begins with the prefix "kubectl-" # so that it begins with the prefix "kubectl-"
cat ./kubectl-hello cat ./kubectl-hello
#!/bin/bash ```
```shell
#!/bin/sh
# this plugin prints the words "hello world" # this plugin prints the words "hello world"
echo "hello world" echo "hello world"
```
# with our plugin written, let's make it executable With a plugin written, let's make it executable:
sudo chmod +x ./kubectl-hello ```bash
chmod a+x ./kubectl-hello
# and move it to a location in our PATH # and move it to a location in our PATH
sudo mv ./kubectl-hello /usr/local/bin sudo mv ./kubectl-hello /usr/local/bin
sudo chown root:root /usr/local/bin
# we have now created and "installed" a kubectl plugin. # You have now created and "installed" a kubectl plugin.
# we can begin using our plugin by invoking it from kubectl as if it were a regular command # You can begin using this plugin by invoking it from kubectl as if it were a regular command
kubectl hello kubectl hello
``` ```
``` ```
@@ -425,16 +429,18 @@ hello world
``` ```
```shell ```shell
# we can "uninstall" a plugin, by simply removing it from our PATH # You can "uninstall" a plugin, by removing it from the folder in your
# $PATH where you placed it
sudo rm /usr/local/bin/kubectl-hello sudo rm /usr/local/bin/kubectl-hello
``` ```
In order to view all of the plugins that are available to `kubectl`, we can use In order to view all of the plugins that are available to `kubectl`, use
the `kubectl plugin list` subcommand: the `kubectl plugin list` subcommand:
```shell ```shell
kubectl plugin list kubectl plugin list
``` ```
The output is similar to:
``` ```
The following kubectl-compatible plugins are available: The following kubectl-compatible plugins are available:
@@ -442,11 +448,11 @@ The following kubectl-compatible plugins are available:
/usr/local/bin/kubectl-foo /usr/local/bin/kubectl-foo
/usr/local/bin/kubectl-bar /usr/local/bin/kubectl-bar
``` ```
`kubectl plugin list` also warns you about plugins that are not
executable, or that are shadowed by other plugins; for example:
```shell ```shell
# this command can also warn us about plugins that are sudo chmod -x /usr/local/bin/kubectl-foo # remove execute permission
# not executable, or that are overshadowed by other
# plugins, for example
sudo chmod -x /usr/local/bin/kubectl-foo
kubectl plugin list kubectl plugin list
``` ```
``` ```
@@ -460,11 +466,15 @@ The following kubectl-compatible plugins are available:
error: one plugin warning was found error: one plugin warning was found
``` ```
We can think of plugins as a means to build more complex functionality on top You can think of plugins as a means to build more complex functionality on top
of the existing kubectl commands: of the existing kubectl commands:
```shell ```shell
cat ./kubectl-whoami cat ./kubectl-whoami
```
The next few examples assume that you already made `kubectl-whoami` have
the following contents:
```shell
#!/bin/bash #!/bin/bash
# this plugin makes use of the `kubectl config` command in order to output # this plugin makes use of the `kubectl config` command in order to output
@@ -472,27 +482,28 @@ cat ./kubectl-whoami
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}' kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}'
``` ```
Running the above plugin gives us an output containing the user for the currently selected Running the above command gives you an output containing the user for the
context in our KUBECONFIG file: current context in your KUBECONFIG file:
```shell ```shell
# make the file executable # make the file executable
sudo chmod +x ./kubectl-whoami sudo chmod +x ./kubectl-whoami
# and move it into our PATH # and move it into your PATH
sudo mv ./kubectl-whoami /usr/local/bin sudo mv ./kubectl-whoami /usr/local/bin
kubectl whoami kubectl whoami
Current user: plugins-user Current user: plugins-user
``` ```
To find out more about plugins, take a look at the [example cli plugin](https://github.com/kubernetes/sample-cli-plugin).
## {{% heading "whatsnext" %}} ## {{% heading "whatsnext" %}}
Start using the [kubectl](/docs/reference/generated/kubectl/kubectl-commands/) commands. * Start using the [kubectl](/docs/reference/generated/kubectl/kubectl-commands/) commands.
* To find out more about plugins, take a look at the [example cli plugin](https://github.com/kubernetes/sample-cli-plugin).