Esta sección de la documentación de Kubernetes contiene páginas que
muestran cómo acometer tareas individuales. Cada página de tarea muestra cómo
realizar una única cosa, típicamente proporcionando una pequeña secuencia de comandos.
Interfaz Web de Usuario (Tablero de Control)
Despliega y accede al interfaz web de usuario del Tablero de Control para ayudarte en la gestión y monitorización de las aplicaciones en contenedores de tu clúster de Kubenertes.
Usar la línea de comandos con kubectl
Instala y configura la herramienta de línea de comandos kubectl para gestionar de forma directa tus clústers de Kubernetes.
Configurar Pods y Contenedores
Realiza tareas comunes de configuración para tus Pods y Contenedores.
Ejecutar Aplicaciones
Realiza tareas comunes de gestión de aplicaciones, como actualizaciones de lanzamiento, inyectar información en los pods, y auto-escalado horizontal de pods.
Ejecutar Jobs
Ejecuta Jobs usando procesado paralelo.
Acceder a las Aplicaciones de un Clúster
Configura el balanceo de carga, re-envío de puertos, o configura el cortafuegos o las configuraciones de DNS para acceder a las aplicaciones en un clúster.
Monitorización, Trazas, y Depuración
Configura la monitorización y las trazas para identificar problemas en un clúster o depurar una aplicación en un contenedor.
Acceder a la API de Kubernetes
Aprende varios métodos para acceder directamente a la API de Kubernetes.
Usar TLS
Configura tu aplicación para que confíe y use el Certificado de Autoridad (CA) raíz de tu clúster.
Administrar un Clúster
Aprende tareas comunes de administración de un clúster.
Administrar la Federación
Configura componentes en una federación de clústers.
Gestionar Aplicaciones con Estado
Realiza tareas comunes de gestión de aplicaciones con estado, incluyendo escalado, borrado y depuración de StatefulSets.
Daemons del Clúster
Realiza tareas comunes de gestión de un DaemonSet, como llevar a cabo una actualización de lanzamiento.
Gestionar GPUs
Configura y planifica GPUs de NVIDIA para hacerlas disponibles como recursos a los nodos de un clúster.
Gestionar HugePages
Configura y planifica HugePages como un recurso planificado en un clúster.
Configurar las herramientas de Kubernetes en su computadora.
kubectl
Usa la herramienta de línea de comandos de Kubernetes, kubectl, para desplegar y gestionar aplicaciones en Kubernetes. Usando kubectl, puedes inspeccionar recursos del clúster; crear, eliminar, y actualizar componentes; explorar tu nuevo clúster y arrancar aplicaciones.
Ver Instalar y Configurar kubectl para más información sobre cómo descargar y instalar kubectl y configurarlo para acceder su clúster.
De forma similar a kind, minikube es una herramienta que le permite usar Kubernetes en su máquina local. minikube le permite ejecutar un único nodo en su computadora personal (PC de Windows, macOS y Linux) para que se pueda probar Kubernetes, o para su trabajo de desarrollo.
Se puede seguir la guía oficial de minikube si su enfoque esta instalando la herramienta.
Se debe utilizar la versión de kubectl con una minor versión de diferencia con
tu cluster. Por ejemplo, un cliente con versión v1.31 se puede comunicar
con las siguientes versiones de plano de control v1.30,
v1.31 y v1.32.
Utilizar la última versión compatible de kubectl evita posibles errores.
Instalar kubectl en Linux
Existen los siguientes métodos para instalar kubectl en Linux:
Para descargar una versión específica reemplaza la siguiente parte del comando con la
versión que desea instalar $(curl -L -s https://dl.k8s.io/release/stable.txt)
Por ejemplo, para descargar la versión 1.31.0 en linux x86-64:
Actualiza el índice del paquete apt, luego instala los paquetes necesarios para Kubernetes:
sudo apt-get update
# apt-transport-https may be a dummy package; if so, you can skip that packagesudo apt-get install -y apt-transport-https ca-certificates curl gnupg
Descarga la llave pública firmada para los repositorios de Kubernetes. La misma llave firmada es usada para todos los repositorios por lo que se puede obviar la versión en la URL:
Agregar el repositorio apropiado de Kubernetes. Si quieres una versión de Kubernetes diferente a v1.31,
reemplace v1.31 con la versión deseada en el siguiente comando:
# Esto sobrescribe cualquier configuración existente en el archivo /etc/apt/sources.list.d/kubernetes.listecho'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
Nota:
Para actualizar kubectl a una minor release diferente, se debe reemplazar la versión en el archivo /etc/apt/sources.list.d/kubernetes.list antes de ejecutar apt-get update y apt-get upgrade. Este procedimiento se describe con más detalle en Cambiando el Repositorio de Kubernetes.
Actualiza el índice de apt, luego instala kubectl:
En versiones anteriores a Debian 12 y Ubuntu 22.04 el directorio /etc/apt/keyrings no existe por defecto, puede ser creado usando el comando sudo mkdir -m 755 /etc/apt/keyrings
Agregar Kubernetes al repositorio yum. Si deseas usar una versión de Kubernetes
diferente a v1.31, reemplaza v1.31 con
la versión deseada en el siguiente comando:
# Lo siguiente reemplaza cualquier configuración existente en /etc/yum.repos.d/kubernetes.repocat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.31/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.31/rpm/repodata/repomd.xml.key
EOF
Nota:
Para actualizar kubectl a otra versión, será necesario modificar la versión en /etc/yum.repos.d/kubernetes.repo
antes de ejecutar yum update. Este procedimiento se describe con más detalle en Changing The Kubernetes Package Repository.
Instalar kubectl utilizando yum:
sudo yum install -y kubectl
Agregar Kubernetes al repositorio zypper. Si deseas usar una versión de Kubernetes
diferente a v1.31, reemplaza v1.31 con
la versión deseada en el siguiente comando:
# Lo siguiente reemplaza cualquier configuración existente en /etc/zypp/repos.d/kubernetes.repocat <<EOF | sudo tee /etc/zypp/repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.31/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.31/rpm/repodata/repomd.xml.key
EOF
Nota:
Para actualizar kubectl a otra versión será necesario modificar la versión en /etc/zypp/repos.d/kubernetes.repo
antes de ejecutar zypper update. Este procedimiento se describe con más detalle en Changing The Kubernetes Package Repository.
Para que kubectl encuentre y acceda a un clúster de Kubernetes, necesita un
archivo kubeconfig, que se crea automáticamente cuando creas un clúster usando
kube-up.sh
o implementar con éxito un clúster de Minikube.
De forma predeterminada, la configuración de kubectl se encuentra en ~/.kube/config.
Verifique que kubectl esté configurado correctamente obteniendo el estado del clúster:
kubectl cluster-info
Si ve una respuesta de URL, kubectl está configurado correctamente para acceder a su clúster.
Si ve un mensaje similar al siguiente, kubectl no está configurado correctamente o no puede conectarse a un clúster de Kubernetes.
The connection to the server <server-name:port> was refused - did you specify the right host or port?
Por ejemplo, si tiene la intención de ejecutar un clúster de Kubernetes en su computadora portátil (localmente), primero necesitará instalar una herramienta como Minikube y luego volver a ejecutar los comandos indicados anteriormente.
Si kubectl cluster-info devuelve la respuesta de la URL pero no puede acceder a su clúster, para verificar si está configurado correctamente, use:
kubectl cluster-info dump
Configuraciones opcionales y plugins de kubectl
Habilitar el autocompletado en la shell
Kubectl tiene soporte para autocompletar en Bash, Zsh, Fish y Powershell,
lo que puede agilizar el tipeo.
A continuación están los procedimientos para configurarlo en Bash, Fish y Zsh.
El script de completado de kubectl para Bash se puede generar con el comando kubectl completion bash. Obtener el script de completado en su shell habilita el autocompletado de kubectl.
Sin embargo, el script de completado depende de bash-completion, lo que significa que primero debe instalar este software (puedes probar si tienes bash-completion ya instalado ejecutando type _init_completion).
Instalar bash-complete
El completado de bash es proporcionado por muchos administradores de paquetes (ver aquí). Puedes instalarlo con apt-get install bash-completion o yum install bash-completion, etc.
Los comandos anteriores crean /usr/share/bash-completion/bash_completion, que es el script principal de bash-complete. Dependiendo de su administrador de paquetes, debe obtener manualmente este archivo de perfil en su ~/.bashrc.
Para averiguarlo, recargue su shell y ejecute type _init_completion. Si el comando tiene éxito, ya está configurado; de lo contrario, agregue lo siguiente a su archivo ~/.bashrc:
source /usr/share/bash-completion/bash_completion
Vuelva a cargar su shell y verifique que la finalización de bash esté correctamente instalada escribiendo type _init_completion.
Habilitar el autocompletado de kubectl
Ahora debe asegurarse de que el script de completado de kubectl se obtenga en todas sus sesiones de shell. Hay dos formas de hacer esto:
Obtenga el script de completado en su perfil ~/.bashrc:
Si tiene un alias para kubectl, puede extender el completado del shell para trabajar con ese alias:
echo'alias k=kubectl' >>~/.bashrc
echo'complete -o default -F __start_kubectl k' >>~/.bashrc
Nota:
El código fuente de bash-complete todos los scripts se encuentra en /etc/bash_completion.d.
Ambos enfoques son equivalentes. Después de recargar su shell, el autocompletado de kubectl debería estar funcionando.
Nota:
Se requiere kubectl 1.23 o superior para utilizar el autocompletado de Fish.
El script de autocompletado de Fish puede ser generado con el comando kubectl completion fish. Leyendo este archivo en su Shell habilita el autocompletado de kubectl.
Para hacer esto en todas sus sesiones agregue la siguiente linea a su archivo ~/.config/fish/config.fish:
kubectl completion fish | source
Después de recargar tu shell, el autocompletado para kubectl estará funcionando automáticamente.
El script de completado de kubectl para Zsh se puede generar con el comando kubectl completion zsh. Obtener el script de completado en su shell habilita el autocompletado de kubectl.
Para hacerlo en todas sus sesiones de shell, agregue lo siguiente a su perfil ~/.zshrc:
source <(kubectl completion zsh)
Si tiene un alias para kubectl, puede extender el completado del shell para trabajar con ese alias:
echo'alias k=kubectl' >>~/.zshrc
echo'compdef __start_kubectl k' >>~/.zshrc
Después de recargar su shell, el autocompletado de kubectl debería estar funcionando.
Si recibe un error como complete:13: command not found: compdef,
luego agregue lo siguiente al comienzo de su perfil ~/.zshrc:
autoload -Uz compinit
compinit
Instalar el plugin kubectl convert
Un plugin para la herramienta de línea de comandos de Kubernetes kubectl, que le permite convertir manifiestos entre diferentes versiones de la API. Esto puede ser particularmente útil para migrar manifiestos a una versión no obsoleta de la API con la versión más reciente de Kubernetes.
Para obtener más información, visite migrar a APIs no obsoletas
Descarga la última versión con el siguiente comando:
Se debe utilizar la versión de kubectl con la menor diferencia de versión de respecto de
su clúster. Por ejemplo, un cliente con versión v1.31 se puede comunicar
con los siguientes versiones de plano de control v1.30,
v1.31, and v1.32.
Utilizar la última versión compatible de kubectl evita posibles errores.
Instalar kubectl en macOS
Existen los siguientes métodos para instalar kubectl en macOS:
Para descargar una versión específica, reemplaza la siguiente parte del comando con la
versión que deseas instalar $(curl -L -s https://dl.k8s.io/release/stable.txt)
Por ejemplo, para descargar la versión 1.31.0 en macOS:
Asegúrate que el PATH /usr/local/bin forme parte de las variables de entorno.
Test para asegurar que la versión instalada está actualizada:
kubectl version --client
Se puede utilizar lo siguiente para una vista detallada de la versión:
kubectl version --client --output=yaml
Luego de instalar el plugin puede eliminar los archivos de instalación:
rm kubectl kubectl.sha256
Instalar utilizando Homebrew en macOS
Si está utilizando Homebrew en macOS,
puede instalar kubectl con Homebrew.
Ejecute el comando para instalar:
brew install kubectl
ó
brew install kubernetes-cli
Test para asegurar que la versión instalada está actualizada:
kubectl version --client
Instalar con Macports en macOS
Si esta en macOS y utiliza Macports,
puedes instalar kubectl con Macports.
Ejecute el comando para instalar:
sudo port selfupdate
sudo port install kubectl
Test para asegurar que la versión instalada está actualizada:
kubectl version --client
Verificar la configuración de kubectl
Para que kubectl encuentre y acceda a un clúster de Kubernetes, necesita un
archivo kubeconfig, que se crea automáticamente cuando creas un clúster usando
kube-up.sh
o implementar con éxito un clúster de Minikube.
De forma predeterminada, la configuración de kubectl se encuentra en ~/.kube/config.
Verifique que kubectl esté configurado correctamente obteniendo el estado del clúster:
kubectl cluster-info
Si ve una respuesta de URL, kubectl está configurado correctamente para acceder a su clúster.
Si ve un mensaje similar al siguiente, kubectl no está configurado correctamente o no puede conectarse a un clúster de Kubernetes.
The connection to the server <server-name:port> was refused - did you specify the right host or port?
Por ejemplo, si tiene la intención de ejecutar un clúster de Kubernetes en su computadora portátil (localmente), primero necesitará instalar una herramienta como Minikube y luego volver a ejecutar los comandos indicados anteriormente.
Si kubectl cluster-info devuelve la respuesta de la URL pero no puede acceder a su clúster, para verificar si está configurado correctamente, use:
kubectl cluster-info dump
Configuraciones opcionales y plugins de kubectl
Habilitar el autocompletado en la shell
Kubectl tiene soporte para autocompletar en Bash, Zsh, Fish y Powershell,
lo que puede agilizar el tipeo.
A continuación están los procedimientos para configurarlo en Bash, Fisch y Zsh.
El script de completado de kubectl para Bash se puede generar con kubectl completion bash. Obtener este script en su shell permite el completado de kubectl.
Sin embargo, el script de finalización de kubectl depende de bash-completion que, por lo tanto, debe instalar previamente.
Advertencia:
Hay dos versiones de bash-complete, v1 y v2. V1 es para Bash 3.2 (
que es el predeterminado en macOS), y v2 es para Bash 4.1+. El script de completado de kubectl no funciona correctamente con bash-complete v1 y Bash 3.2. Requiere bash-complete v2 y Bash 4.1+. Por lo tanto, para poder usar correctamente la finalización de kubectl en macOS, debe instalar y usar Bash 4.1+ (instrucciones). Las siguientes instrucciones asumen que usa Bash 4.1+ (es decir, cualquier versión de Bash de 4.1 o posterior).
Actualizar Bash
Las siguientes instrucciones asumen que usa Bash 4.1+. Puede verificar la versión de su Bash ejecutando:
echo$BASH_VERSION
Si es demasiado antiguo, puede instalarlo o actualizarlo usando Homebrew:
brew install bash
Vuelva a cargar su shell y verifique que se esté utilizando la versión deseada:
echo$BASH_VERSION$SHELL
Homebrew generalmente lo instala en /usr/local/bin/bash.
Instalar bash-complete
Nota:
Como se mencionó antes, estas instrucciones asumen que usa Bash 4.1+, lo que significa que instalará bash-completacion v2 (a diferencia de Bash 3.2 y bash-deployment v1, en cuyo caso el completado de kubectl no funcionará).
Puede probar si ya tiene instalado bash-complete v2 con type _init_completion. Si no es así, puede instalarlo con Homebrew:
brew install bash-completion@2
Como se indica en el resultado de este comando, agregue lo siguiente a su archivo ~/.bash_profile:
Si tiene un alias para kubectl, puede extender el completado del shell para trabajar con ese alias:
echo'alias k=kubectl' >>~/.bash_profile
echo'complete -o default -F __start_kubectl k' >>~/.bash_profile
Si instaló kubectl con Homebrew (como se explica aquí), entonces el script de completado de kubectl ya debería estar en /usr/local/etc/bash_completion.d/kubectl. En ese caso, no necesita hacer nada.
Nota:
La instalación de Homebrew de bash-completion v2 genera todos los archivos en el directorio BASH_COMPLETION_COMPAT_DIR, es por eso que los dos últimos métodos funcionan.
En cualquier caso, después de recargar su shell, el completado de kubectl debería estar funcionando.
Nota:
Se requiere kubectl 1.23 o superior para utilizar el autocompletado de Fish.
El script de autocompletado de Fish puede ser generado con el comando kubectl completion fish. Leyendo este archivo en su Shell habilita el autocompletado de kubectl.
Para hacer esto en todas sus sesiones agregue la siguiente linea a su archivo ~/.config/fish/config.fish:
kubectl completion fish | source
Después de recargar tu shell, el autocompletado para kubectl estará funcionando automáticamente.
El script de completado de kubectl para Zsh se puede generar con el comando kubectl completion zsh. Obtener el script de completado en su shell habilita el autocompletado de kubectl.
Para hacerlo en todas sus sesiones de shell, agregue lo siguiente a su perfil ~/.zshrc:
source <(kubectl completion zsh)
Si tiene un alias para kubectl, puede extender el completado del shell para trabajar con ese alias:
echo'alias k=kubectl' >>~/.zshrc
echo'compdef __start_kubectl k' >>~/.zshrc
Después de recargar su shell, el autocompletado de kubectl debería estar funcionando.
Si recibe un error como complete:13: command not found: compdef,
luego agregue lo siguiente al comienzo de su perfil ~/.zshrc:
autoload -Uz compinit
compinit
Instalar el plugin kubectl convert
Un plugin para la herramienta de línea de comandos de Kubernetes kubectl, que le permite convertir manifiestos entre diferentes versiones de la API. Esto puede ser particularmente útil para migrar manifiestos a una versión no obsoleta de la API con la versión más reciente de Kubernetes.
Para obtener más información, visite migrar a APIs no obsoletas
Descarga la última versión con el siguiente comando:
3.1 - Configura un Pod para Usar un Volume como Almacenamiento
En esta página se muestra cómo configurar un Pod para usar un Volume (volumen) como almacenamiento.
El sistema de ficheros de un Contenedor existe mientras el Contenedor exista. Por tanto, cuando un Contenedor es destruido o reiniciado, los cambios realizados en el sistema de ficheros se pierden. Para un almacenamiento más consistente que sea independiente del ciclo de vida del Contenedor, puedes usar un Volume. Esta característica es especialmente importante para aplicaciones que deben mantener un estado, como motores de almacenamiento clave-valor (por ejemplo Redis) y bases de datos.
Antes de empezar
Debes tener un cluster Kubernetes a tu dispocición, y la herramienta de línea de comandos kubectl debe estar configurada. Si no tienes un cluster, puedes crear uno utilizando Minikube,
o puedes utilizar una de las siguientes herramientas en línea:
Para comprobar la versión, introduzca kubectl version.
Configura un Volume para un Pod
En este ejercicio crearás un Pod que ejecuta un único Contenedor. Este Pod tiene un Volume de tipo emptyDir (directorio vacío) que existe durante todo el ciclo de vida del Pod, incluso cuando el Contenedor es destruido y reiniciado. Aquí está el fichero de configuración del Pod:
Verifica que el Contenedor del Pod se está ejecutando y después observa los cambios en el Pod
kubectl get pod redis --watch
La salida debería ser similar a:
NAME READY STATUS RESTARTS AGE
redis 1/1 Running 0 13s
En otro terminal, abre una sesión interactiva dentro del Contenedor que se está ejecutando:
kubectl exec -it redis -- /bin/bash
En el terminal, ve a /data/redis y crea un fichero:
root@redis:/data# cd /data/redis/
root@redis:/data/redis# echo Hello > test-file
En el terminal, lista los procesos en ejecución:
root@redis:/data/redis# apt-get update
root@redis:/data/redis# apt-get install procps
root@redis:/data/redis# ps aux
La salida debería ser similar a:
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
redis 1 0.1 0.1 33308 3828 ? Ssl 00:46 0:00 redis-server *:6379
root 12 0.0 0.0 20228 3020 ? Ss 00:47 0:00 /bin/bash
root 15 0.0 0.0 17500 2072 ? R+ 00:48 0:00 ps aux
En el terminal, mata el proceso de Redis:
root@redis:/data/redis# kill <pid>
donde <pid> es el ID de proceso (PID) de Redis.
En el terminal original, observa los cambios en el Pod de Redis. Eventualmente verás algo como lo siguiente:
NAME READY STATUS RESTARTS AGE
redis 1/1 Running 0 13s
redis 0/1 Completed 0 6m
redis 1/1 Running 1 6m
En este punto, el Contenedor ha sido destruido y reiniciado. Esto es debido a que el Pod de Redis tiene una
restartPolicy (política de reinicio)
de Always (siempre).
Abre un terminal en el Contenedor reiniciado:
kubectl exec -it redis -- /bin/bash
En el terminal, ve a /data/redis y verifica que test-file todavía existe:
root@redis:/data/redis# cd /data/redis/
root@redis:/data/redis# ls
test-file
Elimina el Pod que has creado para este ejercicio:
Además del almacenamiento local proporcionado por emptyDir, Kubernetes soporta diferentes tipos de soluciones de almacenamiento por red, incluyendo los discos gestionados de los diferentes proveedores cloud, como por ejemplo los Persistent Disks en Google Cloud Platform o el Elastic Block Storage de Amazon Web Services. Este tipo de soluciones para volúmenes son las preferidas para el almacenamiento de datos críticos. Kubernetes se encarga de todos los detalles, tal como montar y desmontar los dispositivos en los nodos del clúster. Revisa Volumes para obtener más información.
4 - Administrar Objetos en Kubernetes
Interactuando con el API de Kubernetes aplicando paradigmas declarativo e imperativo.
4.1 - Administración declarativa de Objetos en Kubernetes usando archivos de Configuración
Objetos en Kubernetes pueden ser creados, actualizados y eliminados utilizando
archivos de configuración almacenados en un directorio. Usando el comando
kubectl apply podrá crearlos o actualizarlos de manera recursiva según sea necesario.
Este método retiene cualquier escritura realizada contra objetos activos en el
sistema sin unirlos de regreso a los archivos de configuración. kubectl diff le
permite visualizar de manera previa los cambios que apply realizará.
Debes tener un cluster Kubernetes a tu dispocición, y la herramienta de línea de comandos kubectl debe estar configurada. Si no tienes un cluster, puedes crear uno utilizando Minikube,
o puedes utilizar una de las siguientes herramientas en línea:
La configuración de objetos declarativa requiere una comprensión firme de la
definición y configuración de objetos de Kubernetes. Si aún no lo ha hecho, lea
y complete los siguientes documentos:
A continuación la definición de términos usados en este documento:
archivo de configuración de objeto / archivo de configuración: Un archivo en el
que se define la configuración de un objeto de Kubernetes. Este tema muestra como
utilizar archivos de configuración con kubectl apply. Los archivos de configuración
por lo general se almacenan en un sistema de control de versiones, como Git.
configuración activa de objeto / configuración activa: Los valores de configuración
activos de un objeto, según estén siendo observados por el Clúster. Esta configuración
se almacena en el sistema de almacenamiento de Kubernetes, usualmente etcd.
escritor de configuración declarativo / escritor declarativo: Una persona o
componente de software que actualiza a un objeto activo. Los escritores activos a
los que se refiere este tema aplican cambios a los archivos de configuración de objetos
y ejecutan kubectl apply para aplicarlos.
Como crear objetos
Utilice kubectl apply para crear todos los objetos definidos en los archivos
de configuración existentes en un directorio específico, con excepción de aquellos que
ya existen:
kubectl apply -f <directorio>/
Esto definirá la anotación kubectl.kubernetes.io/last-applied-configuration: '{...}'
en cada objeto. Esta anotación contiene el contenido del archivo de configuración
utilizado para la creación del objeto.
Nota:
Agregue la opción -R para procesar un directorio de manera recursiva.
El siguiente es un ejemplo de archivo de configuración para un objeto:
diff utiliza server-side dry-run,
que debe estar habilitado en el kube-apiserver.
Dado que diff ejecuta una solicitud de apply en el servidor en modo de simulacro (dry-run),
requiere obtener permisos de PATCH, CREATE, y UPDATE.
Vea Autorización Dry-Run
para más detalles.
Despliegue la configuración activa usando kubectl get:
kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml
La salida le mostrará que la anotación kubectl.kubernetes.io/last-applied-configuration
fue escrita a la configuración activa, y es consistente con los contenidos del archivo
de configuración:
kind:Deploymentmetadata:annotations:# ...# Esta es la representación JSON de simple_deployment.yaml# Fue escrita por kubectl apply cuando el objeto fue creadokubectl.kubernetes.io/last-applied-configuration:| {"apiVersion":"apps/v1","kind":"Deployment",
"metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
"spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
"spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
"ports":[{"containerPort":80}]}]}}}}# ...spec:# ...minReadySeconds:5selector:matchLabels:# ...app:nginxtemplate:metadata:# ...labels:app:nginxspec:containers:- image:nginx:1.14.2# ...name:nginxports:- containerPort:80# ...# ...# ...# ...
Como actualizar objetos
También puede usar kubectl apply para actualizar los objetos definidos en un directorio,
aún cuando esos objetos ya existan en la configuración activa. Con este enfoque logrará
lo siguiente:
Definir los campos que aparecerán en la configuración activa.
Eliminar aquellos campos eliminados en el archivo de configuración, de la configuración activa.
Con el propósito de ilustrar, el comando anterior se refiere a un único archivo
de configuración en vez de un directorio.
Despliegue la configuración activa usando kubectl get:
kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml
La salida le mostrará que la anotación kubectl.kubernetes.io/last-applied-configuration
fue escrita a la configuración activa, y es consistente con los contenidos del archivo
de configuración:
kind:Deploymentmetadata:annotations:# ...# Esta es la representación JSON de simple_deployment.yaml# Fue escrita por kubectl apply cuando el objeto fue creadokubectl.kubernetes.io/last-applied-configuration:| {"apiVersion":"apps/v1","kind":"Deployment",
"metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
"spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
"spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
"ports":[{"containerPort":80}]}]}}}}# ...spec:# ...minReadySeconds:5selector:matchLabels:# ...app:nginxtemplate:metadata:# ...labels:app:nginxspec:containers:- image:nginx:1.14.2# ...name:nginxports:- containerPort:80# ...# ...# ...# ...
De manera directa, actualice el campo replicas en la configuración activa usando kubectl scale.
En este caso no se usa kubectl apply:
Despliegue la configuración activa usando kubectl get:
kubectl get deployment nginx-deployment -o yaml
La salida le muestra que el campo replicas ha sido definido en 2, y que la
anotación last-applied-configuration no contiene el campo replicas:
apiVersion:apps/v1kind:Deploymentmetadata:annotations:# ...# note que la anotación no contiene replicas# debido a que el objeto no fue actualizado usando applykubectl.kubernetes.io/last-applied-configuration:| {"apiVersion":"apps/v1","kind":"Deployment",
"metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
"spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
"spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
"ports":[{"containerPort":80}]}]}}}}# ...spec:replicas:2# definido por scale# ...minReadySeconds:5selector:matchLabels:# ...app:nginxtemplate:metadata:# ...labels:app:nginxspec:containers:- image:nginx:1.14.2# ...name:nginxports:- containerPort:80# ...
Actualice el archivo de configuración simple_deployment.yaml para cambiar el campo image
de nginx:1.14.2 a nginx:1.16.1, y elimine el campo minReadySeconds:
apiVersion:apps/v1kind:Deploymentmetadata:name:nginx-deploymentspec:selector:matchLabels:app:nginxtemplate:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.16.1# actualice el valor de imageports:- containerPort:80
Aplique los cambios realizados al archivo de configuración:
Despliegue la configuración activa usando kubectl get:
kubectl get -f https://k8s.io/examples/application/update_deployment.yaml -o yaml
La salida le mostrará los siguientes cambios hechos a la configuración activa:
El campo replicas retiene el valor de 2 definido por kubectl scale.
Esto es posible ya que el campo fue omitido en el archivo de configuración.
El campo image ha sido actualizado de nginx:1.16.1 a nginx:1.14.2.
La anotación last-applied-configuration ha sido actualizada con la nueva imagen.
El campo minReadySeconds ha sido despejado.
La anotación last-applied-configuration ya no contiene el campo minReadySeconds
apiVersion:apps/v1kind:Deploymentmetadata:annotations:# ...# La anotación contiene la imagen acutalizada a nginx 1.11.9,# pero no contiene la actualización de las replicas a 2kubectl.kubernetes.io/last-applied-configuration:| {"apiVersion":"apps/v1","kind":"Deployment",
"metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
"spec":{"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
"spec":{"containers":[{"image":"nginx:1.16.1","name":"nginx",
"ports":[{"containerPort":80}]}]}}}}# ...spec:replicas:2# Definido por `kubectl scale`. Ignorado por `kubectl apply`.# minReadySeconds fue despejado por `kubectl apply`# ...selector:matchLabels:# ...app:nginxtemplate:metadata:# ...labels:app:nginxspec:containers:- image:nginx:1.16.1# Definido `kubectl apply`# ...name:nginxports:- containerPort:80# ...# ...# ...# ...
Advertencia:
No se puede combinar kubectl apply con comandos de configuración imperativa de objetos
como create y replace. Esto se debe a que create
y replace no retienen la anotación kubectl.kubernetes.io/last-applied-configuration
que kubectl apply utiliza para calcular los cambios por realizar.
Como eliminar objetos
Hay dos opciones diferentes para eliminar objetos gestionados por kubectl apply.
Manera recomendada: kubectl delete -f <archivo>
La manera recomendada de eliminar objetos de manera manual es utilizando el comando
imperativo, ya que es más explícito en relación a lo que será eliminado, y es
menos probable que resulte en algo siendo eliminado sin la intención del usuario.
kubectl delete -f <archivo>
Manera alternativa: kubectl apply -f <directorio/> --prune -l etiqueta=deseada
Únicamente utilice esta opción si está seguro de saber lo que está haciendo.
Advertencia:
kubectl apply --prune se encuentra aún en alpha, y cambios incompatibles con versiones previas
podrían ser introducidos en lanzamientos futuros.
Advertencia:
Sea cuidadoso(a) al usar este comando, para evitar eliminar objetos
no intencionalmente.
Como una alternativa a kubectl delete, puede usar kubectl apply para identificar objetos a ser
eliminados, luego de que sus archivos de configuración han sido eliminados del directorio. El commando apply con --prune
consulta a la API del servidor por todos los objetos que coincidan con un grupo de etiquetas, e intenta relacionar
la configuración obtenida de los objetos activos contra los objetos según sus archivos de configuración.
Si un objeto coincide con la consulta, y no tiene un archivo de configuración en el directorio, pero si
tiene una anotación last-applied-configuration, entonces será eliminado.
apply con --prune debería de ser ejecutado únicamente en contra del directorio
raíz que contiene los archivos de configuración. Ejecutarlo en contra de sub-directorios
podría causar que objetos sean eliminados no intencionalmente, si son retornados en la
consulta por selección de etiqueta usando -l <etiquetas> y no existen en el subdirectorio.
Como visualizar un objeto
Puede usar kubectl get con -o yaml para ver la configuración de objetos activos:
kubectl get -f <archivo|url> -o yaml
Como son las diferencias calculadas y unidas por apply
Precaución:
Un patch (parche) es una operación de actualización con alcance a campos específicos
de un objeto, y no al objeto completo. Esto permite actualizar únicamente grupos de campos
específicos en un objeto sin tener que leer el objeto primero.
Cuando kubectl apply actualiza la configuración activa para un objeto, lo hace enviando
una solicitud de patch al servidor de API. El patch define actualizaciones para campos
específicos en la configuración del objeto activo. El comando kubectl apply calcula esta solicitud
de patch usando el archivo de configuración, la configuración activa, y la anotación last-applied-configuration
almacenada en la configuración activa.
Calculando la unión de un patch
El comando kubectl apply escribe los contenidos de la configuración a la anotación
kubectl.kubernetes.io/last-applied-configuration. Esto es usado para identificar aquellos campos
que han sido eliminados de la configuración y deben ser limpiados. Los siguientes pasos
son usados para calcular que campos deben ser eliminados o definidos:
Calculo de campos por eliminar. Estos son los campos presentes en last-applied-configuration pero ausentes en el archivo de configuración.
Calculo de campos por agregar o definir. Estos son los campos presentes en el archivo de configuración, con valores inconsistentes con la configuración activa.
A continuación un ejemplo. Suponga que este es el archivo de configuración para un objeto de tipo Deployment:
apiVersion:apps/v1kind:Deploymentmetadata:name:nginx-deploymentspec:selector:matchLabels:app:nginxtemplate:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.16.1# actualice el valor de imageports:- containerPort:80
También, suponga que esta es la configuración activa para ese mismo objeto de tipo Deployment:
apiVersion:apps/v1kind:Deploymentmetadata:annotations:# ...# tome nota de que la anotación no contiene un valor para replicas# dado que no fue actualizado usando el comando applykubectl.kubernetes.io/last-applied-configuration:| {"apiVersion":"apps/v1","kind":"Deployment",
"metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
"spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
"spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
"ports":[{"containerPort":80}]}]}}}}# ...spec:replicas:2# definidas por scale# ...minReadySeconds:5selector:matchLabels:# ...app:nginxtemplate:metadata:# ...labels:app:nginxspec:containers:- image:nginx:1.14.2# ...name:nginxports:- containerPort:80# ...
Estos son los cálculos de unión que serían realizados por kubectl apply:
Calcular los campos por eliminar, leyendo los valores de last-applied-configuration
y comparándolos con los valores en el archivo de configuración.
Limpiar los campos definidos en null de manera explícita en el archivo de configuración
sin tomar en cuenta si se encuentran presentes en la anotación last-applied-configuration.
En este ejemplo, minReadySeconds aparece en la anotación
last-applied-configuration pero no aparece en el archivo de configuración.
Acción: Limpiar minReadySeconds de la configuración activa.
Calcular los campos por ser definidos, al leer los valores del fichero de configuración
y compararlos con los valores en la configuración activa. En este ejemplo, el valor image
en el archivo de configuración, no coincide con el valor en la configuración activa.
Acción: Definir el campo image en la configuración activa.
Definir el valor de la anotación last-applied-configuration para que sea consistente
con el archivo de configuración.
Unir los resultados de 1, 2 y 3, en una única solicitud de patch para enviar al servidor de API.
Esta es la configuración activa como resultado de esta unión:
apiVersion:apps/v1kind:Deploymentmetadata:annotations:# ...# La anotación contiene la imágen actualizada a nginx 1.11.9,# pero no contiene la actualización a 2 replicaskubectl.kubernetes.io/last-applied-configuration:| {"apiVersion":"apps/v1","kind":"Deployment",
"metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
"spec":{"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
"spec":{"containers":[{"image":"nginx:1.16.1","name":"nginx",
"ports":[{"containerPort":80}]}]}}}}# ...spec:selector:matchLabels:# ...app:nginxreplicas:2# Definido por `kubectl scale`. Ignorado por `kubectl apply`.# minReadySeconds eliminado por `kubectl apply`# ...template:metadata:# ...labels:app:nginxspec:containers:- image:nginx:1.16.1# Definido por `kubectl apply`# ...name:nginxports:- containerPort:80# ...# ...# ...# ...
Como se unen los diferentes tipos de campos
La manera en la que los campos en un archivo de configuración son unidos con la
configuración activa depende del tipo de campo. Existen varios tipos de campos:
primitivo: Campos de cadena de texto (string), enteros (integer), o lógicos (boolean).
Por ejemplo, image y replicas son campos de tipo primitivo. Acción: Reemplazarlos.
mapa, también llamados objeto: Campo de tipo mapa o un tipo
complejo que contiene sub-campos. Por ejemplo, labels,
annotations,spec y metadata son todos mapas. Acción: Unir los elementos o sub-campos.
lista: Campos que contienen una lista de elementos que pueden ser de tipo primitivo o mapa.
Como ejemplos, containers, ports, y args son listas. Acción: Varía.
Cuando kubectl apply actualiza un campo de tipo mapa o lista, típicamente no reemplaza
el campo completo, sino actualiza los sub-elementos individuales.
Por ejemplo, cuando se hace una unión del campo spec en un Deployment, el spec
completo no es reemplazado, por el contrario, únicamente los sub-campos de spec como
replica son comparados y unidos.
Uniendo cambios en campos primitivos
Campos primitivos son limpiados o reemplazados.
Nota:
- determina que "no aplica" debido a que el valor no es utilizado.
Campo en el archivo de configuración
Campo en la configuración activa
Campo en last-applied-configuration
Acción
Si
Si
-
Define el valor en el archivo de configuración como activo.
Si
No
-
Define el valor a la configuración local.
No
-
Si
Elimina de la configuración activa.
No
-
No
No hacer nada. Mantiene el valor activo.
Uniendo cambios en campos de un mapa
Los campos que conjuntamente representan un mapa, son unidos al comparar cada uno de los subcampos o elementos del mapa:
Nota:
- determina que "no aplica" debido a que el valor no es utilizado.
Propiedad en archivo de configuración
Propiedad en configuración activa
Campo en last-applied-configuration
Acción
Si
Si
-
Comparar valores de sub-propiedades.
Si
No
-
Usar configuración local.
No
-
Si
Eliminar de la configuración activa.
No
-
No
No hacer nada. Mantener el valor activo.
Uniendo cambios en campos de tipo lista
El unir cambios en una lista utiliza una de tres posibles estrategias:
Reemplazar la lista si todos sus elementos son primitivos.
Unir elementos individuales en líneas de elementos complejos.
Unir una lista de elementos primitivos.
Se define la estrategia elegida con base en cada campo.
Reemplazar una lista si todos sus elementos son primitivos
Trata la lista como si fuese un campo primitivo. Reemplaza o elimina la lista completa.
Esto preserva el orden de los elementos.
Ejemplo: Usando kubectl apply para actualizar el campo args de un Contenedor en un Pod.
Esto define el valor de args en la configuración activa, al valor en el archivo de configuración.
Cualquier elemento de args que haya sido previamente agregado a la configuración activa se perderá.
El orden de los elementos definidos en args en el archivo de configuración, serán conservados
en la configuración activa.
# valor en last-applied-configurationargs:["a","b"]# valores en archivo de configuraciónargs:["a","c"]# configuración activaargs:["a","b","d"]# resultado posterior a la uniónargs:["a","c"]
Explicación: La unión utilizó los valores del archivo de configuración para definir los nuevos valores de la lista.
Unir elementos individuales en una lista de elementos complejos
Trata la lista como un mapa, y trata cada campo específico de cada elemento como una llave.
Agrega, elimina o actualiza elementos individuales. Esta operación no conserva el orden.
Esta estrategia de unión utiliza una etiqueta especial en cada campo llamada patchMergeKey. La etiqueta
patchMergeKey es definida para cada campo en el código fuente de Kubernetes:
types.go
Al unir una lista de mapas, el campo especificado en patchMergeKey para el elemento dado
se utiliza como un mapa de llaves para ese elemento.
Ejemplo: Utilice kubectl apply para actualizar el campo containers de un PodSpec.
Esto une la lista como si fuese un mapa donde cada elemento utiliza name por llave.
# valor en last-applied-configurationcontainers:- name:nginximage:nginx:1.16- name: nginx-helper-a # llave:nginx-helper-a; será eliminado en resultadoimage:helper:1.3- name: nginx-helper-b # llave:nginx-helper-b; será conservadoimage:helper:1.3# valor en archivo de configuracióncontainers:- name:nginximage:nginx:1.16- name:nginx-helper-bimage:helper:1.3- name: nginx-helper-c # llavel:nginx-helper-c; será agregado en el resultadoimage:helper:1.3# configuración activacontainers:- name:nginximage:nginx:1.16- name:nginx-helper-aimage:helper:1.3- name:nginx-helper-bimage:helper:1.3args:["run"]# Campo será conservado- name: nginx-helper-d # llave:nginx-helper-d; será conservadoimage:helper:1.3# resultado posterior a la unióncontainers:- name:nginximage:nginx:1.16# Elemento nginx-helper-a fue eliminado- name:nginx-helper-bimage:helper:1.3args:["run"]# Campo fue conservado- name:nginx-helper-c# Elemento fue agregadoimage:helper:1.3- name:nginx-helper-d# Elemento fue ignoradoimage:helper:1.3
Explicación:
El contenedor llamado "nginx-helper-a" fué eliminado al no aparecer ningún
contenedor llamado "nginx-helper-a" en el archivo de configuración.
El contenedor llamado "nginx-helper-b" mantiene los cambios existentes en args
en la configuración activa. kubectl apply pudo identificar que
el contenedor "nginx-helper-b" en la configuración activa es el mismo
"nginx-helper-b" que aparece en el archivo de configuración, aún teniendo diferentes
valores en los campos (no existe args en el archivo de configuración). Esto sucede
debido a que el valor del campo patchMergeKey (name) es idéntico en ambos.
El contenedor llamado "nginx-helper-c" fue agregado ya que no existe ningún contenedor
con ese nombre en la configuración activa, pero si existe uno con ese nombre
en el archivo de configuración.
El contendor llamado "nginx-helper-d" fue conservado debido a que no aparece
ningún elemento con ese nombre en last-applied-configuration.
Unir una lista de elementos primitivos
A partir de Kubernetes 1.5, el unir listas de elementos primitivos no es soportado.
Nota:
La etiqueta patchStrategy en types.go es la que
determina cual de las estrategias aplica para cualquier campo en particular.
Para campos de tipo lista, el campo será reemplazado cuando no exista una especificación de patchStrategy.
Valores de campo por defecto
El Servidor de API define algunos campos a sus valores por defecto si no son especificados
al momento de crear un objeto.
Aquí puede ver un archivo de configuración para un Deployment. Este archivo no especifica
el campo strategy:
Despliegue la configuración activa usando kubectl get:
kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml
La salida muestra que el servidor de API definió varios campos con los valores por defecto
en la configuración activa. Estos campos no fueron especificados en el archivo de
configuración.
apiVersion:apps/v1kind:Deployment# ...spec:selector:matchLabels:app:nginxminReadySeconds:5replicas:1# valor por defecto definido por apiserverstrategy:rollingUpdate:# valor por defecto definido por apiserver - derivado de strategy.typemaxSurge:1maxUnavailable:1type:RollingUpdate# valor por defecto definido por apiservertemplate:metadata:creationTimestamp:nulllabels:app:nginxspec:containers:- image:nginx:1.14.2imagePullPolicy:IfNotPresent# valor por defecto definido por apiservername:nginxports:- containerPort:80protocol:TCP# valor por defecto definido por apiserverresources:{}# valor por defecto definido por apiserverterminationMessagePath:/dev/termination-log# valor por defecto definido por apiserverdnsPolicy:ClústerFirst# valor por defecto definido por apiserverrestartPolicy:Always# valor por defecto definido por apiserversecurityContext:{}# valor por defecto definido por apiserverterminationGracePeriodSeconds:30# valor por defecto definido por apiserver# ...
En una solicitud de patch, los campos definidos a valores por defecto no son redefinidos a excepción
de cuando hayan sido limpiados de manera explícita como parte de la solicitud de patch. Esto puede
causar comportamientos no esperados para campos cuyo valor por defecto es basado en los valores
de otros campos. Cuando el otro campo ha cambiado, el valor por defecto de ellos no será actualizado
de no ser que sean limpiados de manera explícita.
Por esta razón, se recomienda que algunos campos que reciben un valor por defecto del
servidor sean definidos de manera explícita en los archivos de configuración, aun cuando
el valor definido sea idéntico al valor por defecto. Esto facilita la identificación
de valores conflictivos que podrían no ser revertidos a valores por defecto por parte
del servidor.
Ejemplo:
# last-applied-configurationspec:template:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.14.2ports:- containerPort:80# archivo de configuraciónspec:strategy:type:Recreate# valor actualizadotemplate:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.14.2ports:- containerPort:80# configuración activaspec:strategy:type:RollingUpdate# valor por defectorollingUpdate:# valor por defecto derivado del campo typemaxSurge :1maxUnavailable:1template:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.14.2ports:- containerPort:80# resultado posterior a la unión - ERROR!spec:strategy:type: Recreate # valor actualizado:incompatible con RollingUpdaterollingUpdate: # valor por defecto:incompatible con "type: Recreate"maxSurge :1maxUnavailable:1template:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.14.2ports:- containerPort:80
Explicación:
El usuario crea un Deployment sin definir strategy.type.
El servidor define strategy.type a su valor por defecto de RollingUpdate y
agrega los valores por defecto a strategy.rollingUpdate.
El usuario cambia strategy.type a Recreate. Los valores de strategy.rollingUpdate
se mantienen en su configuración por defecto, sin embargo el servidor espera que se limpien.
Si los valores de strategy.rollingUpdate hubiesen sido definidos inicialmente en el archivo
de configuración, hubiese sido más claro que requerían ser eliminados.
Apply fallará debido a que strategy.rollingUpdate no fue eliminado. El campo strategy.rollingupdate
no puede estar definido, si el valor de strategy.type es Recreate.
Recomendación: Estos campos deberían de ser definidos de manera explícita en el archivo de configuración:
Etiquetas de Selectors y PodTemplate en cargas de trabajo como Deployment, StatefulSet, Job, DaemonSet,
ReplicaSet, y ReplicationController
Estrategia de rollout para un Deployment
Como limpiar campos definidos a valores por defecto por el servidor, o definidos por otros escritores
Campos que no aparecen en el archivo de configuración pueden ser limpiados si se define su valor
a null y luego se aplica el archivo de configuración.
Para los campos definidos a valores por defecto por el servidor, esto provoca que se reestablezca
a sus valores por defecto.
Como cambiar al propietario de un campo entre un archivo de configuración y un escritor imperativo
Estos son los únicos métodos que debe usar para cambiar un campo individual de un objeto:
Usando kubectl apply.
Escribiendo de manera directa a la configuración activa sin modificar el archivo de configuración:
por ejemplo, usando kubectl scale.
Cambiando al propietario de un campo de un escritor imperativo a un archivo de configuración
Añada el campo al archivo de configuración, y no realice nuevas actualizaciones a la configuración
activa que no sucedan por medio de kubectl apply.
Cambiando al propietario de un archivo de configuración a un escritor imperativo
A partir de Kubernetes 1.5, el cambiar un campo que ha sido definido por medio de un
archivo de configuración para que sea modificado por un escritor imperativo requiere
pasos manuales:
Eliminar el campo del archivo de configuración.
Eliminar el campo de la anotación kubectl.kubernetes.io/last-applied-configuration en el objeto activo.
Cambiando los métodos de gestión
Los objetos en Kubernetes deberían de ser gestionados utilizando únicamente un método
a la vez. El alternar de un método a otro es posible, pero es un proceso manual.
Nota:
Esta bien el usar eliminación imperativa junto a gestión declarativa.
Migrando de gestión imperativa con comandos a configuración declarativa de objetos
El migrar de gestión imperativa utilizando comandos a la gestión declarativa de objetos
requiere varios pasos manuales:
Exporte el objeto activo a un archivo local de configuración:
kubectl get <tipo>/<nombre> -o yaml > <tipo>_<nombre>.yaml
Elimine de manera manual el campo status del archivo de configuración.
Nota:
Este paso es opcional, ya que `kubectl apply` no actualiza el campo `status`
aunque este presente en el archivo de configuración.
Defina la anotación kubectl.kubernetes.io/last-applied-configuration en el objeto:
Modifique el proceso para usar kubectl apply para gestionar el objeto de manera exclusiva.
Definiendo los selectores para el controlador y las etiquetas de PodTemplate
Advertencia:
Se desaconseja encarecidamente actualizar los selectores en controladores.
La forma recomendada es definir una etiqueta única e inmutable para PodTemplate usada
únicamente por el selector del controlador sin tener ningún otro significado semántico.
Desde la versión 1.14, Kubectl también admite la gestión de objetos de Kubernetes utilizando un archivo de kustomización. Para ver Recursos encontrados en un directorio que contiene un archivo de kustomización, ejecuta el siguiente comando:
kubectl kustomize <directorio_de_kustomización>
Para aplicar esos Recursos, ejecuta kubectl apply con la bandera --kustomize o -k :
Debes tener un cluster Kubernetes a tu dispocición, y la herramienta de línea de comandos kubectl debe estar configurada. Si no tienes un cluster, puedes crear uno utilizando Minikube,
o puedes utilizar una de las siguientes herramientas en línea:
Para comprobar la versión, introduzca kubectl version.
Descripción General de Kustomize
Kustomize es una herramienta para personalizar configuraciones de Kubernetes. Ofrece características para manejar archivos de configuración de aplicaciones, tales como:
Generar recursos a partir de otras fuentes.
Establecer campos transversales para los recursos.
Componer y personalizar colecciones de recursos.
Generando Recursos
ConfigMaps y Secrets almacenan configuración o datos sensibles utilizados por otros objetos de Kubernetes, como los Pods. La fuente de verdad de los ConfigMaps o Secrets suele ser externa a un clúster, como un archivo .properties o un archivo de clave SSH.
Kustomize tiene secretGenerator y configMapGenerator, que generan Secret y ConfigMap a partir de archivos o literales.
configMapGenerator
Para generar un ConfigMap desde un archivo, añade una entrada en la lista files en configMapGenerator. Aquí tienes un ejemplo de cómo generar un ConfigMap con un elemento de datos de un archivo .properties:
Para generar un ConfigMap desde un archivo env, añade una entrada en la lista de envs en configMapGenerator. Aquí tienes un ejemplo de cómo generar un ConfigMap con un elemento de datos de un archivo .env:
Cada variable en el archivo .env se convierte en una clave separada en el ConfigMap que generas. Esto es diferente del ejemplo anterior, que incorpora un archivo llamado application.properties (y todas sus entradas) como el valor para una única clave.
Los ConfigMaps también pueden generarse a partir de pares clave-valor literales. Para generar un ConfigMap a partir de una literal clave-valor, añade una entrada a la lista literals en configMapGenerator. Aquí hay un ejemplo de cómo generar un ConfigMap con un elemento de datos de un par clave-valor:
Para usar un ConfigMap generado en un Deployment, refiérelo por el nombre del configMapGenerator. Kustomize reemplazará automáticamente este nombre con el nombre generado.
Este es un ejemplo de un Deployment que utiliza un ConfigMap generado:
Puedes generar Secrets a partir de archivos o pares clave-valor literales. Para generar un Secret a partir de un archivo, añade una entrada a la lista files en secretGenerator. Aquí tienes un ejemplo de cómo generar un Secret con un elemento de datos de un archivo.
Para generar un Secret a partir de una literal clave-valor, añade una entrada a la lista literals en secretGenerator. Aquí tienes un ejemplo de cómo generar un Secret con un elemento de datos de un par clave-valor.
Los ConfigMaps y Secrets generados tienen un sufijo de hash de contenido añadido. Esto asegura que se genere un nuevo ConfigMap o Secret cuando se cambian los contenidos. Para desactivar el comportamiento de añadir un sufijo, se puede utilizar generatorOptions. Además, es posible especificar opciones transversales para los ConfigMaps y Secrets generados.
Es bastante común establecer campos transversales para todos los recursos de Kubernetes en un proyecto.
Algunos casos de uso para establecer campos transversales:
Establecer el mismo espacio de nombres para todos los Recursos
Es común componer un conjunto de recursos en un proyecto y gestionarlos dentro del mismo archivo o directorio.
Kustomize ofrece la composición de recursos desde diferentes archivos y la aplicación de parches u otras personalizaciones a ellos.
Composición
Kustomize admite la composición de diferentes recursos. El campo resources, en el archivo kustomization.yaml, define la lista de recursos para incluir en una configuración. Establece la ruta al archivo de configuración de un recurso en la lista resources.
Aquí hay un ejemplo de una aplicación NGINX compuesta por un Deployment y un Service:
Los Recursos de kubectl kustomize ./ contienen tanto los objetos de Deployment como los de Service.
Personalizando
Los parches pueden usarse para aplicar diferentes personalizaciones a los recursos. Kustomize admite diferentes mecanismos de parcheo a través de patchesStrategicMerge y patchesJson6902. patchesStrategicMerge es una lista de rutas de archivo. Cada archivo debe resolverse en un parche de fusión estratégica. Los nombres dentro de los parches deben coincidir con los nombres de recursos que ya están cargados. Se recomiendan pequeños parches que hagan una sola cosa. Por ejemplo, crear un parche para aumentar el número de réplicas del Deployment y otro parche para establecer el límite de memoria.
No todos los recursos o campos admiten parches de fusión estratégica. Para admitir la modificación de campos arbitrarios en recursos arbitrarios,
Kustomize ofrece la implementacion a través de JSON patchpatchesJson6902.
Para encontrar el Recurso correcto para un parche Json, el grupo, versión, tipo y nombre de ese recurso necesitan ser especificados en kustomization.yaml. Por ejemplo, aumentar el número de réplicas de un objeto de Deployment también se puede hacer a través de patchesJson6902.
Además de los parches, Kustomize también ofrece personalizar imágenes de contenedores o inyectar valores de campos de otros objetos en contenedores sin crear parches. Por ejemplo, puedes cambiar la imagen utilizada dentro de los contenedores especificando la nueva imagen en el campo images en kustomization.yaml.
A veces, la aplicación que se ejecuta en un Pod puede necesitar usar valores de configuración de otros objetos. Por ejemplo, un Pod de un objeto de Deployment necesita leer el nombre del Service correspondiente desde Env o como un argumento de comando.
Dado que el nombre del Service puede cambiar a medida que se agrega namePrefix o nameSuffix en el archivo kustomization.yaml. No se recomienda codificar de manera fija el nombre del Service en el argumento del comando. Para este uso, Kustomize puede inyectar el nombre del Service en los contenedores a través de vars.
Kustomize tiene los conceptos de bases y overlays. Una base es un directorio con un kustomization.yaml, que contiene un conjunto de recursos y personalización asociada. Una base puede ser un directorio local o un directorio de un repositorio remoto, siempre que haya un kustomization.yaml presente dentro. Un overlay es un directorio con un kustomization.yaml que se refiere a otros directorios de kustomization como sus bases. Una base no tiene conocimiento de un overlay y puede ser utilizada en múltiples overlays. Un overlay puede tener múltiples bases y compone todos los recursos de las bases y también puede tener personalizaciones encima de ellos.
Esta base puede ser utilizada en múltiples overlays. Puedes agregar diferentes namePrefix u otros campos transversales en diferentes overlays. Aquí hay dos overlays utilizando la misma base.
Usa --kustomize o -k en comandos de kubectl para reconocer recursos gestionados por
kustomization.yaml.
Nota que -k debe apuntar a un directorio de kustomization, tal como:
kubectl apply -k <kustomization directory>/
Dando como resultado el siguientekustomization.yaml,
Ejecuta el siguiente comando para aplicar el objeto de Deployment dev-my-nginx:
> kubectl apply -k ./
deployment.apps/dev-my-nginx created
Ejecuta uno de los siguientes comandos para ver el objeto de Deployment dev-my-nginx:
kubectl get -k ./
kubectl describe -k ./
Ejecuta el siguiente comando para comparar el objecto Deployment dev-my-nginx contra el
estado en el que estaría el clúster si se aplicara el manifiesto:
kubectl diff -k ./
Ejecuta el siguiente comando para eliminar el objeto de Deployment dev-my-nginx:
4.3 - Administración Imperativa de Objetos de Kubernetes Mediante Archivos de Configuración
Los objetos de Kubernetes se pueden crear, actualizar y eliminar utilizando la herramienta
de línea de comandos kubectl junto con un archivo de configuración de objetos escrito en YAML o JSON.
Este documento explica cómo definir y gestionar objetos utilizando archivos de configuración.
Debes tener un cluster Kubernetes a tu dispocición, y la herramienta de línea de comandos kubectl debe estar configurada. Si no tienes un cluster, puedes crear uno utilizando Minikube,
o puedes utilizar una de las siguientes herramientas en línea:
Puede usar kubectl create -f para crear un objeto a partir de un archivo de configuración.
Consulta la referencia de la API de Kubernetes
para mas detalles.
kubectl create -f <filename|url>
¿Cómo actualizar objetos?
Advertencia:
La actualización de objetos con el comando replace elimina todas las
partes de la especificación no especificadas en el archivo de configuración. Esto no debe
usarse con objetos cuyas especificaciones son administradas
parcialmente por el clúster, como Services de tipo LoadBalancer, donde el
campo externalIPs se administra independientemente del archivo de
configuración. Los campos administrados de forma independiente deben copiarse en
el archivo de configuración para evitar que replace los elimine.
Puedes usar kubectl replace -f para actualizar un objeto en activo de acuerdo con un archivo de configuración.
kubectl replace -f <filename|url>
¿Cómo eliminar objetos?
Puedes usar kubectl delete -f para eliminar un objeto que se describe en un
archivo de configuración.
kubectl delete -f <filename|url>
Nota:
Si el archivo de configuración especifica el campo generateName en la sección metadata en lugar del campo name, no puede eliminar el objeto usando kubectl delete -f <filename|url>. Tendrás que usar otras banderas para eliminar el objeto. Por ejemplo:
Puedes usar kubectl get -f para ver información sobre un objeto que está
descrito en un archivo de configuración.
kubectl get -f <filename|url> -o yaml
La bandera -o yaml especifica que se imprime la configuración completa del objeto. Utiliza kubectl get -h para ver una lista de opciones.
Limitaciones
Los comandos create, replace y delete funcionan bien cuando la configuración de cada objeto está completamente definida y registrada en su archivo de configuración. Sin embargo, cuando se actualiza un objeto activo y las actualizaciones no se combinan en su archivo de configuración las actualizaciones se perderán la próxima vez que se ejecute un replace. Esto puede suceder si un controlador, como un HorizontalPodAutoscaler, realiza actualizaciones directamente a un objeto en activo.
Los comandos create, replace y delete funcionan bien cuando la configuración de cada objeto
está completamente definida y registrada en su archivo
de configuración. Sin embargo, cuando se actualiza un objeto activo y las actualizaciones no se combinan
en su archivo de configuración las actualizaciones se perderán la próxima vez que
se ejecute un replace. Esto puede suceder si un controlador, como un
HorizontalPodAutoscaler, realice actualizaciones directamente a un objeto en activo.
Ejemplo:
Creas un objeto a partir de un archivo de configuración.
Otra fuente actualiza el objeto cambiando algún campo.
Reemplaza el objeto del archivo de configuración. Cambios hechos por
la otra fuente en el paso 2 se pierden.
Si necesitas admitir varios escritores en el mismo objeto, puede usar kubectl apply para administrar el objeto.
Crear y editar un objeto desde una URL sin guardar la configuración
Supongamos que tienes la URL de un archivo de configuración de objeto. Puedes usar
Exporta el objeto en vivo a un archivo de configuración de objeto local.
que apuntan a un archivo de configuración que podría ser modificado por el lector.
kubectl create -f <url> --edit
Migración de comandos imperativos a configuración de objetos imperativos
La migración de comandos imperativos a la configuración de objetos imperativos implica varios pasos manuales.
Exporta el objeto en vivo a un archivo de configuración de objeto local.
kubectl get <kind>/<name> -o yaml > <kind>_<name>.yaml
Elimina manualmente el campo de estado del archivo de configuración del objeto.
Para la gestión posterior de objetos, utiliza replace exclusivamente.
kubectl replace -f <kind>_<name>.yaml
Definiendo selectores de controlador y etiquetas PodTemplate
Advertencia:
Se desaconseja encarecidamente actualizar los selectores de los controladores.
El enfoque recomendado es definir una etiqueta PodTemplate única e inmutable utilizada únicamente por el selector del controlador sin ningún otro significado semántico.
Etiqueta de ejemplo:
selector:matchLabels:controller-selector:"apps/v1/deployment/nginx"template:metadata:*[Referencia de la API de Kubernetes](/docs/reference/generated/kubernetes-api/v1.31/)controller-selector:"apps/v1/deployment/nginx"
4.4 - Actualiza Objetos del API en su sitio (in Place) usando kubectl patch
Usa kubectl patch para actualizar objetos del API de kubernetes sin reemplazarlos. Usa strategic merge patch o JSON merge patch.
Esta tarea muestra cómo utilizar kubectl patch para actualizar un objeto del API sin reemplazarlo.
Los ejercicios de esta tarea demuestran el uso de "strategic merge patch" y "JSON merge patch"
Antes de empezar
Debes tener un cluster Kubernetes a tu dispocición, y la herramienta de línea de comandos kubectl debe estar configurada. Si no tienes un cluster, puedes crear uno utilizando Minikube,
o puedes utilizar una de las siguientes herramientas en línea:
El resultado muestra que el Deployment tiene dos Pods. El 1/1 indica
que cada Pod tiene un contenedor:
NAME READY STATUS RESTARTS AGE
patch-demo-28633765-670qr 1/1 Running 0 23s
patch-demo-28633765-j5qs3 1/1 Running 0 23s
Toma nota de los nombres de los Pods que se están ejecutando. Verás que estos Pods son
terminados y reemplazados posteriormente.
En este punto cada Pod tiene un contenedor que ejecuta una imagen de nginx. Ahora
supón que quieres que cada Pod tenga dos contenedores: uno que ejecute nginx
y otro que ejecute redis.
Crea un archivo llamado patch-file.yaml con el siguiente contenido:
Revisa los Pods asociados con tu Deployment modificado:
kubectl get pods
El resultado muestra que los Pods tienen un nombre distinto a los que se estaban
ejecutando anteriormente. El Deployment terminó los Pods viejos y creo dos nuevos
que cumplen con la especificación actualizada del Deployment. El 2/2 indica que
cada Pod tiene dos contenedores:
NAME READY STATUS RESTARTS AGE
patch-demo-1081991389-2wrn5 2/2 Running 0 1m
patch-demo-1081991389-jmg7b 2/2 Running 0 1m
Un vistazo más de cerca a uno de los Pods del patch-demo:
kubectl get pod <your-pod-name> --output yaml
El resultado muestra que el Pod tienen dos contenedores: uno ejecutando nginx y otro redis:
containers:
- image: redis
...
- image: nginx
...
Notas acerca de strategic merge patch
El patch que hiciste en el ejercicio anterior se llama strategic merge patch.
Toma en cuenta que el path no reemplazó la lista containers. Sino que agregó
un contenedor nuevo a la lista. En otras palabras, la lista en el patch fue agregada
a la lista ya existente. Esto no es lo que pasa siempre que se utiliza strategic merge patch
en una lista. En algunos casos la lista existente podría ser reemplazada en lugar de unir ambas.
Con strategic merge patch, la lista existente puede ser reemplazada o unida con la nueva
dependiendo de la estrategia de patch. La estrategia de patch se especifica en el valor de la clave
patchStrategyen un campo tag del código fuente de Kubernetes. Por ejemplo el
campo Containers de la struct PodSpec tiene un valor de merge en su clave patchStrategy:
También puedes consultar la estrategia de patch en
OpenApi spec:
"io.k8s.api.core.v1.PodSpec": {...,"containers": {"description": "List of containers belonging to the pod. ...."},"x-kubernetes-patch-merge-key": "name","x-kubernetes-patch-strategy": "merge"}
Toma en cuenta que la lista de tolerations en el PodSpec fue reemplazada, no unida.
Esto es porque el campo de Tolerations del PodSpec no tiene una clave patchStrategy en su campo de tag.
por lo tanto strategic merge patch utiliza la estrategia de patch por defecto, la cual es replace.
type PodSpec struct {
... Tolerations []Toleration `json:"tolerations,omitempty" protobuf:"bytes,22,opt,name=tolerations"`...}
Usa JSON merge patch para actualizar un Deployment
Con JSON merge patch, si quieres actualizar una lista
tienes que especificar la lista nueva en su totalidad
y reemplazar la lista existente con la lista nueva.
El comando kubectl patch tiene un parámetro type que acepta los siguientes valores:
La lista containers que especificaste en el patch solo tiene un contenedor.
el resultado muestra que tu lista con un contenedor reemplazó a la lista containers preexistente.
En el resultado se puede ver que los Pods existentes fueron terminados y se
crearon Pods nuevos. El 1/1 indica que cada Pod nuevo esta ejecutando un solo
contenedor.
NAME READY STATUS RESTARTS AGE
patch-demo-1307768864-69308 1/1 Running 0 1m
patch-demo-1307768864-c86dc 1/1 Running 0 1m
Usa strategic merge patch para actualizar un Deployment utilizando la estrategia retainKeys
Aquí esta el archivo de configuración para un Deployment que usa la estrategia RollingUpdate:
En el resultado se puede ver que no es posible definir el type como Recreate cuando hay un value definido para spec.strategy.rollingUpdate:
The Deployment "retainkeys-demo" is invalid: spec.strategy.rollingUpdate: Forbidden: may not be specified when strategy `type` is 'Recreate'
La forma para quitar el valor para spec.strategy.rollingUpdate al momento de cambiar el valor type es usar la estrategia retainKeys para el strategic merge.
Crea otro archivo llamado patch-file-retainkeys.yaml con el siguiente contenido:
spec:strategy:$retainKeys:- typetype:Recreate
Con este Patch definimos que solo queremos conservar la clave type del objeto strategy. Por lo tanto la clave rollingUpdate será eliminada durante la operación de modificación.
Modifica tu Deployment de nuevo con este nuevo Patch:
kubectl get deployment retainkeys-demo --output yaml
El resultado muestra que el objeto strategy en el Deployment ya no contiene la clave rollingUpdate:
spec:strategy:type:Recreatetemplate:
Notas acerca de strategic merge patch utilizando la estrategia retainKeys
La modificación realizada en el ejercicio anterior tiene el nombre de strategic merge patch con estrategia retainKeys. Este método introduce una
nueva directiva $retainKeys que tiene las siguientes estrategias:
Contiene una lista de strings.
Todos los campos que necesiten ser preservados deben estar presentes en la lista $retainKeys.
Todos los campos que estén presentes serán combinados con el objeto existente.
Todos los campos faltantes serán removidos o vaciados al momento de la modificación.
Todos los campos en la lista $retainKeys deberán ser un superconjunto o idéntico a los campos presentes en el Patch.
La estrategia retainKeys no funciona para todos los objetos. Solo funciona cuando el valor de la key patchStrategyen el campo tag de el código fuente de
Kubernetes contenga retainKeys. Por ejemplo, el campo Strategy del struct DeploymentSpec tiene un valor de retainKeys en su tag patchStrategy
También puedes revisar la estrategia retainKeys en la especificación de OpenApi:
"io.k8s.api.apps.v1.DeploymentSpec": {...,"strategy": {"$ref": "#/definitions/io.k8s.api.apps.v1.DeploymentStrategy","description": "The deployment strategy to use to replace existing pods with new ones.","x-kubernetes-patch-strategy": "retainKeys"},....}
Actualiza la cantidad de réplicas de un objeto utilizando kubectl patch con --subresource
FEATURE STATE:Kubernetes v1.24 [alpha]
La bandera --subresource=[subresource-name] es utilizada con comandos de kubectl como get,
patch y replace para obtener y actualizar los subrecursos status y scale de los recursos
(aplicable para las versiones de kubectl de v1.24 en adelante). Esta bandera se utiliza con
todos los recursos del API (incluidos en k8s o CRs) que tengan los subrecursos status o scale.
Deployment es un ejemplo de un objeto con estos subrecursos.
A continuación se muestra un ejemplo de un Deployment con dos réplicas:
apiVersion:apps/v1# Usa apps/v1beta2 para versiones anteriores a 1.9.0kind:Deploymentmetadata:name:nginx-deploymentspec:selector:matchLabels:app:nginxreplicas:2# indica al controlador que ejecute 2 podstemplate:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.7.9ports:- containerPort:80
Si ejecutas kubectl patch y especificas la bandera --subresource para un recurso que no soporte
un subrecurso en particular, el servidor del API regresará un error 404 Not Found.
Resumen
En este ejercicio utilizaste kubectl patch para cambiar la configuración en ejecución de
un objeto de tipo Deployment. No hubo cambios al archivo de configuración que se utilizó
originalmente para crear el Deployment. Otros comandos utilizados para actualizar objetos del API
incluyen:
kubectl annotate,
kubectl edit,
kubectl replace,
kubectl scale,
y
kubectl apply.
Nota:
Strategic merge patch no tiene soporte para Custom Resources (CRs).
6.1 - Corre una aplicación stateless usando un Deployment
Ésta página enseña como correr una aplicación stateless usando un deployment de Kubernetes.
Objetivos
Crear un deployment de nginx.
Usar kubectl para obtener información acerca del deployment.
Actualizar el deployment.
Antes de empezar
Debes tener un cluster Kubernetes a tu dispocición, y la herramienta de línea de comandos kubectl debe estar configurada. Si no tienes un cluster, puedes crear uno utilizando Minikube,
o puedes utilizar una de las siguientes herramientas en línea:
Su versión de Kubernetes debe ser como mínimo v1.9.
Para comprobar la versión, introduzca kubectl version.
Creando y explorando un nginx deployment
Puedes correr una aplicación creando un deployment de Kubernetes, y puedes describir el deployment en un fichero YAML. Por ejemplo, el siguiente fichero YAML describe un deployment que corre la imágen Docker nginx:1.7.9:
apiVersion:apps/v1# Usa apps/v1beta2 para versiones anteriores a 1.9.0kind:Deploymentmetadata:name:nginx-deploymentspec:selector:matchLabels:app:nginxreplicas:2# indica al controlador que ejecute 2 podstemplate:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.7.9ports:- containerPort:80
Name: nginx-deployment
Namespace: default
CreationTimestamp: Tue, 30 Aug 2016 18:11:37 -0700
Labels: app=nginx
Annotations: deployment.kubernetes.io/revision=1
Selector: app=nginx
Replicas: 2 desired | 2 updated | 2 total | 2 available | 0 unavailable
StrategyType: RollingUpdate
MinReadySeconds: 0
RollingUpdateStrategy: 1 max unavailable, 1 max surge
Pod Template:
Labels: app=nginx
Containers:
nginx:
Image: nginx:1.7.9
Port: 80/TCP
Environment: <none>
Mounts: <none>
Volumes: <none>
Conditions:
Type Status Reason
---- ------ ------
Available True MinimumReplicasAvailable
Progressing True NewReplicaSetAvailable
OldReplicaSets: <none>
NewReplicaSet: nginx-deployment-1771418926 (2/2 replicas created)
No events.
Lista los pods creados por el deployment:
kubectl get pods -l app=nginx
El resultado es similar a esto:
NAME READY STATUS RESTARTS AGE
nginx-deployment-1771418926-7o5ns 1/1 Running 0 16h
nginx-deployment-1771418926-r18az 1/1 Running 0 16h
Muestra información acerca del pod:
kubectl describe pod <pod-name>
donde <pod-name> es el nombre de uno de los pods.
Actualizando el deployment
Puedes actualizar el deployment aplicando un nuevo fichero YAML. El siguiente fichero YAML
especifica que el deployment debería ser actualizado para usar nginx 1.8.
apiVersion:apps/v1# Usa apps/v1beta2 para versiones anteriores a 1.9.0kind:Deploymentmetadata:name:nginx-deploymentspec:selector:matchLabels:app:nginxreplicas:2template:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.8# Actualiza la versión de nginx de 1.7.9 a 1.8ports:- containerPort:80
Comprueba como el deployment crea nuevos pods con la nueva imagen mientras va eliminando los pods con la especificación antigua:
kubectl get pods -l app=nginx
Escalando la aplicación aumentado el número de replicas
Puedes aumentar el número de pods en tu deployment aplicando un nuevo fichero YAML.
El siguiente fichero YAML especifica un total de 4 replicas, lo que significa que el deployment debería tener cuatro pods:
apiVersion:apps/v1# Usa apps/v1beta2 para versiones anteriores a 1.9.0kind:Deploymentmetadata:name:nginx-deploymentspec:selector:matchLabels:app:nginxreplicas:4# Actualiza el número de réplicas de 2 a 4template:metadata:labels:app:nginxspec:containers:- name:nginximage:nginx:1.8ports:- containerPort:80
NAME READY STATUS RESTARTS AGE
nginx-deployment-148880595-4zdqq 1/1 Running 0 25s
nginx-deployment-148880595-6zgi1 1/1 Running 0 25s
nginx-deployment-148880595-fxcez 1/1 Running 0 2m
nginx-deployment-148880595-rwovn 1/1 Running 0 2m
Eliminando un deployment
Elimina el deployment por el nombre:
kubectl delete deployment nginx-deployment
ReplicationControllers
La manera preferida de crear una aplicación con múltiples instancias es usando un Deployment, el cual usa un ReplicaSet. Antes de que Deployment y ReplicaSet fueran introducidos en Kubernetes, aplicaciones con múltiples instancias eran configuradas usando un
ReplicationController.
Esta página muestra cómo escalar un StatefulSet. Escalar un StatefulSet es
incrementar o decrementar el número de réplicas.
Antes de empezar
Los StatefulSets están solamente disponibles en Kubernetes 1.5 o posterior.
Para verificar su versión de Kubernetes puede ejecutar kubectl version.
No todas las aplicaciones que manejan estados escalan correctamente. Si no está seguro sobre si
puede escalar sus StatefulSets, visite los conceptos de StatefulSet
o el tutorial sobre StatefulSet para más información.
Solamente se debe realizar un escalamiento cuando esté lo suficientemente seguro del buen funcionamiento
de su clúster y de las aplicaciones que manejan estados.
Escalando StatefulSets
Uso de kubectl para escalar StatefulSets
Como primer paso, identifica el StatefulSet que deseas escalar.
kubectl get statefulsets <nombre-del-stateful-set>
Si el StatefulSet fue inicialmente creado con kubectl apply,
puedes actualizar .spec.replicas en el manifiesto previamente definido y ahí hacer kubectl apply:
El escalamiento hacia abajo no funciona correctamente
No se puede escalar hacia abajo un StatefulSet cuando alguno de los Pods que administra está
dañado. Desescalar solo tiene lugar después de tener los Pods disponibles.
Si spec.replicas > 1, Kubernetes no puede determinar la razón de un Pod dañado.
Esto puede ser el resultado de una falla permanente o una falla transitoria. Una falla
transitoria puede ser causada por un reinicio necesario para una actualización o mantenimiento.
Si el Pod está dañado con una falla permanente, escalar
sin corregir la falla puede llevarnos a un estado donde el StatefulSet cae en
una cantidad de miembros inferior a la cantidad de replicas que son necesarias para funcionar
correctamente. Esto puede causar que el StatefulSet no este disponible.
Si el Pod está dañado por una falla transitoria y el Pod puede volver a estar disponible nuevamente,
el error transitorio puede interferir con la operación de escalar. Algunas bases de datos
distribuidas tienen errores cuando los nodos se unen y abandonan en el mismo momento. Es mejor
analizar acerca de escalar la operación a nivel de la aplicación y realizar
el escalamiento solamente cuando está seguro que el clúster de la aplicación está
funcionando y en buen estado.
Esta página muestra cómo se debe eliminar un StatefulSet.
Antes de empezar
Se asume que se tiene una aplicación del tipo StatefulSet corriendo en tu clúster.
Borrando un StatefulSet
Se puede eliminar un StatefulSet de la misma manera que se eliminan el resto de los recursos en Kubernetes:
Usa el comando kubectl delete y especifica el StatefulSet, usando su nombre o el archivo con el que fue creado.
Puede suceder que necesites eliminar los servicios headless asociados después de eliminar el StatefulSet.
kubectl delete service <nombre-del-servicio>
Cuando se elimina un StatefulSet utilizando kubectl, el StatefulSet escala a 0.
Todos los Pods que eran parte de esta carga de trabajo son eliminados. Si tú quieres eliminar
solo el StatefulSet y no los Pods utiliza --cascade=orphan. Por ejemplo:
kubectl delete -f <archivo.yaml> --cascade=orphan
Agregando --cascade=orphan al comando kubectl delete, los Pods administrados por el StatefulSet
dejan de pertenecer al StatefulSet cuando es eliminado. Si los pods tienen una
etiqueta app.kubernetes.io/name=MyApp se los puede eliminar de la siguiente manera:
Eliminar los Pods de un StatefulSet no va a eliminar los volúmenes asociados.
Esto es para asegurar que se tiene una oportunidad de copiar los datos fuera del volumen
antes de eliminarlo. Borrar el PVC después de que los pods estén terminados puede disparar
la eliminación del Volumen Persistente que hay detrás dependiendo de la clase de almacenamiento
y la política de reclamo. Nunca debes asumir la capacidad de acceder a un volumen
después de la eliminación del claim.
Nota:
Ten cuidado al borrar un PVC ya que puede llevar una pérdida de datos.
Eliminación completa de un StatefulSet
Para eliminar todo en un StatefulSet, incluyendo los pods asociados,
se puede correr una serie de comandos similares a los siguientes:
En este ejemplo, los Pods tienen la etiqueta app.kubernetes.io/name=MyApp,
sustituye la misma por tu propia etiqueta.
Forzar la eliminación de los Pods de un StatefulSet
Si encuentras algunos pods bloqueados en tu StatefulSet en el estado 'Terminating'
o 'Unknown' por un largo período de tiempo, puede ser que necesites intervenir
manualmente para forzar la eliminación de los pods del apiserver.
Ésta es una tarea potencialmente riesgosa. Visita Forzar eliminación de Pods en StatefulSet
para más detalles.
Esta página muestra cómo eliminar Pods que son parte de un
StatefulSet,
y explica las consideraciones a tener en cuenta al hacerlo.
Antes de empezar
Esta es una tarea bastante avanzada y tiene el potencial de violar algunas de las propiedades
inherentes de StatefulSet.
Antes de proceder, familiarízate con las consideraciones enumeradas a continuación.
Consideraciones de StatefulSet
En la operación normal de un StatefulSet, nunca hay necesidad de eliminar forzosamente un Pod de StatefulSet.
El controlador de StatefulSet es responsable de
crear, escalar y eliminar miembros del StatefulSet. Intenta asegurar que el número especificado
de Pods, desde el ordinal 0 hasta N-1, estén vivos y listos. StatefulSet asegura que, en cualquier momento,
exista como máximo un Pod con una identidad dada, corriendo en un clúster. Esto se refiere a la semántica de
como máximo uno proporcionada por un StatefulSet.
La eliminación manual forzada debe realizarse con precaución, ya que tiene el potencial de violar la
semántica de como máximo uno, inherente a StatefulSet. Los StatefulSets pueden usarse para ejecutar aplicaciones distribuidas y
agrupadas que necesitan una identidad de red estable y almacenamiento estable.
Estas aplicaciones a menudo tienen configuraciones que dependen de un conjunto de un número fijo de
miembros con identidades fijas. Tener múltiples miembros con la misma identidad puede ser desastroso
y puede llevar a pérdida de datos (por ejemplo, escenario de cerebro dividido en sistemas basados en quórum).
Eliminar Pods
Puedes realizar una eliminación de Pod paulatina con el siguiente comando:
kubectl delete pods <pod>
Para que lo anterior conduzca a una terminación paulatina, el Pod no debe especificar un
pod.Spec.TerminationGracePeriodSeconds de 0. La práctica de establecer un
pod.Spec.TerminationGracePeriodSeconds de 0 segundos es insegura y se desaconseja rotundamente
para los Pods de StatefulSet. La eliminación paulatina es segura y garantizará que el Pod
se apague de manera paulatina, antes de que kubelet elimine el nombre en el apiserver.
Un Pod no se elimina automáticamente cuando un nodo no es accesible.
Los Pods que se ejecutan en un Nodo inaccesible entran en el estado 'Terminating' o 'Unknown' después de un
tiempo de espera.
Los Pods también pueden entrar en estos estados cuando el usuario intenta la eliminación paulatina de un Pod
en un nodo inaccesible.
Las únicas formas en que un Pod en tal estado puede ser eliminado del apiserver son las siguientes:
El objeto Node es eliminado (ya sea por ti, o por el Controlador de Nodo).).
Kubelet, en el nodo no responsivo, comienza a responder, mata el Pod y elimina la entrada del apiserver.
Eliminación forzada del Pod por el usuario.
La mejor práctica recomendada es usar el primer o segundo enfoque. Si un nodo está confirmado
como muerto (por ejemplo, desconectado permanentemente de la red, apagado, etc.), entonces elimina
el objeto Node. Si el nodo es afectado de una partición de red, entonces trata de resolver esto
o espera a que se resuelva. Cuando la partición se solucione, kubelet completará la eliminación
del Pod y liberará su nombre en el apiserver.
Normalmente, el sistema completa la eliminación una vez que el Pod ya no se está ejecutando en un nodo, o
el nodo es eliminado por un administrador. Puedes anular esto forzando la eliminación del Pod.
Eliminación Forzosa
Las eliminaciones forzosas no esperan confirmación de kubelet de que el Pod ha sido terminado.
Independientemente de si una eliminación forzosa tiene éxito en matar un Pod, inmediatamente
liberará el nombre del apiserver. Esto permitiría que el controlador de StatefulSet cree un Pod de reemplazo
con esa misma identidad; esto puede llevar a la duplicación de un Pod que aún está en ejecución,
y si dicho Pod todavía puede comunicarse con los otros miembros del StatefulSet,
violará la semántica de como máximo uno que StatefulSet está diseñado para garantizar.
Cuando eliminas forzosamente un Pod de StatefulSet, estás afirmando que el Pod en cuestión nunca
volverá a hacer contacto con otros Pods en el StatefulSet y su nombre puede ser liberado de forma segura para que
se cree un reemplazo.
Si quieres eliminar un Pod de forma forzosa usando la versión de kubectl >= 1.5, haz lo siguiente:
6.5 - Especificando un presupuesto de disrupción para tu aplicación
Ésta pagina enseña como limitar el numero de disrupciones concurrentes que afectan a tu aplicación definiendo presupuestos de disrupción de pods, Pod Disruption Budgets (PDB) en inglés. Estos presupuestos definen el mínimo número de pods que deben estar ejecutándose en todo momento para asegurar la disponibilidad de la aplicación durante operaciones de mantenimiento efectuadas sobre los nodos por los administradores del cluster.
Antes de empezar
Tener permisos de administrador sobre la aplicación que esta corriendo en Kubernetes y requiere alta disponibilidad
Deberías confirmar con el propietario del cluster o proveedor de servicio que respetan Presupuestos de Disrupción para Pods.
Protegiendo una aplicación con un PodDisruptionBudget
Identifica la aplicación que quieres proteger con un PodDisruptionBudget (PDB).
Revisa como afectan las disrupciones a tú aplicación.
Crea un PDB usando un archivo YAML.
Crea el objecto PDB desde el archivo YAML.
Identifica la applicación que quieres proteger
El caso más común es proteger aplicaciones que usan uno de los controladores incorporados
en Kubernetes:
Deployment
Replicationcontrolador
ReplicaSet
StatefulSet
En este caso, toma nota del .spec.selector que utiliza el controlador; el mismo se utilizará en el spec.selector del PDB.
También puedes utilizar PDBs para proteger pods que no estan gestionados por uno de los controladores listados arriba, o agrupaciones arbitrarias de pods, con algunas restricciones descritas en Controladores Arbitrarios y Selectors.
Revisa como afectan las disrupciones a tú aplicación
Decide cuántas instancias de tu aplicación pueden estar fuera de servicio al mismo
tiempo debido a disrupciones voluntarias de corto plazo.
Frontend stateless:
Objetivo: evitar reducir capacidad para servir por mas de 10%.
Solución: usar un PDB que especifica minAvailable 90%.
Aplicación Stateful con una sola instancia:
Objetivo: no terminar esta aplicación sin primero confirmar conmigo.
Posible Solución 1: No usar un PDB y tolerar inactividad ocasional.
Posible Solución 2: Crea un PDB con maxUnavailable=0. Entiende que el operador del cluster debe consultar contigo antes de terminar tu aplicación. Cuando el operador te contacte, prepara tu aplicación para downtime y elimina el PDB para indicar que estas preparado para la disrupción. Crea el PDB de nuevo al terminar la disrupción.
Aplicación Stateful con múltiples instancias como Consul, ZooKeeper, etcd, Redis o MySQL:
Objetivo: no reducir el numero de instancias por debajo del quorum, de lo contrario, las escrituras fallarían.
Posible Solución 1: fijar maxUnavailable a 1 (funciona con diferentes escalas de aplicación).
Posible Solución 2: fijar minAvailable al tamaño del quorum (e.g. 3 cuando hay un total de 5 instancias). (Permite mas disrupciones a la vez.).
Trabajos por lote reiniciables:
Objetivo: El trabajo debe completarse en caso de una interrupción voluntaria.
Posible solución: No cree un PDB. El controlador de Jobs creará un pod de reemplazo.
Especificando un PodDisruptionBudget
Un PodDisruptionBudget tiene tres atributos:
Un label selector .spec.selector para especificar el grupo de
pods donde aplicar el presupuesto. Este campo es requerido.
.spec.minAvailable que es una descripción del número de pods del grupo que deben estar disponibles después del desalojo, incluso en ausencia del pod desalojado. minAvailable puede ser un número absoluto o un porcentaje.
.spec.maxUnavailable (disponible en Kubernetes 1.7 y superior) que es una descripción
del numero de pods del grupo que pueden estar indisponibles despues del desalojo. Puede ser un número absoluto o un porcentaje.
Nota:
Para las versiones 1.8 y anteriores: al crear un PodDisruptionBudget
utilizando la herramienta de línea de comandos kubectl, el campo minAvailable es 1 por defecto si no se especifica minAvailable ni maxUnavailable.
Puedes especificar únicamente un valor para maxUnavailable y minAvailable por PodDisruptionBudget.
maxUnavailable solo se puede usar para controlar el desalojo de pods
que tienen un controlador asociado manejándolos. En los ejemplos a continuación, "réplicas deseadas"
hace referencia al valor 'scale' del controlador que gestiona el grupo de pods seleccionados por el
PodDisruptionBudget.
Ejemplo 1: Con un minAvailable de 5, se permiten los desalojos siempre que dejen
5 o más pods disponibles entre las seleccionadas por el selector del PodDisruptionBudget.
Ejemplo 2: Con un minAvailable del 30%, se permiten los desalojos mientras que al menos 30% de la cantidad de réplicas se mantengan disponibles.
Ejemplo 3: Con un maxUnavailable de 5, se permiten desalojos siempre que haya como máximo 5
réplicas indisponibles entre el número total de réplicas deseadas.
Ejemplo 4: Con un maxUnavailable de 30%, se permiten los desalojos siempre y cuando no más del 30%
de las réplicas esten indisponibles.
En el uso típico, se usaría un solo presupuesto para una colección de pods administrados por
un controlador, por ejemplo, los pods en un solo ReplicaSet o StatefulSet.
Nota:
Un presupuesto de disrupción no garantiza que el número/porcentaje de pods especificado
siempre estarán disponibles. Por ejemplo, un nodo que alberga un
pod del grupo puede fallar cuando el grupo está en el tamaño mínimo
especificados en el presupuesto, lo que hace que el número de pods disponibles este por debajo del tamaño especificado. El presupuesto solo puede proteger contra
desalojos voluntarios, pero no todas las causas de indisponibilidad.
Un maxUnavailable de 0% (o 0) o un minAvailable de 100% (o igual al
número de réplicas) puede prevenir que los nodos sean purgados completamente.
Esto está permitido según la semántica de PodDisruptionBudget.
Puedes encontrar ejemplos de presupuestos de disrupción de pods definidas a continuación. Los ejemplos aplican al grupo de pods que tienen la etiqueta app: zookeeper.
Por ejemplo, si el objeto anterior zk-pdb selecciona los pods de un StatefulSet de tamaño 3, ambas
especificaciones tienen el mismo significado exacto. Se recomienda el uso de maxUnavailable ya que
responde automáticamente a los cambios en el número de réplicas del controlador correspondiente.
Crea el objeto PDB
Puedes crear el objeto PDB con el comando kubectl apply -f mypdb.yaml.
No puedes actualizar objetos PDB. Deben ser eliminados y recreados.
Comprueba el estado del PDB
Utiliza kubectl para comprobar que se ha creado tu PDB.
Suponiendo que en realidad no tengas pods que coincidan con app: zookeeper en su namespace,
entonces verás algo como esto:
kubectl get poddisruptionbudgets
NAME MIN-AVAILABLE ALLOWED-DISRUPTIONS AGE
zk-pdb 2 0 7s
Si hay pods que coinciden (por ejemplo, 3), entonces debes ver algo similar a esto:
kubectl get poddisruptionbudgets
NAME MIN-AVAILABLE ALLOWED-DISRUPTIONS AGE
zk-pdb 2 1 7s
El valor distinto a cero de ALLOWED-DISRUPTIONS significa que el controlador de disrupción ha visto los pods, contó los pods coincidentes, y actualizó el estado del PDB.
Puedes obtener más información sobre el estado de un PDB con este comando:
Por último, los PodDisruptionBudgets también se pueden consultar con kubectl utilizando el nombre corto pdb:
kubectl get pdb
NAME MIN-AVAILABLE ALLOWED-DISRUPTIONS AGE
zk-pdb 20 7s
Controladores y selectors arbitrarios
Puedes omitir esta sección si solo utilizas PDBs con los controladores integrados de aplicaciones (Deployment, Replicationcontrolador, ReplicaSet y StatefulSet), con el selector de PDB coincidiendo con el selector del controlador.
Puedes utilizar un PDB con pods controlados por otro tipo de controlador, por un
"Operator", o pods individuales, pero con las siguientes restricciones:
solo puedes usar .spec.minAvailable, no .spec.maxUnavailable.
solo puedes usar un número entero en .spec.minAvailable, no un porcentaje.
Puedes usar un selector que selecciona un subconjunto o superconjunto de los pods que pertenecen a un controlador incorporado. Sin embargo, cuando hay varios PDB en un namespace, debes tener cuidado de no
crear PDBs cuyos selectores se superponen.
7 - Monitoreo, Logging y Depuración
Configurar el monitoreo y el logging para solucionar problemas de un clúster o depurar una aplicación en contenedores.
A veces las cosas salen mal. Esta guía tiene como objetivo solucionarlas. Tiene
dos secciones:
Depuración de tu aplicación - Útil
para usuarios que están implementando código en Kubernetes y se preguntan por qué no funciona.
Depuración de tu clúster - Útil
para administradores de clústeres y personas cuyo clúster de Kubernetes no funciona correctamente.
También debe comprobar los problemas conocidos del release
usado.
Obteniendo Ayuda
Si ninguna de las guías anteriores resuelve su problema, existen varias formas de obtener ayuda de la comunidad de Kubernetes.
Preguntas
La documentación de este sitio ha sido estructurada para brindar respuestas a una amplia gama de preguntas. Conceptos explican la arquitectura de Kubernetes
y cómo funciona cada componente, mientras Configuración proporciona
instrucciones prácticas para empezar. Tareas muestran cómo
realizar tareas de uso común, y Tutoriales son recorridos más completos de escenarios de desarrollo reales, específicos de la industria o de extremo a extremo. La sección de Referencia proporciona
documentación detallada sobre el Kubernetes API
y las interfaces de línea de comandos (CLIs), tal como kubectl.
¡Ayuda! ¡Mi pregunta no está tratada! ¡Necesito ayuda ahora!
Stack Exchange, Stack Overflow o Server Fault
Si tienes preguntas relacionadas con desarrollo de software para tu aplicación en contenedores,
puedes preguntar en Stack Overflow.
Si tienes preguntas sobre Kubernetes relacionadas con administración de clústeres o configuración,
puedes preguntar en Server Fault.
También hay varios sitios de Stack Exchange que podrían ser el lugar adecuado para hacer preguntas sobre Kubernetes en áreas como
DevOps,
Ingeniería de Software,
o InfoSec.
Es posible que otra persona de la comunidad ya haya hecho una pregunta similar o
pueda ayudar con su problema.
Muchas personas de la comunidad de Kubernetes se reúnen en Kubernetes Slack en el canal #kubernetes-users.
Slack requiere registro; puedes solicitar una invitación, el registro está abierto a todos. No dudes en participar y hacer todas y cada una de las preguntas.
Una vez registrado, ingresa a la Organización de Kubernetes en Slack
a través de tu navegador web o mediante la aplicación dedicada de Slack.
Una vez que estés registrado, explora la creciente lista de canales para diversos temas de
interés. Por ejemplo, las personas nuevas en Kubernetes también pueden querer unirse al canal
#kubernetes-novice. Como otro ejemplo, los desarrolladores deberían unirse al canal
#kubernetes-contributors.
También hay muchos canales en idiomas locales o específicos de cada país. Siéntete libre de unirte a
estos canales para obtener soporte e información localizados:
Antes de presentar un problema, busca problemas existentes para ver si tu problema ya está cubierto.
Si presenta un error, incluya información detallada sobre cómo reproducir el
problema, como por ejemplo:
Versión de Kubernetes: kubectl version
Proveedor de nube, distribución del sistema operativo, configuración de red y versión del contenedor runtime
Pasos para reproducir el problema
7.1 - Solución de Problemas de Aplicaciones
7.1.1 - Depurar Contenedores de Inicialización
Esta página muestra cómo investigar problemas relacionados con la ejecución
de los contenedores de inicialización (init containers). Las líneas de comando del ejemplo de abajo
se refieren al Pod como <pod-name> y a los Init Containers como <init-container-1> e
<init-container-2> respectivamente.
Antes de empezar
Debes tener un cluster Kubernetes a tu dispocición, y la herramienta de línea de comandos kubectl debe estar configurada. Si no tienes un cluster, puedes crear uno utilizando Minikube,
o puedes utilizar una de las siguientes herramientas en línea:
También puedes acceder al estado del Init Container de forma programática mediante
la lectura del campo status.initContainerStatuses dentro del Pod Spec:
kubectl get pod nginx --template '{{.status.initContainerStatuses}}'
Este comando devolverá la misma información que arriba en formato JSON.
Acceder a los logs de los Init Containers
Indica el nombre del Init Container así como el nombre del Pod para
acceder a sus logs.
kubectl logs <pod-name> -c <init-container-2>
Los Init Containers que ejecutan secuencias de línea de comandos muestran los comandos
conforme se van ejecutando. Por ejemplo, puedes hacer lo siguiente en Bash
indicando set -x al principio de la secuencia.
Comprender el estado de un Pod
Un estado de un Pod que comienza con Init: especifica el estado de la ejecución de
un Init Container. La tabla a continuación muestra algunos valores de estado de ejemplo
que puedes encontrar al depurar Init Containers.
Estado
Significado
Init:N/M
El Pod tiene M Init Containers, y por el momento se han completado N.
Init:Error
Ha fallado la ejecución de un Init Container.
Init:CrashLoopBackOff
Un Init Container ha fallado de forma repetida.
Pending
El Pod todavía no ha comenzado a ejecutar sus Init Containers.
PodInitializing o Running
El Pod ya ha terminado de ejecutar sus Init Containers.
7.2 - Solución de Problemas de Clústeres
7.2.1 - Auditoría
La auditoría de Kubernetes proporciona un conjunto de registros cronológicos referentes a la seguridad
que documentan la secuencia de actividades que tanto los usuarios individuales, como
los administradores y otros componentes del sistema ha realizado en el sistema.
Así, permite al administrador del clúster responder a las siguientes cuestiones:
¿qué ha pasado?
¿cuándo ha pasado?
¿quién lo ha iniciado?
¿sobre qué ha pasado?
¿dónde se ha observado?
¿desde dónde se ha iniciado?
¿hacia dónde iba?
El componente Kube-apiserver lleva a cabo la auditoría. Cada petición en cada fase
de su ejecución genera un evento, que se pre-procesa según un cierto reglamento y
se escribe en un backend. Este reglamento determina lo que se audita
y los backends persisten los registros. Las implementaciones actuales de backend
incluyen los archivos de logs y los webhooks.
Cada petición puede grabarse junto con una "etapa" asociada. Las etapas conocidas son:
RequestReceived - La etapa para aquellos eventos generados tan pronto como
el responsable de la auditoría recibe la petición, pero antes de que sea delegada al
siguiente responsable en la cadena.
ResponseStarted - Una vez que las cabeceras de la respuesta se han enviado,
pero antes de que el cuerpo de la respuesta se envíe. Esta etapa sólo se genera
en peticiones de larga duración (ej. watch).
ResponseComplete - El cuerpo de la respuesta se ha completado y no se enviarán más bytes.
Panic - Eventos que se generan cuando ocurre una situación de pánico.
Nota:
La característica de registro de auditoría incrementa el consumo de memoria del servidor API
porque requiere de contexto adicional para lo que se audita en cada petición.
De forma adicional, el consumo de memoria depende de la configuración misma del registro.
Reglamento de Auditoría
El reglamento de auditoría define las reglas acerca de los eventos que deberían registrarse y
los datos que deberían incluir. La estructura del objeto de reglas de auditoría se define
en el audit.k8s.io grupo de API. Cuando se procesa un evento, se compara
con la lista de reglas en orden. La primera regla coincidente establece el "nivel de auditoría"
del evento. Los niveles de auditoría conocidos son:
None - no se registra eventos que disparan esta regla.
Metadata - se registra los metadatos de la petición (usuario que la realiza, marca de fecha y hora, recurso,
verbo, etc.), pero no la petición ni el cuerpo de la respuesta.
Request - se registra los metadatos del evento y el cuerpo de la petición, pero no el cuerpo de la respuesta.
Esto no aplica para las peticiones que no son de recurso.
RequestResponse - se registra los metadatos del evento, y los cuerpos de la petición y la respuesta.
Esto no aplica para las peticiones que no son de recurso.
Es posible indicar un archivo al definir el reglamento en el kube-apiserver
usando el parámetro --audit-policy-file. Si dicho parámetros se omite, no se registra ningún evento.
Nótese que el campo rulesdebe proporcionarse en el archivo del reglamento de auditoría.
Un reglamento sin (0) reglas se considera ilegal.
Abajo se presenta un ejemplo de un archivo de reglamento de auditoría:
apiVersion:audit.k8s.io/v1# Esto es obligatorio.kind:Policy# No generar eventos de auditoría para las peticiones en la etapa RequestReceived.omitStages:- "RequestReceived"rules:# Registrar los cambios del pod al nivel RequestResponse- level:RequestResponseresources:- group:""# Los recursos "pods" no hacen coincidir las peticiones a cualquier sub-recurso de pods,# lo que es consistente con la regla RBAC.resources:["pods"]# Registrar "pods/log", "pods/status" al nivel Metadata- level:Metadataresources:- group:""resources:["pods/log","pods/status"]# No registrar peticiones al configmap denominado "controller-leader"- level:Noneresources:- group:""resources:["configmaps"]resourceNames:["controller-leader"]# No registrar peticiones de observación hechas por "system:kube-proxy" sobre puntos de acceso o servicios- level:Noneusers:["system:kube-proxy"]verbs:["watch"]resources:- group:""# Grupo API baseresources:["endpoints","services"]# No registrar peticiones autenticadas a ciertas rutas URL que no son recursos.- level:NoneuserGroups:["system:authenticated"]nonResourceURLs:- "/api*"# Coincidencia por comodín.- "/version"# Registrar el cuerpo de la petición de los cambios de configmap en kube-system.- level:Requestresources:- group:""# Grupo API baseresources:["configmaps"]# Esta regla sólo aplica a los recursos en el Namespace "kube-system".# La cadena vacía "" se puede usar para seleccionar los recursos sin Namespace.namespaces:["kube-system"]# Registrar los cambios de configmap y secret en todos los otros Namespaces al nivel Metadata.- level:Metadataresources:- group:""# Grupo API baseresources:["secrets","configmaps"]# Registrar todos los recursos en core y extensions al nivel Request.- level:Requestresources:- group:""# Grupo API base- group:"extensions"# La versión del grupo NO debería incluirse.# Regla para "cazar" todos las demás peticiones al nivel Metadata.- level:Metadata# Las peticiones de larga duración, como los watches, que caen bajo esta regla no# generan un evento de auditoría en RequestReceived.omitStages:- "RequestReceived"
Puedes usar un archivo mínimo de reglamento de auditoría para registrar todas las peticiones al nivel Metadata de la siguiente forma:
# Log all requests at the Metadata level.apiVersion:audit.k8s.io/v1kind:Policyrules:- level:Metadata
El perfil de auditoría utilizado por GCE debería servir como referencia para
que los administradores construyeran sus propios perfiles de auditoría.
Backends de auditoría
Los backends de auditoría persisten los eventos de auditoría en un almacenamiento externo.
El Kube-apiserver por defecto proporciona tres backends:
Backend de logs, que escribe los eventos en disco
Backend de webhook, que envía los eventos a una API externa
Backend dinámico, que configura backends de webhook a través de objetos de la API AuditSink.
En todos los casos, la estructura de los eventos de auditoría se define por la API del grupo
audit.k8s.io. La versión actual de la API es
v1.
Nota:
En el caso de parches, el cuerpo de la petición es una matriz JSON con operaciones de parcheado, en vez
de un objeto JSON que incluya el objeto de la API de Kubernetes apropiado. Por ejemplo,
el siguiente cuerpo de mensaje es una petición de parcheado válida para
/apis/batch/v1/namespaces/some-namespace/jobs/some-job-name.
El backend de logs escribe los eventos de auditoría a un archivo en formato JSON.
Puedes configurar el backend de logs de auditoría usando el siguiente
parámetro de kube-apiserver flags:
--audit-log-path especifica la ruta al archivo de log que el backend utiliza para
escribir los eventos de auditoría. Si no se especifica, se deshabilita el backend de logs. - significa salida estándar
--audit-log-maxage define el máximo número de días a retener los archivos de log
--audit-log-maxbackup define el máximo número de archivos de log a retener
--audit-log-maxsize define el tamaño máximo en megabytes del archivo de logs antes de ser rotado
Backend de Webhook
El backend de Webhook envía eventos de auditoría a una API remota, que se supone es la misma API
que expone el kube-apiserver. Puedes configurar el backend de webhook de auditoría usando
los siguientes parámetros de kube-apiserver:
--audit-webhook-config-file especifica la ruta a un archivo con configuración del webhook.
La configuración del webhook es, de hecho, un archivo kubeconfig.
--audit-webhook-initial-backoff especifica la cantidad de tiempo a esperar tras una petición fallida
antes de volver a intentarla. Los reintentos posteriores se ejecutan con retraso exponencial.
El archivo de configuración del webhook usa el formato kubeconfig para especificar la dirección remota
del servicio y las credenciales para conectarse al mismo.
En la versión 1.13, los backends de webhook pueden configurarse dinámicamente.
Procesamiento por lotes
Tanto el backend de logs como el de webhook permiten procesamiento por lotes. Si usamos el webhook como ejemplo,
aquí se muestra la lista de parámetros disponibles. Para aplicar el mismo parámetro al backend de logs,
simplemente sustituye webhook por log en el nombre del parámetro. Por defecto,
el procesimiento por lotes está habilitado en webhook y deshabilitado en log. De forma similar,
por defecto la regulación (throttling) está habilitada en webhook y deshabilitada en log.
--audit-webhook-mode define la estrategia de memoria intermedia (búfer), que puede ser una de las siguientes:
batch - almacenar eventos y procesarlos de forma asíncrona en lotes. Esta es la estrategia por defecto.
blocking - bloquear todas las respuestas del servidor API al procesar cada evento de forma individual.
blocking-strict - igual que blocking, pero si ocurre un error durante el registro de la audtoría en la etapa RequestReceived, la petición completa al apiserver fallará.
Los siguientes parámetros se usan únicamente en el modo batch:
--audit-webhook-batch-buffer-size define el número de eventos a almacenar de forma intermedia antes de procesar por lotes.
Si el ritmo de eventos entrantes desborda la memoria intermedia, dichos eventos se descartan.
--audit-webhook-batch-max-size define el número máximo de eventos en un único proceso por lotes.
--audit-webhook-batch-max-wait define la cantidad máxima de tiempo a esperar de forma incondicional antes de procesar los eventos de la cola.
--audit-webhook-batch-throttle-qps define el promedio máximo de procesos por lote generados por segundo.
--audit-webhook-batch-throttle-burst define el número máximo de procesos por lote generados al mismo tiempo si el QPS permitido no fue usado en su totalidad anteriormente.
Ajuste de parámetros
Los parámetros deberían ajustarse a la carga del apiserver.
Por ejemplo, si kube-apiserver recibe 100 peticiones por segundo, y para cada petición se audita
las etapas ResponseStarted y ResponseComplete, deberías esperar unos ~200
eventos de auditoría generados por segundo. Asumiendo que hay hasta 100 eventos en un lote,
deberías establecer el nivel de regulación (throttling) por lo menos a 2 QPS. Además, asumiendo
que el backend puede tardar hasta 5 segundos en escribir eventos, deberías configurar el tamaño de la memoria intermedia para almacenar hasta 5 segundos de eventos, esto es,
10 lotes, o sea, 1000 eventos.
En la mayoría de los casos, sin embargo, los valores por defecto de los parámetros
deberían ser suficientes y no deberías preocuparte de ajustarlos manualmente.
Puedes echar un vistazo a la siguientes métricas de Prometheus que expone kube-apiserver
y también los logs para monitorizar el estado del subsistema de auditoría:
apiserver_audit_event_total métrica que contiene el número total de eventos de auditoría exportados.
apiserver_audit_error_total métrica que contiene el número total de eventos descartados debido a un error durante su exportación.
Truncado
Tanto el backend de logs como el de webhook permiten truncado. Como ejemplo, aquí se indica la
lista de parámetros disponible para el backend de logs:
audit-log-truncate-enabled indica si el truncado de eventos y por lotes está habilitado.
audit-log-truncate-max-batch-size indica el tamaño máximo en bytes del lote enviado al backend correspondiente.
audit-log-truncate-max-event-size indica el tamaño máximo en bytes del evento de auditoría enviado al backend correspondiente.
Por defecto, el truncado está deshabilitado tanto en webhook como en log; un administrador del clúster debe configurar bien el parámetro audit-log-truncate-enabled o audit-webhook-truncate-enabled para habilitar esta característica.
Backend dinámico
FEATURE STATE:Kubernetes v1.13 [alpha]
En la versión 1.13 de Kubernetes, puedes configurar de forma dinámica los backends de auditoría usando objetos de la API AuditSink.
Para habilitar la auditoría dinámica, debes configurar los siguientes parámetros de apiserver:
--audit-dynamic-configuration: el interruptor principal. Cuando esta característica sea GA, el único parámetro necesario.
--feature-gates=DynamicAuditing=true: en evaluación en alpha y beta.
--runtime-config=auditregistration.k8s.io/v1alpha1=true: habilitar la API.
Cuando se habilita, un objeto AuditSink se provisiona de la siguiente forma:
Para una definición completa de la API, ver AuditSink. Múltiples objetos existirán como soluciones independientes.
Aquellos backends estáticos que se configuran con parámetros en tiempo de ejecución no se ven impactados por esta característica.
Sin embargo, estos backends dinámicos comparten las opciones de truncado del webhook estático, de forma que si dichas opciones se configura con parámetros en tiempo de ejecución, entonces se aplican a todos los backends dinámicos.
Reglamento
El reglamento de AuditSink es diferente del de la auditoría en tiempo de ejecución. Esto es debido a que el objeto de la API sirve para casos de uso diferentes. El reglamento continuará
evolucionando para dar cabida a más casos de uso.
El campo level establece el nivel de auditoría indicado a todas las peticiones. El campo stages es actualmente una lista de las etapas que se permite registrar.
Seguridad
Los administradores deberían tener en cuenta que permitir el acceso en modo escritura de esta característica otorga el modo de acceso de lectura
a toda la información del clúster. Así, el acceso debería gestionarse como un privilegio de nivel cluster-admin.
Rendimiento
Actualmente, esta característica tiene implicaciones en el apiserver en forma de incrementos en el uso de la CPU y la memoria.
Aunque debería ser nominal cuando se trata de un número pequeño de destinos, se realizarán pruebas adicionales de rendimiento para entender su impacto real antes de que esta API pase a beta.
Configuración multi-clúster
Si estás extendiendo la API de Kubernetes mediante la capa de agregación, puedes también
configurar el registro de auditoría para el apiserver agregado. Para ello, pasa las opciones
de configuración en el mismo formato que se describe arriba al apiserver agregado
y configura el mecanismo de ingestión de logs para que recolecte los logs de auditoría.
Cada uno de los apiservers puede tener configuraciones de auditoría diferentes con
diferentes reglamentos de auditoría.
Ejemplos de recolectores de Logs
Uso de fluentd para recolectar y distribuir eventos de auditoría a partir de un archivo de logs
Fluentd es un recolector de datos de libre distribución que proporciona una capa unificada de registros.
En este ejemplo, usaremos fluentd para separar los eventos de auditoría por nombres de espacio:
Instala fluentd, fluent-plugin-forest y fluent-plugin-rewrite-tag-filter en el nodo donde corre kube-apiserver
Nota:
Fluent-plugin-forest y fluent-plugin-rewrite-tag-filter son plugins de fluentd. Puedes obtener detalles de la instalación de estos plugins en el documento [fluentd plugin-management][fluentd_plugin_management_doc].
Crea un archivo de configuración para fluentd:
cat <<'EOF' > /etc/fluentd/config
# fluentd conf runs in the same host with kube-apiserver
<source>
@type tail
# audit log path of kube-apiserver
path /var/log/kube-audit
pos_file /var/log/audit.pos
format json
time_key time
time_format %Y-%m-%dT%H:%M:%S.%N%z
tag audit
</source>
<filter audit>
#https://github.com/fluent/fluent-plugin-rewrite-tag-filter/issues/13
@type record_transformer
enable_ruby
<record>
namespace ${record["objectRef"].nil? ? "none":(record["objectRef"]["namespace"].nil? ? "none":record["objectRef"]["namespace"])}
</record>
</filter>
<match audit>
# route audit according to namespace element in context
@type rewrite_tag_filter
<rule>
key namespace
pattern /^(.+)/
tag ${tag}.$1
</rule>
</match>
<filter audit.**>
@type record_transformer
remove_keys namespace
</filter>
<match audit.**>
@type forest
subtype file
remove_prefix audit
<template>
time_slice_format %Y%m%d%H
compress gz
path /var/log/audit-${tag}.*.log
format json
include_time_key true
</template>
</match>
EOF
Arranca fluentd:
fluentd -c /etc/fluentd/config -vv
Arranca el componente kube-apiserver con las siguientes opciones:
Comprueba las auditorías de los distintos espacios de nombres en /var/log/audit-*.log
Uso de logstash para recolectar y distribuir eventos de auditoría desde un backend de webhook
Logstash es una herramienta de libre distribución de procesamiento de datos en servidor.
En este ejemplo, vamos a usar logstash para recolectar eventos de auditoría a partir de un backend de webhook,
y grabar los eventos de usuarios diferentes en archivos distintos.
cat <<EOF > /etc/logstash/config
input{
http{
#TODO, figure out a way to use kubeconfig file to authenticate to logstash
#https://www.elastic.co/guide/en/logstash/current/plugins-inputs-http.html#plugins-inputs-http-ssl
port=>8888
}
}
filter{
split{
# Webhook audit backend sends several events together with EventList
# split each event here.
field=>[items]
# We only need event subelement, remove others.
remove_field=>[headers, metadata, apiVersion, "@timestamp", kind, "@version", host]
}
mutate{
rename => {items=>event}
}
}
output{
file{
# Audit events from different users will be saved into different files.
path=>"/var/log/kube-audit-%{[event][user][username]}/audit"
}
}
EOF
Comprueba las auditorías en los directorios /var/log/kube-audit-*/audit de los nodos de logstash
Nótese que además del plugin para salida en archivos, logstash ofrece una variedad de salidas adicionales
que permiten a los usuarios enviar la información donde necesiten. Por ejemplo, se puede enviar los eventos de auditoría
al plugin de elasticsearch que soporta búsquedas avanzadas y analíticas.
7.2.2 - Escribiendo Logs con Elasticsearch y Kibana
Este artículo describe cómo configurar un clúster para la ingesta de logs en
Elasticsearch y su posterior visualización
con Kibana, a modo de alternativa a
Stackdriver Logging cuando se utiliza la plataforma GCE.
Nota:
No se puede desplegar de forma automática Elasticsearch o Kibana en un clúster alojado en Google Kubernetes Engine. Hay que desplegarlos de forma manual.
Para utilizar Elasticsearch y Kibana para escritura de logs del clúster, deberías configurar
la siguiente variable de entorno que se muestra a continuación como parte de la creación
del clúster con kube-up.sh:
KUBE_LOGGING_DESTINATION=elasticsearch
También deberías asegurar que KUBE_ENABLE_NODE_LOGGING=true (que es el valor por defecto en la plataforma GCE).
Así, cuando crees un clúster, un mensaje te indicará que la recolección de logs de los daemons de Fluentd
que corren en cada nodo enviará dichos logs a Elasticsearch:
cluster/kube-up.sh
...
Project: kubernetes-satnam
Zone: us-central1-b
... calling kube-up
Project: kubernetes-satnam
Zone: us-central1-b
+++ Staging server tars to Google Storage: gs://kubernetes-staging-e6d0e81793/devel
+++ kubernetes-server-linux-amd64.tar.gz uploaded (sha1 = 6987c098277871b6d69623141276924ab687f89d)
+++ kubernetes-salt.tar.gz uploaded (sha1 = bdfc83ed6b60fa9e3bff9004b542cfc643464cd0)
Looking for already existing resources
Starting master and configuring firewalls
Created [https://www.googleapis.com/compute/v1/projects/kubernetes-satnam/zones/us-central1-b/disks/kubernetes-master-pd].
NAME ZONE SIZE_GB TYPE STATUS
kubernetes-master-pd us-central1-b 20 pd-ssd READY
Created [https://www.googleapis.com/compute/v1/projects/kubernetes-satnam/regions/us-central1/addresses/kubernetes-master-ip].
+++ Logging using Fluentd to elasticsearch
Tanto los pods por nodo de Fluentd, como los pods de Elasticsearch, y los pods de Kibana
deberían ejecutarse en el namespace de kube-system inmediatamente después
de que el clúster esté disponible.
Los pods de fluentd-elasticsearch recogen los logs de cada nodo y los envían a los
pods de elasticsearch-logging, que son parte de un servicio llamado elasticsearch-logging.
Estos pods de Elasticsearch almacenan los logs y los exponen via una API REST.
El pod de kibana-logging proporciona una UI via web donde leer los logs almacenados en
Elasticsearch, y es parte de un servicio denominado kibana-logging.
Los servicios de Elasticsearch y Kibana ambos están en el namespace kube-system
y no se exponen de forma directa mediante una IP accesible públicamente. Para poder acceder a dichos logs,
sigue las instrucciones acerca de cómo Acceder a servicios corriendo en un clúster.
Si tratas de acceder al servicio de elasticsearch-logging desde tu navegador,
verás una página de estado que se parece a la siguiente:
A partir de ese momento, puedes introducir consultas de Elasticsearch directamente en el navegador, si lo necesitas.
Echa un vistazo a la documentación de Elasticsearch
para más detalles acerca de cómo hacerlo.
De forma alternativa, puedes ver los logs de tu clúster en Kibana (de nuevo usando las
instrucciones para acceder a un servicio corriendo en un clúster).
La primera vez que visitas la URL de Kibana se te presentará una página que te pedirá
que configures una vista de los logs. Selecciona la opción de valores de serie temporal
y luego @timestamp. En la página siguiente selecciona la pestaña de Discover
y entonces deberías ver todos los logs. Puedes establecer el intervalo de actualización
en 5 segundos para refrescar los logs de forma regular.
Aquí se muestra una vista típica de logs desde el visor de Kibana:
Siguientes pasos
¡Kibana te permite todo tipo de potentes opciones para explorar tus logs! Puedes encontrar
algunas ideas para profundizar en el tema en la documentación de Kibana.
7.2.3 - Pipeline de métricas de recursos
Desde Kubernetes 1.8, las métricas de uso de recursos, tales como el uso de CPU y memoria del contenedor,
están disponibles en Kubernetes a través de la API de métricas. Estas métricas son accedidas directamente
por el usuario, por ejemplo usando el comando kubectl top, o usadas por un controlador en el cluster,
por ejemplo el Horizontal Pod Autoscaler, para la toma de decisiones.
La API de Métricas
A través de la API de métricas, Metrics API en inglés, puedes obtener la cantidad de recursos usados
actualmente por cada nodo o pod. Esta API no almacena los valores de las métricas,
así que no es posible, por ejemplo, obtener la cantidad de recursos que fueron usados por
un nodo hace 10 minutos.
La API de métricas está completamente integrada en la API de Kubernetes:
se expone a través del mismo endpoint que las otras APIs de Kubernetes bajo el path /apis/metrics.k8s.io/
ofrece las mismas garantías de seguridad, escalabilidad y confiabilidad
La API está definida en el repositorio k8s.io/metrics. Puedes encontrar
más información sobre la API ahí.
Nota:
La API requiere que el servidor de métricas esté desplegado en el clúster. En otro caso no estará
disponible.
Servidor de Métricas
El Servidor de Métricas es un agregador
de datos de uso de recursos de todo el clúster.
A partir de Kubernetes 1.8, el servidor de métricas se despliega por defecto como un objeto de
tipo Deployment en clústeres
creados con el script kube-up.sh. Si usas otro mecanismo de configuración de Kubernetes, puedes desplegarlo
usando los yamls de despliegue
proporcionados. Está soportado a partir de Kubernetes 1.7 (más detalles al final).
El servidor reune métricas de la Summary API, que es expuesta por el Kubelet en cada nodo.
El servidor de métricas se añadió a la API de Kubernetes utilizando el
Kubernetes aggregator introducido en Kubernetes 1.7.
Puedes aprender más acerca del servidor de métricas en el documento de diseño.
