Kubernetes: Up and Running, 3ª Edición

Capítulo 4. Comandos comunes de kubectl

Este trabajo se ha traducido utilizando IA. Agradecemos tus opiniones y comentarios: [e-mail]

La utilidad de línea de comandos kubectl es una herramienta potente, y en los capítulos siguientes la utilizarás para crear objetos e interactuar con la API de Kubernetes. Antes, sin embargo, tiene sentido repasar los comandos básicos de kubectl que se aplican a todos los objetos de Kubernetes.

Espacios de nombres

Kubernetes utiliza espacios de nombres para organizar los objetos en el clúster. Puedes pensar en cada espacio de nombres como una carpeta que contiene un conjunto de objetos. Por defecto, la herramienta de línea de comandos kubectl interactúa con el espacio de nombres default. Si quieres utilizar un espacio de nombres diferente, puedes pasar akubectl la bandera --namespace. Por ejemplo kubectl --namespace=mystuff hace referencia a objetos del espacio de nombres mystuff. También puedes utilizar la bandera abreviada-n si te sientes conciso. Si quieres interactuar con todos los espacios de nombres -por ejemplo, para listar todos los Pods de tu clúster- puedes pasar la bandera --all-namespaces.

Contextos

Si quieres cambiar el espacio de nombres predeterminado de forma más permanente, puedes utilizar un contexto. Esto se registra en un archivo de configuración de kubectl, normalmente ubicado en $HOME/.kube/config. Este archivo de configuración también almacena cómo encontrar y autenticarse en tu clúster. Por ejemplo, puedes crear un contexto con un espacio de nombres predeterminado diferente para tus comandos kubectl utilizando:

$ kubectl config set-context my-context --namespace=mystuff

Esto crea un nuevo contexto, pero en realidad todavía no empieza a utilizarlo. Para utilizar este contexto recién creado, puedes ejecutar

$ kubectl config use-context my-context

También se pueden utilizar contextos para gestionar distintos clusters o distintos usuarios para autenticarse en esos clusters utilizando las banderas --users o--clusters con el comando set-context.

Visualización de los objetos de la API de Kubernetes

Todo lo que contiene Kubernetes está representado por un recurso RESTful. A lo largo de este libro, nos referiremos a estos recursos como objetos Kubernetes. Cada objeto Kubernetes existe en una ruta HTTP única; por ejemplo, https://your-k8s.com/api/v1/namespaces/default/pods/my-pod conduce a la representación de un Pod en el espacio de nombres predeterminado denominado my-pod. El comando kubectl realiza solicitudes HTTP a estas URL para acceder a los objetos Kubernetes que residen en estas rutas.

El comando más básico para ver los objetos de Kubernetes a través de kubectl es get. Si ejecutas kubectl get <resource-name>obtendrás un listado de todos los recursos del espacio de nombres actual. Si quieres obtener un recurso concreto, puedes utilizar kubectl get <resource-name> <obj-name>.

Por defecto, kubectl utiliza una impresora legible por humanos para ver las respuestas del servidor API, pero esta impresora legible por humanos elimina muchos de los detalles de los objetos para que quepa cada objeto en una línea del terminal. Una forma de obtener algo más de información es añadir la bandera -o wide, que proporciona más detalles, en una línea más larga. Si quieres ver el objeto completo, también puedes ver los objetos como JSON o YAML sin procesar utilizando las banderas -o json o -o yaml, respectivamente.

Una opción habitual para manipular la salida de kubectl es eliminar las cabeceras, lo que suele ser útil cuando se combina kubectl con tuberías Unix (por ejemplo, kubectl ... | awk ...). Si especificas la bandera --no-headers, kubectl omitirá las cabeceras en la parte superior de la tabla legible por humanos.

Otra tarea habitual es extraer campos específicos del objeto. kubectl utiliza el lenguaje de consulta JSONPath para seleccionar campos en el objeto devuelto. Los detalles completos de JSONPath están fuera del alcance de este capítulo, pero como ejemplo, este comando extraerá e imprimirá la dirección IP del Pod especificado:

$ kubectl get pods my-pod -o jsonpath --template={.status.podIP}

También puedes ver varios objetos de distintos tipos utilizando, por ejemplo, una lista de tipos separada por comas:

$ kubectl get pods,services

Esto mostrará todos los Pods y servicios de un espacio de nombres determinado.

Si estás interesado en obtener información más detallada sobre un objeto concreto, utiliza el comando describe:

$ kubectl describe <resource-name> <obj-name>

Esto proporcionará una rica descripción multilínea legible por humanos del objeto, así como de cualquier otro objeto y evento relevante y relacionado en el clúster Kubernetes.

Si quieres ver una lista de los campos admitidos para cada tipo de objeto de Kubernetes, puedes utilizar el comando explain:

$ kubectl explain pods

A veces quieres observar continuamente el estado de un determinado recurso de Kubernetes para ver los cambios que se producen en él. Por ejemplo, puedes estar esperando a que se reinicie tu aplicación. La bandera --watchpermite esto. Puedes añadir esta bandera a cualquier comando kubectl get para monitorizar continuamente el estado de un recurso concreto.

Crear, actualizar y destruir objetos de Kubernetes

Los objetos de la API de Kubernetes se representan como archivos JSON o YAML. Estos archivos son devueltos por el servidor en respuesta a una consulta o enviados al servidor como parte de una solicitud de API. Puedes utilizar estos archivos YAML o JSON para crear, actualizar o eliminar objetos en el servidor Kubernetes.

Supongamos que tienes un objeto simple almacenado en obj.yaml. Puedes utilizar kubectl para crear este objeto en Kubernetes ejecutando:

$ kubectl apply -f obj.yaml

Observa que no es necesario que especifiques en el tipo de recurso del objeto; se obtiene del propio archivo del objeto.

Del mismo modo, después de realizar cambios en el objeto, puedes volver a utilizar el comando apply para actualizarlo:

$ kubectl apply -f obj.yaml

La herramienta apply sólo modificará los objetos que sean diferentes de los objetos actuales del cluster. Si los objetos que estás creando ya existen en el clúster, simplemente saldrá con éxito sin realizar ningún cambio. Esto la hace útil para bucles en los que quieras asegurarte de que el estado del clúster coincide con el estado del sistema de archivos. Puedes utilizar repetidamente apply para reconciliar el estado.

Si quieres ver lo que hará el comando apply sin realizar realmente los cambios, puedes utilizar la bandera --dry-run para imprimir los objetos en el terminal sin enviarlos realmente al servidor.

Nota

Si te apetece hacer ediciones interactivas en lugar de editar un archivo local, puedes utilizar el comando edit, que descargará el último estado del objeto y luego lanzará un editor que contiene la definición:

$ kubectl edit <resource-name> <obj-name>

Después de guardar el archivo, se cargará automáticamente en el clúster de Kubernetes.

El comando apply también registra el historial de configuraciones anteriores en una anotación dentro del objeto. Puedes manipular estos registros con los comandosedit-last-applied, set-last-applied y view-last-applied. Por ejemplo:

$ kubectl apply -f myobj.yaml view-last-applied

te mostrará el último estado que se aplicó al objeto.

Cuando quieras borrar un objeto, basta con que ejecutes

$ kubectl delete -f obj.yaml

Es importante tener en cuenta que kubectl no te pedirá que confirmes el borrado. Una vez que emitas el comando , el objeto se borrará.

Del mismo modo, puedes eliminar un objeto utilizando el tipo y el nombre del recurso:

$ kubectl delete <resource-name> <obj-name>

Etiquetar y anotar objetos

Las etiquetas y anotaciones son etiquetas para tus objetos. Hablaremos de las diferencias en el Capítulo 6, pero por ahora, puedes actualizar las etiquetas y anotaciones de cualquier objeto de Kubernetes utilizando los comandos label y annotate. Por ejemplo, para añadir la etiqueta color=red a un Pod llamado bar, puedes ejecutar

$ kubectl label pods bar color=red

La sintaxis para las anotaciones es idéntica.

Por defecto, label y annotate no te permitirán sobrescribir una etiqueta existente. Para ello, debes añadir la bandera --overwrite.

Si quieres eliminar una etiqueta, puedes utilizar la <label-name>- sintaxis:

$ kubectl label pods bar color-

Esto eliminará la etiqueta color del Pod llamado bar.

Comandos de depuración

kubectl también pone a tu disposición una serie de comandos para depurar tus contenedores. Puedes utilizar lo siguiente para ver los registros de un contenedor en ejecución:

$ kubectl logs <pod-name>

Si tienes varios contenedores en tu Pod, puedes elegir el contenedor que quieres ver utilizando la bandera -c.

Por defecto, kubectl logs lista los registros actuales y sale. Si, por el contrario, quieres enviar continuamente los registros al terminal sin salir, puedes añadir el indicador de línea de comandos -f (seguir).

También puedes utilizar el comando exec para ejecutar un comando en un contenedor en ejecución:

$ kubectl exec -it <pod-name> -- bash

Esto te proporcionará un intérprete de comandos interactivo dentro del contenedor en ejecución para que puedas realizar más depuraciones.

Si no tienes disponible bash o algún otro terminal dentro de tu contenedor, siempre puedes attach al proceso en ejecución:

$ kubectl attach -it <pod-name>

El comando attach es similar a kubectl logs, pero te permitirá enviar entradas al proceso en ejecución, suponiendo que ese proceso esté configurado para leer de la entrada estándar.

También puedes copiar archivos de a y desde un contenedor utilizando el comando cp:

$ kubectl cp <pod-name>:</path/to/remote/file> </path/to/local/file>

Esto copiará un archivo de un contenedor en ejecución a tu máquina local. También puedes especificar directorios o invertir la sintaxis para copiar un archivo de tu máquina local al contenedor.

Si quieres acceder a tu Pod a través de la red, puedes utilizar el comando port-forward para reenviar el tráfico de red desde la máquina local al Pod. Esto te permite tunelizar de forma segura el tráfico de red hacia contenedores que podrían no estar expuestos en ningún lugar de la red pública. Por ejemplo, el siguiente comando:

$ kubectl port-forward <pod-name> 8080:80

abre una conexión que reenvía el tráfico desde la máquina local en el puerto 8080 al contenedor remoto en el puerto 80.

Nota

También puedes utilizar el comando port-forward con servicios especificando services/<service-name> en lugar de <pod-name>pero ten en cuenta que si haces un reenvío de puertos a un servicio, las peticiones sólo se reenviarán a un único Pod de ese servicio. No pasarán por el equilibrador de carga del servicio.

Si quieres ver los eventos de Kubernetes, puedes utilizar el comando kubectl get events para ver una lista de los 10 últimos eventos de todos los objetos de un espacio de nombres determinado:

$ kubectl get events

También puedes transmitir los eventos a medida que se producen añadiendo --watch al comando kubectl get events. También puedes incluir -A para ver los acontecimientos en todos los espacios de nombres.

Por último, si te interesa saber cómo está utilizando recursos tu clúster, puedes utilizar el comando top para ver la lista de recursos en uso por nodos o Pods. Este comando:

$ kubectl top nodes

mostrará el total de CPU y memoria en uso por los nodos, tanto en unidades absolutas (por ejemplo, núcleos) como en porcentaje de recursos disponibles (por ejemplo, número total de núcleos). Del mismo modo, este comando

$ kubectl top pods

mostrará todos los Pods y su uso de recursos. Por defecto, sólo muestra los Pods del espacio de nombres actual, pero puedes añadir la bandera --all-namespaces para ver el uso de recursos de todos los Pods del clúster.

Estos comandos de top sólo funcionan si se está ejecutando un servidor de métricas en tu clúster. Los servidores de métricas están presentes en casi todos los entornos Kubernetes gestionados y también en muchos entornos no gestionados. Pero si estos comandos fallan, puede deberse a que necesites instalar un servidor de métricas.

Gestión de clústeres

La herramienta kubectl también puede utilizarse para gestionar el propio clúster. La acción más común que realiza la gente para gestionar su clúster es acordonar y vaciar un nodo concreto. Cuando acordonas un nodo, evitas que se programen futuros Pods en esa máquina. Cuando drenas un nodo, eliminas cualquier Pod que se esté ejecutando actualmente en esa máquina. Un buen ejemplo de uso de estos comandos sería eliminar una máquina física para repararla o actualizarla. En ese caso, puedes utilizar kubectl cordon seguido de kubectl drain para retirar de forma segura la máquina del clúster. Una vez reparada la máquina, puedes utilizar kubectl uncordon para volver a activar la programación de Pods en el nodo. No existe el comando undrain; los Pods se programarán de forma natural en el nodo vacío a medida que se vayan creando. Para algo rápido que afecte a un nodo (por ejemplo, el reinicio de una máquina), generalmente no es necesario acordonar o drenar; sólo es necesario si la máquina va a estar fuera de servicio el tiempo suficiente como para que quieras que los Pods se muevan a una máquina diferente.

Autocompletar comandos

kubectl admite la integración con tu shell para activar el autocompletado de comandos y recursos. Dependiendo de tu entorno, puede que necesites instalar el paquete bash-completion antes de activar el autocompletado de comandos. Puedes hacerlo utilizando el gestor de paquetes adecuado:

# macOS
$ brew install bash-completion

# CentOS/Red Hat
$ yum install bash-completion

# Debian/Ubuntu
$ apt-get install bash-completion

Cuando lo instales en macOS, asegúrate de seguir las instrucciones de brew sobre cómo activar la finalización de tabulaciones utilizando tu ${HOME}/.bash_profile.

Una vez instalado bash-completion, puedes activarlo temporalmente para tu terminal utilizando:

$ source <(kubectl completion bash)

Para que esto sea automático en cada terminal, añádelo a tu archivo ${HOME}/.bashrc:

$ echo "source <(kubectl completion bash)" >> ${HOME}/.bashrc

Si utilizas zsh, puedes encontrar instrucciones similares en.

Formas alternativas de ver tu racimo

Además de kubectl, existen otras herramientas para interactuar con tu clúster de Kubernetes. Por ejemplo, existen complementos para varios editores que integran Kubernetes y el entorno del editor, entre ellos:

• Código de Visual Studio

• IntelliJ

• Eclipse

Si utilizas un servicio gestionado de Kubernetes, la mayoría de ellos también cuentan con una interfaz gráfica para Kubernetes integrada en su experiencia de usuario basada en web. Kubernetes gestionado en la nube pública también se integra con sofisticadas herramientas de monitoreo que pueden ayudarte a obtener información sobre el funcionamiento de tus aplicaciones.

También hay varias interfaces gráficas de código abierto para Kubernetes, como Rancher Dashboard y el proyecto Headlamp.

Resumen

kubectl es una potente herramienta para gestionar tus aplicaciones en tu clúster Kubernetes. En este capítulo se han ilustrado muchos de los usos habituales de la herramienta, pero kubectl dispone de una gran cantidad de ayuda integrada. Puedes empezar a ver esta ayuda con:

$ kubectl help

o:

$ kubectl help <command-name>