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

En Kubernetes, configure pods para consumir la configuración de ConfigMaps. Permite desacoplar la configuración de las imágenes de contenedor, lo que hace que las aplicaciones sean fácilmente portables. El proveedor de Kubernetes de Azure App Configuration puede construir ConfigMaps y secretos a partir de sus valores de clave y referencias de Key Vault en Azure App Configuration. Permite aprovechar las ventajas de Azure App Configuration para centralizar el almacenamiento y la administración de la configuración sin que haya 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 una carga de trabajo de Azure Kubernetes Service en la que se ejecuta una aplicación ASP.NET Core sencilla que consume la configuración de un archivo JSON.

azd init -t azure-appconfig-aks
azd up

Requisitos previos

• Un almacén de App Configuration. Crear un almacén.
• Una instancia de Azure Container Registry. Cree un registro.
• Un clúster de Azure Kubernetes Service (AKS) al que se concede permiso para extraer imágenes de Azure Container Registry. Creación de un clúster de AKS.
• SDK de .NET 6.0 o versiones posteriores.
• CLI de Azure
• Docker Desktop
• helm
• kubectl

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

En esta sección, creará una aplicación web de ASP.NET Core sencilla que se ejecuta en Azure Kubernetes Service (AKS). La aplicación lee la configuración de un archivo JSON local. En la sección siguiente, lo habilitará para consumir la configuración desde Azure App Configuration sin cambiar el código de la aplicación. Si ya tiene una aplicación de AKS que lea la configuración de un archivo, puede omitir esta sección e ir a Uso del proveedor de Kubernetes de App Configuration. Solo tiene que asegurarse de que el archivo de configuración generado por el proveedor coincide con la ruta de acceso del archivo usada por la aplicación.

Crear una aplicación

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

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

2. Abra Index.cshtml en el directorio Pages y actualice el contenido con 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 y agregue un archivo mysettings.json al mismo con el siguiente contenido.

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

4. Abra program.cs y agregue el archivo JSON al origen de configuración, para lo que debe llamar al método AddJsonFile.

   // 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 existing code in program.cs
   // ... ...
   

Incluir la aplicación en contenedores

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

   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 y que se usa para crear una imagen de contenedor.

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

3. Ejecute el siguiente comando para compilar una imagen de contenedor denominada aspnetapp.

   docker build --tag aspnetapp .
   

Inserción de la imagen en Azure Container Registry

1. Ejecute el comando az acr login para iniciar sesión en el registro de contenedor. En el ejemplo siguiente se inicia sesión en un registro denominado myregistry. Reemplace el nombre del Registro por el suyo.

   az acr login --name myregistry
   

   El comando devuelve Login Succeeded una vez que el inicio de sesión es correcto.

2. Use la etiqueta docker para crear una etiqueta myregistry.azurecr.io/aspnetapp:v1 para la imagen aspnetapp.

   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, debería ver al menos dos imágenes: aspnetapp y myregistry.azurecr.io/aspnetapp.

3. Use docker push para cargar la imagen en el registro de contenedor. Por ejemplo, el siguiente comando inserta la imagen en un repositorio denominado aspnetapp con la 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. Agregue un archivo deployment.yaml al directorio Implementación con el siguiente contenido para crear una implementación. Reemplace el valor de template.spec.containers.image por la imagen que creó en el paso 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. Agregue un archivo service.yaml al directorio Implementación con el siguiente contenido para crear un servicio LoadBalancer.

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

4. Ejecute el siguiente comando para implementar la aplicación en el clúster de AKS.

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

5. Ejecute el siguiente comando y obtenga la dirección IP externa expuesta por el servicio LoadBalancer.

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

6. Abra una ventana del explorador y vaya a la dirección IP que obtuvo en el paso anterior. La página web tiene este aspecto:

   

Uso del proveedor de Kubernetes de App Configuration

Ahora que tiene una aplicación que se ejecuta en AKS, implementará el proveedor de Kubernetes de App Configuration en el clúster de AKS que se ejecuta como 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 Azure App Configuration

Agregue los siguientes pares clave-valor al almacén de App Configuration y deje Etiqueta y Tipo de contenido con sus valores predeterminados. Para obtener más información sobre cómo agregar pares clave-valor a un almacén mediante Azure Portal o la CLI, vaya a Creación de un par clave-valor.

Configuración del proveedor de Kubernetes de App Configuration

1. Para obtener las credenciales de acceso para su clúster de AKS, ejecute el siguiente comando. Reemplace el valor de los parámetros name y resource-group por la instancia de AKS:

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

2. Instale el proveedor de Kubernetes de Azure App Configuration en el clúster de AKS mediante helm:

   helm install azureappconfiguration.kubernetesprovider \
        oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
        --namespace azappconfig-system \
        --create-namespace
   

   Sugerencia

   El proveedor de Kubernetes de App Configuration también está disponible como extensión de AKS. Esta integración permite una instalación y administración perfectas a través de la CLI de Azure, las plantillas de ARM o las plantillas de Bicep. El uso de la extensión de AKS facilita las actualizaciones automáticas de versiones secundarias o de parches, lo que garantiza que el sistema esté siempre actualizado. Para obtener instrucciones detalladas sobre la instalación, consulte la extensión Azure App Configuration para Azure Kubernetes Service.

3. Agregue un archivo appConfigurationProvider.yaml al directorio Implementación con el siguiente contenido para crear un recurso AzureAppConfigurationProvider. AzureAppConfigurationProvider es un recurso personalizado que define los datos que se van a descargar desde un almacén de Azure App Configuration y 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 creado a partir de los datos del almacén de App Configuration con el siguiente comportamiento:

   • ConfigMap no se creará si ya existe un ConfigMap con el mismo nombre en el mismo espacio de nombres.
   • ConfigMap se restablecerá 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 eliminará si se desinstala el proveedor de Kubernetes de App Configuration.

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

5. Actualice el archivo deployment.yaml del directorio Implementación para usar ConfigMap configmap-created-by-appconfig-provider como volumen de datos montado. Es importante asegurarse de que volumeMounts.mountPath coincide con el WORKDIR especificado en Dockerfile y el directorio de configuración creado antes.

   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
   

6. Ejecute el siguiente comando para implementar los cambios. Reemplace el espacio de nombres si usa la aplicación de AKS existente.

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

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

   

Solución de problemas

Si no ve que la aplicación recoja los datos del almacén de App Configuration, ejecute el siguiente comando para validar que ConfigMap se crea correctamente.

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

Si configMap no se crea, 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 recuperó datos del almacén de App Configuration correctamente, la propiedad phase de la sección de estado 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: "2023-04-06T06:17:06Z"
  lastSyncTime: "2023-04-06T06:17:06Z"
  message: Complete sync settings to ConfigMap or Secret
  phase: COMPLETE

Si la fase no es COMPLETE, los datos no se descargan del almacén de App Configuration correctamente. Ejecute el siguiente comando para mostrar los registros del proveedor de Kubernetes de Azure App Configuration.

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

Uso de registros para solución de problemas adicional. Consulte la sección de preguntas más frecuentes para conocer los problemas comunes.

Preguntas más frecuentes

¿Por qué no se generan ConfigMap o Secret?

Puede seguir los pasos que se indican en la guía para la solución de problemas, con el fin de recopilar registros para obtener información detallada sobre los errores. Estas son algunas de las causas comunes.

• RESPUESTA 403: 403 Prohibido: la identidad configurada carece de los permisos necesarios para acceder al almacén de App Configuration. Consulte la sección Autenticación para ver ejemplos que coincidan con la identidad que usa.
• Se encuentra una referencia de Key Vault en App Configuration, pero "spec.secret" no estaba configurado: 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 las instancias 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 más información y ejemplos, consulte Referencia de Key Vault.

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

Asegúrese de especificar los selectores de valor de clave correctos para que coincidan con los datos esperados. Si no se especifica ningún selector, todos los valores de clave sin una etiqueta se descargarán desde el almacén de App Configuration. Cuando use un filtro 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 la documentación de la selección de valores de clave.

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

Para personalizar la instalación debe especificar 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 más información, consulte la guía de instalación.

¿Por qué no puedo autenticarme con Azure 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 Azure 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 establecer temporalmente workloadIdentity.globalServiceAccountEnabled=true durante la instalación del proveedor. Tenga en cuenta que la compatibilidad con el uso de la cuenta de servicio del proveedor quedará en desuso en una futura versión.

Limpieza de recursos

Desinstale el proveedor de Kubernetes de App Configuration del clúster de AKS si desea mantener el clúster de AKS.

helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system

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.

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.

Pasos siguientes

En esta guía de inicio rápido:

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

Para aprender a actualizar las cargas de trabajo de AKS para poner al día dinámicamente la configuración, continúe con el siguiente tutorial.

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