Overview of kubectl

    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 reference documentation. For installation instructions see .

    Use the following syntax to run kubectl commands from your terminal window:

    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 are case-insensitive and you can specify the singular, plural, or abbreviated forms. For example, the following commands produce the same output:

    1.   kubectl get pod pod1
    2.   kubectl get pods pod1
    3.   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<#>

      • since YAML tends to be more user-friendly, especially for configuration files.Example: kubectl get pod -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.

    If you need help, just run kubectl help from the terminal window.

    Operations

    The following table includes short descriptions and the general syntax for all of the kubectl operations:

    Remember: For more about command operations, see the reference documentation.

    The following table includes a list of all the supported resource types and their abbreviated aliases.

    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 reference documentation.

    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

    1. kubectl [command] [TYPE] [NAME] -o <output_format>

    Depending on the kubectl operation, the following output formats are supported:

    Example

    In this example, the following command outputs the details for a single pod as a YAML formatted object:

    1. kubectl get pod web-pod-13je7 -o yaml

    Remember: See the kubectl reference documentation for details about which output format is supported by each command.

    Custom columns

    To define custom columns and output only the details that you want into a table, you can use the custom-columns option. You can choose to define the custom columns inline or use a template file: -o custom-columns=<spec> or -o custom-columns-file=<filename>.

    Examples

    Inline:

    1. kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion

    Template file:

    1. kubectl get pods <pod-name> -o custom-columns-file=template.txt

    where the template.txt file contains:

    1. NAME          RSRC
    2. metadata.name metadata.resourceVersion

    The result of running either command is:

    1. NAME           RSRC
    2. submit-queue   610995

    Server-side columns

    kubectl supports receiving specific column information from the server about objects.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 feature is enabled by default in kubectl 1.11 and higher. To disable it, add the—server-print=false flag to the kubectl get command.

    Examples

    To print information about the status of a pod, use a command like the following:

    1. kubectl get pods <pod-name> --server-print=false

    Output looks like this:

    Sorting list objects

    Syntax

    1. kubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>
    Example

    To print a list of pods sorted by name, you run:

    1. kubectl get pods --sort-by=.metadata.name

    Use the following set of examples to help you familiarize yourself with running the commonly used kubectl operations:

    kubectl apply - Apply or Update a resource from a file or stdin.

    1. # Create a service using the definition in example-service.yaml.
    2. kubectl apply -f example-service.yaml
    4. # Create a replication controller using the definition in example-controller.yaml.
    6. # Create the objects that are defined in any .yaml, .yml, or .json file within the <directory> directory.
    7. kubectl apply -f <directory>

    - List one or more resources.

    1. # List all pods in plain-text output format.
    2. kubectl get pods
    4. # List all pods in plain-text output format and include additional information (such as node name).
    5. kubectl get pods -o wide
    7. # List the replication controller with the specified name in plain-text output format. Tip: You can shorten and replace the 'replicationcontroller' resource type with the alias 'rc'.
    8. kubectl get replicationcontroller <rc-name>
    10. # List all replication controllers and services together in plain-text output format.
    11. kubectl get rc,services
    13. # List all daemon sets in plain-text output format.
    14. kubectl get ds
    16. # List all pods running on node server01
    17. kubectl get pods --field-selector=spec.nodeName=server01

    kubectl describe - Display detailed state of one or more resources, including the uninitialized ones by default.

    1. # Display the details of the node with name <node-name>.
    2. kubectl describe nodes <node-name>
    4. # Display the details of the pod with name <pod-name>.
    5. kubectl describe pods/<pod-name>
    7. # Display the details of all the pods that are managed by the replication controller named <rc-name>.
    8. # Remember: Any pods that are created by the replication controller get prefixed with the name of the replication controller.
    9. kubectl describe pods <rc-name>
    11. # Describe all pods
    12. kubectl describe pods
    Note: The kubectl get command is usually used for retrieving one or moreresources of the same resource type. It features a rich set of flags that allowsyou to customize the output format using the -o or —output flag, for example.You can specify the -w or —watch flag to start watching updates to a particularobject. The kubectl describe command is more focused on describing the manyrelated aspects of a specified resource. It may invoke several API calls to theAPI server to build a view for the user. For example, the kubectl describe nodecommand retrieves not only the information about the node, but also a summary ofthe pods running on it, the events generated for the node etc.

    kubectl delete - Delete resources either from a file, stdin, or specifying label selectors, names, resource selectors, or resources.

    1. # Delete a pod using the type and name specified in the pod.yaml file.
    2. kubectl delete -f pod.yaml
    4. # Delete all the pods and services that have the label name=<label-name>.
    5. kubectl delete pods,services -l name=<label-name>
    7. # Delete all the pods and services that have the label name=<label-name>.
    8. kubectl delete pods,services -l name=<label-name>
    10. # Delete all pods, including uninitialized ones.
    11. kubectl delete pods --all

    kubectl exec - Execute a command against a container in a pod.

    1. # Get output from running 'date' from pod <pod-name>. By default, output is from the first container.
    2. kubectl exec <pod-name> date
    3. # Get output from running 'date' in container <container-name> of pod <pod-name>.
    4. kubectl exec <pod-name> -c <container-name> date
    6. # Get an interactive TTY and run /bin/bash from pod <pod-name>. By default, output is from the first container.
    7. kubectl exec -ti <pod-name> /bin/bash

    kubectl logs - Print the logs for a container in a pod.

    1. # Return a snapshot of the logs from pod <pod-name>.
    2. kubectl logs <pod-name>
    4. # Start streaming the logs from pod <pod-name>. This is similar to the 'tail -f' Linux command.
    5. kubectl logs -f <pod-name>

    Examples: Creating and using plugins

    Use the following set of examples to help you familiarize yourself with writing and using kubectl plugins:

    1. hello world
    1. # we can "uninstall" a plugin, by simply removing it from our PATH
    2. sudo rm /usr/local/bin/kubectl-hello

    In order to view all of the plugins that are available to kubectl, we can usethe kubectl plugin list subcommand:

    1. kubectl plugin list
    1. The following kubectl-compatible plugins are available:
    3. /usr/local/bin/kubectl-hello
    4. /usr/local/bin/kubectl-foo
    5. /usr/local/bin/kubectl-bar
    1. # this command can also warn us about plugins that are
    2. # not executable, or that are overshadowed by other
    3. # plugins, for example
    4. sudo chmod -x /usr/local/bin/kubectl-foo
    5. kubectl plugin list
    1. The following kubectl-compatible plugins are available:
    3. /usr/local/bin/kubectl-hello
    4. /usr/local/bin/kubectl-foo
    5.   - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
    6. /usr/local/bin/kubectl-bar
    8. error: one plugin warning was found

    We can think of plugins as a means to build more complex functionality on topof the existing kubectl commands:

    1. cat ./kubectl-whoami
    2. #!/bin/bash
    4. # this plugin makes use of the `kubectl config` command in order to output
    5. # information about the current user, based on the currently selected context
    6. kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ .context.user }}{{ end }}{{ end }}'

    Running the above plugin gives us an output containing the user for the currently selectedcontext in our KUBECONFIG file:

    1. # make the file executable
    2. sudo chmod +x ./kubectl-whoami
    4. # and move it into our PATH
    5. sudo mv ./kubectl-whoami /usr/local/bin
    7. kubectl whoami

    To find out more about plugins, take a look at the .

    Start using the kubectl commands.

    Feedback

    Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it onStack Overflow.Open an issue in the GitHub repo if you want toorsuggest an improvement.