k3s/docs/user-guide/kubectl-overview.md

PLEASE NOTE: This document applies to the HEAD of the source tree

If you are using a released version of Kubernetes, you should refer to the docs that go with that version.

The latest 1.0.x release of this document can be found [here](http://releases.k8s.io/release-1.0/docs/user-guide/kubectl-overview.md).

Documentation for other releases can be found at releases.k8s.io.

kubectl overview

Table of Contents

• kubectl overview
  • Overview
  • Common Operations
  • Kubectl Operations
  • Resource Types

This overview is intended for anyone who wants to use kubectl command line tool to interact with Kubernetes cluster. Please remember that it is built for quick started with kubectl; for complete and detailed information, please refer to kubectl.

TODO: auto-generate this file to stay up with kubectl changes. Please see #14177.

Overview

kubectl controls the Kubernetes cluster manager. The synopsis is:

kubectl [command] [TYPE] [NAME] [flags]

This specifies:

• command is a certain operation performed on a given resource(s), such as create, get, describe, delete etc.
• TYPE is the type of resource(s). Both singular and plural forms are accepted. For example, node(s), namespace(s), pod(s), replicationcontroller(s), service(s) etc.
• NAME is the name of resource(s). TYPE NAME can be specified as TYPE name1 name2 or TYPE/name1 TYPE/name2. TYPE NAME can also be specified by one or more file arguments: -f file1 -f file2 ..., use YAML rather than JSON since YAML tends to be more user-friendly for config.
• flags are used to provide more control information when running a command. For example, you can use -s or --server to specify the address and port of the Kubernetes API server. Command line flags override their corresponding default values and environment variables. Use short flags sparingly, only for the most frequently used options.

Please use kubectl help [command] for detailed information about a command.

Please refer to kubectl for a complete list of available commands and flags.

Common Operations

For explanation, here I gave some mostly often used kubectl command examples. Please replace sample names with actual values if you would like to try these commands.

1. kubectl create - Create a resource by filename or stdin

    // Create a service using the data in example-service.yaml.
    $ kubectl create -f example-service.yaml
   
    // Create a replication controller using the data in example-controller.yaml.
    $ kubectl create -f example-controller.yaml
   
    // Create objects whose definitions are in a directory. This looks for config objects in all .yaml, .yml, and .json files in <directory> and passes them to create.
    $ kubectl create -f <directory>
   

2. kubectl get - Display one or many resources

    // List all pods in ps output format.
    $ kubectl get pods
   
    // List all pods in ps output format with more information (such as node name).
    $ kubectl get pods -o wide
   
    // List a single replication controller with specified name in ps output format. You can use the alias 'rc' instead of 'replicationcontroller'.
    $ kubectl get replicationcontroller <rc-name>
   
    // List all replication controllers and services together in ps output format.
    $ kubectl get rc,services
   

3. kubectl describe - Show details of a specific resource or group of resources

    // Describe a node
    $ kubectl describe nodes <node-name>
   
    // Describe a pod
    $ kubectl describe pods/<pod-name>
   
    // Describe all pods managed by the replication controller <rc-name>
    // (rc-created pods get the name of the rc as a prefix in the pod the name).
    $ kubectl describe pods <rc-name>
   

4. kubectl delete - Delete resources by filenames, stdin, resources and names, or by resources and label selector

    // Delete a pod using the type and name specified in pod.yaml.
    $ kubectl delete -f pod.yaml
   
    // Delete pods and services with label name=<label-name>.
    $ kubectl delete pods,services -l name=<label-name>
   
    // Delete all pods
    $ kubectl delete pods --all
   

5. kubectl exec - Execute a command in a container

    // Get output from running 'date' from pod <pod-name>, using the first container by default.
    $ kubectl exec <pod-name> date
   
    // Get output from running 'date' in <container-name> from pod <pod-name>.
    $ kubectl exec <pod-name> -c <container-name> date
   
    // Get an interactive tty and run /bin/bash from pod <pod-name>, using the first container by default.
    $ kubectl exec -ti <pod-name> /bin/bash
   

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

    // Returns snapshot of logs from pod <pod-name>.
    $ kubectl logs <pod-name>
   
    // Starts streaming of logs from pod <pod-name>, it is something like 'tail -f'.
    $ kubectl logs -f <pod-name>
   

Kubectl Operations

The following table describes all kubectl operations and their general synopsis:

Operation	Synopsis	Description
annotate	`kubectl annotate [--overwrite] (-f FILENAME	TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]`
api-versions	kubectl api-versions	Print available API versions
attach	kubectl attach POD -c CONTAINER	Attach to a running container
cluster-info	kubectl cluster-info	Display cluster info
config	kubectl config SUBCOMMAND	Modifies kubeconfig files
create	kubectl create -f FILENAME	Create a resource by filename or stdin
delete	`kubectl delete ([-f FILENAME]	TYPE [(NAME
describe	`kubectl describe (-f FILENAME	TYPE [NAME_PREFIX
edit	`kubectl edit (RESOURCE/NAME	-f FILENAME)`
exec	kubectl exec POD [-c CONTAINER] -- COMMAND [args...]	Execute a command in a container
expose	`kubectl expose (-f FILENAME	TYPE NAME) [--port=port] [--protocol=TCP
get	`kubectl get [(-o	--output=)json
label	`kubectl label [--overwrite] (-f FILENAME	TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]`
logs	kubectl logs [-f] [-p] POD [-c CONTAINER]	Print the logs for a container in a pod
namespace	kubectl namespace [namespace]	SUPERSEDED: Set and view the current Kubernetes namespace
patch	`kubectl patch (-f FILENAME	TYPE NAME) -p PATCH`
port-forward	kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]	Forward one or more local ports to a pod
proxy	kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix]	Run a proxy to the Kubernetes API server
replace	kubectl replace -f FILENAME	Replace a resource by filename or stdin
rolling-update	`kubectl rolling-update OLD_CONTROLLER_NAME ([NEW_CONTROLLER_NAME] --image=NEW_CONTAINER_IMAGE	-f NEW_CONTROLLER_SPEC)`
run	kubectl run NAME --image=image [--env="key=value"] [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json]	Run a particular image on the cluster
scale	`kubectl scale [--resource-version=version] [--current-replicas=count] --replicas=COUNT (-f FILENAME	TYPE NAME)`
stop	`kubectl stop (-f FILENAME	TYPE (NAME
version	kubectl version	Print the client and server version information

Resource Types

The kubectl supports the following resource types, and their abbreviated aliases:

Resource Type	Abbreviated Alias
componentstatuses	cs
events	ev
endpoints	ep
horizontalpodautoscalers	hpa
limitranges	limits
nodes	no
namespaces	ns
pods	po
persistentvolumes	pv
persistentvolumeclaims	pvc
resourcequotas	quota
replicationcontrollers	rc
daemonsets	ds
services	svc
ingress	ing