kubectl Quick Reference

This page contains a list of commonly used kubectl commands and flags.

Note:

These instructions are for Kubernetes v1.31. To check the version, use the kubectl version command.

Kubectl autocomplete

BASH

  1. source <(kubectl completion bash) # set up autocomplete in bash into the current shell, bash-completion package should be installed first.
  2. echo "source <(kubectl completion bash)" >> ~/.bashrc # add autocomplete permanently to your bash shell.

You can also use a shorthand alias for kubectl that also works with completion:

  1. alias k=kubectl
  2. complete -o default -F __start_kubectl k

ZSH

  1. source <(kubectl completion zsh) # set up autocomplete in zsh into the current shell
  2. echo '[[ $commands[kubectl] ]] && source <(kubectl completion zsh)' >> ~/.zshrc # add autocomplete permanently to your zsh shell

FISH

Note:

Requires kubectl version 1.23 or above.

  1. echo 'kubectl completion fish | source' > ~/.config/fish/completions/kubectl.fish && source ~/.config/fish/completions/kubectl.fish

A note on --all-namespaces

Appending --all-namespaces happens frequently enough that you should be aware of the shorthand for --all-namespaces:

kubectl -A

Kubectl context and configuration

Set which Kubernetes cluster kubectl communicates with and modifies configuration information. See Authenticating Across Clusters with kubeconfig documentation for detailed config file information.

  1. kubectl config view # Show Merged kubeconfig settings.
  2. # use multiple kubeconfig files at the same time and view merged config
  3. KUBECONFIG=~/.kube/config:~/.kube/kubconfig2
  4. kubectl config view
  5. # Show merged kubeconfig settings and raw certificate data and exposed secrets
  6. kubectl config view --raw
  7. # get the password for the e2e user
  8. kubectl config view -o jsonpath='{.users[?(@.name == "e2e")].user.password}'
  9. # get the certificate for the e2e user
  10. kubectl config view --raw -o jsonpath='{.users[?(.name == "e2e")].user.client-certificate-data}' | base64 -d
  11. kubectl config view -o jsonpath='{.users[].name}' # display the first user
  12. kubectl config view -o jsonpath='{.users[*].name}' # get a list of users
  13. kubectl config get-contexts # display list of contexts
  14. kubectl config get-contexts -o name # get all context names
  15. kubectl config current-context # display the current-context
  16. kubectl config use-context my-cluster-name # set the default context to my-cluster-name
  17. kubectl config set-cluster my-cluster-name # set a cluster entry in the kubeconfig
  18. # configure the URL to a proxy server to use for requests made by this client in the kubeconfig
  19. kubectl config set-cluster my-cluster-name --proxy-url=my-proxy-url
  20. # add a new user to your kubeconf that supports basic auth
  21. kubectl config set-credentials kubeuser/foo.kubernetes.com --username=kubeuser --password=kubepassword
  22. # permanently save the namespace for all subsequent kubectl commands in that context.
  23. kubectl config set-context --current --namespace=ggckad-s2
  24. # set a context utilizing a specific username and namespace.
  25. kubectl config set-context gce --user=cluster-admin --namespace=foo \
  26. && kubectl config use-context gce
  27. kubectl config unset users.foo # delete user foo
  28. # short alias to set/show context/namespace (only works for bash and bash-compatible shells, current context to be set before using kn to set namespace)
  29. alias kx='f() { [ "$1" ] && kubectl config use-context $1 || kubectl config current-context ; } ; f'
  30. alias kn='f() { [ "$1" ] && kubectl config set-context --current --namespace $1 || kubectl config view --minify | grep namespace | cut -d" " -f6 ; } ; f'

Kubectl apply

apply manages applications through files defining Kubernetes resources. It creates and updates resources in a cluster through running kubectl apply. This is the recommended way of managing Kubernetes applications on production. See Kubectl Book.

Creating objects

Kubernetes manifests can be defined in YAML or JSON. The file extension .yaml, .yml, and .json can be used.

  1. kubectl apply -f ./my-manifest.yaml # create resource(s)
  2. kubectl apply -f ./my1.yaml -f ./my2.yaml # create from multiple files
  3. kubectl apply -f ./dir # create resource(s) in all manifest files in dir
  4. kubectl apply -f https://example.com/manifest.yaml # create resource(s) from url (Note: this is an example domain and does not contain a valid manifest)
  5. kubectl create deployment nginx --image=nginx # start a single instance of nginx
  6. # create a Job which prints "Hello World"
  7. kubectl create job hello --image=busybox:1.28 -- echo "Hello World"
  8. # create a CronJob that prints "Hello World" every minute
  9. kubectl create cronjob hello --image=busybox:1.28 --schedule="*/1 * * * *" -- echo "Hello World"
  10. kubectl explain pods # get the documentation for pod manifests
  11. # Create multiple YAML objects from stdin
  12. kubectl apply -f - <<EOF
  13. apiVersion: v1
  14. kind: Pod
  15. metadata:
  16. name: busybox-sleep
  17. spec:
  18. containers:
  19. - name: busybox
  20. image: busybox:1.28
  21. args:
  22. - sleep
  23. - "1000000"
  24. ---
  25. apiVersion: v1
  26. kind: Pod
  27. metadata:
  28. name: busybox-sleep-less
  29. spec:
  30. containers:
  31. - name: busybox
  32. image: busybox:1.28
  33. args:
  34. - sleep
  35. - "1000"
  36. EOF
  37. # Create a secret with several keys
  38. kubectl apply -f - <<EOF
  39. apiVersion: v1
  40. kind: Secret
  41. metadata:
  42. name: mysecret
  43. type: Opaque
  44. data:
  45. password: $(echo -n "s33msi4" | base64 -w0)
  46. username: $(echo -n "jane" | base64 -w0)
  47. EOF

Viewing and finding resources

  1. # Get commands with basic output
  2. kubectl get services # List all services in the namespace
  3. kubectl get pods --all-namespaces # List all pods in all namespaces
  4. kubectl get pods -o wide # List all pods in the current namespace, with more details
  5. kubectl get deployment my-dep # List a particular deployment
  6. kubectl get pods # List all pods in the namespace
  7. kubectl get pod my-pod -o yaml # Get a pod's YAML
  8. # Describe commands with verbose output
  9. kubectl describe nodes my-node
  10. kubectl describe pods my-pod
  11. # List Services Sorted by Name
  12. kubectl get services --sort-by=.metadata.name
  13. # List pods Sorted by Restart Count
  14. kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'
  15. # List PersistentVolumes sorted by capacity
  16. kubectl get pv --sort-by=.spec.capacity.storage
  17. # Get the version label of all pods with label app=cassandra
  18. kubectl get pods --selector=app=cassandra -o \
  19. jsonpath='{.items[*].metadata.labels.version}'
  20. # Retrieve the value of a key with dots, e.g. 'ca.crt'
  21. kubectl get configmap myconfig \
  22. -o jsonpath='{.data.ca\.crt}'
  23. # Retrieve a base64 encoded value with dashes instead of underscores.
  24. kubectl get secret my-secret --template='{{index .data "key-name-with-dashes"}}'
  25. # Get all worker nodes (use a selector to exclude results that have a label
  26. # named 'node-role.kubernetes.io/control-plane')
  27. kubectl get node --selector='!node-role.kubernetes.io/control-plane'
  28. # Get all running pods in the namespace
  29. kubectl get pods --field-selector=status.phase=Running
  30. # Get ExternalIPs of all nodes
  31. kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'
  32. # List Names of Pods that belong to Particular RC
  33. # "jq" command useful for transformations that are too complex for jsonpath, it can be found at https://jqlang.github.io/jq/
  34. sel=${$(kubectl get rc my-rc --output=json | jq -j '.spec.selector | to_entries | .[] | "\(.key)=\(.value),"')%?}
  35. echo $(kubectl get pods --selector=$sel --output=jsonpath={.items..metadata.name})
  36. # Show labels for all pods (or any other Kubernetes object that supports labelling)
  37. kubectl get pods --show-labels
  38. # Check which nodes are ready
  39. JSONPATH='{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status};{end}{end}' \
  40. && kubectl get nodes -o jsonpath="$JSONPATH" | grep "Ready=True"
  41. # Check which nodes are ready with custom-columns
  42. kubectl get node -o custom-columns='NODE_NAME:.metadata.name,STATUS:.status.conditions[?(@.type=="Ready")].status'
  43. # Output decoded secrets without external tools
  44. kubectl get secret my-secret -o go-template='{{range $k,$v := .data}}{{"### "}}{{$k}}{{"\n"}}{{$v|base64decode}}{{"\n\n"}}{{end}}'
  45. # List all Secrets currently in use by a pod
  46. kubectl get pods -o json | jq '.items[].spec.containers[].env[]?.valueFrom.secretKeyRef.name' | grep -v null | sort | uniq
  47. # List all containerIDs of initContainer of all pods
  48. # Helpful when cleaning up stopped containers, while avoiding removal of initContainers.
  49. kubectl get pods --all-namespaces -o jsonpath='{range .items[*].status.initContainerStatuses[*]}{.containerID}{"\n"}{end}' | cut -d/ -f3
  50. # List Events sorted by timestamp
  51. kubectl get events --sort-by=.metadata.creationTimestamp
  52. # List all warning events
  53. kubectl events --types=Warning
  54. # Compares the current state of the cluster against the state that the cluster would be in if the manifest was applied.
  55. kubectl diff -f ./my-manifest.yaml
  56. # Produce a period-delimited tree of all keys returned for nodes
  57. # Helpful when locating a key within a complex nested JSON structure
  58. kubectl get nodes -o json | jq -c 'paths|join(".")'
  59. # Produce a period-delimited tree of all keys returned for pods, etc
  60. kubectl get pods -o json | jq -c 'paths|join(".")'
  61. # Produce ENV for all pods, assuming you have a default container for the pods, default namespace and the `env` command is supported.
  62. # Helpful when running any supported command across all pods, not just `env`
  63. for pod in $(kubectl get po --output=jsonpath={.items..metadata.name}); do echo $pod && kubectl exec -it $pod -- env; done
  64. # Get a deployment's status subresource
  65. kubectl get deployment nginx-deployment --subresource=status

Updating resources

  1. kubectl set image deployment/frontend www=image:v2 # Rolling update "www" containers of "frontend" deployment, updating the image
  2. kubectl rollout history deployment/frontend # Check the history of deployments including the revision
  3. kubectl rollout undo deployment/frontend # Rollback to the previous deployment
  4. kubectl rollout undo deployment/frontend --to-revision=2 # Rollback to a specific revision
  5. kubectl rollout status -w deployment/frontend # Watch rolling update status of "frontend" deployment until completion
  6. kubectl rollout restart deployment/frontend # Rolling restart of the "frontend" deployment
  7. cat pod.json | kubectl replace -f - # Replace a pod based on the JSON passed into stdin
  8. # Force replace, delete and then re-create the resource. Will cause a service outage.
  9. kubectl replace --force -f ./pod.json
  10. # Create a service for a replicated nginx, which serves on port 80 and connects to the containers on port 8000
  11. kubectl expose rc nginx --port=80 --target-port=8000
  12. # Update a single-container pod's image version (tag) to v4
  13. kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -
  14. kubectl label pods my-pod new-label=awesome # Add a Label
  15. kubectl label pods my-pod new-label- # Remove a label
  16. kubectl label pods my-pod new-label=new-value --overwrite # Overwrite an existing value
  17. kubectl annotate pods my-pod icon-url=http://goo.gl/XXBTWq # Add an annotation
  18. kubectl annotate pods my-pod icon-url- # Remove annotation
  19. kubectl autoscale deployment foo --min=2 --max=10 # Auto scale a deployment "foo"

Patching resources

  1. # Partially update a node
  2. kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'
  3. # Update a container's image; spec.containers[*].name is required because it's a merge key
  4. kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'
  5. # Update a container's image using a json patch with positional arrays
  6. kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'
  7. # Disable a deployment livenessProbe using a json patch with positional arrays
  8. kubectl patch deployment valid-deployment --type json -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'
  9. # Add a new element to a positional array
  10. kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'
  11. # Update a deployment's replica count by patching its scale subresource
  12. kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'

Editing resources

Edit any API resource in your preferred editor.

  1. kubectl edit svc/docker-registry # Edit the service named docker-registry
  2. KUBE_EDITOR="nano" kubectl edit svc/docker-registry # Use an alternative editor

Scaling resources

  1. kubectl scale --replicas=3 rs/foo # Scale a replicaset named 'foo' to 3
  2. kubectl scale --replicas=3 -f foo.yaml # Scale a resource specified in "foo.yaml" to 3
  3. kubectl scale --current-replicas=2 --replicas=3 deployment/mysql # If the deployment named mysql's current size is 2, scale mysql to 3
  4. kubectl scale --replicas=5 rc/foo rc/bar rc/baz # Scale multiple replication controllers

Deleting resources

  1. kubectl delete -f ./pod.json # Delete a pod using the type and name specified in pod.json
  2. kubectl delete pod unwanted --now # Delete a pod with no grace period
  3. kubectl delete pod,service baz foo # Delete pods and services with same names "baz" and "foo"
  4. kubectl delete pods,services -l name=myLabel # Delete pods and services with label name=myLabel
  5. kubectl -n my-ns delete pod,svc --all # Delete all pods and services in namespace my-ns,
  6. # Delete all pods matching the awk pattern1 or pattern2
  7. kubectl get pods -n mynamespace --no-headers=true | awk '/pattern1|pattern2/{print $1}' | xargs kubectl delete -n mynamespace pod

Interacting with running Pods

  1. kubectl logs my-pod # dump pod logs (stdout)
  2. kubectl logs -l name=myLabel # dump pod logs, with label name=myLabel (stdout)
  3. kubectl logs my-pod --previous # dump pod logs (stdout) for a previous instantiation of a container
  4. kubectl logs my-pod -c my-container # dump pod container logs (stdout, multi-container case)
  5. kubectl logs -l name=myLabel -c my-container # dump pod container logs, with label name=myLabel (stdout)
  6. kubectl logs my-pod -c my-container --previous # dump pod container logs (stdout, multi-container case) for a previous instantiation of a container
  7. kubectl logs -f my-pod # stream pod logs (stdout)
  8. kubectl logs -f my-pod -c my-container # stream pod container logs (stdout, multi-container case)
  9. kubectl logs -f -l name=myLabel --all-containers # stream all pods logs with label name=myLabel (stdout)
  10. kubectl run -i --tty busybox --image=busybox:1.28 -- sh # Run pod as interactive shell
  11. kubectl run nginx --image=nginx -n mynamespace # Start a single instance of nginx pod in the namespace of mynamespace
  12. kubectl run nginx --image=nginx --dry-run=client -o yaml > pod.yaml
  13. # Generate spec for running pod nginx and write it into a file called pod.yaml
  14. kubectl attach my-pod -i # Attach to Running Container
  15. kubectl port-forward my-pod 5000:6000 # Listen on port 5000 on the local machine and forward to port 6000 on my-pod
  16. kubectl exec my-pod -- ls / # Run command in existing pod (1 container case)
  17. kubectl exec --stdin --tty my-pod -- /bin/sh # Interactive shell access to a running pod (1 container case)
  18. kubectl exec my-pod -c my-container -- ls / # Run command in existing pod (multi-container case)
  19. kubectl debug my-pod -it --image=busybox:1.28 # Create an interactive debugging session within existing pod and immediately attach to it
  20. kubectl debug node/my-node -it --image=busybox:1.28 # Create an interactive debugging session on a node and immediately attach to it
  21. kubectl top pod # Show metrics for all pods in the default namespace
  22. kubectl top pod POD_NAME --containers # Show metrics for a given pod and its containers
  23. kubectl top pod POD_NAME --sort-by=cpu # Show metrics for a given pod and sort it by 'cpu' or 'memory'

Copying files and directories to and from containers

  1. kubectl cp /tmp/foo_dir my-pod:/tmp/bar_dir # Copy /tmp/foo_dir local directory to /tmp/bar_dir in a remote pod in the current namespace
  2. kubectl cp /tmp/foo my-pod:/tmp/bar -c my-container # Copy /tmp/foo local file to /tmp/bar in a remote pod in a specific container
  3. kubectl cp /tmp/foo my-namespace/my-pod:/tmp/bar # Copy /tmp/foo local file to /tmp/bar in a remote pod in namespace my-namespace
  4. kubectl cp my-namespace/my-pod:/tmp/foo /tmp/bar # Copy /tmp/foo from a remote pod to /tmp/bar locally

Note:

kubectl cp requires that the ‘tar’ binary is present in your container image. If ‘tar’ is not present, kubectl cp will fail. For advanced use cases, such as symlinks, wildcard expansion or file mode preservation consider using kubectl exec.

  1. tar cf - /tmp/foo | kubectl exec -i -n my-namespace my-pod -- tar xf - -C /tmp/bar # Copy /tmp/foo local file to /tmp/bar in a remote pod in namespace my-namespace
  2. kubectl exec -n my-namespace my-pod -- tar cf - /tmp/foo | tar xf - -C /tmp/bar # Copy /tmp/foo from a remote pod to /tmp/bar locally

Interacting with Deployments and Services

  1. kubectl logs deploy/my-deployment # dump Pod logs for a Deployment (single-container case)
  2. kubectl logs deploy/my-deployment -c my-container # dump Pod logs for a Deployment (multi-container case)
  3. kubectl port-forward svc/my-service 5000 # listen on local port 5000 and forward to port 5000 on Service backend
  4. kubectl port-forward svc/my-service 5000:my-service-port # listen on local port 5000 and forward to Service target port with name <my-service-port>
  5. kubectl port-forward deploy/my-deployment 5000:6000 # listen on local port 5000 and forward to port 6000 on a Pod created by <my-deployment>
  6. kubectl exec deploy/my-deployment -- ls # run command in first Pod and first container in Deployment (single- or multi-container cases)

Interacting with Nodes and cluster

  1. kubectl cordon my-node # Mark my-node as unschedulable
  2. kubectl drain my-node # Drain my-node in preparation for maintenance
  3. kubectl uncordon my-node # Mark my-node as schedulable
  4. kubectl top node # Show metrics for all nodes
  5. kubectl top node my-node # Show metrics for a given node
  6. kubectl cluster-info # Display addresses of the master and services
  7. kubectl cluster-info dump # Dump current cluster state to stdout
  8. kubectl cluster-info dump --output-directory=/path/to/cluster-state # Dump current cluster state to /path/to/cluster-state
  9. # View existing taints on which exist on current nodes.
  10. kubectl get nodes -o='custom-columns=NodeName:.metadata.name,TaintKey:.spec.taints[*].key,TaintValue:.spec.taints[*].value,TaintEffect:.spec.taints[*].effect'
  11. # If a taint with that key and effect already exists, its value is replaced as specified.
  12. kubectl taint nodes foo dedicated=special-user:NoSchedule

Resource types

List all supported resource types along with their shortnames, API group, whether they are namespaced, and kind:

  1. kubectl api-resources

Other operations for exploring API resources:

  1. kubectl api-resources --namespaced=true # All namespaced resources
  2. kubectl api-resources --namespaced=false # All non-namespaced resources
  3. kubectl api-resources -o name # All resources with simple output (only the resource name)
  4. kubectl api-resources -o wide # All resources with expanded (aka "wide") output
  5. kubectl api-resources --verbs=list,get # All resources that support the "list" and "get" request verbs
  6. kubectl api-resources --api-group=extensions # All resources in the "extensions" API group

Formatting output

To output details to your terminal window in a specific format, add the -o (or --output) flag to a supported kubectl command.

Output formatDescription
-o=custom-columns=<spec>Print a table using a comma separated list of custom columns
-o=custom-columns-file=<filename>Print a table using the custom columns template in the <filename> file
-o=go-template=<template>Print the fields defined in a golang template
-o=go-template-file=<filename>Print the fields defined by the golang template in the <filename> file
-o=jsonOutput a JSON formatted API object
-o=jsonpath=<template>Print the fields defined in a jsonpath expression
-o=jsonpath-file=<filename>Print the fields defined by the jsonpath expression in the <filename> file
-o=namePrint only the resource name and nothing else
-o=wideOutput in the plain-text format with any additional information, and for pods, the node name is included
-o=yamlOutput a YAML formatted API object

Examples using -o=custom-columns:

  1. # All images running in a cluster
  2. kubectl get pods -A -o=custom-columns='DATA:spec.containers[*].image'
  3. # All images running in namespace: default, grouped by Pod
  4. kubectl get pods --namespace default --output=custom-columns="NAME:.metadata.name,IMAGE:.spec.containers[*].image"
  5. # All images excluding "registry.k8s.io/coredns:1.6.2"
  6. kubectl get pods -A -o=custom-columns='DATA:spec.containers[?(@.image!="registry.k8s.io/coredns:1.6.2")].image'
  7. # All fields under metadata regardless of name
  8. kubectl get pods -A -o=custom-columns='DATA:metadata.*'

More examples in the kubectl reference documentation.

Kubectl output verbosity and debugging

Kubectl verbosity is controlled with the -v or --v flags followed by an integer representing the log level. General Kubernetes logging conventions and the associated log levels are described here.

VerbosityDescription
—v=0Generally useful for this to always be visible to a cluster operator.
—v=1A reasonable default log level if you don’t want verbosity.
—v=2Useful steady state information about the service and important log messages that may correlate to significant changes in the system. This is the recommended default log level for most systems.
—v=3Extended information about changes.
—v=4Debug level verbosity.
—v=5Trace level verbosity.
—v=6Display requested resources.
—v=7Display HTTP request headers.
—v=8Display HTTP request contents.
—v=9Display HTTP request contents without truncation of contents.

What’s next