De Cero a Kubernetes Parte 2: Bootstrap del Cluster — Namespaces, Ingress, cert-manager y Storage

Serie: De Cero a Kubernetes — Parte 1 · Parte 2 · Parte 3 · Parte 4 · Parte 5

En la Parte 1 construimos un cluster Kubernetes con Terraform y kubeadm. Tres nodos listos pero vacíos. Hoy lo convertimos en una plataforma utilizable: tráfico externo con TLS automático, storage para bases de datos, namespaces que separan entornos, y permisos que evitan que un deploy en staging borre producción.

Todo con Terraform. Cero kubectl apply manual.

¿Por qué Terraform para el bootstrap y no ArgoCD?

Esta es una pregunta que recibimos mucho. La respuesta está en el orden de dependencias:

┌─────────────────────────────────────────┐
│  Terraform (infraestructura + bootstrap) │
│  VMs, redes, kubeadm, namespaces,       │
│  ingress, cert-manager, storage, RBAC   │
│  ↓                                      │
│  Terraform instala ArgoCD               │
│  ↓                                      │
│  ArgoCD maneja las aplicaciones         │
│  (backend, frontends, DB)               │
└─────────────────────────────────────────┘

Terraform gestiona lo que ArgoCD necesita para existir. Una vez que ArgoCD está corriendo, le pasamos el control de las aplicaciones. Si intentas usar ArgoCD para bootstrappear el ingress controller que necesita ArgoCD para exponer su propia UI, tienes un problema circular. Terraform rompe ese ciclo.

Lo que construiremos hoy

┌──────────────────────────────────────────────┐
│                 INTERNET                      │
│                    │                          │
│         ┌──────────▼──────────┐               │
│         │  nginx ingress      │               │
│         │  (NodePort 30080)   │               │
│         │  + cert-manager     │               │
│         │  + Let's Encrypt    │               │
│         └──────────┬──────────┘               │
│                    │                          │
│    ┌───────────────┼───────────────┐          │
│    ▼               ▼               ▼          │
│ ┌────────┐  ┌──────────┐  ┌──────────┐       │
│ │production│ │ staging  │  │infrastructure│    │
│ │namespace │ │namespace │  │ namespace  │    │
│ └────────┘  └──────────┘  └──────────┘       │
│                                                │
│ Storage: local-path-provisioner (PVC)          │
│ RBAC: ServiceAccounts + Roles                 │
└──────────────────────────────────────────────┘

Paso 1: Conectar Terraform al cluster

Necesitamos el provider de Kubernetes apuntando al cluster que creamos en la Parte 1:

# providers.tf (agregar al main.tf de la Parte 1)
provider "kubernetes" {
  host                   = "https://${hcloud_server.control_plane.ipv4_address}:6443"
  client_certificate     = base64decode(data.local_file.kubeconfig.content)
  client_key             = base64decode(data.local_file.kubeconfig.content)
  cluster_ca_certificate = base64decode(data.local_file.kubeconfig.content)
  # ⚠️ En producción: usar data source apropiado para extraer
  # cada campo del kubeconfig. Aquí simplificamos con un
  # provisioner que copia el archivo del control-plane.
}

provider "helm" {
  kubernetes {
    host                   = "https://${hcloud_server.control_plane.ipv4_address}:6443"
    client_certificate     = base64decode(var.k8s_client_cert)
    client_key             = base64decode(var.k8s_client_key)
    cluster_ca_certificate = base64decode(var.k8s_ca_cert)
  }
}

Nota práctica: Para este tutorial, extraemos los certificados del kubeconfig con un local_file data source. En producción, usarías un backend de secretos (Vault, AWS Secrets Manager) y los inyectarías como variables de entorno.

Paso 2: Namespaces — la base de todo

Los namespaces son la unidad de aislamiento lógico en Kubernetes. Sin ellos, todos los recursos viven en default y el desorden es garantía de problemas:

resource "kubernetes_namespace" "production" {
  metadata {
    name = "production"
    labels = {
      environment = "production"
      managed-by  = "terraform"
    }
  }
}

resource "kubernetes_namespace" "staging" {
  metadata {
    name = "staging"
    labels = {
      environment = "staging"
      managed-by  = "terraform"
    }
  }
}

resource "kubernetes_namespace" "infrastructure" {
  metadata {
    name = "infrastructure"
    labels = {
      environment = "infrastructure"
      managed-by  = "terraform"
    }
  }
}

resource "kubernetes_namespace" "argocd" {
  metadata {
    name = "argocd"
    labels = {
      environment = "infrastructure"
      managed-by  = "terraform"
    }
  }
}

La convención: production para cargas de trabajo reales, staging para pruebas pre-producción, infrastructure para componentes del sistema (ingress, cert-manager, storage), argocd para la herramienta GitOps.

Paso 3: Storage — local-path-provisioner

Kubernetes necesita un StorageClass que cree PersistentVolumes dinámicamente cuando un pod pide un PVC. En Hetzner usamos local-path-provisioner (de Rancher), que crea volúmenes en el disco local del nodo:

resource "helm_release" "local_path_provisioner" {
  name       = "local-path-provisioner"
  namespace  = kubernetes_namespace.infrastructure.metadata[0].name
  repository = "https://rancher.github.io/local-path-provisioner"
  chart      = "local-path-provisioner"
  version    = "0.0.28"

  set {
    name  = "storageClass.defaultClass"
    value = "true"
  }

  set {
    name  = "nodePathMap[0].node"
    value = "DEFAULT_PATH_FOR_NON_LISTED_NODES"
  }

  set {
    name  = "nodePathMap[0].paths[0]"
    value = "/var/local-path-provisioner"
  }
}

¿Por qué no Rook/Ceph? Para un cluster de 3 nodos modestos, Ceph es sobreingeniería. local-path-provisioner es perfecto: los datos viven en /var/local-path-provisioner del nodo donde corre el pod. La limitación es que si ese nodo muere, el volumen se pierde. Para producción seria, más adelante migras a Longhorn (replicación) o usas volúmenes de cloud (Hetzer volumes).

Paso 4: nginx ingress controller — la puerta de entrada

El ingress controller es el reverse proxy que recibe tráfico externo y lo rutea a los Services correctos dentro del cluster. Usamos nginx, el más probado del ecosistema:

resource "helm_release" "ingress_nginx" {
  name       = "ingress-nginx"
  namespace  = kubernetes_namespace.infrastructure.metadata[0].name
  repository = "https://kubernetes.github.io/ingress-nginx"
  chart      = "ingress-nginx"
  version    = "4.11.2"

  set {
    name  = "controller.service.type"
    value = "NodePort"
  }

  set {
    name  = "controller.service.nodePorts.http"
    value = "30080"
  }

  set {
    name  = "controller.service.nodePorts.https"
    value = "30443"
  }

  set {
    name  = "controller.config.proxy-body-size"
    value = "50m"
  }

  set {
    name  = "controller.config.proxy-read-timeout"
    value = "60"
  }

  set {
    name  = "controller.config.proxy-send-timeout"
    value = "60"
  }
}

Detalles importantes:

Usamos NodePort porque Hetzner no tiene LoadBalancer nativo. El ingress escucha en el puerto 30080 (HTTP) y 30443 (HTTPS) de cada nodo
proxy-body-size: 50m permite uploads de archivos
Los timeouts de proxy en 60s evitan que requests largos (migraciones, backups) se corten

En producción real: apuntas un balanceador de carga (Hetzner Load Balancer, Cloudflare Tunnel, o un nginx externo) al NodePort 30080/30443 de los workers. También puedes instalar hcloud-cloud-controller-manager para que Hetzner cree Load Balancers automáticamente.

Paso 5: cert-manager — TLS automático con Let's Encrypt

Nadie debería manejar certificados TLS a mano en 2026. cert-manager los crea, renueva 30 días antes de expirar, y los inyecta como Secrets:

resource "helm_release" "cert_manager" {
  name       = "cert-manager"
  namespace  = kubernetes_namespace.infrastructure.metadata[0].name
  repository = "https://charts.jetstack.io"
  chart      = "cert-manager"
  version    = "1.16.1"

  set {
    name  = "installCRDs"
    value = "true"
  }

  set {
    name  = "prometheus.enabled"
    value = "false"
  }
}

Después de instalar cert-manager, creamos los ClusterIssuers:

# Staging — para pruebas, sin rate limits fuertes
resource "kubernetes_manifest" "cluster_issuer_staging" {
  manifest = {
    apiVersion = "cert-manager.io/v1"
    kind       = "ClusterIssuer"
    metadata = {
      name = "letsencrypt-staging"
    }
    spec = {
      acme = {
        server  = "https://acme-staging-v02.api.letsencrypt.org/directory"
        email   = var.letsencrypt_email
        privateKeySecretRef = {
          name = "letsencrypt-staging-account-key"
        }
        solvers = [{
          http01 = {
            ingress = {
              class = "nginx"
            }
          }
        }]
      }
    }
  }
}

# Production — certificados de verdad
resource "kubernetes_manifest" "cluster_issuer_production" {
  manifest = {
    apiVersion = "cert-manager.io/v1"
    kind       = "ClusterIssuer"
    metadata = {
      name = "letsencrypt-production"
    }
    spec = {
      acme = {
        server  = "https://acme-v02.api.letsencrypt.org/directory"
        email   = var.letsencrypt_email
        privateKeySecretRef = {
          name = "letsencrypt-production-account-key"
        }
        solvers = [{
          http01 = {
            ingress = {
              class = "nginx"
            }
          }
        }]
      }
    }
  }

  depends_on = [helm_release.cert_manager]
}

La diferencia staging vs production: Let's Encrypt tiene rate limits estrictos en producción (50 certificados por dominio por semana). Si estás probando configuraciones de ingress, usas staging. Cuando todo funciona, cambias a production.

Paso 6: RBAC mínimo viable

Para este tutorial necesitamos un ServiceAccount que las aplicaciones usarán:

resource "kubernetes_service_account" "apps" {
  metadata {
    name      = "apps-sa"
    namespace = kubernetes_namespace.production.metadata[0].name
  }
}

resource "kubernetes_role" "apps" {
  metadata {
    name      = "apps-role"
    namespace = kubernetes_namespace.production.metadata[0].name
  }

  rule {
    api_groups = [""]
    resources  = ["pods", "services", "configmaps", "secrets"]
    verbs      = ["get", "list", "watch"]
  }

  rule {
    api_groups = ["apps"]
    resources  = ["deployments"]
    verbs      = ["get", "list", "watch"]
  }
}

resource "kubernetes_role_binding" "apps" {
  metadata {
    name      = "apps-rolebinding"
    namespace = kubernetes_namespace.production.metadata[0].name
  }

  role_ref {
    api_group = "rbac.authorization.k8s.io"
    kind      = "Role"
    name      = kubernetes_role.apps.metadata[0].name
  }

  subject {
    kind      = "ServiceAccount"
    name      = kubernetes_service_account.apps.metadata[0].name
    namespace = kubernetes_namespace.production.metadata[0].name
  }
}

Esto es intencionalmente restrictivo: las apps pueden leer recursos pero no modificarlos ni crear nuevos. En la Parte 4 configuraremos un ServiceAccount específico para el backend con permisos de lectura de Secrets.

Paso 7: Verificación — probar TLS real

Creamos un ingress de prueba con TLS:

resource "kubernetes_manifest" "test_ingress" {
  manifest = {
    apiVersion = "networking.k8s.io/v1"
    kind       = "Ingress"
    metadata = {
      name      = "test-ingress"
      namespace = "production"
      annotations = {
        "cert-manager.io/cluster-issuer"            = "letsencrypt-staging"
        "nginx.ingress.kubernetes.io/ssl-redirect"  = "true"
      }
    }
    spec = {
      ingressClassName = "nginx"
      tls = [{
        hosts      = ["test.tudominio.com"]
        secretName = "test-tls"
      }]
      rules = [{
        host = "test.tudominio.com"
        http = {
          paths = [{
            path     = "/"
            pathType = "Prefix"
            backend = {
              service = {
                name = "echo-service"
                port = { number = 80 }
              }
            }
          }]
        }
      }]
    }
  }
}

Después de terraform apply, apuntas el DNS test.tudominio.com a la IP pública de cualquier nodo y verificas:

curl -v https://test.tudominio.com:30443
# < HTTP/2 200
# < SSL certificate verified: CN = test.tudominio.com
# (Fake LE Intermediate X1) ← staging, esperado

Cuando confirmas que funciona, cambias el annotation a letsencrypt-production y obtienes un certificado real. cert-manager lo renovará automáticamente cada 60 días.

Estructura final de Terraform hasta ahora

infra/
├── main.tf                    # Providers + recursos principales
├── variables.tf
├── outputs.tf
├── terraform.tfvars
├── versions.tf
├── cloud-init/
│   ├── control-plane.yaml
│   └── worker.yaml
├── modules/
│   ├── kubernetes-core/       # (opcional — refactor futuro)
│   │   ├── namespaces.tf
│   │   ├── storage.tf
│   │   ├── ingress.tf
│   │   ├── cert-manager.tf
│   │   └── rbac.tf
└── .gitignore

Qué aprendiste en esta parte

Namespaces como capa de aislamiento entre entornos
Por qué Terraform maneja el bootstrap y ArgoCD maneja las apps
nginx ingress controller expuesto vía NodePort
cert-manager + Let's Encrypt para TLS automático con renovación
local-path-provisioner como StorageClass dinámica
RBAC mínimo viable con ServiceAccounts, Roles y RoleBindings
El flujo ClusterIssuer → Ingress annotation → Secret TLS → certificado listo

En la Parte 3, desplegaremos ArgoCD, configuraremos GitOps con el patrón app-of-apps, y tendremos nuestro primer despliegue automático desde GitHub.

En Guayoyo Tech no solo escribimos tutoriales — diseñamos y desplegamos arquitecturas como esta para empresas reales. Kubernetes, Terraform, ArgoCD, pipelines CI/CD, y todo el ecosistema cloud-native: lo armamos contigo, sin humo y sin vendor lock-in. Si quieres que tu infraestructura se parezca a lo que acabas de leer, hablemos gratis 15 minutos. Tu cluster, tu nube, tus reglas — nosotros ponemos la ingeniería.

推荐订阅源

DEV Community