Saltar al contenido principal

Instalación de Kubernetes

La instalación de Kubernetes en un cluster de nodos puede ser un proceso complejo la primera vez, pero no te preocupes. En esta guía agruparé distintos tutoriales de instalación con distintos motores de contenedores y distintos sistemas operativos. El proceso está muy mascado y probado, pero si tienes algún problema, no dudes en abrir un issue en el repositorio de Github.

Para todas las instalaciones, estos son los requisitos mínimos y los recomendados para un cluster de Kubernetes:

Requisitos mínimos y recomendados para un cluster de Kubernetes

Si prefieres ver la instalación en vídeo, aquí lo tienes: Instalación de Kubernetes

Nota sobre versiones: en los ejemplos usamos Kubernetes v1.33. Puedes instalar otra versión cambiando el número en las URLs del repositorio y en los paquetes. Los repositorios antiguos (apt.kubernetes.io y packages.cloud.google.com) fueron retirados en 2024; usa siempre los repositorios comunitarios pkgs.k8s.io como se muestra a continuación.

Ubuntu Server 24.04 con Containerd​

Nodo maestro​

NOTA: Hasta el paso 11 todos los comandos se ejecutan con el usuario root. A partir de ese paso, se ejecutarán con el usuario normal que se haya creado en el sistema, en mi caso pabpereza.

  1. Actualizar paquetería e instalar requisitos previos:
apt update && apt upgrade -y

apt install curl apt-transport-https git wget software-properties-common lsb-release ca-certificates socat -y
  1. Desactivar swap (el kubelet, por defecto, no arranca con la swap activa):
swapoff -a
sed -i '/swap/s/^\(.*\)$/#\1/g' /etc/fstab # Auto comenta la línea de swap en fstab
  1. Cargar los módulos necesarios del kernel y añadir la configuración de sysctl:
modprobe overlay
modprobe br_netfilter

cat << EOF | tee /etc/sysctl.d/kubernetes.conf
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF
  1. Aplicar la configuración de sysctl y comprobar que se ha aplicado correctamente:
sysctl --system
  1. Instalar las claves gpg de Docker para poder instalar containerd:
mkdir -p /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
| sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  1. Instalar containerd y configurar el daemon para que use cgroups de systemd:
apt update && apt install containerd.io -y

containerd config default | tee /etc/containerd/config.toml

sed -e's/SystemdCgroup = false/SystemdCgroup = true/g' -i /etc/containerd/config.toml

systemctl restart containerd
  1. Instalar las claves gpg de Kubernetes:
mkdir -p -m 755 /etc/apt/keyrings

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key \
| sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
  1. Añadir el repositorio de Kubernetes 1.33 (puedes cambiar la versión modificando las URLs):
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] \
https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /" \
| sudo tee /etc/apt/sources.list.d/kubernetes.list

apt update
  1. Instalar kubeadm, kubelet y kubectl:
apt install -y kubeadm=1.33.1-1.1 kubelet=1.33.1-1.1 kubectl=1.33.1-1.1

apt-mark hold kubelet kubeadm kubectl # Bloquear actualizaciones automáticas

Puedes consultar las versiones exactas disponibles en el repositorio con apt-cache madison kubeadm.

  1. Buscamos nuestra IP y la añadimos al fichero /etc/hosts con el nombre del nodo maestro (en mi caso k8scp, de control plane, pero puedes darle el nombre que prefieras):
echo "<IP> k8scp" >> /etc/hosts

Puedes obtener tu IP con el comando ip a, ip addr show o hostname -i.

  1. Iniciar el cluster con kubeadm. Importante: elige un rango de IPs para los pods que no se solape con la red de tus máquinas ni con otros rangos en uso (de lo contrario tendrás problemas de enrutado difíciles de diagnosticar). Por último, añadimos el nombre del nodo maestro (recuerda usar el del paso anterior) y el puerto 6443:
kubeadm init --pod-network-cidr=<rango de IPs para pods> --control-plane-endpoint=<nombre añadido en el /etc/hosts>:6443

# Por ejemplo:
# kubeadm init --pod-network-cidr=192.168.0.0/16 --control-plane-endpoint=k8scp:6443

Guarda la salida del comando: incluye el kubeadm join que usaremos después para unir los nodos worker.

  1. Configurar kubectl e instalar el autocompletado (desde aquí, con tu usuario normal):
mkdir -p $HOME/.kube

sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config

sudo chown $(id -u):$(id -g) $HOME/.kube/config

sudo apt install bash-completion -y

source <(kubectl completion bash)

echo 'source <(kubectl completion bash)' >> ~/.bashrc # persistir autocompletado

Esto nos permitirá usar el autocompletado en la terminal de bash: si pulsamos tabulador después de escribir kubectl, nos mostrará las opciones disponibles.

  1. Instalar Helm, necesario para instalar algunas aplicaciones en Kubernetes, incluido Cilium (la CNI que vamos a instalar):
curl -fsSL https://packages.buildkite.com/helm-linux/helm-debian/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null

echo "deb [signed-by=/usr/share/keyrings/helm.gpg] https://packages.buildkite.com/helm-linux/helm-debian/any/ any main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list

sudo apt update

sudo apt install helm -y
  1. Instalar Cilium, una CNI (Container Network Interface) que permitirá comunicar los pods entre sí:
helm repo add cilium https://helm.cilium.io/

helm repo update

helm template cilium cilium/cilium --version 1.17.4 \
--namespace kube-system > cilium.yaml

kubectl apply -f cilium.yaml
  1. (Opcional y no recomendado) Si quieres que tu nodo maestro también ejecute pods como si fuera un worker (útil en laboratorios con un solo nodo), elimina su taint:
kubectl taint nodes --all node-role.kubernetes.io/control-plane-

Podríamos reactivar la restricción (taint) para que el nodo maestro no ejecute pods con el comando:

kubectl taint nodes --all node-role.kubernetes.io/control-plane:NoSchedule

En versiones antiguas de Kubernetes (anteriores a la 1.24) existía también el taint node-role.kubernetes.io/master, hoy eliminado en favor de control-plane.

Nodo worker​

Esta parte de la instalación la haremos sobre el servidor que queramos añadir al cluster. En este caso, el nodo worker.

  1. Repetir los pasos 1 a 10 del nodo maestro. IMPORTANTE: en el fichero /etc/hosts debes añadir la IP y el nombre del nodo maestro, exactamente igual que hiciste en él. No lo adaptes a este nodo.

  2. Unir el nodo worker al cluster con el comando que nos proporcionó kubeadm init en el nodo maestro:

kubeadm join <nombre del nodo maestro>:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

El token se puede obtener con el comando kubeadm token list lanzado en el nodo maestro. Si hubiera expirado, se puede generar uno nuevo con kubeadm token create. De hecho, kubeadm token create --print-join-command te genera el comando de unión completo, con token y hash incluidos.

El hash también se puede obtener manualmente con el siguiente comando de openssl, lanzado en el nodo maestro:

openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -hex | sed 's/^.* //'
  1. Comprobar que el nodo worker se ha unido correctamente al cluster. Lanza el siguiente comando en el nodo maestro (es posible que tarde un poco en aparecer como Ready):
kubectl get nodes

Ubuntu Server 20.04 y 22.04 con Containerd​

El proceso es prácticamente idéntico al de Ubuntu 24.04. La única diferencia reseñable es que, en esta variante, usaremos Calico como CNI en lugar de Cilium.

ATENCIÓN: si vienes de tutoriales antiguos, los repositorios apt.kubernetes.io y packages.cloud.google.com ya no existen. Usa los repositorios pkgs.k8s.io como se indica en los pasos 7 y 8 de la sección anterior.

Nodo maestro​

  1. Instalar requisitos previos:
apt install curl apt-transport-https vim git wget gnupg2 \
software-properties-common ca-certificates uidmap -y
  1. Desactivar swap:
swapoff -a
sed -i '/swap/s/^\(.*\)$/#\1/g' /etc/fstab # Auto comenta la línea de swap en fstab
  1. Cargar los módulos necesarios y hacerlos persistentes:
modprobe overlay
modprobe br_netfilter

sudo tee /etc/modules-load.d/k8s.conf <<EOF
overlay
br_netfilter
EOF
  1. Configurar sysctl:
cat << EOF | tee /etc/sysctl.d/kubernetes.conf
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF

sysctl --system # Aplica la configuración
  1. Añadir al fichero /etc/hosts la IP y el nombre de la máquina (ATENCIÓN: pon la IP del nodo maestro si estás configurando un worker). Con esto podremos configurar el cluster usando el nombre de la máquina en vez de la IP:
echo "<IP> <NOMBRE>" >> /etc/hosts
  1. Instalar containerd (mismos pasos 5 y 6 de la sección de Ubuntu 24.04):
mkdir -p /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
| sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

apt update && apt install containerd.io -y
  1. Configurar containerd para que use cgroups de systemd:
mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

sed -e's/SystemdCgroup = false/SystemdCgroup = true/g' -i /etc/containerd/config.toml
  1. Iniciar containerd:
systemctl enable containerd
systemctl restart containerd
  1. Instalar kubeadm, kubelet y kubectl desde los repositorios pkgs.k8s.io:
# Añadir clave y repositorio de Kubernetes
mkdir -p -m 755 /etc/apt/keyrings

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key \
| sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] \
https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /" \
| sudo tee /etc/apt/sources.list.d/kubernetes.list

# Instalar paquetes
apt update && apt install -y kubelet kubeadm kubectl
# Especificar versión concreta, por ejemplo:
#apt install -y kubelet=1.33.1-1.1 kubeadm=1.33.1-1.1 kubectl=1.33.1-1.1

# Bloquear actualizaciones automáticas
apt-mark hold kubelet kubeadm kubectl

# Iniciar kubelet
systemctl enable kubelet
  1. Iniciar el cluster en el nodo maestro:
kubeadm init --pod-network-cidr=<rango de IPs para pods> --control-plane-endpoint=<nombre añadido en /etc/hosts>:6443
  1. Configurar kubectl:
mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config
  1. Instalar la red de pods: Este paso es importante: tendremos que editar el archivo de configuración de la red de pods para que funcione correctamente. En este caso usaremos Calico, pero puedes usar cualquier otra CNI. Debemos especificar en la variable CALICO_IPV4POOL_CIDR el mismo rango de IPs que usamos en el paso 10:
wget https://raw.githubusercontent.com/projectcalico/calico/v3.29.1/manifests/calico.yaml

# Editar el archivo de configuración de Calico descomentando las líneas. Quedando así:
- name: CALICO_IPV4POOL_CIDR
  value: "rango de IPs para pods"

Por ejemplo:

            # The default IPv4 pool to create on startup if none exists. Pod IPs will be
            # chosen from this range. Changing this value after installation will have
            # no effect. This should fall within `--cluster-cidr`.
            - name: CALICO_IPV4POOL_CIDR
              value: "192.168.0.0/16"
  1. Aplicar la red de pods:
kubectl apply -f calico.yaml

Nodo worker​

Repetimos los pasos 1 a 9 del nodo maestro. Esta vez, en el fichero /etc/hosts tenemos que añadir la IP y el nombre del nodo maestro.

  1. Unir el worker al cluster:
kubeadm join <nombre del nodo maestro>:6443 --token <token> --discovery-token-ca-cert-hash sha256:<hash>

El token se puede obtener con el comando kubeadm token list lanzado en el nodo maestro. Si hubiera expirado, se puede generar uno nuevo con kubeadm token create. Recuerda que kubeadm token create --print-join-command te da el comando completo.

El hash se puede obtener con el siguiente comando de openssl, lanzado en el nodo maestro:

openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -hex | sed 's/^.* //'

Volver al índice