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,
kubectly Helm instalados localmente - El registro, las imágenes y
k8s-pull.passde 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, sinImagePullBackOff - [ ] La comprobación de estado del ALB informa que los destinos están sanos
- [ ]
/api/healthresponde 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:
-
Esperar un balanceador de carga desde un manifiesto
- Problema: Aplica un Service
type: LoadBalancery 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: Localcon la IP vinculada al nodo que ejecuta el controlador de entrada.
- Problema: Aplica un Service
-
ImagePullBackOffen cada pod- Problema:
kubectl describe podmuestra 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-registryen 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.
- Problema:
-
Cambiar un argumento inmutable de un grupo de nodos
- Problema: Aumenta
ram_sizey el plan muestra la destrucción y recreación del grupo. - Por qué ocurre:
cores_count,ram_size,storage_sizey 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.
- Problema: Aumenta
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_replacerecrea el grupo con tiempo de inactividad - Un Service
LoadBalanceren 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: