La mayoría de los complementos de Kubernetes se instalan en un clúster que ya funciona. Cilium es distinto: como CNI, es el networking del clúster, lo que significa que el clúster debe crearse sin una CNI predeterminada que ya ocupe ese papel, o Cilium no tendrá nada que reemplazar. Esta guía cubre esa secuencia usando un clúster local de kind y luego instala Cilium con Helm.

Por qué importa el orden aquí

Un clúster de Kubernetes normalmente arranca con alguna CNI ya instalada que gestiona el networking de los Pods: kindnet en kind, o la predeterminada de un proveedor de nube. Si instalas Cilium sobre una CNI ya activa, terminas con dos plugins de red intentando ser dueños del mismo trabajo, lo cual no funciona. Cilium tiene que ser la única CNI, lo que significa desactivar la predeterminada que de otro modo ocuparía ese papel antes de instalar Cilium, no después.

Crea un clúster con la CNI predeterminada desactivada

En kind, esto es un ajuste de la configuración del clúster, no algo que se desactiva después:

# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  disableDefaultCNI: true
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 30080
        hostPort: 80
      - containerPort: 30443
        hostPort: 443
  - role: worker

kind create cluster --config kind-config.yaml
kubectl get nodes

Espera que todos los nodos aparezcan como NotReady. Es lo esperado, no un fallo: sin una CNI instalada todavía, los nodos no pueden marcarse como listos. Los extraPortMappings no son necesarios para una instalación básica; se configuran de antemano para guías posteriores de esta serie que exponen servicios externamente a través de kind, que no tiene un balanceador de carga en la nube que reparta direcciones enrutables por sí mismo.

Si estás en un servicio de Kubernetes administrado en la nube en lugar de un clúster local, consulta la documentación de ese proveedor para saber cómo crear un clúster sin su CNI predeterminada; el mecanismo difiere según el proveedor, pero el requisito de fondo, que ninguna CNI ocupe el papel antes de que se instale Cilium, es el mismo en todas partes.

Instala los CRD de Gateway API antes que Cilium, si vas a usar Gateway API

Si planeas usar Kubernetes Gateway API con Cilium (se cubre en la siguiente guía), instala ahora sus CustomResourceDefinitions, antes de habilitar el soporte de Gateway API en la propia instalación de Cilium. El controlador de Gateway API de Cilium espera que esos CRD (GatewayClass, Gateway, HTTPRoute y tipos relacionados) ya existan en el clúster:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml

Fija una versión concreta de Gateway API en lugar de descargar siempre la más reciente. Gateway API avanza más rápido de lo que todas las implementaciones pueden seguir, y las notas de versión de Cilium especifican con qué versión de Gateway API se ha probado realmente cada versión de Cilium; usar una versión de CRD más nueva de la que Cilium soporta es una fuente realista de errores confusos que no tienen nada que ver con tu propia configuración.

Instala Cilium con Helm

helm repo add cilium https://helm.cilium.io
helm repo update
helm show values cilium/cilium --version 1.19.0 > cilium-values.yaml

Revisar el archivo completo de valores predeterminados antes de instalar merece los pocos minutos que lleva; es largo, pero es la lista autorizada de lo que se puede configurar. Para un clúster donde también usarás Gateway API, los ajustes que más importan:

# cilium-values.yaml (extracto relevante)
kubeProxyReplacement: true

gatewayAPI:
  enabled: true
  gatewayClass:
    create: false   # crea tu propio GatewayClass de forma explícita, se cubre en la siguiente guía

hubble:
  enabled: true
  relay:
    enabled: true
  ui:
    enabled: true

kubeProxyReplacement: true hace que Cilium asuma por completo el enrutamiento de Services, en eBPF, como se explicó en la guía anterior, en lugar de ejecutarse junto a kube-proxy. Establecer gatewayClass.create en false es una decisión deliberada, no un valor predeterminado que tengas que mantener: significa que tú creas y eres dueño del recurso GatewayClass (útil si lo gestionas mediante una herramienta GitOps como Argo CD o Flux, de modo que se rastree igual que el resto de tu configuración) en lugar de dejar que el chart de Helm cree uno implícitamente. Habilitar Hubble y su interfaz aquí te da las herramientas de observabilidad a las que se hace referencia a lo largo de esta serie, aunque no son necesarias para que Gateway API o BGP funcionen por sí solos.

helm install cilium cilium/cilium \
  --version 1.19.0 \
  --namespace kube-system \
  -f cilium-values.yaml

Confirma la instalación

kubectl get pods -n kube-system -l k8s-app=cilium
kubectl get nodes

Los Pods de Cilium deberían llegar a Running y, cuando lo hagan, los nodos que estaban NotReady justo después de crear el clúster deberían pasar a Ready de inmediato; no hace falta nada más para esa transición, es el propio agente de Cilium arrancando en cada nodo lo que la desbloquea.

Una nota sobre qué puedes cambiar con seguridad más adelante

kubeProxyReplacement y qué CNI está instalada son el tipo de ajustes que conviene acertar en el momento de la instalación; cambiarlos en un clúster en producción es disruptivo y no es algo con lo que experimentar a la ligera. La mayoría del resto de valores, límites de recursos, qué funciones están habilitadas, configuración de Hubble, se pueden ajustar más adelante con helm upgrade sobre el mismo archivo de valores sin ese mismo nivel de cautela.