Cómo kubectl usa la API de Kubernetes

kubectl

kubectl Fuente: https://blog.risingstack.com/what-is-kubernetes-how-to-get-started/

Como ya sabes, y si no lo sabes te lo cuento ahora, en Kubernetes, cualquier tipo de consulta o comando se lleva a cabo a través de llamadas a la API del mismo. El componente encargado de recibir y procesar dichas peticiones se llama: API Server. Este componente se encuentra en el nodo o nodos maestros del cluster.

API Server

Fuente: https://blog.openshift.com/kubernetes-deep-dive-api-server-part-1/

Mi compañero y amigo Cybercaronte y yo ya hemos publicado varios artículos relacionados con Kubernetes, en los cuales si has leído, sabrás que existe una herramienta con la que podemos intereactuar con nuestro clúster desde la línea de comandos: kubectl. Aunque existen interfaces gráficas, la forma más común y usada es a través de dicha herramienta.

Las opciones que esta utilidad provee son bastante amplias. En esta entrada vamos a hablar sólo de un parámetro común a prácticamente todas las opciones ofrecidas por kubectl: la verbosidad (verbosity).

Para saber que ocurre cuando ejecutamos un comando con kubectl, podemos usar la opción -v o –v. Esta opción acepta a su vez un número, el cual indica el nivel de verbosidad que queremos obtener. Dicho número va desde el 0 al 9, y la información que reporta kubectl con cada número es la siguiente:

Verbosity

Fuente: https://kubernetes.io/docs/reference/kubectl/cheatsheet/

Si ejecutamos el sisguiente comando:

kubectl get pods
NAME                     READY   STATUS    RESTARTS   AGE
nginx-7bb7cd8db5-8z6t8   1/1     Running   0          33s

Vemos que kubectl nos devuelve los pods que tenemos corriendo en el espacio de nombres default. Ahora hagamos los mismo con vervosidad de nivel 5:

kubectl get pods -v=5
I0819 17:02:54.174578   30833 get.go:564] no kind "Table" is registered for version "meta.k8s.io/v1beta1" in scheme "k8s.io/kubernetes/pkg/api/legacyscheme/scheme.go:30"
NAME                     READY   STATUS    RESTARTS   AGE
nginx-7bb7cd8db5-8z6t8   1/1     Running   0          26s

Como se puede observar, en este caso, además de los pods que hay corriendo, obtenemos información extra. Los niveles del 0 al 5 nos vienen muy bien para depurar o ver que acciones lleva a cabo kubectl, pero los níveles en los que quiero hacer hincapié en esta entrada son del 6 al 9.

Activando estos niveles, no sólo son muy útiles para depurar y ver que hace kubectl, pero también son muy educativos, sobre todo si nos queremos familiarizar con su API, ya que estos niveles nos muestran que llamadas a la API hace kubectl.

Veamos un ejemplo en nivel 6: (sólo voy a dejar las líneas que nos interesa)

kubectl get pods -v=6
...
I0819 17:11:39.565753   30923 round_trippers.go:438] GET https://192.168.99.110:8443/api/v1/namespaces/default/pods?limit=500 200 OK in 12 milliseconds
...

Como se puede ver, para obtener los pods del espacio de nombre actual (default), kubectl hace una llamada a https://192.168.99.110:8443/api/v1/namespaces/default/pods?limit=500 que además, podemos apreciar que limita el número de pods a 500, con lo que si tienes más de 500 pods corriendo en tu espacio de nombre y kubectl sólo te devuelve 500, ya sabes el porqué ;).

Ahora subamos de nivel:

kubectl get pods -v=7
...
I0819 17:22:29.600084   31029 round_trippers.go:416] GET https://192.168.99.110:8443/api/v1/namespaces/default/pods?limit=500
I0819 17:22:29.600108   31029 round_trippers.go:423] Request Headers:
I0819 17:22:29.600118   31029 round_trippers.go:426]     Accept: application/json;as=Table;v=v1beta1;g=meta.k8s.io, application/json
I0819 17:22:29.600132   31029 round_trippers.go:426]     User-Agent: kubectl/v1.15.2 (darwin/amd64) kubernetes/f627830
I0819 17:22:29.612086   31029 round_trippers.go:441] Response Status: 200 OK in 11 milliseconds
...

La diferencia con el nivel 6, es que además de los recursos que son llamados, también podemos ver las cabeceras HTTP con las que se llaman a dichos recursos.

El nivel 8 y el 9, además de las cabeceras, nos muestra el contenido del cuerpo de la petición (si existe) y respuesta (el nivel 9 muestra el contenido sin truncar), veamos otro ejemplo:

kubectl get pods -v=8
...
I0819 17:22:22.188395   31000 request.go:947] Response Body: {"kind":"Table","apiVersion":"meta.k8s.io/v1beta1","metadata":{"selfLink":"/api/v1/namespaces/default/pods","resourceVersion":"70162"},"columnDefinitions":[{"name":"Name","type":"string","format":"name","description":"Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names","priority":0},{"name":"Ready","type":"string","format":"","description":"The aggregate readiness state of this pod for accepting traffic.","priority":0},{"name":"Status","type":"string","format":"","description":"The aggregate status of the containers in this pod.","priority":0},{"name":"Restarts","type":"integer","format":"","description":"The number of times the containers in this pod have been restarted.","priority":0},{"name":"Age","type":"string [truncated 2611 chars]
...

Veamos un ejemplo de un comando un poco más complejo dónde se requiera el uso de varias llamadas:

kubectl describe pod nginx-7bb7cd8db5-8z6t8 -v=6
...
I0819 17:26:27.770772   31121 round_trippers.go:438] GET https://192.168.99.110:8443/api/v1/namespaces/default/pods/nginx-7bb7cd8db5-8z6t8 200 OK in 12 milliseconds
I0819 17:26:27.777728   31121 round_trippers.go:438] GET https://192.168.99.110:8443/api/v1/namespaces/default/pods/nginx-7bb7cd8db5-8z6t8 200 OK in 2 milliseconds
I0819 17:26:27.786906   31121 round_trippers.go:438] GET https://192.168.99.110:8443/api/v1/namespaces/default/events?fieldSelector=involvedObject.name%3Dnginx-7bb7cd8db5-8z6t8%2CinvolvedObject.namespace%3Ddefault%2CinvolvedObject.uid%3D9e77227d-cc08-4365-aeab-c0bbbfc1c1d8 200 OK in 2 milliseconds
...

Como se puede observar el comando describe requiere más de una llamada a la API. Por último veamos que ocurre durante la creación de un deployment con el comando run:

kubectl run nginx2 --image nginx -v=8
...
I0819 17:29:23.727063   31398 round_trippers.go:416] GET https://192.168.99.110:8443/apis/apps/v1?timeout=32s
I0819 17:29:23.727097   31398 round_trippers.go:423] Request Headers:
...
I0819 17:29:23.749539   31398 request.go:947] Request Body: {"kind":"Deployment","apiVersion":"apps/v1","metadata":{"name":"nginx2","creationTimestamp":null,"labels":{"run":"nginx2"}},"spec":{"replicas":1,"selector":{"matchLabels":{"run":"nginx2"}},"template":{"metadata":{"creationTimestamp":null,"labels":{"run":"nginx2"}},"spec":{"containers":[{"name":"nginx2","image":"nginx","resources":{}}]}},"strategy":{}},"status":{}}
I0819 17:29:23.749618   31398 round_trippers.go:416] POST https://192.168.99.110:8443/apis/apps/v1/namespaces/default/deployments
I0819 17:29:23.749631   31398 round_trippers.go:423] Request Headers:
I0819 17:29:23.749638   31398 round_trippers.go:426]     Content-Type: application/json
I0819 17:29:23.749645   31398 round_trippers.go:426]     User-Agent: kubectl/v1.15.2 (darwin/amd64) kubernetes/f627830
...

En este caso vemos como no sólo se hacen peticiones GET, sino también POST, y gracias al nivel 8 podemos ver el contenido de dichas peticiones.

Así puedes ir probando comandos y jugando con los niveles de verbosidad. Si quieres aprender más sobre la API de Kuberntes, además de su documentación obviamente, usando la verbosidad puedes aprender un poco más de forma algo más interactiva.

Happy Hacking!