16 min de lectura

Objetivos de aprendizaje

Al final de este módulo, podrás:

  • Aprovisionar un clúster y un grupo de nodos de Managed Kubernetes con `ionoscloud_k8s_cluster` y `ionoscloud_k8s_node_pool`, y recuperar el kubeconfig
  • Desplegar la API, el frontend y el worker de TaskBoard con Deployments, Services, ConfigMaps y Secrets que obtienen imágenes desde el Private Container Registry
  • Configurar el ingress para TaskBoard con un controlador de ingress NodePort detrás de un Application Load Balancer aprovisionado por separado
  • Escalar y actualizar grupos de nodos sin tiempo de inactividad, utilizando varios grupos para el aislamiento de cargas de trabajo
  • Depurar pods en estado de fallo con `kubectl` y saber dónde se encuentran los registros del clúster en IONOS CLOUD

Unidad 3.2: Despliegue y operaciones de Kubernetes

Introducción

Las imágenes de TaskBoard se encuentran en el registro de la Unidad 3.1. Ahora necesitan un lugar para ejecutarse. Managed Kubernetes ejecuta el plano de control; usted administra los grupos de nodos y las cargas de trabajo mediante código.

Algunas partes funcionan de manera diferente a otras plataformas de Kubernetes. Un Service de tipo LoadBalancer adjunta una IP estática a un nodo en lugar de crear un equilibrador de carga, y los nodos se reemplazan durante el mantenimiento.

En esta unidad, usted aprovisiona el clúster con Terraform, conecta kubectl, despliega las cargas de trabajo de TaskBoard, coloca el ALB de la Unidad 2.3 frente a un controlador de entrada y opera los grupos de nodos. En el laboratorio de código, usted lleva TaskBoard desde terraform apply hasta un endpoint funcional detrás del ALB.

1. Aprovisionamiento de MKS con Terraform

1.1 El Cluster

resource "ionoscloud_k8s_cluster" "taskboard" {
  name        = "taskboard-dev"
  k8s_version = var.k8s_version

  maintenance_window {
    day_of_the_week = "Sunday"
    time            = "02:00:00Z"
  }

  api_subnet_allow_list = ["203.0.113.0/24"]

  s3_buckets {
    name = "taskboard-k8s-audit-7f3a"
  }
}

Solo se requiere name. api_subnet_allow_list restringe el acceso al servidor de la API de Kubernetes a estas CIDR; el tráfico interno del clúster no se ve afectado, y sin una lista, el acceso no está restringido. s3_buckets especifica el nombre de un bucket existente de IONOS Cloud Object Storage para los registros de auditoría de la API de Kubernetes. La ventana de mantenimiento se abre a la hora que usted configure y permanece abierta durante cuatro horas.

Lea la versión predeterminada actual de la API y pásela, en lugar de copiar una versión antigua de un ejemplo:

curl --silent "https://api.ionos.com/cloudapi/v6/k8s/versions/default" \
  --header "Authorization: Bearer $IONOS_TOKEN"
export TF_VAR_k8s_version="<version from the response>"

Las versiones menores compatibles son 1.32, 1.33, 1.34 y 1.35. La versión 1.32 alcanza su fin de vida en IONOS CLOUD el 1 de diciembre de 2026, y no se pueden crear nuevos grupos de nodos para un clúster en una versión EOL. No se admiten las degradaciones de versión.

1.2 El grupo de nodos

# In the existing ionoscloud_lan.app and ionoscloud_lan.db from Unit 2.2, add:
# lifecycle {
#   create_before_destroy = true
# }

resource "ionoscloud_k8s_node_pool" "general" {
  datacenter_id     = ionoscloud_datacenter.taskboard.id
  k8s_cluster_id    = ionoscloud_k8s_cluster.taskboard.id
  name              = "general"
  k8s_version       = ionoscloud_k8s_cluster.taskboard.k8s_version
  server_type       = "VCPU"
  availability_zone = "AUTO"
  storage_type      = "SSD"
  node_count        = 2
  cores_count       = 2
  ram_size          = 4096
  storage_size      = 20

  lans {
    id   = ionoscloud_lan.app.id
    dhcp = true
  }

  lans {
    id   = ionoscloud_lan.db.id
    dhcp = true
  }

  maintenance_window {
    day_of_the_week = "Sunday"
    time            = "03:00:00Z"
  }
}

Los bloques lans conectan cada Node con la LAN privada de la aplicación de la Unidad 2.2, donde el ALB los alcanza en la Sección 4, y con la LAN de bases de datos, donde los pods alcanzan PostgreSQL, In-Memory DB y Kafka (Unidad 2.5). Los grupos de nodos obtienen sus direcciones IP en una LAN privada a través de DHCP. El proveedor recomienda create_before_destroy en las LAN para que el grupo de nodos se actualice antes de que se destruya una LAN.

Estos argumentos son inmutables: name, cpu_family, availability_zone, cores_count, ram_size, storage_size y storage_type. allow_replace = true los modifica destruyendo y recreando el grupo, lo que causa tiempo de inactividad para todos los pods en él. server_type acepta DedicatedCore o VCPU, y puede cambiar un grupo existente entre ellos. Un núcleo aprovisionado equivale a 2 CPUs de Managed Kubernetes.

1.3 Obtención del Kubeconfig

data "ionoscloud_k8s_cluster" "taskboard" {
  id         = ionoscloud_k8s_cluster.taskboard.id
  depends_on = [ionoscloud_k8s_node_pool.general]
}

resource "local_file" "kubeconfig" {
  sensitive_content = yamlencode(jsondecode(data.ionoscloud_k8s_cluster.taskboard.kube_config))
  filename          = "kubeconfig.yaml"
}

La fuente de datos devuelve kube_config, y su nodo config completo se marca como sensible. Escribir el kubeconfig en un archivo supone un riesgo de seguridad: manténgalo fuera de Git. Fuera de Terraform, obtiene el mismo archivo desde la API o la CLI:

curl --silent "https://api.ionos.com/cloudapi/v6/k8s/$CLUSTER_ID/kubeconfig" \
  --header "Authorization: Bearer $IONOS_TOKEN" > kubeconfig.yaml
ionosctl k8s kubeconfig get --cluster-id "$CLUSTER_ID"

La API devuelve YAML de forma predeterminada, o JSON cuando la cabecera Accept lo solicita. Solo los administradores pueden recuperar el kubeconfig de un clúster sin un grupo de nodos; todos los demás usuarios deben crear primero un grupo de nodos.

2. Conexión al Cluster

export KUBECONFIG="$PWD/kubeconfig.yaml"
kubectl config get-contexts
kubectl get nodes -o wide
kubectl create namespace taskboard
kubectl config set-context --current --namespace=taskboard

Utilice el kubeconfig descargado para la configuración, no para las implementaciones diarias.

2.1 RBAC para implementaciones

Para la pipeline de CI en la Unidad 3.3, cree una cuenta de servicio que solo pueda administrar el espacio de nombres de TaskBoard:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: taskboard-deployer
  namespace: taskboard
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: taskboard-deployer-edit
  namespace: taskboard
subjects:
  - kind: ServiceAccount
    name: taskboard-deployer
    namespace: taskboard
roleRef:
  kind: ClusterRole
  name: edit
  apiGroup: rbac.authorization.k8s.io

El ClusterRole edit integrado, vinculado a través de un RoleBinding, otorga derechos únicamente dentro de taskboard. Quién puede crear clústeres es un privilegio de IONOS CLOUD: un grupo necesita createK8sCluster (Crear clústeres de Kubernetes en el DCD).

3. Workloads de TaskBoard

3.1 Extracción desde el Private Container Registry

kubectl create secret docker-registry taskboard-registry \
  --docker-server="$CR_HOST" \
  --docker-username=taskboard-k8s-pull \
  --docker-password="$(cat k8s-pull.pass)" \
  --namespace taskboard

El secret contiene el token de solo extracción de la Unidad 3.1. Hágalo referencia en cada especificación de pod a través de imagePullSecrets. Sin él, los pods permanecen en ImagePullBackOff, porque el registro nunca permite extracciones sin autenticación.

3.2 Deployment, Service, ConfigMap y Secret

apiVersion: v1
kind: ConfigMap
metadata:
  name: taskboard-config
data:
  LOG_LEVEL: "info"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: taskboard-api
spec:
  replicas: 2
  selector:
    matchLabels: { app: taskboard-api }
  template:
    metadata:
      labels: { app: taskboard-api }
    spec:
      imagePullSecrets:
        - name: taskboard-registry
      containers:
        - name: api
          image: <registry-hostname>/taskboard/api:<git-sha>
          ports:
            - containerPort: 8000
          envFrom:
            - configMapRef: { name: taskboard-config }
            - secretRef: { name: taskboard-db }
          resources:
            requests: { cpu: 250m, memory: 256Mi }
            limits: { memory: 512Mi }
          readinessProbe:
            httpGet: { path: /api/health, port: 8000 }
---
apiVersion: v1
kind: Service
metadata:
  name: taskboard-api
spec:
  selector: { app: taskboard-api }
  ports:
    - port: 80
      targetPort: 8000

El Secret taskboard-db contiene los valores de conexión de PostgreSQL de la Unidad 2.5; créelo desde su almacén de secretos, nunca desde un archivo en Git. El Deployment web utiliza el puerto 8080, y el Deployment worker no tiene un Service. Establezca las solicitudes y los límites: un nodo que se quede sin RAM puede terminar NotReady, ocupado con E/S de disco.

4. Ingress: Controladores en Nodes, Load Balancers provisionados por separado

4.1 Qué hace un servicio LoadBalancer en MKS

apiVersion: v1
kind: Service
metadata:
  name: demo
spec:
  type: LoadBalancer
  loadBalancerIP: 198.51.100.20   # an IP you reserved in IP Management
  selector: { app: demo }
  ports:
    - port: 80

En un pool de nodos públicos, esto no crea un ALB ni un NLB. IONOS CLOUD asigna una IP estática pre-reservada o reserva una nueva, y la adjunta como IP secundaria a un Node worker. Ese Node actúa como el Node de entrada; kube-proxy reenvía el tráfico a los pods en otros nodos, y esa etapa de NAT reemplaza la IP del cliente. Cada Node proporciona hasta 2 Gbit/s en la interfaz pública. Sin loadBalancerIP, la dirección se libera cuando elimina el Service. Los pools de nodos privados no admiten el tipo LoadBalancer.

4.2 TaskBoard: Controlador de entrada detrás del ALB

TaskBoard utiliza el ALB administrado de la Unidad 2.3, aprovisionado con Terraform, no desde un manifiesto. El controlador de entrada se ejecuta en los nodos worker y se expone como un NodePort; el ALB envía el tráfico a los nodos en la LAN de la aplicación.

helm repo add traefik https://traefik.github.io/charts
helm install traefik traefik/traefik --namespace ingress --create-namespace \
  --set service.type=NodePort --set ports.web.nodePort=30080
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: taskboard
spec:
  ingressClassName: traefik
  rules:
    - http:
        paths:
          - path: /api
            pathType: Prefix
            backend: { service: { name: taskboard-api, port: { number: 80 } } }
          - path: /
            pathType: Prefix
            backend: { service: { name: taskboard-web, port: { number: 80 } } }

El grupo de destino ahora apunta a las direcciones de los Node en la LAN de la aplicación, en el NodePort:

variable "ingress_node_ips" {
  type = list(string)
}

resource "ionoscloud_target_group" "ingress" {
  name             = "taskboard-ingress"
  algorithm        = "ROUND_ROBIN"
  protocol         = "HTTP"
  protocol_version = "HTTP1"

  dynamic "targets" {
    for_each = var.ingress_node_ips
    content {
      ip     = targets.value
      port   = 30080
      weight = 100
    }
  }

  http_health_check {
    path       = "/api/health"
    method     = "GET"
    match_type = "STATUS_CODE"
    response   = "200"
  }
}

Dirija la regla de reenvío de la Unidad 2.3 a ionoscloud_target_group.ingress.id. Lea las direcciones de los Node que se encuentran en 10.10.1.0/24 desde kubectl get nodes -o wide, o desde el interior de un Node. Los Node se reemplazan durante el mantenimiento (sección 5), por lo que verifique la lista de destinos después de cada cambio en el grupo de nodos.

5. Operaciones y depuración de grupos de nodos

5.1 Escalado y múltiples grupos

resource "ionoscloud_k8s_node_pool" "workers" {
  # ... same required arguments as Section 1.2, name = "workers"
  node_count = 1
  auto_scaling {
    min_node_count = 1
    max_node_count = 4
  }
  labels = { pool = "workers" }
  taints {
    key    = "dedicated"
    value  = "worker"
    effect = "NoSchedule"
  }
  lifecycle {
    ignore_changes = [node_count]
  }
}

Un segundo grupo de nodos aísla el worker de fondo de TaskBoard: el taint mantiene a los demás pods fuera, y el Deployment del worker recibe una toleration correspondiente y un nodeSelector de pool: workers. Con auto_scaling, el autoscaler cambia el número de nodos, por lo que ignore_changes impide que Terraform entre en conflicto con él. El autoscaler se mantiene entre su valor mínimo y máximo, no puede exceder la cuota del contrato y no puede escalar a 0.

Límite Valor
Nodos por grupo de nodos 100 como máximo, 20 recomendados
Grupos de nodos por clúster 500
Nodos por clúster 5000
Pods por nodo 110

5.2 Actualizaciones y mantenimiento

Durante el mantenimiento de un grupo de nodos, todos los nodos del grupo se reemplazan, uno tras otro, comenzando por el nodo más antiguo. Primero se incorpora un nodo nuevo, y luego el nodo antiguo se drena y se elimina. Los nodos son inmutables, por lo que las actualizaciones de software también llegan como nodos nuevos. El mantenimiento considera la ventana de cuatro horas; los nodos que no se reemplazan a tiempo se reemplazan en el siguiente mantenimiento.

Los grupos de nodos pueden ejecutar una versión de Kubernetes anterior a la del control plane, pero nunca una más nueva, y las versiones menores pueden diferir como máximo en 1. Para actualizar, primero aumente k8s_version en el clúster y luego en cada grupo. Prepare sus cargas de trabajo para la expulsión en cualquier momento: ejecute al menos dos réplicas y utilice PodDisruptionBudgets que permitan que un pod se vaya.

5.3 Depuración

kubectl get pods -o wide
kubectl describe pod <pod>                 # events: ImagePullBackOff, scheduling, probes
kubectl logs deploy/taskboard-api --since=15m
kubectl exec -it deploy/taskboard-api -- sh
kubectl get events --sort-by=.lastTimestamp

kubectl es su herramienta principal para problemas de carga de trabajo. El Logging Service recibe lo que un agente de Fluent Bit envía o lo que usted envía en formato OTLP, por lo que los registros de aplicaciones llegan a él solo después de que usted despliegue un agente o los envíe a través de OTLP (Unidad 5.1). Los registros de auditoría de la API del clúster se envían al bucket de Object Storage en s3_buckets. Si un nodo se vuelve no receptivo, reemplácelo a través de la API con POST /k8s/{k8sClusterId}/nodepools/{nodePoolId}/nodes/{nodeId}/replace.

Tarjeta rápida de referencia de la API

Endpoints principales de la API para el tema de esta unidad:

Método Endpoint Descripción
GET /k8s/versions/default Versión predeterminada para nuevos clústeres y grupos de nodos
POST /k8s Crear un clúster
POST /k8s/{k8sClusterId}/nodepools Crear un grupo de nodos
GET /k8s/{k8sClusterId}/kubeconfig Descargar el kubeconfig (YAML de forma predeterminada)
POST /k8s/{k8sClusterId}/nodepools/{nodePoolId}/nodes/{nodeId}/replace Reemplazar un nodo sin respuesta

URL base: https://api.ionos.com/cloudapi/v6 Autenticación: Authorization: Bearer <token>

Laboratorio de código

Objetivo: Desplegar TaskBoard en Managed Kubernetes: crear el clúster y el grupo de nodos con Terraform, desplegar los manifiestos con un secreto de extracción del registro y verificar el endpoint a través del ALB.

Requisitos previos:

  • Cuenta de IONOS CLOUD con un token de API en IONOS_TOKEN
  • Terraform, kubectl y Helm instalados localmente
  • El registro, las imágenes y k8s-pull.pass de la Unidad 3.1
  • La configuración del centro de datos, la LAN de la aplicación y el ALB de las Unidades 2.2 y 2.3

Paso 1: Agregar el clúster y el grupo de nodos

Agregue a su configuración el clúster (Sección 1.1, sin s3_buckets a menos que tenga un bucket), el grupo de nodos (Sección 1.2) y el archivo kubeconfig (Sección 1.3).

export TF_VAR_k8s_version="<default version from /k8s/versions/default>"
terraform apply -target=ionoscloud_k8s_node_pool.general -target=local_file.kubeconfig

Salida esperada:

ionoscloud_k8s_cluster.taskboard: Creation complete after ...
ionoscloud_k8s_node_pool.general: Creation complete after ...
local_file.kubeconfig: Creation complete after ...

Paso 2: Conectar

export KUBECONFIG="$PWD/kubeconfig.yaml"
kubectl get nodes

Salida esperada:

NAME        STATUS   ROLES    AGE   VERSION
<node-1>    Ready    <none>   ...   v<version>
<node-2>    Ready    <none>   ...   v<version>

Paso 3: Crear el espacio de nombres y los secretos

kubectl create namespace taskboard
kubectl -n taskboard create secret docker-registry taskboard-registry \
  --docker-server="$CR_HOST" --docker-username=taskboard-k8s-pull \
  --docker-password="$(cat k8s-pull.pass)"
kubectl -n taskboard create secret generic taskboard-db --from-literal=DATABASE_URL="$DATABASE_URL"

Salida esperada:

namespace/taskboard created
secret/taskboard-registry created
secret/taskboard-db created

Paso 4: Despliegue de las cargas de trabajo

kubectl -n taskboard apply -f k8s/
kubectl -n taskboard rollout status deploy/taskboard-api

Salida esperada:

deployment "taskboard-api" successfully rolled out

Paso 5: Instale el controlador de entrada y el recurso Ingress

helm install traefik traefik/traefik --namespace ingress --create-namespace \
  --set service.type=NodePort --set ports.web.nodePort=30080
kubectl -n taskboard apply -f k8s/ingress.yaml

Salida esperada:

STATUS: deployed
ingress.networking.k8s.io/taskboard created

Paso 6: Apuntar el ALB a los nodos

kubectl get nodes -o wide        # note each node's address in 10.10.1.0/24
export TF_VAR_ingress_node_ips='["10.10.1.x","10.10.1.y"]'
terraform apply

Salida esperada:

ionoscloud_target_group.ingress: Creation complete after ...
ionoscloud_application_loadbalancer_forwardingrule.http: Modifications complete after ...

Paso 7: Verificar el endpoint

curl --silent "http://$(terraform output -raw alb_ip)/api/health"

Salida esperada:

{"status": "ok"}

Lista de verificación:

  • [ ] Ambos nodos están Ready
  • [ ] Todos los pods de TaskBoard están Running, sin ImagePullBackOff
  • [ ] La comprobación de estado del ALB informa que los destinos están sanos
  • [ ] /api/health responde a través de la IP del ALB

Limpieza:

helm uninstall traefik --namespace ingress
terraform destroy -auto-approve
rm -f kubeconfig.yaml

Errores comunes

Errores de desarrollo que debe evitar con el tema de esta unidad:

  1. Esperar un balanceador de carga desde un manifiesto

    • Problema: Aplica un Service type: LoadBalancer y busca un nuevo ALB, pero todo el tráfico llega a un solo nodo y sus registros muestran direcciones IP internas de nodos en lugar de las direcciones IP de los clientes.
    • Por qué ocurre: En MKS, el Service obtiene una IP estática en un nodo de entrada, y kube-proxy NAT reemplaza la dirección del cliente.
    • Solución: Provisione el ALB o NLB por separado con Terraform (sección 4.2), o use externalTrafficPolicy: Local con la IP vinculada al nodo que ejecuta el controlador de entrada.
  2. ImagePullBackOff en cada pod

    • Problema: kubectl describe pod muestra un error de autorización al obtener imágenes del registro.
    • Por qué ocurre: La especificación del pod no tiene imagePullSecrets, el secreto está en otro espacio de nombres, o el token caducó y se eliminó.
    • Solución: Cree el secreto docker-registry en el espacio de nombres de la carga de trabajo, refiérase a él en la especificación del pod y no asigne fecha de caducidad al token de obtención o rotélo antes de la fecha de caducidad.
  3. Cambiar un argumento inmutable de un grupo de nodos

    • Problema: Aumenta ram_size y el plan muestra la destrucción y recreación del grupo.
    • Por qué ocurre: cores_count, ram_size, storage_size y los otros argumentos de la plantilla son inmutables.
    • Solución: Cree un nuevo grupo con el nuevo tamaño, mueva las cargas de trabajo mediante etiquetas o drenando los nodos, y luego elimine el grupo antiguo.

Resumen

Ahora puede ejecutar TaskBoard en Managed Kubernetes desde el código. Terraform crea el clúster, los grupos de nodos y el kubeconfig; las cargas de trabajo se descargan desde el Private Container Registry mediante un secreto de descarga; y un controlador de entrada en los nodos se encuentra detrás de un ALB aprovisionado por separado. Sabe cómo el mantenimiento reemplaza los nodos y dónde buscar cuando un pod falla.

Puntos clave:

  • Lea la versión predeterminada desde /k8s/versions/default; los grupos de nodos pueden ir por detrás del plano de control como máximo una versión menor
  • Los argumentos de la plantilla de nodo son inmutables; allow_replace recrea el grupo con tiempo de inactividad
  • Un Service LoadBalancer en MKS es una IP estática en un solo nodo, no un ALB o NLB
  • Cada pod que se descarga desde el registro necesita una entrada imagePullSecrets
  • El mantenimiento del grupo de nodos reemplaza los nodos uno por uno dentro de una ventana de cuatro horas; mantenga los grupos con 20 nodos o menos

Terminología importante:

  • Grupo de nodos: Un grupo de nodos con el mismo tipo de servidor, CPU, RAM y almacenamiento, gestionado como ionoscloud_k8s_node_pool
  • Kubeconfig: El archivo con la dirección del servidor de API y las credenciales que utiliza kubectl
  • Nodo de entrada: El nodo de trabajo que contiene la IP estática de un Service LoadBalancer
  • NodePort: Un tipo de Service que abre un puerto fijo en cada nodo, utilizado aquí como puerto de destino del ALB
  • imagePullSecrets: El campo de la especificación del pod que hace referencia a las credenciales del registro para imágenes privadas

Próximos pasos

Siga aprendiendo: Unidad 3.3: Pipelines CI/CD para IONOS CLOUD

Temas relacionados: