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
NodePortporque Hetzner no tiene LoadBalancer nativo. El ingress escucha en el puerto 30080 (HTTP) y 30443 (HTTPS) de cada nodo
proxy-body-size: 50mpermite 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.