Configuración del entorno de ejecución con variables de entorno y secretos

  • 7 minutos

Los servicios de inteligencia artificial suelen depender de sistemas externos y requieren muchas configuraciones en tiempo de ejecución. Normalmente, se configuran puntos de conexión, marcas de características y opciones de selección de modelos mediante variables de entorno. Puede controlar la configuración confidencial, como las claves de API, mediante secretos y referencias secretas.

Configura opciones no sensibles con variables de entorno

Las variables de entorno son una buena opción para la configuración no confidencial, como los niveles de registro, las marcas de características y las direcciones URL de dependencia. Este enfoque mantiene las imágenes de contenedor portátiles entre entornos porque puede ejecutar la misma imagen con valores de configuración diferentes. En el caso de las cargas de trabajo de IA, las variables de entorno también le ayudan a optimizar el comportamiento, como los tiempos de espera de solicitud y los tamaños de lote sin volver a generar imágenes.

Puede establecer variables de entorno durante la creación o puede agregarlas más adelante. En el ejemplo siguiente se usa --env-vars durante la creación.

az containerapp create -n ai-api -g rg-aca-demo \
    --environment aca-env-demo \
    --image myregistry.azurecr.io/ai-api:v1 \
    --ingress external --target-port 8000 \
    --env-vars LOG_LEVEL=info FEATURE_EMBEDDINGS=true

Si desea agregar o actualizar variables sin quitar las existentes, puede usar --set-env-vars durante una actualización.

az containerapp update -n ai-api -g rg-aca-demo \
    --set-env-vars LOG_LEVEL=debug

Almacenar configuración confidencial como secretos de Container Apps

Los secretos permiten mantener los valores confidenciales fuera de las imágenes de contenedor y del control de código fuente. La protección de valores confidenciales es importante para los servicios de inteligencia artificial, ya que las claves de API del proveedor, las credenciales de base de datos y las claves de firma giran periódicamente. Al almacenar los secretos por separado, puede rotar los secretos sin tener que regenerar ni redeployar la imagen.

Puede crear o actualizar secretos mediante az containerapp secret set. Los secretos se proporcionan como key=value pares.

az containerapp secret set -n ai-api -g rg-aca-demo \
    --secrets embeddings-api-key="REPLACE_WITH_REAL_VALUE"

Si necesita hacer referencia a Azure Key Vault, la CLI también admite un formato de referencia de Key Vault para secretos. Use este enfoque cuando quiera que Key Vault sea el sistema de registro y quiera que la aplicación contenedora capture el secreto en tiempo de ejecución.

Referenciar secretos desde variables de entorno

La mayoría de los marcos de trabajo de aplicaciones leen la configuración de las variables de entorno. Container Apps admite referencias secretas para que pueda asignar un secreto a una variable de entorno sin exponer el valor, que es un patrón común para las aplicaciones de IA que llaman a puntos de conexión de modelo externos.

Para hacer referencia a un secreto, establezca el valor de la variable de entorno en secretref:<secret-name>. En el ejemplo siguiente se establece EMBEDDINGS_API_KEY en el valor secreto.

az containerapp update -n ai-api -g rg-aca-demo \
    --set-env-vars EMBEDDINGS_API_KEY=secretref:embeddings-api-key

Uso de YAML para estandarizar la configuración en tiempo de ejecución

La configuración basada en YAML es útil cuando se desea una única fuente de verdad revisable para la configuración del entorno de ejecución. Esto es especialmente importante para los servicios de inteligencia artificial en los que los pequeños cambios de configuración pueden afectar al costo, la latencia y el flujo de datos. Un archivo YAML también se convierte en un artefacto estable para canalizaciones de CI y CD.

En el ejemplo siguiente se muestra un fragmento de YAML centrado que establece una variable de entorno no confidencial y una referencia secreta. Debe mantener los valores secretos fuera de los archivos YAML y almacenar solo los nombres secretos en el control de código fuente.

# Code fragment - focus on environment variables and secret references
properties:
  template:
    containers:
    - name: ai-api
      env:
      - name: LOG_LEVEL
        value: info
      - name: EMBEDDINGS_API_KEY
        secretRef: embeddings-api-key

Después de actualizar el archivo YAML, puede aplicarlo con az containerapp update --yaml. Este comando trata el archivo YAML como origen de configuración completo.

az containerapp update -n ai-api -g rg-aca-demo \
    --yaml ./containerapp.yml

Procedimientos recomendados para la configuración en tiempo de ejecución

La configuración en tiempo de ejecución debe reducir el riesgo y simplificar las operaciones. Puede usar los procedimientos siguientes para mantener la configuración manejable a medida que crece la solución de IA.

  • Separe la configuración de las imágenes: Use variables de entorno y secretos para que la misma imagen se pueda ejecutar en varios entornos.
  • Preferir referencias secretas: Use secretref: y secretRef , por tanto, los valores secretos no aparezcan en archivos YAML ni en el historial de shell.
  • Rotación intencionada de secretos: Actualice los secretos independientemente de las imágenes para que pueda responder rápidamente a los requisitos de rotación de credenciales.
  • Utilice YAML para la coherencia: Controle YAML en el sistema de gestión de código fuente para reducir el desfase y hacer cambios de configuración que se puedan revisar.

Recursos adicionales

Estos recursos proporcionan material de referencia más profundo sobre cómo Container Apps almacena secretos y los proyecta en los contenedores en tiempo de ejecución. Use la referencia de la CLI para az containerapp secret cuando necesite los formatos de secretos admitidos exactos, incluidas las referencias de Key Vault y los requisitos de identidad. Use el artículo de administración de secretos para obtener instrucciones operativas sobre las actualizaciones y la rotación.