Merge pull request #53000 from MicrosoftDocs/NEW-configure-apps-azure-kubernetes-service

New configure apps azure kubernetes service module

Author: v-ccolin

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/1-introduction.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.configure-apps-azure-kubernetes-service.introduction
+title: Introduction
+metadata:
+  title: Introduction
+  description: Introduction
+  ms.date: 12/14/2025
+  author: jeffkoms
+  ms.author: jeffko
+  ms.topic: unit
+azureSandbox: false
+durationInMinutes: 3
+content: |
+  [!include[](includes/1-introduction.md)]

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/2-define-configmaps.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.configure-apps-azure-kubernetes-service.define-configmaps
+title: Define ConfigMaps for application settings
+metadata:
+  title: Define ConfigMaps for Application Settings
+  description: Define ConfigMaps for application settings
+  ms.date: 12/14/2025
+  author: jeffkoms
+  ms.author: jeffko
+  ms.topic: unit
+azureSandbox: false
+durationInMinutes: 10
+content: |
+  [!include[](includes/2-define-configmaps.md)]

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/3-implement-secrets.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.configure-apps-azure-kubernetes-service.implement-secrets
+title: Implement secrets for sensitive data
+metadata:
+  title: Implement Secrets for Sensitive Data
+  description: Implement secrets for sensitive data
+  ms.date: 12/14/2025
+  author: jeffkoms
+  ms.author: jeffko
+  ms.topic: unit
+azureSandbox: false
+durationInMinutes: 10
+content: |
+  [!include[](includes/3-implement-secrets.md)]

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/4-persistent-storage.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.configure-apps-azure-kubernetes-service.persistent-storage
+title: Attach persistent storage to an app
+metadata:
+  title: Attach Persistent Storage to an App
+  description: Attach persistent storage to an app
+  ms.date: 12/14/2025
+  author: jeffkoms
+  ms.author: jeffko
+  ms.topic: unit
+azureSandbox: false
+durationInMinutes: 12
+content: |
+  [!include[](includes/4-persistent-storage.md)]

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/5-exercise-configure-apps.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.configure-apps-azure-kubernetes-service.exercise-configure-apps
+title: Exercise - Configure apps on Azure Kubernetes Service
+metadata:
+  title: Exercise - Configure Apps on Azure Kubernetes Service
+  description: Exercise - Configure apps on Azure Kubernetes Service
+  ms.date: 12/14/2025
+  author: jeffkoms
+  ms.author: jeffko
+  ms.topic: unit
+azureSandbox: false
+durationInMinutes: 30
+content: |
+  [!include[](includes/5-exercise-configure-apps.md)]

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/6-module-assessment.yml

@@ -0,0 +1,70 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.configure-apps-azure-kubernetes-service.module-assessment
+title: Module assessment
+metadata:
+  title: Module Assessment
+  description: Module assessment
+  ms.date: 12/16/2025
+  author: jeffkoms
+  ms.author: jeffko
+  ms.topic: unit
+azureSandbox: false
+durationInMinutes: 5
+content: |
+quiz:
+  questions:
+  - content: "You need to store a database connection string for your application running on AKS. The connection string contains a password and shouldn't be visible in your source code repository. Which Kubernetes resource should you use?"
+    choices:
+    - content: "ConfigMap, because it stores configuration data"
+      isCorrect: false
+      explanation: "ConfigMaps are designed for nonsensitive configuration. While they keep data out of container images, they shouldn't be used for credentials or passwords."
+    - content: "Secret, because it stores sensitive values and keeps credentials out of source control"
+      isCorrect: true
+      explanation: "Secrets are the correct choice for storing sensitive values like connection strings with passwords. They keep credentials out of source control and can be protected with RBAC policies."
+    - content: "PersistentVolumeClaim, because it provides storage for application data"
+      isCorrect: false
+      explanation: "PersistentVolumeClaims provide durable filesystem storage, not a mechanism for storing and injecting credentials into Pods."
+  - content: "Your AI application reads feature flags and service endpoints from environment variables. You want to update these settings without rebuilding your container image. How should you inject these nonsensitive values into your Pods?"
+    choices:
+    - content: "Create a ConfigMap with the settings and reference the keys using configMapKeyRef in the Deployment"
+      isCorrect: true
+      explanation: "ConfigMaps are designed for nonsensitive configuration. Using configMapKeyRef lets you inject values as environment variables and update them without rebuilding images."
+    - content: "Store the values in a Secret and mount it as a volume"
+      isCorrect: false
+      explanation: "While this would work technically, Secrets are intended for sensitive data. ConfigMaps are the appropriate resource for nonsensitive configuration like feature flags."
+    - content: "Hardcode the values in the Deployment manifest and update the manifest when settings change"
+      isCorrect: false
+      explanation: "Hardcoding values in the Deployment manifest couples configuration to the deployment definition. ConfigMaps let you change settings independently of the Deployment."
+  - content: "You create a PersistentVolumeClaim in your AKS cluster. What happens when you apply the PVC manifest?"
+    choices:
+    - content: "You must manually create an Azure Disk in the Azure portal before the PVC can bind"
+      isCorrect: false
+      explanation: "AKS StorageClasses handle dynamic provisioning automatically. You don't need to manually create Azure storage resources."
+    - content: "AKS uses the specified StorageClass to automatically provision Azure storage that backs the PVC"
+      isCorrect: true
+      explanation: "AKS includes preconfigured StorageClasses that dynamically provision Azure Disk or Azure Files resources when you create a PVC. No manual storage creation is required."
+    - content: "The PVC remains unbound until you create a matching PersistentVolume manifest"
+      isCorrect: false
+      explanation: "With dynamic provisioning through StorageClasses, you don't need to manually create PersistentVolume manifests. AKS creates them automatically."
+  - content: "Your application needs to access API keys stored in a Kubernetes Secret. You want to make the keys available as environment variables in the container. Which field should you use in the Deployment manifest to reference the Secret?"
+    choices:
+    - content: "valueFrom with secretKeyRef"
+      isCorrect: true
+      explanation: "The valueFrom field with secretKeyRef is the correct way to inject Secret values as environment variables. This resolves the Secret key at Pod start time."
+    - content: "Volumes with secret type"
+      isCorrect: false
+      explanation: "This approach mounts the Secret as files in the container filesystem, not as environment variables. Use this when your application reads secrets from files."
+    - content: "configMapKeyRef pointing to the Secret name"
+      isCorrect: false
+      explanation: "configMapKeyRef is used to reference ConfigMaps, not Secrets. You must use secretKeyRef to reference Secret keys."
+  - content: "You need to decide between mounting a ConfigMap as environment variables or as files. Your application reads a JSON configuration file at startup. Which approach should you choose?"
+    choices:
+    - content: "Mount the ConfigMap as environment variables because all applications can read environment variables"
+      isCorrect: false
+      explanation: "While applications can read environment variables, this approach doesn't provide a JSON file on disk. The application expects a file, not environment variables."
+    - content: "Mount the ConfigMap as files using a volume so the JSON file appears on disk where the application expects it"
+      isCorrect: true
+      explanation: "When an application expects configuration files on disk, mount the ConfigMap as a volume. Each key becomes a file in the mount directory."
+    - content: "Store the JSON content in a Secret and use secretKeyRef to inject it as an environment variable"
+      isCorrect: false
+      explanation: "This approach doesn't match the requirement. The application needs a file on disk, not an environment variable. Also, Secrets are for sensitive data, and this appears to be nonsensitive configuration."

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/7-summary.yml

@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.configure-apps-azure-kubernetes-service.summary
+title: Summary
+metadata:
+  title: Summary
+  description: Summary
+  ms.date: 12/14/2025
+  author: jeffkoms
+  ms.author: jeffko
+  ms.topic: unit
+azureSandbox: false
+durationInMinutes: 2
+content: |
+  [!include[](includes/7-summary.md)]

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/includes/1-introduction.md

@@ -0,0 +1,14 @@
+AI applications on Azure need safe configuration, strong secret handling, and durable storage. These capabilities help you meet latency, reliability, and governance goals. Configuring applications on Azure Kubernetes Service (AKS) lets you externalize settings. You can also secure sensitive values and attach persistent storage for stateful AI workloads.
+
+Imagine you deploy an AI inference API that serves models at scale. The service needs environment-specific settings for endpoints. It also needs API keys for upstream services and a durable location for temporary artifacts and user uploads. You aim for predictable rollouts and secure operations. Without Kubernetes features, teams hardcode values into containers. They risk leaking credentials or losing state when Pods restart. ConfigMaps let you separate configuration from code. Secrets protect sensitive values like API keys and connection strings. PersistentVolumeClaims (PVCs) give you durable storage that survives Pod restarts. Together, these features help you run stateful AI workloads securely on AKS.
+
+## After completing this module, you'll be able to:
+
+- Explain why externalized configuration and secret handling matter for AI solutions on Azure
+- Implement ConfigMaps for nonsensitive settings and inject them into Pods
+- Implement Secrets for sensitive values and consume them securely in Pods
+- Attach persistent storage using PersistentVolume and PersistentVolumeClaim for stateful AI workloads
+- Deploy and verify configuration and storage on AKS using `kubectl`
+
+> [!NOTE]
+> All examples in this module follow current Kubernetes resource APIs. Validate fields against official Kubernetes and AKS documentation when adapting to your environment.

learn-pr/wwl-data-ai/configure-apps-azure-kubernetes-service/includes/2-define-configmaps.md

@@ -0,0 +1,115 @@
+AI inference services on Azure often require different settings across environments. You want to change these settings without rebuilding containers. ConfigMaps store non-sensitive configuration, such as feature flags and service endpoints. They keep configuration out of images and source code. This approach lets you make fast, controlled changes to settings. You can inject ConfigMap values into Pods as environment variables or as mounted files. Choose environment variables when your application reads from the process environment. Choose mounted files when your application expects configuration files on disk.
+
+> [!NOTE]
+> All code examples in this module show configuration patterns for Kubernetes resources. The specific values and resource names are examples. Adapt them to match your application requirements and naming conventions.
+
+## Define a ConfigMap
+
+A ConfigMap is a Kubernetes resource that stores configuration data as key-value pairs. You declare it using YAML and apply it to your cluster. The `data` field holds your configuration keys and their string values. ConfigMap data is limited to 1 MiB total size per ConfigMap. This limit ensures fast synchronization to nodes and efficient etcd storage. For larger configuration files or binary data, use persistent volumes or external configuration services. Use the `binaryData` field for base64-encoded binary values when necessary. ConfigMap keys must consist of alphanumeric characters, dashes, underscores, or dots.
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-settings
+data:
+  FEATURE_X_ENABLED: "true"
+  SERVICE_ENDPOINT: "https://api.example.com"
+  # File-like configuration can use multi-line values
+  app.config: |
+    log_level=info
+    timeout_seconds=30
+```
+
+## Consume ConfigMap values in a Deployment
+
+You inject configuration into Pods through environment variables. This approach uses the `valueFrom` field with `configMapKeyRef` to reference specific keys from your ConfigMap. When the Pod starts, Kubernetes reads the ConfigMap and sets the environment variables in the container. You can also use `envFrom` with `configMapRef` to load all keys from a ConfigMap as environment variables in one declaration. This bulk loading approach works well when you have many configuration values and want to avoid repetitive YAML. After you deploy, validate that Pods receive expected values. Use `kubectl describe pod` and check your application logs to confirm the settings are correct.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web-api
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: web-api
+  template:
+    metadata:
+      labels:
+        app: web-api
+    spec:
+      containers:
+      - name: api
+        image: myregistry.azurecr.io/web-api:v1
+        env:
+        - name: FEATURE_X_ENABLED
+          valueFrom:
+            configMapKeyRef:
+              name: app-settings
+              key: FEATURE_X_ENABLED
+        - name: SERVICE_ENDPOINT
+          valueFrom:
+            configMapKeyRef:
+              name: app-settings
+              key: SERVICE_ENDPOINT
+        # Alternative: load all keys as environment variables
+        # envFrom:
+        # - configMapRef:
+        #     name: app-settings
+```
+
+## Mount ConfigMap as files
+
+Some applications expect configuration files on disk rather than environment variables. You can mount a ConfigMap as files in the container filesystem. This approach uses a volume backed by the ConfigMap. You then add a `volumeMount` entry in the container spec to mount that volume at a specific path. Each key in the ConfigMap becomes a file in the mount directory. When you mount ConfigMaps as volumes, Kubernetes automatically updates the files when you modify the ConfigMap. The kubelet checks for updates on each sync period. However, containers using ConfigMaps as environment variables do not receive automatic updates and require Pod restarts. The automatic update behavior does not apply when you use `subPath` mounts. The following snippet shows the volume and mount configuration. Include these sections inside your Pod or Deployment spec.
+
+```yaml
+# Code fragment - focus on volume mount
+volumes:
+- name: config-volume
+  configMap:
+    name: app-settings
+    # Optional: select specific keys to mount as files
+    # items:
+    # - key: app.config
+    #   path: application.conf
+containers:
+- name: api
+  volumeMounts:
+  - name: config-volume
+    mountPath: /app/config
+    readOnly: true
+```
+
+## Use immutable ConfigMaps
+
+You can mark a ConfigMap as immutable to protect against accidental changes that could disrupt running applications. Immutable ConfigMaps offer performance benefits in large clusters by allowing Kubernetes to close watches on these resources. This reduces load on the API server when you have many ConfigMaps. Once you set a ConfigMap to immutable, you cannot change its data or revert the immutable setting. You must delete and recreate the ConfigMap to make changes. Existing Pods maintain mount points to the deleted ConfigMap until they restart. Use immutable ConfigMaps for configuration that should not change during application runtime. This pattern works well for configuration tied to specific application versions where changes require redeployment.
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-settings-v2
+data:
+  FEATURE_X_ENABLED: "true"
+  SERVICE_ENDPOINT: "https://api.example.com"
+immutable: true
+```
+
+## Integrate with Azure App Configuration
+
+You can use [Azure App Configuration](/azure/azure-app-configuration/overview) for centralized configuration management across multiple applications and environments. The [Azure App Configuration Kubernetes Provider](/azure/azure-app-configuration/quickstart-azure-kubernetes-service) runs in your cluster and generates ConfigMaps from data stored in App Configuration. This provider creates standard Kubernetes ConfigMaps that your applications consume through environment variables or volume mounts. The provider synchronizes changes from App Configuration to your cluster automatically. You can manage feature flags, configuration values, and Key Vault references in App Configuration and have them appear as ConfigMaps in your cluster. This approach separates configuration management from cluster operations and provides a centralized view of settings across multiple AKS clusters.
+
+## Verify with kubectl
+
+You can apply the manifests and inspect resources to confirm the configuration is available to your Pods. These manifests are typically stored in files named *configmap.yaml* (ConfigMap) and *deployment.yaml* (Deployment).
+
+```bash
+kubectl apply -f configmap.yaml
+kubectl apply -f deployment.yaml
+kubectl describe configmap app-settings
+kubectl describe deployment web-api
+# Check if Pod received configuration as environment variables
+kubectl exec <pod-name> -- printenv | grep FEATURE
+```