|
1 | 1 | --- |
2 | | -title: " Some things you didn’t know about kubectl " |
| 2 | +title: "Some things you didn’t know about kubectl" |
3 | 3 | date: 2015-10-28 |
4 | 4 | slug: some-things-you-didnt-know-about-kubectl_28 |
5 | 5 | url: /blog/2015/10/Some-Things-You-Didnt-Know-About-Kubectl_28 |
6 | 6 | --- |
7 | | -[kubectl](https://github.com/kubernetes/kubernetes/blob/master/docs/user-guide/kubectl-overview.md) is the command line tool for interacting with Kubernetes clusters. Many people use it every day to deploy their container workloads into production clusters. But there’s more to kubectl than just `kubectl create -f or kubectl rolling-update`. kubectl is a veritable multi-tool of container orchestration and management. Below we describe some of the features of kubectl that you may not have seen. |
8 | 7 |
|
9 | | -**Important Note** : Most of these features are part of the upcoming 1.1 release of Kubernetes. They are not present in the current stable 1.0.x release series. |
| 8 | +**Author:** Brendan Burns (Google) |
10 | 9 |
|
| 10 | +[kubectl](/docs/reference/kubectl/) is the command line tool for interacting with Kubernetes clusters. Many people use it every day to deploy their container workloads into production clusters. But there’s more to kubectl than just `kubectl create -f or kubectl rolling-update`. kubectl is a veritable multi-tool of container orchestration and management. Below we describe some of the features of kubectl that you may not have seen. |
11 | 11 |
|
12 | | -##### Run interactive commands |
| 12 | +## Run interactive commands |
13 | 13 |
|
14 | 14 | `kubectl run` has been in kubectl since the 1.0 release, but recently we added the ability to run interactive containers in your cluster. That means that an interactive shell in your Kubernetes cluster is as close as: |
15 | 15 |
|
16 | | -``` |
17 | | -$> kubectl run -i --tty busybox --image=busybox --restart=Never -- sh |
18 | | -Waiting for pod default/busybox-tv9rm to be running, status is Pending, pod ready: false |
19 | | -Waiting for pod default/busybox-tv9rm to be running, status is Running, pod ready: false |
| 16 | +```console |
| 17 | +$> kubectl run -i --tty busybox --image=busybox --restart=Never -- sh |
| 18 | +Waiting for pod default/busybox-tv9rm to be running, status is Pending, pod ready: false |
| 19 | +Waiting for pod default/busybox-tv9rm to be running, status is Running, pod ready: false |
20 | 20 | $> # ls |
21 | 21 | bin dev etc home proc root sys tmp usr var |
22 | | -$> # exit |
| 22 | +$> # exit |
23 | 23 | ``` |
24 | | -The above `kubectl` command is equivalent to `docker run -i -t busybox sh.` Sadly we mistakenly used `-t` for template in kubectl 1.0, so we need to retain backwards compatibility with existing CLI user. But the existing use of `-t` is deprecated and we’ll eventually shorten `--tty` to `-t`. |
25 | 24 |
|
26 | | -In this example, `-i` indicates that you want an allocated `stdin` for your container and indicates that you want an interactive session, `--restart=Never` indicates that the container shouldn’t be restarted after you exit the terminal and `--tty` requests that you allocate a TTY for that session. |
| 25 | +The above `kubectl` command is equivalent to `docker run -i -t busybox sh`. Sadly we mistakenly used `-t` for template in kubectl 1.0, so we need to retain backwards compatibility with existing CLI user. But the existing use of `-t` is deprecated and we’ll eventually shorten `--tty` to `-t`. |
27 | 26 |
|
| 27 | +In this example, `-i` indicates that you want an allocated `stdin` for your container and indicates that you want an interactive session, `--restart=Never` indicates that the container shouldn’t be restarted after you exit the terminal and `--tty` requests that you allocate a TTY for that session. |
28 | 28 |
|
29 | | -##### View your Pod’s logs |
| 29 | +## View your Pod’s logs |
30 | 30 |
|
31 | | -Sometimes you just want to watch what’s going on in your server. For this, `kubectl logs` is the subcommand to use. Adding the -f flag lets you live stream new logs to your terminal, just like tail -f. |
32 | | - $> kubectl logs -f redis-izl09 |
| 31 | +Sometimes you just want to watch what’s going on in your server. For this, `kubectl logs` is the subcommand to use. Adding the -f flag lets you live stream new logs to your terminal, just like tail -f. |
33 | 32 |
|
34 | | -##### Attach to existing containers |
| 33 | +```console |
| 34 | +$> kubectl logs -f redis-izl09 |
| 35 | +``` |
35 | 36 |
|
36 | | -In addition to interactive execution of commands, you can now also attach to any running process. Like kubectl logs, you’ll get stderr and stdout data, but with attach, you’ll also be able to send stdin from your terminal to the program. Awesome for interactive debugging, or even just sending ctrl-c to a misbehaving application. |
| 37 | +## Attach to existing containers |
37 | 38 |
|
38 | | - $> kubectl attach redis -i |
| 39 | +In addition to interactive execution of commands, you can now also attach to any running process. Like kubectl logs, you’ll get stderr and stdout data, but with attach, you’ll also be able to send stdin from your terminal to the program. Awesome for interactive debugging, or even just sending ctrl-c to a misbehaving application. |
39 | 40 |
|
| 41 | +```console |
| 42 | +$> kubectl attach redis -i |
40 | 43 |
|
41 | 44 | 1:C 12 Oct 23:05:11.848 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf |
42 | 45 |
|
43 | | -``` |
44 | | - _._ |
45 | | - _.-``__''-._ |
| 46 | + _._ |
| 47 | + _.-``__''-._ |
46 | 48 | _.-`` `. `_. ''-._ Redis 3.0.3 (00000000/0) 64 bit |
47 | | - .-`` .-```. ```\/ _.,_ ''-._ |
| 49 | + .-`` .-```. ```\/ _.,_ ''-._ |
48 | 50 | ( ' , .-` | `, ) Running in standalone mode |
49 | 51 | |`-._`-...-` __...-.``-._|'` _.-'| Port: 6379 |
50 | 52 | | `-._ `._ / _.-' | PID: 1 |
51 | | - `-._ `-._ `-./ _.-' _.-' |
52 | | - |`-._`-._ `-.__.-' _.-'_.-'| |
| 53 | + `-._ `-._ `-./ _.-' _.-' |
| 54 | + |`-._`-._ `-.__.-' _.-'_.-'| |
53 | 55 | | `-._`-._ _.-'_.-' | http://redis.io |
54 | | -`-._ `-._`-.__.-'_.-' _.-' |
55 | | - |`-._`-._ `-.__.-' _.-'_.-'| |
56 | | - | `-._`-._ _.-'_.-' | |
57 | | - `-._ `-._`-.__.-'_.-' _.-' |
58 | | - `-._ `-.__.-' _.-' |
59 | | - `-._ _.-' |
60 | | - `-.__.-' |
| 56 | +`-._ `-._`-.__.-'_.-' _.-' |
| 57 | + |`-._`-._ `-.__.-' _.-'_.-'| |
| 58 | + | `-._`-._ _.-'_.-' | |
| 59 | + `-._ `-._`-.__.-'_.-' _.-' |
| 60 | + `-._ `-.__.-' _.-' |
| 61 | + `-._ _.-' |
| 62 | + `-.__.-' |
61 | 63 |
|
62 | 64 | 1:M 12 Oct 23:05:11.849 # Server started, Redis version 3.0.3 |
63 | 65 | ``` |
64 | 66 |
|
65 | | -##### Forward ports from Pods to your local machine |
| 67 | +## Forward ports from Pods to your local machine |
66 | 68 |
|
67 | 69 | Often times you want to be able to temporarily communicate with applications in your cluster without exposing them to the public internet for security reasons. To achieve this, the port-forward command allows you to securely forward a port on your local machine through the kubernetes API server to a Pod running in your cluster. For example: |
68 | 70 |
|
69 | | -`$> kubectl port-forward redis-izl09 6379` |
| 71 | +```console |
| 72 | +$> kubectl port-forward redis-izl09 6379 |
| 73 | +``` |
70 | 74 |
|
71 | | -Opens port 6379 on your local machine and forwards communication to that port to the Pod or Service in your cluster. For example, you can use the ‘telnet’ command to poke at a Redis service in your cluster: |
| 75 | +Opens port 6379 on your local machine and forwards communication to that port to the Pod or Service in your cluster. For example, you can use the `telnet` command to poke at a Redis service in your cluster: |
72 | 76 |
|
73 | | -``` |
74 | | -$> telnet localhost 6379 |
75 | | -INCR foo |
76 | | -:1 |
| 77 | +```console |
| 78 | +$> telnet localhost 6379 |
| 79 | +INCR foo |
| 80 | +:1 |
77 | 81 | INCR foo |
78 | | -:2 |
| 82 | +:2 |
79 | 83 | ``` |
80 | 84 |
|
81 | | -### Execute commands inside an existing container |
82 | | -In addition to being able to attach to existing processes inside a container, the “exec” command allows you to spawn new processes inside existing containers. This can be useful for debugging, or examining your pods to see what’s going on inside without interrupting a running service. `kubectl exec` is different from `kubectl run`, because it runs a command inside of an _existing_ container, rather than spawning a new container for execution. |
| 85 | +## Execute commands inside an existing container |
| 86 | +In addition to being able to attach to existing processes inside a container, the `exec` command allows you to spawn new processes inside existing containers. This can be useful for debugging, or examining your pods to see what’s going on inside without interrupting a running service. `kubectl exec` is different from `kubectl run`, because it runs a command inside of an _existing_ container, rather than spawning a new container for execution. |
83 | 87 |
|
84 | | -``` |
| 88 | +```console |
85 | 89 | $> kubectl exec redis-izl09 -- ls / |
86 | 90 | bin |
87 | 91 | boot |
|
93 | 97 | ``` |
94 | 98 |
|
95 | 99 |
|
96 | | -##### Add or remove Labels |
97 | | - |
98 | | -Sometimes you want to dynamically add or remove labels from a Pod, Service or Replication controller. Maybe you want to add an existing Pod to a Service, or you want to remove a Pod from a Service. No matter what you want, you can easily and dynamically add or remove labels using the `kubectl label` subcommand: |
| 100 | +## Add or remove Labels |
99 | 101 |
|
100 | | -`$> kubectl label pods redis-izl09 mylabel=awesome ` |
101 | | -`pod "redis-izl09" labeled` |
| 102 | +Sometimes you want to dynamically add or remove labels from a Pod, Service or Replication controller. Maybe you want to add an existing Pod to a Service, or you want to remove a Pod from a Service. No matter what you want, you can easily and dynamically add or remove labels using the `kubectl label` subcommand: |
102 | 103 |
|
| 104 | +```console |
| 105 | +`$> kubectl label pods redis-izl09 mylabel=awesome ` |
| 106 | +`pod "redis-izl09" labeled` |
| 107 | +``` |
103 | 108 |
|
104 | | -##### Add annotations to your objects |
105 | | - |
106 | | -Just like labels, you can add or remove annotations from API objects using the kubectl annotate subcommand. Unlike labels, annotations are there to help describe your object, but aren’t used to identify pods via label queries ([more details on annotations](https://github.com/kubernetes/kubernetes/blob/master/docs/user-guide/annotations.md#annotations)). For example, you might add an annotation of an icon for a GUI to use for displaying your pods. |
| 109 | +## Add annotations to your objects |
107 | 110 |
|
108 | | -`$> kubectl annotate pods redis-izl09 icon-url=http://goo.gl/XXBTWq ` |
109 | | -`pod "redis-izl09" annotated` |
| 111 | +Just like labels, you can add or remove annotations from API objects using the kubectl annotate subcommand. Unlike labels, annotations are there to help describe your object, but aren’t used to identify pods via label queries ([more details on annotations](/docs/concepts/overview/working-with-objects/annotations/)). For example, you might add an annotation of an icon for a GUI to use for displaying your pods. |
110 | 112 |
|
| 113 | +```console |
| 114 | +$> kubectl annotate pods redis-izl09 icon-url=http://goo.gl/XXBTWq |
| 115 | +pod "redis-izl09" annotated |
| 116 | +``` |
111 | 117 |
|
112 | | -##### Output custom format |
| 118 | +## Output custom format |
113 | 119 |
|
114 | | -Sometimes, you want to customize the fields displayed when kubectl summarizes an object from your cluster. To do this, you can use the `custom-columns-file` format. `custom-columns-file` takes in a template file for rendering the output. Again, JSONPath expressions are used in the template to specify fields in the API object. For example, the following template first shows the number of restarts, and then the name of the object: |
| 120 | +Sometimes, you want to customize the fields displayed when kubectl summarizes an object from your cluster. To do this, you can use the `custom-columns-file` format. `custom-columns-file` takes in a template file for rendering the output. Again, JSONPath expressions are used in the template to specify fields in the API object. For example, the following template first shows the number of restarts, and then the name of the object: |
115 | 121 |
|
116 | | -``` |
117 | | -$> cat cols.tmpl |
118 | | -RESTARTS NAME |
119 | | -.status.containerStatuses[0].restartCount .metadata.name |
| 122 | +```console |
| 123 | +$> cat cols.tmpl |
| 124 | +RESTARTS NAME |
| 125 | +.status.containerStatuses[0].restartCount .metadata.name |
120 | 126 | ``` |
121 | 127 |
|
122 | | -If you pass this template to the `kubectl get pods` command you get a list of pods with the specified fields displayed. |
| 128 | +If you pass this template to the `kubectl get pods` command you get a list of pods with the specified fields displayed. |
123 | 129 |
|
124 | 130 | ``` |
125 | | - $> kubectl get pods redis-izl09 -o=custom-columns-file --template=cols.tmpl RESTARTS NAME |
| 131 | +$> kubectl get pods redis-izl09 -o=custom-columns-file --template=cols.tmpl RESTARTS NAME |
126 | 132 | 0 redis-izl09 |
127 | 133 | 1 redis-abl42 |
128 | 134 | ``` |
129 | 135 |
|
130 | | -##### Easily manage multiple Kubernetes clusters |
| 136 | +## Easily manage multiple Kubernetes clusters |
131 | 137 |
|
132 | | -If you’re running multiple Kubernetes clusters, you know it can be tricky to manage all of the credentials for the different clusters. Using the `kubectl config` subcommands, switching between different clusters is as easy as: |
| 138 | +If you’re running multiple Kubernetes clusters, you know it can be tricky to manage all of the credentials for the different clusters. Using the `kubectl config` subcommands, switching between different clusters is as easy as: |
133 | 139 |
|
134 | | - $> kubectl config use-context |
| 140 | +```console |
| 141 | +$> kubectl config use-context |
| 142 | +``` |
135 | 143 |
|
136 | | -Not sure what clusters are available? You can view currently configured clusters with: |
| 144 | +Not sure what clusters are available? You can view currently configured clusters with: |
137 | 145 |
|
138 | | - $> kubectl config view |
| 146 | +```console |
| 147 | +$> kubectl config view |
| 148 | +``` |
139 | 149 |
|
140 | | -Phew, that outputs a lot of text. To restrict it down to only the things we’re interested in, we can use a JSONPath template: |
| 150 | +Phew, that outputs a lot of text. To restrict it down to only the things we’re interested in, we can use a JSONPath template: |
141 | 151 |
|
142 | | - $> kubectl config view -o jsonpath="{.context[*].name}" |
| 152 | +```console |
| 153 | +$> kubectl config view -o jsonpath="{.context[*].name}" |
| 154 | +``` |
143 | 155 |
|
144 | 156 | Ahh, that’s better. |
145 | 157 |
|
146 | 158 |
|
147 | | -##### Conclusion |
| 159 | +## Conclusion |
148 | 160 |
|
149 | | -So there you have it, nine new and exciting things you can do with your Kubernetes cluster and the kubectl command line. If you’re just getting started with Kubernetes, check out [Google Container Engine](https://cloud.google.com/container-engine/) or other ways to [get started with Kubernetes](/docs/tutorials/kubernetes-basics/). |
| 161 | +So there you have it, nine new and exciting things you can do with your Kubernetes cluster and the kubectl command line. If you’re just getting started with Kubernetes, check out [Google Container Engine](https://cloud.google.com/container-engine/) or other ways to [get started with Kubernetes](/docs/tutorials/kubernetes-basics/). |
150 | 162 |
|
151 | | -- Brendan Burns, Google Software Engineer |
|
0 commit comments