Managing resources on a kubernetes cluster using kubectl

If you have been playing with Kubernetes, you should already be familiar with the kubectl command, at least at a basic level. Kubernetes is an open-source tool, originally developed by Google, used for automating deployment and management and auto-scaling of containerized applications. In this article we will be reviewing kubectl and what it is used for in Kubernetes.

kubectl is a powerful command line tool that is used for running commands against Kubernetes clusters. It interacts with the Kubernetes API and its shared state to deploy and manage applications on the Kubernetes cluster.

Install and Setup kubectl

Let’s look at steps required to install kubectl and get it ready for use on Kubernetes cluster. There are different ways you can setup kubectl. One method is by downloading application binary to your OS and make it executable or install it (Windows), and an alternative method involves building the tool from source code available on Github. But the most preferred method is downloading a ready binary file. The method covered here is binary installation.

Install kubectl from binary

Kubectl binary is available on github and can be installed on Linux, Unix and Windows systems.

Prerequisites

1. Kubernetes cluster already setup. We can do this easily from http://stakater.com
2. Internet connection
3. curl or wget tool installed (For Mac and Linux) — refer to your OS documentation on how to install it.
4. Knowledge of basic Linux/Unix commands; mv, chmod, curl, export — not a must

With all above prerequisites met, proceed to install kubectl.

Run the following commands to install the latest release of kubectl, this covers installation for Linux, MacOS, and Windows.

Linux and MacOS:

Download kubectl binary

curl -LO https://storage.googleapis.com/kubernetes-release/release/`curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt`/bin/darwin/amd64/kubectl

Move the binary to /usr/local/bin/ directory and make it executable.

mv ./kubectl /usr/local/bin/
chmod +x /usr/local/bin/kubectl

Make sure /usr/local/bin/ is in your $PATH.

Windows:

For Windows, download the binary from this link and install it like any other normal Windows application.

Check the kubectl configuration

After successful installation, confirm that kubectl has been properly configured by issuing a command which checks cluster state.

$ kubectl cluster-info
Kubernetes master is running at https://192.168.99.100:8443
To further debug and diagnose cluster problems, use ‘kubectl cluster-info dump’.

If you get a URL response as output, then kubectl is correctly configured and ready for use on your cluster. If you get an error from above command you can dump cluster configuration for further troubleshooting using:

$ kubectl cluster-info dump

To get less content, pipe to head to filter:

$ kubectl cluster-info dump |head
{
 “selfLink”: “/api/v1/nodes”,
 “resourceVersion”: “29495”,
 “Items”: [
 {
 “name”: “minikube”,
 “selfLink”: “/api/v1/nodes/minikube”,
 “uid”: “86b7bd31-e550–11e7–8389–080027320547”,
 “resourceVersion”: “29493”,
 “creationTimestamp”: “2017–12–20T06:39:27Z”,

Enable shell autocompletion for kubectl commands

kubectl comes with built-in bash and zsh completion. This autocompletion is generated by kubectl. It can save you a lot of typing and improve your productivity by autocompleting flags and objects, e.g. pod names and namespaces. To configure autocompletion for kubectl, run:

echo “source <(kubectl completion bash)” >> ~/.bashrc

This will add kubectl autocomplete to your profile so it’s automatically loaded upon any new shell invocation. If you’re using zsh, add the following lines to

# kubectl bash completion
if [ $commands[kubectl] ]; then
 source <(kubectl completion zsh)
fi

Confirm changes:

$ tail -n 5 ~/.zshrc
# kubectl bash completion
if [ $commands[kubectl] ]; then
 source <(kubectl completion zsh)
fi

Now if you type kubectl and press enter, it should list all available options:

$ kubectl <TAB TWICE>
alpha           cluster-info    describe        logs            rollout
annotate        completion      drain           options         run
api-versions    config          edit            patch           scale
apply           convert         exec            plugin          set
attach          cordon          explain         port-forward    taint
auth            cp              expose          proxy           top
autoscale       create          get             replace         uncordon
certificate     delete          label           rolling-update  version

Kubectl commands syntax is

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

This syntax apply for all kubectl commands that you run on your terminal. Where command, TYPE, NAME, and flags are:

Command — This specifies the operation to be performed on a resource, e.g describe, get, delete, create, run, edit, set, convert, label, scale e.t.c

TYPE — This specifies a resource type. Note that resource types are case sensitive, and can be singular, plural, or abbreviated forms. For example commands pod,pods,po will return same output.

NAME — This specifies a resource name, names are case sensitive. If no name is given, details for all resources will be displayed. A resource can be specified by type and name.

Flags — Used to specify optional flags which override default values,example, -s or —server flag is used to specify the address of Kubernetes API Server.

Kubectl Common Operations

Having looked at kubectl basics, let’s proceed to see common kubectl operations that can be performed on Kubernetes cluster.

Create a resource from a file

To create a resource on Kubernetes with kubectl from a file or from stdin, use the following command syntax:

$ kubectl create -f FILENAME

Supported file formats are JSON and YAML. So to create a pod from yaml file named pod.yml, you’ll run

$ kubectl create -f ./pod.yml
pod “mytestserver” created

The same pod.yml contents can be passed as stdin to kubectl command as below.

$ cat pod1.yml | kubectl create -f -
pod “mytestserver1” created

List resources

To list one or more resources, kubectl get command is used for this, it supports plain-text output format. A number of resource types are supported. To get all pods in human readable format, use

$ kubectl get pods
NAME            READY     STATUS    RESTARTS   AGE
mytestserver    1/1       Running   0          59s
mytestserver1   1/1       Running   0          32s

For json output format, use json flag:

$ kubectl get pods -o json | head
{
"apiVersion": "v1",
"items": [
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"creationTimestamp": "2018-01-06T07:00:42Z",
"name": "mytestserver",
"namespace": "default",

To list all pods with more information, wide flag is used.

$ kubectl get pods -o wide
NAME            READY     STATUS    RESTARTS   AGE       IP           NODE
mytestserver    1/1       Running   0          5m        172.17.0.4   minikube
mytestserver1   1/1       Running   0          5m        172.17.0.5   minikube

You can also list more than two resources together by separating them with a comma.

$ kubectl get nodes,jobs,events,pods

Where pods,jobs,events and nodes are resource types. You can consult Kubernetes documentation for all resource types available.

Display detailed state of resources

To display detailed state of a resource with kubectl, the command describe is used. This will print debug information about the given resource. As an example, to display the details of the pod with name <pod-name>, use:

$ kubectl describe pods/<pod-name>

Example:

$ kubectl describe pods/mytestserver
Name:         mytestserver
Namespace:    default
Node:         minikube/192.168.99.100
Start Time:   Sat, 06 Jan 2018 10:00:42 +0300
Labels:       <none>
Annotations:  <none>
Status:       Running
IP:           172.17.0.4
Containers:
hello:
Container ID:   docker://7bb649c9d703bb5c78d48ba0b353fd6d391e16d574a3372b9e431cc7ec11e605
Image:          andygrunwald/simple-webserver
Image ID:       docker-pullable://andygrunwald/simple-webserver@sha256:be5665894aa8df984d34334a837fda2886c107137d0a7b1537c7cb47fe92b9b6
Port:           8082/TCP
State:          Running
Started:      Sat, 06 Jan 2018 10:00:48 +0300
Ready:          True
Restart Count:  0
Environment:    <none>
Mounts:
/var/run/secrets/kubernetes.io/serviceaccount from default-token-k8pmr (ro)
Conditions:
Type           Status
Initialized    True
Ready          True
PodScheduled   True
Volumes:
default-token-k8pmr:
Type:        Secret (a volume populated by a Secret)
SecretName:  default-token-k8pmr
Optional:    false
QoS Class:       BestEffort
Node-Selectors:  <none>
Tolerations:     <none>
Events:
Type    Reason                 Age   From               Message
----    ------                 ----  ----               -------
Normal  Scheduled              10m   default-scheduler  Successfully assigned mytestserver to minikube
Normal  SuccessfulMountVolume  10m   kubelet, minikube  MountVolume.SetUp succeeded for volume "default-token-k8pmr"
Normal  Pulling                10m   kubelet, minikube  pulling image "andygrunwald/simple-webserver"
Normal  Pulled                 10m   kubelet, minikube  Successfully pulled image "andygrunwald/simple-webserver"
Normal  Created                10m   kubelet, minikube  Created container
Normal  Started                10m   kubelet, minikube  Started container

Similar commands are used for other resource types.

Delete resources

With kubectl delete, you can delete resources from either a file or stdin. To delete service defined in a file, you’ll use -f flag followed by the name of the file:

$ kubectl delete -f pod1.yaml
pod “mytestserver1” deleted

This deletes a service using a type and name that’s specified in the service.yml file. To delete all pods including ones that have not been initialized, run

$ kubectl delete pods --all
pod “mytestserver” deleted
pod “mytestserver1” deleted

Execute a command against a container in a pod

If you have containers running in Kubernetes and would like to execute commands on these containers, kubectl exec comes in handy. Let’s say we have a container called apache on pod web, If i want to test internet access through pin, I would run:

$ kubectl exec web -c <container-name> date

Replace <container-name> with the name of your container and date with the command to be executed on a container.

$ kubectl exec mytestserver date
Sat Jan 6 07:18:22 UTC 2018

Print the logs for a container in a pod.

At times you need pull logs from a container for troubleshooting issues, this can be achieved using kubectl logs command. In below example, assuming you want to print logs on a pod named mytestserver with only one container, you’ll run:

$ kubectl logs mytestserver 
2018/01/06 07:17:43 Starting webserver and listen on :8082

Next command below will return snapshot of previous terminated nginx container logs from pod prod-web

$ kubectl logs -p -c hello-world mytestserver1

You can also stream real time logs using -f flag:

$ kubectl logs -f -c hello-world mytestserver1
2018/01/06 07:17:43 Starting webserver and listen on :8082

Other options available are —tail and —since

$ kubectl logs --tail=50 mytestserver # Print most recent 50 lines
$ kubectl logs --since=3h mytestserver # Print last 3 hours logs

Forward one or more local ports to a pod.

If your node has a public IP address and you would like to access service port on a container through host system port, you’ll need to forward ports using kubectl port-forward command. The syntax is:

$ kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT

Below command will forward port 80 on the host to port 80 on the on the pod.

$ kubectl port-forward prod-web 80:80

Edit a resource

To edit a resource using kubectl command line tool, use edit command. It will open the editor defined by your KUBE_EDITOR, or EDITOR environment variables, fallback being vi for Linux and notepad for Windows. The default format is YAML. The syntax is

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

Have a look at below example which edits pod called mytestserver1 using vim editor.

$ KUBE_EDITOR=”vim” kubectl edit pod mytestserver1

Create a secret for use with a Docker registry.

If you have a docker registry which requires authentication, create a new secret for use in Dockercfg. This will be used by commands like docker login command for image pushing and pulling. Commands syntax is as shown

$ kubectl create secret docker-registry mydocker-key \
 --docker-username=test --docker-password=password --docker-email=test@example.com
secret “mydocker-key” created

Replace user with your username, password with real password, and email with a valid email address.

Check for the created secret:

$ kubectl get secret 
NAME                  TYPE                                  DATA      AGE
default-token-k8pmr   kubernetes.io/service-account-token   3         17d
mydocker-key          kubernetes.io/dockercfg               1         57s

Delete secret:

$ kubectl delete secret mydocker-key 
secret “mydocker-key” deleted

Apply a configuration to a resource

You can apply a configuration to a resource by filename or stdin. If the resource doesn’t exist yet, it will be created. The formats accepted are JSON and YAML. Consider these examples

# Apply configuration in mypod.yml to a pod
$ kubectl apply -f ./pod.yml
pod “mytestserver” created
# Apply the JSON passed into stdin to a pod
$ cat mypod.json | kubectl apply -f -

Auto-scale a deployment or replication controller

It’s easy to scale a deployment or replication controller using kubectl command. What you need to do is create an autoscaler that automatically chooses and sets thhe number of pods that run in a kubernetes cluster. This autoscaler can automatically increase or decrease number of pods deployed within the system as needed.

Create deployment

$ kubectl run hello-node --image=hello-node:v1 --port=8080
deployment “hello-node” created

Get deployments:

$ kubectl get deployments
NAME         DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
hello-node   1         1         1            0           1s

Configure autoscaling:

$ kubectl autoscale deployment hello-node --min 2 --max 3 
deployment “hello-node” autoscaled

Again run get deployments command to confirm autoscaling:

$ kubectl get deployment
NAME         DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
hello-node   2         2         2            0           4m
$ kubectl get pod
NAME                          READY     STATUS             RESTARTS   AGE
hello-node-75ddf8bc9d-d7bqj   0/1       ImagePullBackOff   0          5m
hello-node-75ddf8bc9d-sj646   0/1       ImagePullBackOff   0          2m

From above output, you can see the number of pods are now two ( set to minimum):

This will automatically scale a deployment called hello-node with a number of pods between 2 and 3.

To target average CPU utilization of 70%, use:

$ kubectl autoscale deployment hello-node --min=3 --max=7 --cpu-percent=80

Convert config files between different API versions

To convert configuration files between different formats, use kubectl convert command. This support both YAML and JSON formats. An input passed to the command can be a filename, directory, or URL. Output format version is specified using — output-version tag, if no version is specified, latest will be used.

To specify a destination, use -o flag. The default output will be printed to stdout in YAML

Examples:

$ kubectl convert -f tests/pod.yml # convert to latest version and print on stdout
apiVersion: v1
items:
- apiVersion: v1
kind: Pod
metadata:
creationTimestamp: null
name: mytestserver
spec:
containers:
- image: andygrunwald/simple-webserver
imagePullPolicy: Always
name: hello
ports:
- containerPort: 8082
protocol: TCP
resources: {}
terminationMessagePath: /dev/termination-log
terminationMessagePolicy: File
dnsPolicy: ClusterFirst
restartPolicy: Never
schedulerName: default-scheduler
securityContext: {}
terminationGracePeriodSeconds: 30
status: {}
$ kubectl convert -f tests/pod.yml --local -o json # convert and print to stdout in json format
{
"kind": "Pod",
"apiVersion": "v1",
"metadata": {
"name": "mytestserver",
"creationTimestamp": null
},
"spec": {
"containers": [
{
"name": "hello",
"image": "andygrunwald/simple-webserver",
"ports": [
{
"containerPort": 8082,
"protocol": "TCP"
}
],
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"imagePullPolicy": "Always"
}
],
"restartPolicy": "Never",
"terminationGracePeriodSeconds": 30,
"dnsPolicy": "ClusterFirst",
"securityContext": {},
"schedulerName": "default-scheduler"
},
"status": {}
}
$ kubectl convert -f . | kubectl create -f -   # Convert all files in current directory and create them all

Convert to json and redirect output to a file:

$ kubectl convert -f tests/pod.yml --local -o json > pod.json
$ cat pod.json

{
    "kind": "Pod",
    "apiVersion": "v1",
    "metadata": {
        "name": "mytestserver",
        "creationTimestamp": null
    },
    "spec": {
        "containers": [
            {
                "name": "hello",
                "image": "andygrunwald/simple-webserver",
                "ports": [
                    {
                        "containerPort": 8082,
                        "protocol": "TCP"
                    }
                ],
                "resources": {},
                "terminationMessagePath": "/dev/termination-log",
                "terminationMessagePolicy": "File",
                "imagePullPolicy": "Always"
            }
        ],
        "restartPolicy": "Never",
        "terminationGracePeriodSeconds": 30,
        "dnsPolicy": "ClusterFirst",
        "securityContext": {},
        "schedulerName": "default-scheduler"
    },
    "status": {}
}

Conclusion

We have come to the end of our guide on how to manage Kubernetes cluster and resources with kubectl command. We started with the installation of kubectl on Windows and Linux, looked at command line syntax for kubectl command tool, and finalized with examples on management of Kubernetes cluster with kubectl command.