Compartir vía

Inicio rápido: Uso de Azure App Configuration en Azure Kubernetes Service

En Kubernetes, puede configurar pods para consumir datos de configuración de ConfigMaps. Esta práctica mejora la portabilidad de las aplicaciones, ya que puede desacoplar los datos de configuración de las imágenes de contenedor.

El proveedor de Kubernetes de Azure App Configuration ofrece una manera de construir ConfigMaps y secretos de Kubernetes a partir de valores clave y referencias de Azure Key Vault que se almacenan en App Configuration. Al usar este proveedor, puede usar App Configuration para almacenar y administrar de forma centralizada los datos de configuración sin realizar cambios en el código de la aplicación.

ConfigMap se puede consumir como variable de entorno o como un archivo montado. En este inicio rápido, incorporará el proveedor de Kubernetes de Azure App Configuration en la carga de trabajo de AKS. El proveedor crea un objeto ConfigMap a partir de datos en el almacén de App Configuration. En la carga de trabajo, ejecutará una aplicación básica de ASP.NET Core en un pod que consume ConfigMap como un archivo JSON montado en un volumen de datos.

Sugerencia

Para conocer otras formas de acceder a App Configuration desde una carga de trabajo hospedada en Kubernetes, consulte Acceso de Azure Kubernetes Service a App Configuration.

Nota:

Este inicio rápido le guía a través de la configuración del proveedor de Kubernetes de Azure App Configuration. Opcionalmente, puede usar los siguientes comandos de la CLI para desarrolladores de Azure para aprovisionar recursos de Azure e implementar la aplicación de ejemplo que usa este inicio rápido. Estos comandos usan la azure-appconfig-aks plantilla para este propósito. Para más información sobre esta plantilla, consulte el repositorio de GitHub azure-appconfig-aks .

azd init -t azure-appconfig-aks
azd up

Requisitos previos

Creación de una aplicación que se ejecuta en AKS

En esta sección, creará una aplicación web básica ASP.NET Core que se ejecuta en AKS. La aplicación lee los datos de configuración de un archivo JSON local. En la sección siguiente, habilitará la aplicación para que consuma datos de configuración desde App Configuration sin cambiar el código de la aplicación.

Si ya tiene una aplicación de AKS que lee la configuración de un archivo, puede omitir esta sección y ir a Uso del proveedor de Kubernetes de Azure App Configuration. Si omite esta sección, asegúrese de que el archivo de configuración que genera el proveedor coincide con la ruta de acceso de archivo que usa la aplicación.

Crear una aplicación

  1. Use la interfaz de línea de comandos (CLI) de .NET para ejecutar el siguiente comando. Crea un proyecto de aplicación web ASP.NET Core en un nuevo directorio MyWebApp .

    dotnet new webapp --output MyWebApp --framework net8.0

  2. En el directorio MyWebApp , vaya al directorio Pages y abra Index.cshtml. Reemplace el contenido por el código siguiente:

    @page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
@{
    ViewData["Title"] = "Home page";
}

<style>
    h1 {
        color: @Configuration["Settings:FontColor"];
    }
</style>

<div class="text-center">
    <h1>@Configuration["Settings:Message"]</h1>
</div>

  3. Cree un directorio de configuración en la raíz del proyecto. En el directorio config , agregue un archivo mysettings.json que contenga el siguiente contenido:

    {
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}

  4. En el directorio raíz del proyecto, abra Program.cs y agregue el archivo JSON al origen de configuración llamando al AddJsonFile método .

    // Existing code in Program.cs
// ... ...

// Add a JSON configuration source.
builder.Configuration.AddJsonFile("config/mysettings.json", reloadOnChange: true, optional: false);

var app = builder.Build();

// The rest of the existing code in Program.cs
// ... ...

Incluir la aplicación en contenedores

  1. Para compilar la aplicación en modo de versión y crear los recursos en el directorio publicado , ejecute el comando dotnet publish .

    dotnet publish -c Release -o published

  2. Cree un archivo denominado Dockerfile en la raíz del directorio de su proyecto, ábralo en un editor de texto y escriba el siguiente contenido. Un Dockerfile es un archivo de texto que no tiene una extensión. Se usa para crear una imagen de contenedor.

    FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]

  3. Compile una imagen de contenedor denominada aspnetapp mediante la ejecución del comando siguiente:

    docker build --tag aspnetapp .

Inserción de la imagen en Container Registry

  1. Para iniciar sesión en el registro de contenedor, ejecute el comando az acr login . El código siguiente inicia sesión en un registro denominado myregistry. Reemplace ese nombre del Registro por el nombre del registro.

    az acr login --name myregistry

    El comando devuelve Login Succeeded si inicia sesión correctamente.

  2. Para crear una etiqueta denominada myregistry.azurecr.io/aspnetapp:v1 para la aspnetapp imagen, use el comando docker tag . Reemplace por myregistry el nombre del registro.

    docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1

    Sugerencia

    Para revisar la lista de las etiquetas e imágenes de Docker existentes, ejecute docker image ls. En este escenario, la salida debe enumerar al menos dos imágenes: aspnetapp y myregistry.azurecr.io/aspnetapp.

  3. Para cargar la imagen en el registro de contenedor, use el comando docker push . Por ejemplo, el siguiente comando inserta la imagen en un repositorio denominado aspnetapp con etiqueta v1 en el Registro myregistry:

    docker push myregistry.azurecr.io/aspnetapp:v1

Implementación de la aplicación

  1. Cree un directorio de Implementación en el directorio raíz del proyecto.

  2. Para definir una implementación, agregue un archivo deployment.yaml con el siguiente contenido al directorio Deployment . Reemplace el valor de template.spec.containers.image por la etiqueta que creó en la sección anterior.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp-demo
  labels:
    app: aspnetapp-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspnetapp-demo
  template:
    metadata:
      labels:
        app: aspnetapp-demo
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80

  3. Para definir un LoadBalancer servicio, agregue un archivo service.yaml con el siguiente contenido al directorio Implementación :

    apiVersion: v1
kind: Service
metadata:
  name: aspnetapp-demo-service
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: aspnetapp-demo

  4. Para que kubectl pueda conectarse al clúster de AKS, ejecute el siguiente comando. Descarga las credenciales del clúster de AKS y las combina en el contexto del clúster.

    az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>

  5. Para implementar la aplicación en el clúster de AKS y crear los recursos, ejecute los siguientes comandos:

    kubectl create namespace appconfig-demo
kubectl apply -f ./Deployment -n appconfig-demo

  6. Para obtener la dirección IP externa expuesta por el LoadBalancer servicio, ejecute el siguiente comando:

    kubectl get service aspnetapp-demo-service -n appconfig-demo

  7. En una ventana del explorador, vaya a la dirección IP que obtuvo en el paso anterior. La página web debe ser similar a la siguiente captura de pantalla:

    Captura de pantalla de un explorador que muestra la página web de una aplicación. La página contiene texto que indica Mensaje de la configuración local.

Uso del proveedor de Kubernetes de Azure App Configuration

Ahora que tiene una aplicación que se ejecuta en AKS, el siguiente paso es implementar el proveedor de Kubernetes de Azure App Configuration en el clúster de AKS para que se ejecute como un controlador de Kubernetes. El proveedor recupera datos del almacén de App Configuration y crea un ConfigMap, que se puede consumir como archivo JSON montado en un volumen de datos.

Configuración del almacén de App Configuration

Agregue las siguientes claves y valores al almacén de App Configuration. Para cada uno de ellos, use valores predeterminados para Label y Content Type. Para más información sobre cómo agregar valores de clave a un almacén mediante Azure Portal o la CLI de Azure, consulte Creación de un valor de clave.

Clave Valor
Configuración:Color de fuente Verde
Configuración:Mensaje Hola desde Azure App Configuration

Configuración del proveedor de Kubernetes de Azure App Configuration

  1. Instale el proveedor de Kubernetes de Azure App Configuration en el clúster de AKS. Puede instalar el proveedor como una extensión de AKS o mediante un gráfico de Helm. La extensión de AKS proporciona una instalación y administración sin problemas a través de la CLI de Azure, plantillas de Azure Resource Manager (plantillas de ARM) o archivos de Bicep. Además, el uso de la extensión de AKS facilita las actualizaciones automáticas de versiones secundarias y de revisión, lo que ayuda a garantizar que el sistema permanece actualizado.

    Agregue a las extensiones de la k8s-extension CLI de Azure.

    az extension add --name k8s-extension

    Registre el proveedor de KubernetesConfiguration recursos.

    az provider register --namespace Microsoft.KubernetesConfiguration

    Instale la extensión de AKS para App Configuration. Reemplace los cluster-name valores de parámetro y resource-group por los valores correspondientes de la instancia de AKS. De forma predeterminada, el proveedor se instala en el azappconfig-system espacio de nombres .

    az k8s-extension create --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --name appconfigurationkubernetesprovider \
    --extension-type Microsoft.AppConfiguration

    Para más información, consulte Instalación de la extensión de AKS de Azure App Configuration.

  2. Para definir un AzureAppConfigurationProvider recurso, agregue un archivo appConfigurationProvider.yaml con el siguiente contenido al directorio Deployment . AzureAppConfigurationProvider es un recurso personalizado. Define los datos que se van a descargar desde un almacén de App Configuration. También crea un objeto ConfigMap.

    apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData: 
      type: json
      key: mysettings.json
  auth:
    workloadIdentity:
      serviceAccountName: <your-service-account-name>

    Reemplace el valor del campo endpoint por el punto de conexión del almacén de Azure App Configuration. Continúe con el paso siguiente para actualizar la sección auth con la información de autenticación.

    Nota:

    AzureAppConfigurationProvider es un objeto de API declarativo. Define el estado deseado de ConfigMap que se crea a partir de los datos del almacén de App Configuration. La definición del estado deseado especifica el siguiente comportamiento:

    • Se produce un error en la creación de ConfigMap si ya existe un objeto ConfigMap con el mismo nombre en el mismo espacio de nombres.
    • ConfigMap se restablece en función de los datos presentes en el almacén de App Configuration si se elimina o modifica por cualquier otro medio.
    • ConfigMap se elimina si se desinstala el proveedor de Kubernetes de Azure App Configuration.

  3. Para autenticarse con el almacén de App Configuration, siga las instrucciones para usar la identidad de carga de trabajo. Actualice el archivo appConfigurationProvider.yaml reemplazando el serviceAccountName campo por el nombre de la cuenta de servicio que cree al seguir las instrucciones. Para obtener más información sobre otros métodos de autenticación, consulte los ejemplos de Autenticación.

  4. Como se muestra en el código siguiente, actualice el archivo deployment.yaml en el directorio Deployment para usar ConfigMap configmap-created-by-appconfig-provider como volumen de datos montado. Es importante que el volumeMounts.mountPath valor coincida con el WORKDIR valor especificado en dockerfile y el directorio de configuración que creó anteriormente. Además, asegúrese de que el valor de template.spec.containers.image coincide con el nombre de la imagen que creó anteriormente.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp-demo
  labels:
    app: aspnetapp-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspnetapp-demo
  template:
    metadata:
      labels:
        app: aspnetapp-demo
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /app/config
      volumes:
      - name: config-volume 
        configMap: 
          name: configmap-created-by-appconfig-provider

  5. Para implementar los cambios, ejecute el siguiente comando. Actualice el espacio de nombres si usa la aplicación de AKS existente.

    kubectl apply -f ./Deployment -n appconfig-demo

  6. Actualice el explorador. La página muestra el contenido actualizado.

    Captura de pantalla de un explorador que muestra la página web de una aplicación. La página contiene texto verde que indica Hola desde Azure App Configuration.

Solución de problemas

Si la aplicación no lee los datos del almacén de App Configuration, ejecute el siguiente comando para comprobar que ConfigMap se ha creado correctamente:

kubectl get configmap configmap-created-by-appconfig-provider -n appconfig-demo

Si no se crea configMap, ejecute el siguiente comando para obtener el estado de recuperación de datos:

kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

Si el proveedor de Kubernetes de Azure App Configuration recupera datos del almacén de App Configuration correctamente, la phase propiedad de la status sección de la salida debe ser Complete, como se muestra en el ejemplo siguiente:

$ kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
  ... ... ...
status:
  lastReconcileTime: "2025-08-04T13:58:02Z"
  lastSyncTime: "2025-08-04T13:58:02Z"
  message: Complete sync key-values from App Configuration to target ConfigMap or
    Secret.
  phase: Complete

Si la propiedad phase no COMPLETEes , los datos no se descargan del almacén de App Configuration correctamente. Para acceder a los registros del proveedor de Kubernetes de Azure App Configuration, ejecute el siguiente comando:

kubectl logs deployment/az-appconfig-k8s-provider -n azappconfig-system

Uso de registros para solución de problemas adicional. Para obtener soluciones a problemas comunes, consulte Preguntas más frecuentes.

Preguntas más frecuentes

¿Por qué no se está generando el ConfigMap o el Secret?

Para recopilar registros que contienen información detallada sobre errores, siga los pasos descritos en Solución de problemas. Estas son algunas causas comunes de este problema:

  • RESPUESTA 403: 403 Prohibido: la identidad configurada carece de los permisos necesarios para acceder al almacén de App Configuration. Para obtener ejemplos que coincidan con la identidad que usa, consulte Autenticación.
  • Se encuentra una referencia de Key Vault en App Configuration, pero "spec.secret" no se configuró: una o varias referencias de Key Vault se incluyen en los valores de clave seleccionados, pero no se proporciona la información de autenticación de Key Vault. Para mantener la integridad de la configuración, no se carga toda la configuración. Configure la sección spec.secret para proporcionar la información de autenticación necesaria. Para obtener ejemplos y más información, consulte Referencias de Key Vault .

¿Por qué el objeto ConfigMap no contiene los datos esperados?

Asegúrese de que los selectores de clave-valor que especifique coincidan con los datos esperados. Si no especifica ningún selector, todos los valores de clave sin una etiqueta se descargan desde el almacén de App Configuration. Cuando use un filtro de clave, compruebe que coincide con el prefijo de los valores de clave esperados. Si los valores de clave tienen etiquetas, asegúrese de especificar el filtro de etiqueta en los selectores. Para obtener más ejemplos, consulte Selección de clave-valor.

¿Cómo puedo personalizar la instalación del proveedor de Kubernetes de Azure App Configuration?

Puede personalizar la instalación proporcionando valores adicionales de Helm al instalar el proveedor de Kubernetes de Azure App Configuration. Por ejemplo, puede establecer el nivel de registro, configurar el proveedor para que se ejecute en un nodo concreto o deshabilitar la identidad de la carga de trabajo. Para obtener más información, consulte Instalación.

¿Cómo puedo desencadenar una actualización a petición de ConfigMap y Secret?

Puede configurar los datos para que se actualicen automáticamente. Pero hay ocasiones en las que es posible que quiera desencadenar una actualización a petición para obtener los datos más recientes de App Configuration y Key Vault. Para desencadenar una actualización, puede modificar la metadata.annotations sección de AzureAppConfigurationProvider. A continuación, el proveedor de Kubernetes actualiza ConfigMap y Secret con los datos más recientes del almacén de App Configuration y Key Vault. Para obtener un ejemplo, consulte Actualización a petición.

No se recomienda eliminar ni modificar configMap y secret generados por el proveedor de Kubernetes. Los nuevos se generan a partir de los datos más recientes, pero esta situación puede provocar tiempo de inactividad para las aplicaciones durante los errores.

¿Por qué no puedo autenticar con App Configuration mediante la identidad de carga de trabajo después de actualizar el proveedor a la versión 2.0.0?

A partir de la versión 2.0.0, se requiere una cuenta de servicio proporcionada por el usuario para autenticarse con App Configuration mediante la identidad de carga de trabajo. Este cambio mejora la seguridad mediante el aislamiento del espacio de nombres. Anteriormente, se usaba una cuenta de servicio del proveedor de Kubernetes para todos los espacios de nombres. Para obtener instrucciones actualizadas, consulte la documentación sobre el uso de la identidad de carga de trabajo. Si necesita tiempo para migrar a la versión 2.0.0, puede usar temporalmente la configuración durante la workloadIdentity.globalServiceAccountEnabled=true instalación del proveedor. Tenga en cuenta que la compatibilidad con el uso de la cuenta de servicio del proveedor está programada para desuso en una versión futura.

Limpieza de recursos

Si desea desinstalar el proveedor de Kubernetes de Azure App Configuration, pero mantener el clúster de AKS, use el siguiente comando para desinstalar el proveedor:

az k8s-extension delete --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --name appconfigurationkubernetesprovider

Si no quiere seguir usando los recursos que se han creado en este artículo, elimine el grupo de recursos que creó aquí para evitar cargos.

Importante

La eliminación de un grupo de recursos es irreversible. El grupo de recursos y todos los recursos que contiene se eliminan permanentemente. Asegúrese de que no elimina por accidente el grupo de recursos o los recursos equivocados. Si creó los recursos para este artículo en un grupo de recursos que contenga los recursos que desee conservar, elimine cada recurso de forma individual desde su panel respectivo, en lugar de eliminar el grupo de recursos.

  1. Inicie sesión en Azure Portal y después seleccione Grupos de recursos.
  2. En el cuadro de texto Filtrar por nombre, escriba el nombre del grupo de recursos.
  3. En la lista resultados, seleccione el nombre del grupo de recursos para ver la información general.
  4. Seleccione Eliminar grupo de recursos.
  5. Se le pedirá que confirme la eliminación del grupo de recursos. Escriba el nombre del grupo de recursos para confirmar y seleccione Eliminar.

Transcurridos unos instantes, el grupo de recursos y todos sus recursos se eliminan.

Nota:

Si usa la CLI para desarrolladores de Azure para configurar los recursos, puede ejecutar el comando azd down para eliminar todos los recursos creados por la plantilla azure-appconfig-aks.

Pasos siguientes

En esta guía de inicio rápido:

  • Ha creado una aplicación que se ejecuta en AKS.
  • Conecte el clúster de AKS al almacén de App Configuration mediante el proveedor de Kubernetes de Azure App Configuration.
  • Ha creado un objeto ConfigMap con datos del almacén de App Configuration.
  • Ejecutó la aplicación con datos de configuración desde el almacén de App Configuration sin cambiar el código de la aplicación.

Para averiguar cómo actualizar las cargas de trabajo de AKS para actualizar dinámicamente los datos de configuración, continúe con el siguiente tutorial.

Uso de la configuración dinámica en Azure Kubernetes Service

Para más información sobre el proveedor de Kubernetes de Azure App Configuration, consulte Referencia del proveedor de Kubernetes de Azure App Configuration.

  • Last updated on