Implementar contenedores en el Servicio de Aplicaciones de Azure: runtime, configuración, diagnóstico y solución de problemas

radio_button_uncheckedshort_text1. De una imagen portátil a una aplicación web de producción

El contenedor hace que un procesador de documentos con IA se comporte igual en desarrollo, pruebas y producción, pero la imagen no aporta infraestructura, escalado, enrutamiento, secretos ni diagnóstico. El Servicio de Aplicaciones de Azure proporciona esa capa administrada. El equipo publica una imagen Linux, inyecta valores por entorno durante la ejecución y opera el servicio sin administrar hosts.

El ejemplo recibe documentos, extrae texto y metadatos y devuelve datos estructurados. La demanda sube en horario laboral, producción usa Storage y credenciales de API, y los errores deben clasificarse entre pull, inicio, configuración, estado y aplicación.

• Implementar imágenes desde Azure Container Registry u otro registro compatible.
• Configurar inicio, puerto HTTP, almacenamiento compartido, Always On y comprobación de estado.
• Proporcionar configuración, cadenas de conexión, valores por ranura y referencias de Key Vault.
• Usar registros, sitio SCM/Kudu, Azure Monitor y SSH opcional.

Resumen del tema

El Servicio de Aplicaciones convierte una imagen portátil en una aplicación operada al agregar proceso, configuración, escalado, enrutamiento y diagnóstico.

radio_button_uncheckedshort_text2. Orígenes de imagen e implementación en el portal

Una aplicación web para contenedores obtiene su imagen de un registro. Azure Container Registry es la opción natural de producción cuando se requiere identidad de Azure, red privada, replicación geográfica, integración de análisis y control por roles. La opción genérica admite Docker Hub, GitHub Container Registry y registros propios compatibles con Docker Registry HTTP API V2 por HTTPS; una imagen pública no necesita credenciales.

1. Elige suscripción, grupo de recursos, región y nombre globalmente único.
2. Selecciona Contenedor y Linux.
3. Selecciona o crea un plan del Servicio de Aplicaciones.
4. En la pestaña de contenedor, define registro, autenticación, repositorio, imagen y etiqueta explícita.
5. Revisa, crea y valida el nombre de host predeterminado.

En la misma suscripción, el portal puede enumerar registros, repositorios y etiquetas. En otros registros privados, indica URL, usuario y contraseña. Prefiere una etiqueta única y probada en vez de latest.

Resumen del tema

Elige registro, referencia determinista, plan y autenticación; el Servicio de Aplicaciones aprovisiona el runtime y obtiene la imagen.

radio_button_uncheckedshort_text3. Autenticación del registro con identidad administrada

La identidad administrada es la opción recomendada porque evita contraseñas almacenadas. La asignada por el sistema sigue el ciclo de vida de la aplicación. La asignada por el usuario es un recurso independiente que puede prepararse antes y compartirse intencionadamente.

Asigna solo AcrPull en el registro o en el menor ámbito compatible y habilita el uso de esa identidad. Las credenciales administrativas facilitan algunos laboratorios, pero crean un secreto duradero y exigen rotación y auditoría.

az webapp identity assign --resource-group myResourceGroup --name myDocumentProcessor

ACR_ID=$(az acr show --resource-group myResourceGroup --name myregistry --query id -o tsv)
PRINCIPAL_ID=$(az webapp identity show --resource-group myResourceGroup --name myDocumentProcessor --query principalId -o tsv)
az role assignment create --assignee $PRINCIPAL_ID --scope $ACR_ID --role AcrPull

az webapp config set --resource-group myResourceGroup --name myDocumentProcessor \
  --generic-configurations '{"acrUseManagedIdentityCreds": true}'

az webapp config container set --resource-group myResourceGroup --name myDocumentProcessor \
  --container-image-name myregistry.azurecr.io/docprocessor:v1

Con un punto de conexión privado, también se necesitan integración de red virtual, DNS funcional y vnetImagePullEnabled para dirigir el pull por la red virtual.

Resumen del tema

Identidad administrada más AcrPull elimina credenciales; un registro privado también depende de red y DNS.

radio_button_uncheckedshort_text4. CLI, Visual Studio Code, actualizaciones y entrega continua

La CLI de Azure sirve para scripts y CI/CD porque deja explícitos recurso, plan, imagen y etiqueta. Visual Studio Code con extensiones Docker y Servicio de Aplicaciones ofrece un flujo guiado. En producción, identidad y roles deben comprobarse por separado.

Al cambiar la referencia, el servicio reinicia las instancias y obtiene la nueva imagen. Cada reinicio ejecuta un pull, pero descarga solo capas modificadas si existe caché. Una nueva instancia, cambio de host o nivel puede requerir la descarga completa, por lo que el tamaño afecta a la preparación.

Reutilizar una etiqueta no crea por sí solo una versión. Reinicia o habilita implementación continua para que un push invoque el webhook. La canalización debe compilar, probar, publicar una versión inmutable, actualizar, esperar la preparación y conservar datos de reversión.

az webapp config container set -g myResourceGroup -n myDocumentProcessor \
  --container-image-name myregistry.azurecr.io/docprocessor:v2
az webapp deployment container config -g myResourceGroup -n myDocumentProcessor --enable-cd true

Resumen del tema

Automatiza cambios explícitos de versión y conecta los pushes con una liberación probada, observable y reversible.

radio_button_uncheckedshort_text5. Comando de inicio y puerto HTTP

El Servicio de Aplicaciones respeta ENTRYPOINT y CMD. Un comando personalizado puede agregar argumentos, ejecutar inicialización o sustituir valores del framework. Reemplaza CMD, no ENTRYPOINT. Usa shell solo si necesitas operadores como &&.

La documentación actual supone el puerto 80. Si el proceso escucha en otro, define WEBSITES_PORT. La plataforma termina TLS y reenvía HTTP a un solo puerto; el proceso debe enlazarse a 0.0.0.0 y no solo a localhost. EXPOSE no sustituye esta configuración.

az webapp config set --resource-group myResourceGroup --name myDocumentProcessor \
  --startup-file "gunicorn --bind=0.0.0.0:8000 --workers=4 app:application"

az webapp config appsettings set --resource-group myResourceGroup --name myDocumentProcessor \
  --settings WEBSITES_PORT=8000 WEBSITES_ENABLE_APP_SERVICE_STORAGE=true

az webapp config set --resource-group myResourceGroup --name myDocumentProcessor \
  --always-on true --generic-configurations '{"healthCheckPath":"/health"}'

Resumen del tema

Mantén los valores de la imagen cuando sea posible; si cambias CMD, alinea WEBSITES_PORT y escucha en todas las interfaces.

radio_button_uncheckedshort_text6. Almacenamiento persistente, Always On y estado

La capa escribible es efímera. Habilitar el almacenamiento del Servicio de Aplicaciones hace que /home sea persistente y compartido; /home/LogFiles guarda registros accesibles. Planea la cuota del plan y monta Storage cuando capacidad, uso compartido o I/O superen el volumen incorporado.

Always On evita la inactividad y reduce arranques en frío. Está disponible desde Básico y ayuda a API de producción, imágenes grandes e inicio lento. El escalado aún crea instancias, por lo que siguen siendo necesarias imágenes pequeñas.

La comprobación de estado llama a una ruta. Devuelve 200 solo cuando la instancia puede atender. Los fallos repetidos la quitan del balanceador. La ruta configurada debe coincidir exactamente con el endpoint y el cambio reinicia la aplicación.

@app.route('/health')
def health_check():
    try:
        db.execute('SELECT 1')
        storage.list_containers()
        return {'status': 'healthy'}, 200
    except Exception:
        return {'status': 'unhealthy'}, 503

Resumen del tema

Usa /home para persistencia prevista, Always On contra inactividad y una ruta de estado coincidente.

radio_button_uncheckedshort_text7. Configuración de aplicaciones y cadenas de conexión

La configuración son pares cifrados que se inyectan como variables de entorno. Así cada entorno usa la misma imagen. Emplea letras, números y guiones bajos; las claves .NET anidadas en Linux usan doble guion bajo, por ejemplo ConnectionStrings__DefaultConnection.

Las cadenas agregan prefijos: SQLCONNSTR_, SQLAZURECONNSTR_, MYSQLCONNSTR_, POSTGRESQLCONNSTR_ o CUSTOMCONNSTR_. Los runtimes no .NET suelen preferir configuración común porque no aprovechan esos prefijos.

az webapp config appsettings set --resource-group myResourceGroup --name myDocumentProcessor \
  --settings STORAGE_ACCOUNT_NAME=mystorageaccount LOG_LEVEL=INFO MAX_DOCUMENT_SIZE_MB=50

az webapp config connection-string set --resource-group myResourceGroup --name myDocumentProcessor \
  --connection-string-type SQLAzure \
  --settings DefaultConnection="Server=myserver.database.windows.net;Database=mydb;..."

az webapp config appsettings set --resource-group myResourceGroup --name myDocumentProcessor \
  --settings API_KEY="@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/api-key)"

Resumen del tema

Inyecta valores por entorno sin reconstruir y usa cadenas tipadas solo si el runtime espera sus prefijos.

radio_button_uncheckedshort_text8. Edición masiva, ranuras y referencias de Key Vault

Exporta muchos valores como JSON, revísalos y vuelve a aplicarlos. El portal también ofrece edición avanzada. No confirmes secretos reales en el repositorio.

Las ranuras ejecutan versiones separadas en el mismo plan. Un intercambio mueve código y gran parte de la configuración, pero los valores marcados como propios de la ranura permanecen. Identificadores, endpoints, bases de datos, características, diagnóstico detallado y la mayoría de referencias de Key Vault deben fijarse al entorno cuando un intercambio sería peligroso.

Una referencia de Key Vault entrega el secreto como variable normal sin cambiar el código. Habilita identidad administrada y concede lectura, preferiblemente el rol Key Vault Secrets User. Sin versión, sigue la más reciente; la caché se actualiza en 24 horas y un cambio de configuración o actualización explícita fuerza una resolución anterior.

az webapp config appsettings list -g myResourceGroup -n myDocumentProcessor -o json > settings.json
az webapp config appsettings set -g myResourceGroup -n myDocumentProcessor --settings @settings.json
az webapp config appsettings set -g myResourceGroup -n myDocumentProcessor --slot staging \
  --settings ENVIRONMENT=staging API_ENDPOINT=https://api-staging.example.com \
  --slot-settings ENVIRONMENT API_ENDPOINT

Resumen del tema

Trata la configuración como datos revisables, fija valores por entorno y guarda secretos administrados en Key Vault.

radio_button_uncheckedshort_text9. Registros de contenedor, flujo y sitio SCM/Kudu

La plataforma captura stdout y stderr: aplicación, excepciones, framework, solicitudes y ciclo de vida. Escribe registros estructurados sin credenciales ni documentos. El sistema de archivos expone la salida en /home/LogFiles para diagnóstico breve.

az webapp log config --resource-group myResourceGroup --name myDocumentProcessor \
  --docker-container-logging filesystem

az webapp log tail --resource-group myResourceGroup --name myDocumentProcessor

El flujo muestra entradas en tiempo real e identifica instancias. El sitio https://<app-name>.scm.azurewebsites.net ofrece Environment, archivos montados, descargas y volcado de diagnóstico. Es un sitio auxiliar, no el contenedor, y no muestra todos los procesos ni rutas efímeras.

Resumen del tema

Envía salida a stdout/stderr, síguela en incidentes y usa Kudu para variables, archivos y paquetes de diagnóstico.

radio_button_uncheckedshort_text10. Azure Monitor, Log Analytics y SSH opcional

Los registros locales no bastan para retención. La configuración de diagnóstico envía AppServiceConsoleLogs, AppServiceHTTPLogs, AppServicePlatformLogs y AppServiceAppLogs a Azure Monitor, Log Analytics, Event Hubs o Storage. Así se habilitan Kusto, alertas, libros, paneles, retención y correlación.

RESOURCE_ID=$(az webapp show -g myResourceGroup -n myDocumentProcessor --query id -o tsv)
WORKSPACE_ID=$(az monitor log-analytics workspace show -g myResourceGroup -n myWorkspace --query id -o tsv)

az monitor diagnostic-settings create --resource "$RESOURCE_ID" \
  --name appServiceDiagnostics --workspace "$WORKSPACE_ID" \
  --logs '[{"category":"AppServiceConsoleLogs","enabled":true},{"category":"AppServiceHTTPLogs","enabled":true}]'

AppServiceConsoleLogs
| where TimeGenerated > ago(1h)
| where ResultDescription has_any ("error", "exception", "failed")
| project TimeGenerated, _ResourceId, ResultDescription
| order by TimeGenerated desc

SSH es opcional y debe incorporarse en la imagen con OpenSSH, puerto 2222 y la configuración exigida. La sesión entra en una instancia y los cambios desaparecen al reiniciar. Úsalo para inspección puntual, no para implementar.

Resumen del tema

Exporta categorías para análisis y alertas duraderos; reserva SSH para investigación temporal dentro de una instancia.

radio_button_uncheckedshort_text11. Árbol de solución de problemas

Reproduce localmente con valores no secretos y avanza por capas: imagen y registro, configuración, preparación, enrutamiento y dependencias. No atribuyas todos los errores HTTP al código.

Resumen del tema

Diagnostica por capas: pull, inicio, configuración, puerto, enlace, estado, ruta, almacenamiento y dependencias.

radio_button_uncheckedshort_text12. Laboratorio guiado: imagen privada en Servicio de Aplicaciones

El ejercicio estima 30 minutos y necesita permisos de implementación y roles, CLI actual, Visual Studio Code y Python 3.12 opcional. El material indica que ACR Tasks puede no estar disponible con créditos gratuitos; confirma elegibilidad y costes actuales.

1. Crea una API con /health y endpoint de prueba.
2. Crea grupo y Azure Container Registry; compila una etiqueta explícita.
3. Crea plan Linux y aplicación web.
4. Habilita identidad, AcrPull y pull administrado.
5. Configura WEBSITES_PORT, valores, almacenamiento, Always On y estado.
6. Habilita registros y observa el inicio.
7. Prueba host y endpoint; valida valores no sensibles en Kudu.
8. Publica una etiqueta nueva, actualiza y documenta reversión.
9. Elimina el grupo si no contiene activos compartidos.

az group create -n rg-ai200-appservice-lab -l eastus
az acr create -g rg-ai200-appservice-lab -n <registro-unico> --sku Basic
az acr build -r <registro-unico> -t docprocessor:v1 .
az appservice plan create -g rg-ai200-appservice-lab -n plan-ai200 --is-linux --sku B1
az webapp create -g rg-ai200-appservice-lab -p plan-ai200 -n <aplicacion-unica> \
  --container-image-name <registro>.azurecr.io/docprocessor:v1

Resumen del tema

El laboratorio prueba compilación, pull privado, runtime, configuración externa, estado, registros, prueba, actualización y limpieza.

radio_button_uncheckedshort_text13. Evaluación reescrita y explicada

Resumen del tema

Asocia puerto, persistencia, afinidad de ranura, ruta de estado e inspección con su control de plataforma.

radio_button_uncheckedshort_text14. Revisión final y referencias de Microsoft

• Servicio de Aplicaciones obtiene la imagen y administra el runtime.
• Identidad administrada con AcrPull es la autenticación preferida.
• Inicio, puerto, almacenamiento, Always On y estado determinan la ejecución.
• Configuración y Key Vault mantienen entorno y secretos fuera de la imagen.
• Registros, Kudu, Azure Monitor, Log Analytics y SSH forman el diagnóstico.
• La liberación termina tras preparación, prueba, observabilidad y reversión.

1. Microsoft Learn: módulo Implementar contenedores en Servicio de Aplicaciones
2. Configurar un contenedor personalizado
3. Implementación continua de contenedores
4. Configurar la aplicación y cadenas
5. Usar referencias de Key Vault
6. Configurar ranuras de implementación
7. Habilitar registros de diagnóstico
8. Supervisar Servicio de Aplicaciones

Resumen del tema

Un contenedor listo para producción combina implementación determinista, acceso por identidad, runtime explícito, configuración externa y observabilidad duradera.