01 · L'architecture d'un chatbot RAG sur Azure, de bout en bout

Version : 1.0 · Date : 2026-10-23 · Parcours SUPPORT-IA (support N2/N3 de chatbots IA sur Azure)

En une phrase : un chatbot RAG d'entreprise, c'est une application conteneurisée (Web App for Containers ou pods AKS) qui authentifie l'utilisateur avec Microsoft Entra ID, cherche des passages dans Azure AI Search, fait générer la réponse par un modèle Microsoft Foundry, le tout en privé (Private Endpoints, Private DNS zones, VNet integration) et sans clé (managed identities, Workload Identity) ; le support N2/N3 sait suivre une question de saut en saut et sait, à chaque saut, où regarder.

Ce chapitre suppose les bases AKS du parcours AKS : réseau et Private Link (02), identités, Workload ID et Secrets Store CSI Driver (03), GitOps et Argo CD (05), RAG sans clé sur AKS (06). Les modèles, jetons et 429 sont détaillés au chapitre 02, l'observabilité au chapitre 07. Ici, on assemble les pièces avec l'œil du support : qui parle à qui, par quel chemin, avec quelle identité, et quelle trace cela laisse.

Noms à jour (relevé du 23/10/2026) : Azure AI Foundry s'appelle Microsoft Foundry ; les Azure AI services sont devenus les Foundry Tools (ex. Azure Document Intelligence in Foundry Tools) ; les rôles Azure AI User / Owner sont renommés Foundry User / Foundry Owner (mêmes IDs de rôle). La propriété vnetImagePullEnabled d'App Service devient outboundVnetRouting.imagePullTraffic (l'ancienne reste acceptée). Les deux noms circulent encore dans le code d'un client.

Ce que tu dois savoir expliquer en entretien#

1. Les briques et leur rôle#

2. Les quatre chemins#

Quatre flux traversent l'architecture. Les nommer en entretien montre qu'on raisonne en chemins, pas en services.

2.1 Le chemin de la requête#

sequenceDiagram
    actor U as Utilisateur
    participant E as Microsoft Entra ID
    participant W as Web App / Ingress
    participant A as API RAG (pod)
    participant S as Azure AI Search
    participant F as Foundry (Azure OpenAI)
    U->>W: HTTPS (réseau privé)
    W->>E: Redirection SSO (Easy Auth ou MSAL)
    E-->>W: Jeton utilisateur
    W->>A: POST /chat (en-tête traceparent)
    A->>E: Jeton de la managed identity (Workload Identity)
    E-->>A: Jeton d'accès
    A->>F: Embedding de la question
    A->>S: Recherche vectorielle ou hybride
    S-->>A: Passages + métadonnées
    A->>F: Invite augmentée (question + passages)
    F-->>A: Réponse (ou 429 + retry-after-ms)
    A-->>W: Réponse + citations
    W-->>U: Affichage

Le détail saut par saut, avec les commandes, est à la section 6.

2.2 Le chemin de l'ingestion#

Deux façons d'alimenter l'index : un indexer Azure AI Search (pull, planifié) avec un skillset, ou un job d'ingestion dans AKS qui appelle lui-même Document Intelligence et pousse les documents (push). Le schéma montre la première, la plus courante.

Piège : si le Storage a un Private Endpoint, il faut aussi un shared private link, même dans la même région ; sinon le Storage refuse la connexion. Et un shared private link reste « Pending » tant que personne ne l'a approuvé côté Storage.

2.3 Le chemin du déploiement#

Le détail GitOps (push ou pull, Argo CD, Flux) est dans AKS 05.

2.4 Le chemin de la télémétrie#

Tout ce qui n'est pas configuré n'existe pas au moment de l'incident : un Diagnostic setting créé après la panne ne rattrape rien. La carte complète est à la section 7 ; les requêtes KQL sont au chapitre 07.

3. Deux hébergements : Web App for Containers ou AKS#

3.1 Les réglages Web App que le support doit connaître#

# Lecture seule : configuration conteneur, identité et routage d'une Web App
az webapp config show -g <rg> -n <app> --query "{linuxFx:linuxFxVersion, acrMI:acrUseManagedIdentityCreds, acrUAMI:acrUserManagedIdentityID}"
az webapp identity show -g <rg> -n <app>
az webapp vnet-integration list -g <rg> -n <app>
az resource show -g <rg> -n <app> --resource-type Microsoft.Web/sites --query properties.outboundVnetRouting
az webapp log tail -g <rg> -n <app>            # Log stream (exige la journalisation « filesystem »)

Côté AKS, les réglages équivalents (requests, limits, probes, ingress) et le dépannage des pods sont dans AKS 05, section 7.

4. Le réseau privé#

Trois idées suffisent :

1. Private Endpoint = entrée privée d'un service PaaS (une NIC avec une IP du subnet snet-pe). Le service garde son nom public, c'est le DNS qui doit répondre l'IP privée.
2. VNet integration = sortie privée d'une Web App. Elle ne rend pas l'app joignable en privé : c'est le Private Endpoint de l'app qui le fait.
3. Public network access : Disabled sur chaque service : sans chemin privé fonctionnel, l'appel est refusé (403 ou timeout), même avec le bon rôle.

4.1 Les zones DNS à connaître#

Piège ACR : avec un Private Endpoint, l'ACR active les dedicated data endpoints (<acr>.<région>.data.azurecr.io) : une IP privée par réplica. Si l'enregistrement A du data endpoint manque dans la zone, docker login réussit mais le pull des couches échoue. Un cas réel documenté sur Microsoft Q&A : zones gérées en Terraform, A record du data endpoint oublié.

Piège Foundry : une ressource Foundry expose trois suffixes (cognitiveservices, openai, services.ai). Configurer le DNS pour chaque suffixe que le code utilise ; une seule zone liée ne suffit pas si le SDK appelle *.openai.azure.com.

4.2 Tester le réseau depuis l'appelant#

Le test se fait depuis l'appelant (pod, conteneur de la Web App), jamais depuis son poste.

# Depuis un pod existant de l'API, si l'image contient les outils (sinon, pod de debug : voir la remarque)
kubectl exec -n <ns> <pod-api> -- nslookup <search>.search.windows.net   # doit renvoyer 10.x.x.x (IP du snet-pe)
kubectl exec -n <ns> <pod-api> -- nc -z -w 3 <search>.search.windows.net 443 && echo "port 443 joignable"

# Pod de debug éphémère (crée une ressource : à faire valider avant en PRD)
kubectl run netdebug -n <ns> --rm -it --image=mcr.microsoft.com/cbl-mariner/busybox:2.0 -- sh

# Côté Web App : console SSH (Kudu) du conteneur ; le client doit joindre le site SCM (Private Endpoint + DNS scm)
az webapp ssh -g <rg> -n <app>            # ou portail : Development Tools > SSH

4.3 Les cas particuliers#

• Azure AI Search sortant : le service n'est pas dans un VNet ; ses indexers sortent par shared private link (section 2.2).
• Pipeline vers ACR privé : agent dans un VNet (Managed DevOps Pools, en évitant la plage 172.17.0.0/16 réservée par le service, ou self-hosted).
• Télémétrie privée : l'ingestion Application Insights et Log Analytics passe par un Azure Monitor Private Link Scope ; les métriques Managed Prometheus d'un cluster passent par le DCE MSProm-<région>-<cluster> ajouté à l'AMPLS. Une zone privatelink.monitor.azure.com mal liée coupe la télémétrie de tous les composants du VNet.
• Log stream et SSH d'une Web App privée : ils passent par le site SCM ; le poste de l'opérateur doit le joindre en privé.

5. Les identités : qui appelle qui, avec quel rôle#

Le principe : aucune clé. Chaque appelant a une identité Entra, chaque cible un rôle au plus près (la ressource, pas l'abonnement).

Points qui font perdre des heures :

• Propagation : une affectation de rôle prend quelques minutes (Microsoft parle de 5 minutes pour Azure OpenAI, 5 à 10 minutes pour AI Search) ; un 403 juste après l'affectation n'est pas un diagnostic.
• Custom subdomain : l'authentification Entra sur une ressource Azure OpenAI exige un sous-domaine personnalisé (https://<nom>.openai.azure.com), pas le point de terminaison régional.
• AI Search : le mode d'authentification (API Key, Role-based access control, Both) se choisit dans Settings > Keys ; un service resté en API Key refuse les jetons Entra.
• Workload Identity : le subject du federated credential doit être exactement system:serviceaccount:<namespace>:<sa>, le pod porter le label azure.workload.identity/use: "true", le ServiceAccount l'annotation azure.workload.identity/client-id. Détail et lab dans AKS 03.
• AADSTS70021 (No matching federated identity record found) : issuer ou subject qui ne correspond pas, ou federated credential créé il y a quelques secondes (propagation).

# Lecture seule : qui a quel rôle sur la ressource Azure OpenAI ?
az role assignment list --scope <id-ressource-openai> -o table
# L'identité du pod : ServiceAccount, annotation, label du pod, variables injectées
kubectl get sa <sa> -n <ns> -o yaml
kubectl get pod <pod> -n <ns> -o jsonpath='{.metadata.labels}'
kubectl exec <pod> -n <ns> -- env | grep AZURE_
az identity federated-credential list --identity-name <uami> -g <rg> -o table

6. Le voyage d'une question, pas à pas#

Le scénario : un utilisateur interne pose « Quelle est la procédure de remboursement ? ». Voici les dix étapes, ce qui se passe, et où le support regarde si l'étape échoue.

Le fil qui relie tout : l'operation_Id (colonne OperationId dans Log Analytics), égal au trace id W3C. On part de la requête en échec et on liste tout ce qui porte le même identifiant :

// 1. Les requêtes en échec de la dernière heure, par service
AppRequests
| where TimeGenerated > ago(1h) and Success == false
| project TimeGenerated, AppRoleName, Name, ResultCode, DurationMs, OperationId
| order by TimeGenerated desc

// 2. Tout ce qui s'est passé pour une requête donnée (coller l'OperationId)
union AppRequests, AppDependencies, AppExceptions, AppTraces
| where OperationId == "<operation-id>"
| project TimeGenerated, Type, AppRoleName, Name, Target, ResultCode, DurationMs, Message, OuterMessage
| order by TimeGenerated asc

flowchart LR
    A["AppRequests en échec<br/>(front ou API)"] --> B["OperationId"]
    B --> C["AppDependencies<br/>même OperationId"]
    C --> D{"Première dépendance<br/>en erreur ?"}
    D -- "AI Search 403" --> E["Rôle / RBAC du service<br/>(section 5)"]
    D -- "Azure OpenAI 429" --> F["Quota TPM du déploiement<br/>(chapitre 02)"]
    D -- "Timeout" --> G["DNS / Private Endpoint<br/>(section 4)"]
    D -- "Aucune" --> H["AppExceptions<br/>bug applicatif"]

7. Qui logue quoi, et où#

À dire en entretien : « Les métriques de plateforme et l'Activity log existent toujours. Les journaux de ressource n'existent que si un Diagnostic setting les envoie quelque part. La télémétrie applicative n'existe que si le code est instrumenté. Avant tout incident, je vérifie que ces trois couches sont en place. »

8. Méthode : du symptôme au saut fautif#

flowchart TD
    S["Symptôme signalé"] --> Q1{"Tous les utilisateurs<br/>ou un seul ?"}
    Q1 -- "Un seul" --> U["Entra : sign-in logs,<br/>Conditional Access, groupe,<br/>cache navigateur"]
    Q1 -- "Tous" --> Q2{"Depuis quand ?<br/>Corrélé à un changement ?"}
    Q2 --> C["Activity log, historique<br/>Argo CD / pipeline,<br/>Azure Service Health"]
    Q2 --> Q3{"Erreur ou lenteur ?"}
    Q3 -- "Erreur 5xx" --> E["AppRequests en échec<br/>→ OperationId<br/>→ première dépendance en erreur"]
    Q3 -- "Lenteur" --> L["AppDependencies triées par durée<br/>Search Latency, Time to Response,<br/>pods en throttling CPU"]
    Q3 -- "Rien ne répond" --> R["Web App : Log stream, état du site<br/>AKS : kubectl get pods, events,<br/>endpoints de l'Ingress"]
    E --> X["Confirmer côté service :<br/>métriques + Diagnostic settings"]
    L --> X
    R --> X

Règles de conduite N2/N3 :

1. Délimiter : qui est touché, depuis quand, quel changement récent (déploiement, rotation de secret, modification réseau).
2. Remonter le chemin dans l'ordre : entrée, application, dépendances. Le premier saut en erreur est la piste.
3. Confirmer côté service (métriques, Diagnostic settings) avant d'accuser le code ou d'ouvrir un ticket Microsoft.
4. Ne rien modifier en production sans demande validée : le diagnostic se fait en lecture seule.
5. Documenter l'OperationId, l'heure UTC, la requête KQL : c'est ce que demandera le support Microsoft.

9. Symptôme → cause → vérification → correction#

10. Pièges de production#

11. Lab : cartographier un chatbot existant en lecture seule#

Objectif : en arrivant chez le client, produire en une heure la carte de son chatbot. Uniquement des commandes de lecture, après avoir vérifié le contexte (az account show).

# 0. Contexte : quel abonnement ? (si l'environnement n'est pas identifié, le considérer comme PRD)
az account show --query "{sub:name, id:id, tenant:tenantId}" -o table

# 1. Inventaire du resource group du projet
az resource list -g <rg> --query "[].{type:type, name:name}" -o table

# 2. Les Private Endpoints et leur état d'approbation
az network private-endpoint list -g <rg> \
  --query "[].{pe:name, cible:privateLinkServiceConnections[0].privateLinkServiceId, etat:privateLinkServiceConnections[0].privateLinkServiceConnectionState.status}" -o table

# 3. Les zones DNS privées et leurs liens VNet
az network private-dns zone list --query "[].name" -o table
az network private-dns link vnet list -g <rg-dns> -z privatelink.openai.azure.com -o table

# 4. Web App : image, identité, routage
az webapp config container show -g <rg> -n <app>
az webapp identity show -g <rg> -n <app>

# 5. AKS : add-ons d'observabilité, Workload Identity, Argo CD
az aks show -g <rg> -n <aks> --query "{oidc:oidcIssuerProfile.enabled, wi:securityProfile.workloadIdentity.enabled, prom:azureMonitorProfile.metrics.enabled, logs:addonProfiles.omsagent.enabled}"
az k8s-extension list -g <rg> -c <aks> -t managedClusters -o table
kubectl get applications -n argocd

# 6. Les Diagnostic settings de chaque service IA
az monitor diagnostic-settings list --resource <id-openai> -o table
az monitor diagnostic-settings list --resource <id-search> -o table

# 7. Les rôles de l'identité de l'API
az role assignment list --assignee <principal-id> --all -o table

Résultat attendu : un schéma comme celui de la section 1, annoté avec les vrais noms, la liste des zones DNS, des identités et de leurs rôles, et la liste des Diagnostic settings manquants (à proposer, pas à créer soi-même).

12. Questions d'entretien#

1. Décrivez l'architecture d'un chatbot RAG sur Azure.

Un front et une API conteneurisés (Web App for Containers ou AKS), authentification Entra ID, API RAG qui calcule l'embedding de la question, interroge Azure AI Search, puis envoie l'invite augmentée à un modèle Foundry. Ingestion par un indexer AI Search avec Document Intelligence et un skill d'embedding. Tout en Private Endpoints, aucune clé grâce aux managed identities et à Workload Identity. Images dans ACR Premium, déploiement GitOps par Argo CD. Observabilité : Application Insights, Log Analytics, Managed Prometheus, Managed Grafana, Langfuse.

2. Un utilisateur dit que le bot ne répond plus. Par quoi commencez-vous ?

Délimiter (un utilisateur ou tous, depuis quand, changement récent), puis remonter le chemin : Log stream ou AppServiceHTTPLogs à l'entrée, AppRequests en échec, puis toutes les lignes du même OperationId pour trouver la première dépendance en erreur. Je confirme côté service avec les métriques avant de conclure.

3. Tout est privé. Comment la Web App joint-elle Azure OpenAI ?

Par sa VNet integration (sortie dans un subnet délégué), puis le Private Endpoint d'Azure OpenAI dans le subnet des Private Endpoints. Le nom *.openai.azure.com doit résoudre l'IP privée grâce à la zone privatelink.openai.azure.com liée au VNet qui résout. Pour l'entrée, c'est le Private Endpoint de la Web App, pas la VNet integration.

4. 403 vers AI Search alors que le rôle est attribué. Hypothèses ?

Propagation du rôle (quelques minutes), service resté en mode API Key (les jetons Entra sont refusés), rôle de contrôle au lieu de Search Index Data Reader, ou appel qui sort en public parce que le DNS ne résout pas l'IP privée et que l'accès public est désactivé. Je teste le DNS depuis le pod, puis je liste les rôles sur la ressource.

5. Pourquoi le pipeline n'arrive-t-il pas à pousser dans l'ACR ?

L'ACR est privé : les agents hébergés par Microsoft n'ont pas de route vers le Private Endpoint. Il faut un self-hosted agent ou un Managed DevOps Pool injecté dans un VNet qui résout privatelink.azurecr.io, plus une service connection en workload identity federation avec un rôle de push.

6. La Web App n'arrive pas à tirer son image.

Vérifier acrUseManagedIdentityCreds (et l'ID de l'identité user-assigned), le rôle AcrPull, que l'ACR accepte les ARM audience tokens, que le pull passe par le VNet (imagePullTraffic) et que le data endpoint de l'ACR est résolu en IP privée. AppServicePlatformLogs et le Log stream donnent l'erreur exacte.

7. Un document récent n'est jamais cité.

Historique de l'indexer d'abord : document en erreur (réseau, rôle, skill), indexer pas lancé depuis, quota du Document Layout skill. Ensuite vérifier que le document est dans l'index (recherche sur son nom), puis les filtres de sécurité éventuels.

8. Comment suivez-vous une requête de bout en bout ?

Par le trace id W3C propagé dans l'en-tête traceparent, qui devient l'operation_Id de toutes les lignes Application Insights. À condition que chaque service soit instrumenté avec OpenTelemetry et porte un cloud_RoleName distinct.

9. Quelle différence entre Private Endpoint et VNet integration ?

Le Private Endpoint est l'entrée privée d'un service (une IP dans votre VNet). La VNet integration est la sortie de la Web App vers votre VNet. Une Web App totalement privée a besoin des deux.

10. Pourquoi Workload Identity plutôt qu'une clé dans un secret Kubernetes ?

Aucun secret à stocker ni à faire tourner, une identité par application, des rôles au plus près, une trace dans les journaux Entra. Un Secret Kubernetes n'est qu'encodé en base64 et se retrouve dans etcd.

11. Le bot est lent depuis ce matin. Votre démarche ?

AppDependencies triées par durée pour isoler le saut lent ; puis côté service : Time to Response et utilisation PTU pour Azure OpenAI, Search Latency pour AI Search, CPU throttling et restarts pour les pods. Langfuse pour voir si les invites ont grossi (plus de chunks, plus de jetons).

12. Qu'est-ce qui doit être en place avant le premier incident ?

Diagnostic settings sur chaque service IA et sur AKS, Container Insights en ContainerLogV2, Managed Prometheus, instrumentation OpenTelemetry avec cloud_RoleName, Langfuse, alertes sur 5xx, 429 et restarts, et des tableaux Grafana partagés.

13. Fiche à retenir#

• Quatre chemins : requête, ingestion, déploiement, télémétrie ; savoir les dessiner et dire où chacun casse.
• Private Endpoint = entrée privée ; VNet integration = sortie de la Web App ; DNS privé = la moitié des incidents.
• Zones : privatelink.azurewebsites.net, .openai.azure.com, .cognitiveservices.azure.com, .services.ai.azure.com, .search.windows.net, .blob.core.windows.net, .vaultcore.azure.net, .azurecr.io (+ data endpoints).
• Rôles data plane : Cognitive Services OpenAI User (pas Contributor), Search Index Data Reader, Key Vault Secrets User, Storage Blob Data Reader, AcrPull, Monitoring Metrics Publisher.
• Workload Identity : federated credential (issuer, subject exact), annotation du ServiceAccount, label du pod.
• Web App : WEBSITES_PORT, WEBSITES_CONTAINER_START_TIME_LIMIT, acrUseManagedIdentityCreds, imagePullTraffic, authentication-as-arm sur l'ACR.
• Indexer privé : shared private link approuvé + executionEnvironment: private ; historique de l'indexer d'abord.
• ACR privé : agent de build dans un VNet (Managed DevOps Pools ou self-hosted).
• Une question = un OperationId ; partir de l'AppRequests en échec, trouver la première dépendance en erreur.
• Diagnostic settings : rien n'est collecté sans eux ; métriques de plateforme et Activity log, si.

Références#

Relevé du 23/10/2026 :

• Azure Private Endpoint private DNS zone values et scénarios DNS
• Troubleshoot private endpoint connectivity failures
• Configure a custom container for Azure App Service et FAQ App Service on Linux
• Can't pull image from Azure Container Registry to Azure Web App
• Manage App Service virtual network integration routing et Integrate your app with an Azure virtual network
• Use private endpoints for App Service apps
• Authentication and authorization in App Service et Work with user identities
• Enable diagnostic logs for apps in App Service et App Service monitoring data reference
• Open a container shell (SSH) in App Service
• Connect privately to an Azure container registry et dedicated data endpoints
• Build and push images with Azure Pipelines et Build and publish Docker images to ACR
• Configure Managed DevOps Pools networking
• Troubleshoot a workload identity service connection et federated identity credentials considerations
• Use Microsoft Entra Workload ID with AKS
• Troubleshoot Argo CD extension
• Role-based access control for Azure OpenAI, Entra ID authentication for Azure OpenAI et RBAC for Microsoft Foundry
• Configure Azure OpenAI networking
• Manage Azure OpenAI quota et Azure OpenAI monitoring data reference
• Azure AI Search : roles, enable roles, shared private link, service limits, indexer network security, Document Layout skill, attach a billable resource, monitor queries
• Document Intelligence : analyze document response
• Azure Monitor Private Link for Kubernetes
• Troubleshoot OOMKilled in AKS et Kubernetes events in AKS
• Microsoft Q&A (retour d'expérience, non normatif) : ImagePullFailure on App Service with Managed Identity