Implementar y exponer API de inferencia de IA en Azure Kubernetes Service

radio_button_uncheckedshort_text1. De una imagen de contenedor a un punto de conexión de IA de alta disponibilidad

Azure Kubernetes Service (AKS) opera un plano de control de Kubernetes administrado sobre Azure. Tú aportas la capacidad del clúster y las definiciones de las cargas, mientras Azure administra la infraestructura del plano de control. Es apropiado para API de inferencia, búsqueda vectorial y otros componentes de IA que necesitan implementación repetible, resistencia, escalado y acceso de red.

Una API FastAPI en contenedor solo se vuelve operable cuando Kubernetes sabe qué ejecutar, cuántas copias mantener, qué recursos y configuración necesita y cómo llegarán los clientes. Los manifiestos YAML describen ese estado deseado y el clúster reconcilia continuamente la realidad con la declaración.

• Pod es la unidad implementable más pequeña y normalmente contiene un contenedor de aplicación.
• Deployment crea, sustituye y mantiene el número solicitado de Pods.
• Service proporciona IP o DNS estable y distribuye tráfico por etiquetas.
• kubectl envía manifiestos, consulta estados, lee registros y muestra eventos de diagnóstico.

Resumen del tema

AKS administra la orquestación; Pods ejecutan contenedores, Deployments mantienen réplicas, Services estabilizan el acceso y kubectl controla y diagnostica la carga.

radio_button_uncheckedshort_text2. Cómo colaboran Pods, Deployments, Services y etiquetas

Ejecutar un Pod directamente es posible, pero frágil. Un Deployment controla un ReplicaSet, este mantiene los Pods y reemplaza una instancia con error. Un Service no almacena direcciones efímeras: su selector encuentra Pods con etiquetas coincidentes y reenvía conexiones a esos puntos de conexión.

El contrato de etiquetas es crítico. Si la plantilla usa app: inference-api y el Service selecciona otro valor, el Service existe sin endpoints. Los nombres de Deployment y Service no deben coincidir; el puerto 80 del Service puede reenviar correctamente al 8080 del contenedor.

Resumen del tema

Deployment controla el ciclo de los Pods y Service los descubre por etiquetas; son las etiquetas, no los nombres de objetos, las que conectan ambos recursos.

radio_button_uncheckedshort_text3. Anatomía de un manifiesto Deployment de Kubernetes

Un Deployment usa apiVersion apps/v1 y kind Deployment. metadata identifica el objeto y puede indicar un espacio de nombres. spec declara replicas, selector y la plantilla de Pod. La plantilla repite la etiqueta elegida y contiene los contenedores. El archivo declarativo se puede revisar, versionar y volver a aplicar.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-inference-api
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: inference-api
  template:
    metadata:
      labels:
        app: inference-api
    spec:
      containers:
      - name: api
        image: myregistry.azurecr.io/inference-api:v1.0
        ports:
        - containerPort: 8080
        resources:
          requests:
            memory: "2Gi"
            cpu: "1000m"
          limits:
            memory: "4Gi"
            cpu: "2000m"
        env:
        - name: MODEL_NAME
          value: "gpt-4"
        - name: API_KEY
          valueFrom:
            secretKeyRef:
              name: api-secrets
              key: api-key

La referencia de imagen sigue registro.azurecr.io/repositorio:etiqueta. Compila y envía la imagen antes de implementar, comprueba que el clúster pueda acceder, incluye código y dependencias y prefiere una etiqueta de versión inmutable a latest cuando necesites reproducibilidad.

Resumen del tema

El manifiesto reúne identidad, réplicas, etiquetas, plantilla de Pod, imagen, puertos, recursos y configuración en un documento versionable del estado deseado.

radio_button_uncheckedshort_text4. Réplicas, disponibilidad, solicitudes y límites de recursos

Dos réplicas ofrecen tolerancia básica al error de un Pod; tres son una base más sólida para producción; cuatro o más deben justificarse con tráfico y pruebas porque cada copia consume cómputo. Kubernetes reinicia Pods con error, pero varias réplicas permiten seguir atendiendo durante la recuperación.

Las solicitudes reservan recursos para la programación. Si ningún nodo dispone de la CPU o memoria solicitada, el Pod queda Pending. Los límites restringen el consumo: la CPU se ralentiza y superar memoria puede provocar OOMKilled y reinicio. Para un modelo pequeño, 2–4 GiB, cerca de 20 % de margen y uno o dos núcleos son solo un punto inicial.

Resumen del tema

Usa réplicas para resistencia y rendimiento medido; define solicitudes para programación y límites para contención y ajústalos al comportamiento real del modelo.

radio_button_uncheckedshort_text5. Variables de entorno, secretos y acceso al registro

Usa variables literales para valores no confidenciales, como nombre de modelo y URL. Para claves y credenciales, referencia un Secret mediante valueFrom y secretKeyRef. Créalo por separado con kubectl create secret generic api-secrets --from-literal=api-key=<valor>. Nunca confirmes el valor en el manifiesto o historial.

AKS también debe autenticarse en Azure Container Registry. Para un registro RBAC normal, la integración concede AcrPull a la identidad administrada de kubelet. Un registro con ABAC requiere Container Registry Repository Reader. Un registro privado externo puede usar image pull Secret. Comprueba el modelo aplicable.

Resumen del tema

Mantén configuración ordinaria en variables, valores sensibles en Secrets referenciados y concede a kubelet el rol mínimo correcto para extraer imágenes.

radio_button_uncheckedshort_text6. Elegir el tipo correcto de Service de Kubernetes

Las IP de Pods son efímeras. Un Service crea un punto virtual persistente y sigue enviando a Pods coincidentes tras reemplazos. El tipo correcto depende de quién deba llamar la carga.

Para varias aplicaciones HTTP, terminación TLS o reglas de host y ruta, Ingress puede ser más adecuado que un LoadBalancer público por Service. El módulo se concentra en los cuatro tipos anteriores.

Resumen del tema

Usa ClusterIP internamente, NodePort en escenarios directos limitados, LoadBalancer para exposición administrada y ExternalName como alias DNS externo.

radio_button_uncheckedshort_text7. Manifiesto Service, selectores y asignación de puertos

El manifiesto usa apiVersion v1 y kind Service. type controla exposición, selector vincula etiquetas, port recibe clientes y targetPort reenvía a la aplicación. El puerto 80 puede dirigir a FastAPI en 8080; HTTPS suele usar 443 cuando la terminación está configurada.

apiVersion: v1
kind: Service
metadata:
  name: inference-api-service
spec:
  type: LoadBalancer
  selector:
    app: inference-api
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080

Dentro del clúster, DNS sigue nombreservice.namespace.svc.cluster.local. NodePort usa ip-nodo:nodeport, normalmente por encima de 30000. LoadBalancer usa la dirección externa que muestra kubectl get svc.

Resumen del tema

El selector debe coincidir con las etiquetas; port recibe al cliente y targetPort reenvía al proceso de aplicación.

radio_button_uncheckedshort_text8. Aplicar manifiestos y comprender la reconciliación

kubectl apply lee YAML y crea o actualiza objetos. Kubernetes descarga imágenes, programa Pods, inicia contenedores, crea el Service y aprovisiona la red. Es asíncrono: éxito significa que el estado deseado fue aceptado, no que Pods e IP pública estén listos.

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
# Equivalent options:
kubectl apply -f deployment.yaml -f service.yaml
kubectl apply -f .

Aplicar un directorio es cómodo, pero puede enviar YAML no relacionado. Mantén los artefactos delimitados y revisa cambios. Volver a aplicar es idempotente en el modelo declarativo: el plano de control compara configuración y estado vivo.

Resumen del tema

Usa kubectl apply para declarar recursos y observa la reconciliación aparte, porque Pods, descarga de imágenes y Load Balancer terminan de forma asíncrona.

radio_button_uncheckedshort_text9. Comprobar Pods, Deployment, Service, registros y conectividad

Una implementación sana muestra READY esperado, Pods Running, AVAILABLE igual al objetivo y dirección de Service coherente. Pending puede ser transitorio; CrashLoopBackOff indica fallos repetidos. EXTERNAL-IP de LoadBalancer puede quedar pending durante el aprovisionamiento.

kubectl get pods
kubectl get deployment
kubectl get svc inference-api-service
kubectl logs -l app=inference-api

# Test an internal ClusterIP Service
kubectl run -it --rm debug --image=alpine:latest --restart=Never -- sh
wget http://inference-api-service:80

# Test a public LoadBalancer address
curl http://<EXTERNAL-IP>
curl http://<EXTERNAL-IP>/predict -X POST -d '{"input":"test"}'

Para acceso interno, inicia un Pod de depuración desechable y llama al Service. Para acceso externo, prueba la IP pública y una ruta real de inferencia. Estado, preparación e inferencia validan capas distintas: un proceso puede estar vivo sin tener el modelo listo.

Resumen del tema

Revisa estado, registros y dirección del Service y prueba salud, preparación e inferencia real; aceptar el manifiesto no completa la implementación.

radio_button_uncheckedshort_text10. Diagnosticar ImagePullBackOff y CrashLoopBackOff

ImagePullBackOff significa que el nodo no pudo obtener la imagen. Revisa eventos, host, repositorio y etiqueta, confirma su existencia con az acr repository list o show-tags y valida el rol entre AKS y el registro. docker pull manual separa una referencia inválida de un problema de permisos.

CrashLoopBackOff significa que el contenedor inicia y sale repetidamente. Lee registros actuales y --previous y describe el Pod. Causas comunes: variable ausente, Secret inaccesible, comando o puerto incorrecto, fallo al cargar el modelo o configuración no montada. Ejecuta la imagen localmente para aislar el origen.

# Image pull or scheduling events
kubectl describe pod <pod-name>

# Current and previous-container logs
kubectl logs <pod-name>
kubectl logs <pod-name> --since=10m
kubectl logs <pod-name> --previous

# Capacity and Service selectors
kubectl get nodes
kubectl top nodes
kubectl get pods --show-labels
kubectl get pods -L app
kubectl describe svc inference-api-service

Resumen del tema

Usa eventos para imagen y programación, registros actuales y anteriores para errores de aplicación y compara permisos, manifiesto y ejecución local.

radio_button_uncheckedshort_text11. Diagnosticar Pods Pending y Services sin endpoints

Un Pod persistentemente Pending no puede programarse por falta de CPU o memoria solicitada, restricción o problema de nodo. Describe Pod y nodos, consulta kubectl top nodes si Metrics Server está disponible, reduce solicitudes irreales o aumenta capacidad con az aks scale después de validar coste y cuota.

Un Service con Endpoints: <none> no reenvía tráfico. Compara kubectl get pods --show-labels o -L app con kubectl describe svc. Corrige la etiqueta o selector y verifica que los Pods estén Ready.

Resumen del tema

Pending es principalmente una investigación de capacidad y programación; sin endpoints es una investigación de etiquetas, preparación y selectores.

radio_button_uncheckedshort_text12. Ejercicio guiado: implementar una API de inferencia de IA

El laboratorio dura unos 30–40 minutos. Implementa un modelo de Microsoft Foundry, Azure Container Registry y un clúster AKS; completa deployment.yaml y service.yaml con contenedor, sondeos, límites y balanceo; y usa un cliente Python para probar salud, preparación e inferencia.

1. Descarga el proyecto inicial y revisa la aplicación y los marcadores de manifiestos.
2. Implementa recursos de Azure con una identidad autorizada.
3. Completa imagen, sondeos, solicitudes, límites, etiquetas, selectores y puertos.
4. Aplica manifiestos, espera Pods y dirección del LoadBalancer y diagnostica fallos.
5. Ejecuta pruebas de salud, preparación e inferencia y elimina recursos desechables.

Requisitos: suscripción de Azure, Visual Studio Code, Python 3.12 o posterior, la CLI de Azure más reciente y kubectl. Las tareas de Azure Container Registry pueden no estar cubiertas por créditos gratuitos y exigir pago por uso u otro plan de pago.

Resumen del tema

El laboratorio une Microsoft Foundry, Azure Container Registry, AKS, YAML, sondeos, recursos, balanceo y pruebas Python en un flujo completo.

radio_button_uncheckedshort_text13. Revisión de la evaluación y decisiones de examen

Resumen del tema

LoadBalancer expone, requests afecta la programación, etiquetas conectan Service y Pods, --previous recupera el fallo anterior y replicas controla copias.

radio_button_uncheckedshort_text14. Lista de producción y referencias oficiales

• Usa etiquetas de imagen inmutables y valida autenticación AKS-registro.
• Mantén secretos fuera de Git y referencia Secrets o una solución externa.
• Define solicitudes, límites, réplicas y sondeos a partir de pruebas.
• Haz coincidir etiquetas y selectores y valida port con targetPort.
• Observa Pods, disponibilidad, endpoints, eventos, registros, salud, preparación e inferencia.
• Prefiere exposición privada, TLS, Ingress, directivas de red y privilegio mínimo cuando proceda.

1. Azure Kubernetes Service documentation
2. AKS core concepts
3. Deploy an application to AKS
4. Services in Azure Kubernetes Service
5. Authenticate AKS with Azure Container Registry
6. Troubleshoot image pull errors in AKS
7. kubectl command reference

Resumen del tema

La preparación de producción combina imágenes repetibles, acceso mínimo, recursos y sondeos demostrados, red estable y observabilidad por capas respaldada por documentación actual.