GETTING STARTED

This section contains the most basic commands for getting a workload running on your cluster.

• run will start running 1 or more instances of a container image on your cluster.
• expose will load balance traffic across the running instances, and can create a HA proxy for accessing the containers from outside the cluster.

Once your workloads are running, you can use the commands in the WORKING WITH APPS section to inspect them.

create

Create a pod using the data in pod.json

kubectl create -f ./pod.json

Create a pod based on the JSON passed into stdin

cat pod.json | kubectl create -f -

Edit the data in registry.yaml in JSON then create the resource using the edited data

kubectl create -f registry.yaml --edit -o json

Create a resource from a file or from stdin.

JSON and YAML formats are accepted.

Usage

$ kubectl create -f FILENAME

Flags

clusterrole

Create a cluster role named “pod-reader” that allows user to perform “get”, “watch” and “list” on pods

kubectl create clusterrole pod-reader --verb=get,list,watch --resource=pods

Create a cluster role named “pod-reader” with ResourceName specified

kubectl create clusterrole pod-reader --verb=get --resource=pods --resource-name=readablepod --resource-name=anotherpod

Create a cluster role named “foo” with API Group specified

kubectl create clusterrole foo --verb=get,list,watch --resource=rs.apps

Create a cluster role named “foo” with SubResource specified

kubectl create clusterrole foo --verb=get,list,watch --resource=pods,pods/status

Create a cluster role name “foo” with NonResourceURL specified

kubectl create clusterrole "foo" --verb=get --non-resource-url=/logs/*

Create a cluster role name “monitoring” with AggregationRule specified

kubectl create clusterrole monitoring --aggregation-rule="rbac.example.com/aggregate-to-monitoring=true"

Create a cluster role.

Usage

$ kubectl create clusterrole NAME --verb=verb --resource=resource.group [--resource-name=resourcename] [--dry-run=server|client|none]

Flags

clusterrolebinding

Create a cluster role binding for user1, user2, and group1 using the cluster-admin cluster role

kubectl create clusterrolebinding cluster-admin --clusterrole=cluster-admin --user=user1 --user=user2 --group=group1

Create a cluster role binding for a particular cluster role.

Usage

$ kubectl create clusterrolebinding NAME --clusterrole=NAME [--user=username] [--group=groupname] [--serviceaccount=namespace:serviceaccountname] [--dry-run=server|client|none]

Flags

configmap

Create a new config map named my-config based on folder bar

kubectl create configmap my-config --from-file=path/to/bar

Create a new config map named my-config with specified keys instead of file basenames on disk

kubectl create configmap my-config --from-file=key1=/path/to/bar/file1.txt --from-file=key2=/path/to/bar/file2.txt

Create a new config map named my-config with key1=config1 and key2=config2

kubectl create configmap my-config --from-literal=key1=config1 --from-literal=key2=config2

Create a new config map named my-config from the key=value pairs in the file

kubectl create configmap my-config --from-file=path/to/bar

Create a new config map named my-config from an env file

kubectl create configmap my-config --from-env-file=path/to/foo.env --from-env-file=path/to/bar.env

Create a config map based on a file, directory, or specified literal value.

A single config map may package one or more key/value pairs.

When creating a config map based on a file, the key will default to the basename of the file, and the value will default to the file content. If the basename is an invalid key, you may specify an alternate key.

When creating a config map based on a directory, each file whose basename is a valid key in the directory will be packaged into the config map. Any directory entries except regular files are ignored (e.g. subdirectories, symlinks, devices, pipes, etc).

Usage

$ kubectl create configmap NAME [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run=server|client|none]

Flags

cronjob

Create a cron job

kubectl create cronjob my-job --image=busybox --schedule="*/1 * * * *"

Create a cron job with a command

kubectl create cronjob my-job --image=busybox --schedule="*/1 * * * *" -- date

Create a cron job with the specified name.

Usage

$ kubectl create cronjob NAME --image=image --schedule='0/5 * * * ?' -- [COMMAND] [args...]

Flags

deployment

Create a deployment named my-dep that runs the busybox image

kubectl create deployment my-dep --image=busybox

Create a deployment with a command

kubectl create deployment my-dep --image=busybox -- date

Create a deployment named my-dep that runs the nginx image with 3 replicas

kubectl create deployment my-dep --image=nginx --replicas=3

Create a deployment named my-dep that runs the busybox image and expose port 5701

kubectl create deployment my-dep --image=busybox --port=5701

Create a deployment with the specified name.

Usage

$ kubectl create deployment NAME --image=image -- [COMMAND] [args...]

Flags

ingress

Create a single ingress called ‘simple’ that directs requests to foo.com/bar to svc # svc1:8080 with a tls secret “my-cert”

kubectl create ingress simple --rule="foo.com/bar=svc1:8080,tls=my-cert"

Create a catch all ingress of “/path” pointing to service svc:port and Ingress Class as “otheringress”

kubectl create ingress catch-all --class=otheringress --rule="/path=svc:port"

Create an ingress with two annotations: ingress.annotation1 and ingress.annotations2

kubectl create ingress annotated --class=default --rule="foo.com/bar=svc:port" \
--annotation ingress.annotation1=foo \
--annotation ingress.annotation2=bla

Create an ingress with the same host and multiple paths

kubectl create ingress multipath --class=default \
--rule="foo.com/=svc:port" \
--rule="foo.com/admin/=svcadmin:portadmin"

Create an ingress with multiple hosts and the pathType as Prefix

kubectl create ingress ingress1 --class=default \
--rule="foo.com/path*=svc:8080" \
--rule="bar.com/admin*=svc2:http"

Create an ingress with TLS enabled using the default ingress certificate and different path types

kubectl create ingress ingtls --class=default \
--rule="foo.com/=svc:https,tls" \
--rule="foo.com/path/subpath*=othersvc:8080"

Create an ingress with TLS enabled using a specific secret and pathType as Prefix

kubectl create ingress ingsecret --class=default \
--rule="foo.com/*=svc:8080,tls=secret1"

Create an ingress with a default backend

kubectl create ingress ingdefault --class=default \
--default-backend=defaultsvc:http \
--rule="foo.com/*=svc:8080,tls=secret1"

Create an ingress with the specified name.

Usage

$ kubectl create ingress NAME --rule=host/path=service:port[,tls[=secret]]

Flags

job

Create a job

kubectl create job my-job --image=busybox

Create a job with a command

kubectl create job my-job --image=busybox -- date

Create a job from a cron job named “a-cronjob”

kubectl create job test-job --from=cronjob/a-cronjob

Create a job with the specified name.

Usage

$ kubectl create job NAME --image=image [--from=cronjob/name] -- [COMMAND] [args...]

Flags

namespace

Create a new namespace named my-namespace

kubectl create namespace my-namespace

Create a namespace with the specified name.

Usage

$ kubectl create namespace NAME [--dry-run=server|client|none]

Flags

poddisruptionbudget

Create a pod disruption budget named my-pdb that will select all pods with the app=rails label # and require at least one of them being available at any point in time

kubectl create poddisruptionbudget my-pdb --selector=app=rails --min-available=1

Create a pod disruption budget named my-pdb that will select all pods with the app=nginx label # and require at least half of the pods selected to be available at any point in time

kubectl create pdb my-pdb --selector=app=nginx --min-available=50%

Create a pod disruption budget with the specified name, selector, and desired minimum available pods.

Usage

$ kubectl create poddisruptionbudget NAME --selector=SELECTOR --min-available=N [--dry-run=server|client|none]

Flags

priorityclass

Create a priority class named high-priority

kubectl create priorityclass high-priority --value=1000 --description="high priority"

Create a priority class named default-priority that is considered as the global default priority

kubectl create priorityclass default-priority --value=1000 --global-default=true --description="default priority"

Create a priority class named high-priority that cannot preempt pods with lower priority

kubectl create priorityclass high-priority --value=1000 --description="high priority" --preemption-policy="Never"

Create a priority class with the specified name, value, globalDefault and description.

Usage

$ kubectl create priorityclass NAME --value=VALUE --global-default=BOOL [--dry-run=server|client|none]

Flags

quota

Create a new resource quota named my-quota

kubectl create quota my-quota --hard=cpu=1,memory=1G,pods=2,services=3,replicationcontrollers=2,resourcequotas=1,secrets=5,persistentvolumeclaims=10

Create a new resource quota named best-effort

kubectl create quota best-effort --hard=pods=100 --scopes=BestEffort

Create a resource quota with the specified name, hard limits, and optional scopes.

Usage

$ kubectl create quota NAME [--hard=key1=value1,key2=value2] [--scopes=Scope1,Scope2] [--dry-run=server|client|none]

Flags

role

Create a role named “pod-reader” that allows user to perform “get”, “watch” and “list” on pods

kubectl create role pod-reader --verb=get --verb=list --verb=watch --resource=pods

Create a role named “pod-reader” with ResourceName specified

kubectl create role pod-reader --verb=get --resource=pods --resource-name=readablepod --resource-name=anotherpod

Create a role named “foo” with API Group specified

kubectl create role foo --verb=get,list,watch --resource=rs.apps

Create a role named “foo” with SubResource specified

kubectl create role foo --verb=get,list,watch --resource=pods,pods/status

Create a role with single rule.

Usage

$ kubectl create role NAME --verb=verb --resource=resource.group/subresource [--resource-name=resourcename] [--dry-run=server|client|none]

Flags

rolebinding

Create a role binding for user1, user2, and group1 using the admin cluster role

kubectl create rolebinding admin --clusterrole=admin --user=user1 --user=user2 --group=group1

Create a role binding for a particular role or cluster role.

Usage

$ kubectl create rolebinding NAME --clusterrole=NAME|--role=NAME [--user=username] [--group=groupname] [--serviceaccount=namespace:serviceaccountname] [--dry-run=server|client|none]

Flags

secret

Create a secret using specified subcommand.

Usage

$ kubectl create secret

secret docker-registry

If you don’t already have a .dockercfg file, you can create a dockercfg secret directly by using:

kubectl create secret docker-registry my-secret --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL

Create a new secret named my-secret from ~/.docker/config.json

kubectl create secret docker-registry my-secret --from-file=.dockerconfigjson=path/to/.docker/config.json

Create a new secret for use with Docker registries.

Dockercfg secrets are used to authenticate against Docker registries.

When using the Docker command line to push images, you can authenticate to a given registry by running: ‘$ docker login DOCKER_REGISTRY_SERVER —username=DOCKER_USER —password=DOCKER_PASSWORD —email=DOCKER_EMAIL’.

That produces a ~/.dockercfg file that is used by subsequent ‘docker push’ and ‘docker pull’ commands to authenticate to the registry. The email address is optional.

When creating applications, you may have a Docker registry that requires authentication. In order for the nodes to pull images on your behalf, they must have the credentials. You can provide this information by creating a dockercfg secret and attaching it to your service account.

Usage

$ kubectl create docker-registry NAME --docker-username=user --docker-password=password --docker-email=email [--docker-server=string] [--from-file=[key=]source] [--dry-run=server|client|none]

Flags

secret generic

Create a new secret named my-secret with keys for each file in folder bar

kubectl create secret generic my-secret --from-file=path/to/bar

Create a new secret named my-secret with specified keys instead of names on disk

kubectl create secret generic my-secret --from-file=ssh-privatekey=path/to/id_rsa --from-file=ssh-publickey=path/to/id_rsa.pub

Create a new secret named my-secret with key1=supersecret and key2=topsecret

kubectl create secret generic my-secret --from-literal=key1=supersecret --from-literal=key2=topsecret

Create a new secret named my-secret using a combination of a file and a literal

kubectl create secret generic my-secret --from-file=ssh-privatekey=path/to/id_rsa --from-literal=passphrase=topsecret

Create a new secret named my-secret from env files

kubectl create secret generic my-secret --from-env-file=path/to/foo.env --from-env-file=path/to/bar.env

Create a secret based on a file, directory, or specified literal value.

A single secret may package one or more key/value pairs.

When creating a secret based on a file, the key will default to the basename of the file, and the value will default to the file content. If the basename is an invalid key or you wish to chose your own, you may specify an alternate key.

When creating a secret based on a directory, each file whose basename is a valid key in the directory will be packaged into the secret. Any directory entries except regular files are ignored (e.g. subdirectories, symlinks, devices, pipes, etc).

Usage

$ kubectl create generic NAME [--type=string] [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run=server|client|none]

Flags

secret tls

Create a new TLS secret named tls-secret with the given key pair

kubectl create secret tls tls-secret --cert=path/to/tls.cert --key=path/to/tls.key

Create a TLS secret from the given public/private key pair.

The public/private key pair must exist beforehand. The public key certificate must be .PEM encoded and match the given private key.

Usage

$ kubectl create tls NAME --cert=path/to/cert/file --key=path/to/key/file [--dry-run=server|client|none]

Flags

service

Create a service using a specified subcommand.

Usage

$ kubectl create service

service clusterip

Create a new ClusterIP service named my-cs

kubectl create service clusterip my-cs --tcp=5678:8080

Create a new ClusterIP service named my-cs (in headless mode)

kubectl create service clusterip my-cs --clusterip="None"

Create a ClusterIP service with the specified name.

Usage

$ kubectl create clusterip NAME [--tcp=<port>:<targetPort>] [--dry-run=server|client|none]

Flags

service externalname

Create a new ExternalName service named my-ns

kubectl create service externalname my-ns --external-name bar.com

Create an ExternalName service with the specified name.

ExternalName service references to an external DNS address instead of only pods, which will allow application authors to reference services that exist off platform, on other clusters, or locally.

Usage

$ kubectl create externalname NAME --external-name external.name [--dry-run=server|client|none]

Flags

service loadbalancer

Create a new LoadBalancer service named my-lbs

kubectl create service loadbalancer my-lbs --tcp=5678:8080

Create a LoadBalancer service with the specified name.

Usage

$ kubectl create loadbalancer NAME [--tcp=port:targetPort] [--dry-run=server|client|none]

Flags

service nodeport

Create a new NodePort service named my-ns

kubectl create service nodeport my-ns --tcp=5678:8080

Create a NodePort service with the specified name.

Usage

$ kubectl create nodeport NAME [--tcp=port:targetPort] [--dry-run=server|client|none]

Flags

serviceaccount

Create a new service account named my-service-account

kubectl create serviceaccount my-service-account

Create a service account with the specified name.

Usage

$ kubectl create serviceaccount NAME [--dry-run=server|client|none]

Flags

token

Request a token to authenticate to the kube-apiserver as the service account “myapp” in the current namespace

kubectl create token myapp

Request a token for a service account in a custom namespace

kubectl create token myapp --namespace myns

Request a token with a custom expiration

kubectl create token myapp --duration 10m

Request a token with a custom audience

kubectl create token myapp --audience https://example.com

Request a token bound to an instance of a Secret object

kubectl create token myapp --bound-object-kind Secret --bound-object-name mysecret

Request a token bound to an instance of a Secret object with a specific uid

kubectl create token myapp --bound-object-kind Secret --bound-object-name mysecret --bound-object-uid 0d4691ed-659b-4935-a832-355f77ee47cc

Request a service account token.

Usage

$ kubectl create token SERVICE_ACCOUNT_NAME

Flags

get

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

kubectl get replicationcontroller web

List deployments in JSON output format, in the “v1” version of the “apps” API group

kubectl get deployments.v1.apps -o json

List a single pod in JSON output format

kubectl get -o json pod web-pod-13je7

List a pod identified by type and name specified in “pod.yaml” in JSON output format

kubectl get -f pod.yaml -o json

List resources from a directory with kustomization.yaml - e.g. dir/kustomization.yaml

kubectl get -k dir/

Return only the phase value of the specified pod

kubectl get -o template pod/web-pod-13je7 --template={{.status.phase}}

List resource information in custom columns

kubectl get pod test-pod -o custom-columns=CONTAINER:.spec.containers[0].name,IMAGE:.spec.containers[0].image

List all replication controllers and services together in ps output format

kubectl get rc,services

List one or more resources by their type and names

kubectl get rc/web service/frontend pods/web-pod-13je7

List status subresource for a single pod.

kubectl get pod web-pod-13je7 --subresource status

Display one or many resources.

Prints a table of the most important information about the specified resources. You can filter the list using a label selector and the —selector flag. If the desired resource type is namespaced you will only see results in your current namespace unless you pass —all-namespaces.

By specifying the output as ‘template’ and providing a Go template as the value of the —template flag, you can filter the attributes of the fetched resources.

Use “kubectl api-resources” for a complete list of supported resources.

Usage

$ kubectl get [(-o|--output=)json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-as-json|jsonpath-file|custom-columns|custom-columns-file|wide] (TYPE[.VERSION][.GROUP] [NAME | -l label] | TYPE[.VERSION][.GROUP]/NAME ...) [flags]

Flags

run

Start a nginx pod

kubectl run nginx --image=nginx

Start a hazelcast pod and let the container expose port 5701

kubectl run hazelcast --image=hazelcast/hazelcast --port=5701

Start a hazelcast pod and set environment variables “DNS_DOMAIN=cluster” and “POD_NAMESPACE=default” in the container

kubectl run hazelcast --image=hazelcast/hazelcast --env="DNS_DOMAIN=cluster" --env="POD_NAMESPACE=default"

Start a hazelcast pod and set labels “app=hazelcast” and “env=prod” in the container

kubectl run hazelcast --image=hazelcast/hazelcast --labels="app=hazelcast,env=prod"

Dry run; print the corresponding API objects without creating them

kubectl run nginx --image=nginx --dry-run=client

Start a nginx pod, but overload the spec with a partial set of values parsed from JSON

kubectl run nginx --image=nginx --overrides='{ "apiVersion": "v1", "spec": { ... } }'

Start a busybox pod and keep it in the foreground, don’t restart it if it exits

kubectl run -i -t busybox --image=busybox --restart=Never

Start the nginx pod using the default command, but use custom arguments (arg1 .. argN) for that command

kubectl run nginx --image=nginx -- <arg1> <arg2> ... <argN>

Start the nginx pod using a different command and custom arguments

kubectl run nginx --image=nginx --command -- <cmd> <arg1> ... <argN>

Create and run a particular image in a pod.

Usage

$ kubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client] [--overrides=inline-json] [--command] -- [COMMAND] [args...]

Flags

expose

Create a service for a replicated nginx, which serves on port 80 and connects to the containers on port 8000

kubectl expose rc nginx --port=80 --target-port=8000

Create a service for a replication controller identified by type and name specified in “nginx-controller.yaml”, which serves on port 80 and connects to the containers on port 8000

kubectl expose -f nginx-controller.yaml --port=80 --target-port=8000

Create a service for a pod valid-pod, which serves on port 444 with the name “frontend”

kubectl expose pod valid-pod --port=444 --name=frontend

Create a second service based on the above service, exposing the container port 8443 as port 443 with the name “nginx-https”

kubectl expose service nginx --port=443 --target-port=8443 --name=nginx-https

Create a service for a replicated streaming application on port 4100 balancing UDP traffic and named ‘video-stream’.

kubectl expose rc streamer --port=4100 --protocol=UDP --name=video-stream

Create a service for a replicated nginx using replica set, which serves on port 80 and connects to the containers on port 8000

kubectl expose rs nginx --port=80 --target-port=8000

Create a service for an nginx deployment, which serves on port 80 and connects to the containers on port 8000

kubectl expose deployment nginx --port=80 --target-port=8000

Expose a resource as a new Kubernetes service.

Looks up a deployment, service, replica set, replication controller or pod by name and uses the selector for that resource as the selector for a new service on the specified port. A deployment or replica set will be exposed as a service only if its selector is convertible to a selector that service supports, i.e. when the selector contains only the matchLabels component. Note that if no port is specified via —port and the exposed resource has multiple ports, all will be re-used by the new service. Also if no labels are specified, the new service will re-use the labels from the resource it exposes.

Possible resources include (case insensitive):

pod (po), service (svc), replicationcontroller (rc), deployment (deploy), replicaset (rs)

Usage

$ kubectl expose (-f FILENAME | TYPE NAME) [--port=port] [--protocol=TCP|UDP|SCTP] [--target-port=number-or-name] [--name=name] [--external-ip=external-ip-of-service] [--type=type]

Flags

delete

Delete a pod using the type and name specified in pod.json

kubectl delete -f ./pod.json

Delete resources from a directory containing kustomization.yaml - e.g. dir/kustomization.yaml

kubectl delete -k dir

Delete resources from all files that end with ‘.json’ - i.e. expand wildcard characters in file names

kubectl delete -f '*.json'

Delete a pod based on the type and name in the JSON passed into stdin

cat pod.json | kubectl delete -f -

Delete pods and services with same names “baz” and “foo”

kubectl delete pod,service baz foo

Delete pods and services with label name=myLabel

kubectl delete pods,services -l name=myLabel

Delete a pod with minimal delay

kubectl delete pod foo --now

Force delete a pod on a dead node

kubectl delete pod foo --force

Delete all pods

kubectl delete pods --all

Delete resources by file names, stdin, resources and names, or by resources and label selector.

JSON and YAML formats are accepted. Only one type of argument may be specified: file names, resources and names, or resources and label selector.

Some resources, such as pods, support graceful deletion. These resources define a default period before they are forcibly terminated (the grace period) but you may override that value with the —grace-period flag, or pass —now to set a grace-period of 1. Because these resources often represent entities in the cluster, deletion may not be acknowledged immediately. If the node hosting a pod is down or cannot reach the API server, termination may take significantly longer than the grace period. To force delete a resource, you must specify the —force flag. Note: only a subset of resources support graceful deletion. In absence of the support, the —grace-period flag is ignored.

IMPORTANT: Force deleting pods does not wait for confirmation that the pod’s processes have been terminated, which can leave those processes running until the node detects the deletion and completes graceful deletion. If your processes use shared storage or talk to a remote API and depend on the name of the pod to identify themselves, force deleting those pods may result in multiple processes running on different machines using the same identification which may lead to data corruption or inconsistency. Only force delete pods when you are sure the pod is terminated, or if your application can tolerate multiple copies of the same pod running at once. Also, if you force delete pods, the scheduler may place new pods on those nodes before the node has released those resources and causing those pods to be evicted immediately.

Note that the delete command does NOT do resource version checks, so if someone submits an update to a resource right when you submit a delete, their update will be lost along with the rest of the resource.

After a CustomResourceDefinition is deleted, invalidation of discovery cache may take up to 6 hours. If you don’t want to wait, you might want to run “kubectl api-resources” to refresh the discovery cache.

Usage

$ kubectl delete ([-f FILENAME] | [-k DIRECTORY] | TYPE [(NAME | -l label | --all)])

Flags

APP MANAGEMENT

This section contains commands for creating, updating, deleting, and viewing your workloads in a Kubernetes cluster.

apply

Apply the configuration in pod.json to a pod

kubectl apply -f ./pod.json

Apply resources from a directory containing kustomization.yaml - e.g. dir/kustomization.yaml

kubectl apply -k dir/

Apply the JSON passed into stdin to a pod

cat pod.json | kubectl apply -f -

Apply the configuration from all files that end with ‘.json’ - i.e. expand wildcard characters in file names

kubectl apply -f '*.json'

Note: —prune is still in Alpha # Apply the configuration in manifest.yaml that matches label app=nginx and delete all other resources that are not in the file and match label app=nginx

kubectl apply --prune -f manifest.yaml -l app=nginx

Apply the configuration in manifest.yaml and delete all the other config maps that are not in the file

kubectl apply --prune -f manifest.yaml --all --prune-whitelist=core/v1/ConfigMap

Apply a configuration to a resource by file name or stdin. The resource name must be specified. This resource will be created if it doesn’t exist yet. To use ‘apply’, always create the resource initially with either ‘apply’ or ‘create —save-config’.

JSON and YAML formats are accepted.

Alpha Disclaimer: the —prune functionality is not yet complete. Do not use unless you are aware of what the current state is. See https://issues.k8s.io/34274.

Usage

$ kubectl apply (-f FILENAME | -k DIRECTORY)

Flags

edit-last-applied

Edit the last-applied-configuration annotations by type/name in YAML

kubectl apply edit-last-applied deployment/nginx

Edit the last-applied-configuration annotations by file in JSON

kubectl apply edit-last-applied -f deploy.yaml -o json

Edit the latest last-applied-configuration annotations of resources from the default editor.

The edit-last-applied command allows you to directly edit any API resource you can retrieve via the command-line tools. It will open the editor defined by your KUBE_EDITOR, or EDITOR environment variables, or fall back to ‘vi’ for Linux or ‘notepad’ for Windows. You can edit multiple objects, although changes are applied one at a time. The command accepts file names as well as command-line arguments, although the files you point to must be previously saved versions of resources.

The default format is YAML. To edit in JSON, specify “-o json”.

The flag —windows-line-endings can be used to force Windows line endings, otherwise the default for your operating system will be used.

In the event an error occurs while updating, a temporary file will be created on disk that contains your unapplied changes. The most common error when updating a resource is another editor changing the resource on the server. When this occurs, you will have to apply your changes to the newer version of the resource, or update your temporary saved copy to include the latest resource version.

Usage

$ kubectl apply edit-last-applied (RESOURCE/NAME | -f FILENAME)

Flags

set-last-applied

Set the last-applied-configuration of a resource to match the contents of a file

kubectl apply set-last-applied -f deploy.yaml

Execute set-last-applied against each configuration file in a directory

kubectl apply set-last-applied -f path/

Set the last-applied-configuration of a resource to match the contents of a file; will create the annotation if it does not already exist

kubectl apply set-last-applied -f deploy.yaml --create-annotation=true

Set the latest last-applied-configuration annotations by setting it to match the contents of a file. This results in the last-applied-configuration being updated as though ‘kubectl apply -f ‘ was run, without updating any other parts of the object.

Usage

$ kubectl apply set-last-applied -f FILENAME

Flags

view-last-applied

View the last-applied-configuration annotations by type/name in YAML

kubectl apply view-last-applied deployment/nginx

View the last-applied-configuration annotations by file in JSON

kubectl apply view-last-applied -f deploy.yaml -o json

View the latest last-applied-configuration annotations by type/name or file.

The default output will be printed to stdout in YAML format. You can use the -o option to change the output format.

Usage

$ kubectl apply view-last-applied (TYPE [NAME | -l label] | TYPE/NAME | -f FILENAME)

Flags

annotate

Update pod ‘foo’ with the annotation ‘description’ and the value ‘my frontend’ # If the same annotation is set multiple times, only the last value will be applied

kubectl annotate pods foo description='my frontend'

Update a pod identified by type and name in “pod.json”

kubectl annotate -f pod.json description='my frontend'

Update pod ‘foo’ with the annotation ‘description’ and the value ‘my frontend running nginx’, overwriting any existing value

kubectl annotate --overwrite pods foo description='my frontend running nginx'

Update all pods in the namespace

kubectl annotate pods --all description='my frontend running nginx'

Update pod ‘foo’ only if the resource is unchanged from version 1

kubectl annotate pods foo description='my frontend running nginx' --resource-version=1

Update pod ‘foo’ by removing an annotation named ‘description’ if it exists # Does not require the —overwrite flag

kubectl annotate pods foo description-

Update the annotations on one or more resources.

All Kubernetes objects support the ability to store additional data with the object as annotations. Annotations are key/value pairs that can be larger than labels and include arbitrary string values such as structured JSON. Tools and system extensions may use annotations to store their own data.

Attempting to set an annotation that already exists will fail unless —overwrite is set. If —resource-version is specified and does not match the current resource version on the server the command will fail.

Use “kubectl api-resources” for a complete list of supported resources.

Usage

$ kubectl annotate [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]

Flags

autoscale

Auto scale a deployment “foo”, with the number of pods between 2 and 10, no target CPU utilization specified so a default autoscaling policy will be used

kubectl autoscale deployment foo --min=2 --max=10

Auto scale a replication controller “foo”, with the number of pods between 1 and 5, target CPU utilization at 80%

kubectl autoscale rc foo --max=5 --cpu-percent=80

Creates an autoscaler that automatically chooses and sets the number of pods that run in a Kubernetes cluster.

Looks up a deployment, replica set, stateful set, or replication controller by name and creates an autoscaler that uses the given resource as a reference. An autoscaler can automatically increase or decrease number of pods deployed within the system as needed.

Usage

$ kubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU]

Flags

debug

Create an interactive debugging session in pod mypod and immediately attach to it. # (requires the EphemeralContainers feature to be enabled in the cluster)

kubectl debug mypod -it --image=busybox

Create a debug container named debugger using a custom automated debugging image. # (requires the EphemeralContainers feature to be enabled in the cluster)

kubectl debug --image=myproj/debug-tools -c debugger mypod

Create a copy of mypod adding a debug container and attach to it

kubectl debug mypod -it --image=busybox --copy-to=my-debugger

Create a copy of mypod changing the command of mycontainer

kubectl debug mypod -it --copy-to=my-debugger --container=mycontainer -- sh

Create a copy of mypod changing all container images to busybox

kubectl debug mypod --copy-to=my-debugger --set-image=*=busybox

Create a copy of mypod adding a debug container and changing container images

kubectl debug mypod -it --copy-to=my-debugger --image=debian --set-image=app=app:debug,sidecar=sidecar:debug

Create an interactive debugging session on a node and immediately attach to it. # The container will run in the host namespaces and the host’s filesystem will be mounted at /host

kubectl debug node/mynode -it --image=busybox

Debug cluster resources using interactive debugging containers.

‘debug’ provides automation for common debugging tasks for cluster objects identified by resource and name. Pods will be used by default if no resource is specified.

The action taken by ‘debug’ varies depending on what resource is specified. Supported actions include:

Workload: Create a copy of an existing pod with certain attributes changed, for example changing the image tag to a new version. Workload: Add an ephemeral container to an already running pod, for example to add debugging utilities without restarting the pod.
* Node: Create a new pod that runs in the node’s host namespaces and can access the node’s filesystem.

Usage

$ kubectl debug (POD | TYPE[[.VERSION].GROUP]/NAME) [ -- COMMAND [args...] ]

Flags

diff

Diff resources included in pod.json

kubectl diff -f pod.json

Diff file read from stdin

cat service.yaml | kubectl diff -f -

Diff configurations specified by file name or stdin between the current online configuration, and the configuration as it would be if applied.

The output is always YAML.

KUBECTL_EXTERNAL_DIFF environment variable can be used to select your own diff command. Users can use external commands with params too, example: KUBECTL_EXTERNAL_DIFF=”colordiff -N -u”

By default, the “diff” command available in your path will be run with the “-u” (unified diff) and “-N” (treat absent files as empty) options.

Exit status: 0 No differences were found. 1 Differences were found. >1 Kubectl or diff failed with an error.

Note: KUBECTL_EXTERNAL_DIFF, if used, is expected to follow that convention.

Usage

$ kubectl diff -f FILENAME

Flags

edit

Edit the service named ‘registry’

kubectl edit svc/registry

Use an alternative editor

KUBE_EDITOR="nano" kubectl edit svc/registry

Edit the job ‘myjob’ in JSON using the v1 API format

kubectl edit job.v1.batch/myjob -o json

Edit the deployment ‘mydeployment’ in YAML and save the modified config in its annotation

kubectl edit deployment/mydeployment -o yaml --save-config

Edit the deployment/mydeployment’s status subresource

kubectl edit deployment mydeployment --subresource='status'

Edit a resource from the default editor.

The edit command allows you to directly edit any API resource you can retrieve via the command-line tools. It will open the editor defined by your KUBE_EDITOR, or EDITOR environment variables, or fall back to ‘vi’ for Linux or ‘notepad’ for Windows. You can edit multiple objects, although changes are applied one at a time. The command accepts file names as well as command-line arguments, although the files you point to must be previously saved versions of resources.

Editing is done with the API version used to fetch the resource. To edit using a specific API version, fully-qualify the resource, version, and group.

The default format is YAML. To edit in JSON, specify “-o json”.

The flag —windows-line-endings can be used to force Windows line endings, otherwise the default for your operating system will be used.

In the event an error occurs while updating, a temporary file will be created on disk that contains your unapplied changes. The most common error when updating a resource is another editor changing the resource on the server. When this occurs, you will have to apply your changes to the newer version of the resource, or update your temporary saved copy to include the latest resource version.

Usage

$ kubectl edit (RESOURCE/NAME | -f FILENAME)

Flags

kustomize

Build the current working directory

kubectl kustomize

Build some shared configuration directory

kubectl kustomize /home/config/production

Build from github

kubectl kustomize https://github.com/kubernetes-sigs/kustomize.git/examples/helloWorld?ref=v1.0.6

Build a set of KRM resources using a ‘kustomization.yaml’ file. The DIR argument must be a path to a directory containing ‘kustomization.yaml’, or a git repository URL with a path suffix specifying same with respect to the repository root. If DIR is omitted, ‘.’ is assumed.

Usage

$ kubectl kustomize DIR

Flags

label

Update pod ‘foo’ with the label ‘unhealthy’ and the value ‘true’

kubectl label pods foo unhealthy=true

Update pod ‘foo’ with the label ‘status’ and the value ‘unhealthy’, overwriting any existing value

kubectl label --overwrite pods foo status=unhealthy

Update all pods in the namespace

kubectl label pods --all status=unhealthy

Update a pod identified by the type and name in “pod.json”

kubectl label -f pod.json status=unhealthy

Update pod ‘foo’ only if the resource is unchanged from version 1

kubectl label pods foo status=unhealthy --resource-version=1

Update pod ‘foo’ by removing a label named ‘bar’ if it exists # Does not require the —overwrite flag

kubectl label pods foo bar-

Update the labels on a resource.

A label key and value must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores, up to 63 characters each. Optionally, the key can begin with a DNS subdomain prefix and a single ‘/‘, like example.com/my-app.
If —overwrite is true, then existing labels can be overwritten, otherwise attempting to overwrite a label will result in an error. If —resource-version is specified, then updates will use this resource version, otherwise the existing resource-version will be used.

Usage

$ kubectl label [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]

Flags

patch

Partially update a node using a strategic merge patch, specifying the patch as JSON

kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'

Partially update a node using a strategic merge patch, specifying the patch as YAML

kubectl patch node k8s-node-1 -p $'spec:\n unschedulable: true'

Partially update a node identified by the type and name specified in “node.json” using strategic merge patch

kubectl patch -f node.json -p '{"spec":{"unschedulable":true}}'

Update a container’s image; spec.containers[*].name is required because it’s a merge key

kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'

Update a container’s image using a JSON patch with positional arrays

kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'

Update a deployment’s replicas through the scale subresource using a merge patch.

kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'

Update fields of a resource using strategic merge patch, a JSON merge patch, or a JSON patch.

JSON and YAML formats are accepted.

Usage

$ kubectl patch (-f FILENAME | TYPE NAME) [-p PATCH|--patch-file FILE]

Flags

replace

Replace a pod using the data in pod.json

kubectl replace -f ./pod.json

Replace a pod based on the JSON passed into stdin

cat pod.json | kubectl replace -f -

Update a single-container pod’s image version (tag) to v4

kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -

Force replace, delete and then re-create the resource

kubectl replace --force -f ./pod.json

Replace a resource by file name or stdin.

JSON and YAML formats are accepted. If replacing an existing resource, the complete resource spec must be provided. This can be obtained by

$ kubectl get TYPE NAME -o yaml

Usage

$ kubectl replace -f FILENAME

Flags

rollout

Rollback to the previous deployment

kubectl rollout undo deployment/abc

Check the rollout status of a daemonset

kubectl rollout status daemonset/foo

Restart a deployment

kubectl rollout restart deployment/abc

Restart deployments with the app=nginx label

kubectl rollout restart deployment --selector=app=nginx

Manage the rollout of one or many resources.

Valid resource types include:

deployments daemonsets
* statefulsets

Usage

$ kubectl rollout SUBCOMMAND

history

View the rollout history of a deployment

kubectl rollout history deployment/abc

View the details of daemonset revision 3

kubectl rollout history daemonset/abc --revision=3

View previous rollout revisions and configurations.

Usage

$ kubectl rollout history (TYPE NAME | TYPE/NAME) [flags]

Flags

pause

Mark the nginx deployment as paused # Any current state of the deployment will continue its function; new updates # to the deployment will not have an effect as long as the deployment is paused

kubectl rollout pause deployment/nginx

Mark the provided resource as paused.

Paused resources will not be reconciled by a controller. Use “kubectl rollout resume” to resume a paused resource. Currently only deployments support being paused.

Usage

$ kubectl rollout pause RESOURCE

Flags

restart

Restart a deployment

kubectl rollout restart deployment/nginx

Restart a daemon set

kubectl rollout restart daemonset/abc

Restart deployments with the app=nginx label

kubectl rollout restart deployment --selector=app=nginx

Restart a resource.

Resource rollout will be restarted.

Usage

$ kubectl rollout restart RESOURCE

Flags

resume

Resume an already paused deployment

kubectl rollout resume deployment/nginx

Resume a paused resource.

Paused resources will not be reconciled by a controller. By resuming a resource, we allow it to be reconciled again. Currently only deployments support being resumed.

Usage

$ kubectl rollout resume RESOURCE

Flags

status

Watch the rollout status of a deployment

kubectl rollout status deployment/nginx

Show the status of the rollout.

By default ‘rollout status’ will watch the status of the latest rollout until it’s done. If you don’t want to wait for the rollout to finish then you can use —watch=false. Note that if a new rollout starts in-between, then ‘rollout status’ will continue watching the latest revision. If you want to pin to a specific revision and abort if it is rolled over by another revision, use —revision=N where N is the revision you need to watch for.

Usage

$ kubectl rollout status (TYPE NAME | TYPE/NAME) [flags]

Flags

undo

Roll back to the previous deployment

kubectl rollout undo deployment/abc

Roll back to daemonset revision 3

kubectl rollout undo daemonset/abc --to-revision=3

Roll back to the previous deployment with dry-run

kubectl rollout undo --dry-run=server deployment/abc

Roll back to a previous rollout.

Usage

$ kubectl rollout undo (TYPE NAME | TYPE/NAME) [flags]

Flags

scale

Scale a replica set named ‘foo’ to 3

kubectl scale --replicas=3 rs/foo

Scale a resource identified by type and name specified in “foo.yaml” to 3

kubectl scale --replicas=3 -f foo.yaml

If the deployment named mysql’s current size is 2, scale mysql to 3

kubectl scale --current-replicas=2 --replicas=3 deployment/mysql

Scale multiple replication controllers

kubectl scale --replicas=5 rc/foo rc/bar rc/baz

Scale stateful set named ‘web’ to 3

kubectl scale --replicas=3 statefulset/web

Set a new size for a deployment, replica set, replication controller, or stateful set.

Scale also allows users to specify one or more preconditions for the scale action.

If —current-replicas or —resource-version is specified, it is validated before the scale is attempted, and it is guaranteed that the precondition holds true when the scale is sent to the server.

Usage

$ kubectl scale [--resource-version=version] [--current-replicas=count] --replicas=COUNT (-f FILENAME | TYPE NAME)

Flags

set

Configure application resources.

These commands help you make changes to existing application resources.

Usage

$ kubectl set SUBCOMMAND

env

Update deployment ‘registry’ with a new environment variable

kubectl set env deployment/registry STORAGE_DIR=/local

List the environment variables defined on a deployments ‘sample-build’

kubectl set env deployment/sample-build --list

List the environment variables defined on all pods