Here is a comprehensive AKS security best practices guide, organized by layer.Here’s a summary of the seven security layers covered in the guide above:
Identity & Access is the primary perimeter. The recommended best practice is to use groups to provide access rather than individual identities — use a Microsoft Entra ID group membership to bind users to Kubernetes roles rather than individual users. As a user’s group membership changes, their access permissions on the AKS cluster change accordingly. For workloads, use Microsoft Entra Workload ID so pods authenticate to Azure services with short-lived OIDC tokens instead of any stored credentials.
Cluster hardening centres on keeping the API server off the public internet. To keep from exposing the Kubernetes API to the internet, set up a private AKS cluster where the control plane uses an internal IP address instead — traffic between the API server and AKS node pools stays within a private VNet. Combine this with auto-upgrade channels to stay current on Kubernetes versions and node images.
Network security requires Azure CNI to enable NetworkPolicies, a default-deny stance per namespace, and Azure Firewall or NAT Gateway for egress control. To limit network traffic between pods, AKS offers support for Kubernetes network policies, allowing or denying specific network paths within the cluster based on namespaces and label selectors.
Workload security means running every container as non-root with dropped capabilities and a read-only root filesystem. Your applications should be designed for the principle of least number of privileges required. allowPrivilegeEscalation defines if the pod can assume root privileges — design your applications so this setting is always set to false.
Secrets management means using the Key Vault Secrets Store CSI Driver. The Azure Key Vault provider for Secrets Store CSI Driver allows integration of an Azure Key Vault as a secret store with an AKS cluster via a CSI volume — it mounts secrets, keys, and certificates to a pod using a CSI volume and supports autorotation of mounted contents.
Image security requires scanning in CI, enforcing image policies at admission, and using minimal base images pinned to digests rather than tags.
Monitoring ties everything together. Ensure you have an audit trail for the Kubernetes control plane by enabling audit logs for kube-apiserver and kube-controller-manager. Pair with Microsoft Defender for Containers for runtime threat detection and Azure Policy for continuous compliance.
Here’s a Python hands-on version for Azure AI Search that does the core setup programmatically:
creates a search index
uploads sample documents
runs a few search queries
This follows Microsoft’s Python quickstart flow using the Azure SDK packages azure-search-documents and azure-identity. Microsoft’s current Python quickstart for Azure AI Search uses those SDKs and shows index creation, document upload, and querying from Python.
What this lab builds
Python script
↓
Azure AI Search index
↓
Upload sample docs
↓
Run search queries
1. Install packages
pip install azure-search-documents azure-identity
These are the main SDK packages Microsoft documents for Python with Azure AI Search.
You can get the endpoint and admin key from your Azure AI Search resource in the Azure portal. Microsoft’s quickstart uses the service endpoint plus admin credentials to connect and manage indexes.
3. Python script
Save this as azure_search_lab.py:
import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
"content": "Our savings account offers 3.5 percent annual interest and no monthly fee.",
"category": "accounts",
},
{
"id": "2",
"title": "Home Loan Policy",
"content": "Home loans are available with fixed and floating interest rate options.",
"category": "loans",
},
{
"id": "3",
"title": "Credit Card Support",
"content": "You can block or replace your credit card using the mobile banking app.",
"category": "cards",
},
]
result = search_client.upload_documents(documents=documents)
print("Upload results:")
for r in result:
print(f" key={r.key}, succeeded={r.succeeded}")
# 6) Run a few searches
queries = ["interest", "credit card", "loan"]
for q in queries:
print(f"\nSearch query: {q}")
results = search_client.search(search_text=q)
for doc in results:
print(f"- {doc['title']} [{doc['category']}]")
This matches the documented Azure AI Search SDK pattern of using SearchIndexClient for schema management and SearchClient for loading and querying documents.
4. Run it
python azure_search_lab.py
You should see:
index created
documents uploaded
matching results printed for each query
5. What the code is doing
The important pieces are:
SearchIndexClient creates or updates the index schema
SimpleField(..., key=True) defines the required unique key field
SearchableField makes text fields searchable
SearchClient.upload_documents() pushes documents into the index
SearchClient.search() runs queries against the index
Azure AI Search requires a unique key field for each document in an index, and the Python SDK supports document upload and full-text querying exactly this way.
6. Add filtering
You can also filter on fields like category:
results = search_client.search(
search_text="interest",
filter="category eq 'accounts'"
)
Azure AI Search supports filters on fields marked filterable in the schema.
7. Next upgrade: vector and hybrid search
For a chatbot or RAG app, the next step is to add:
an embeddings field
vector search
ideally hybrid search
Microsoft’s current guidance recommends hybrid search for many production use cases because it combines keyword and vector retrieval.
8. Common mistakes
The most common ones are:
forgetting the key field
using the query key instead of the admin key for index creation
not marking fields filterable before trying to filter on them
expecting search to work before uploading documents
These are all consistent with Azure AI Search’s index/schema and credential model in the official SDK docs and quickstarts.
Here’s a hands-on Azure AI Search setup using the Azure portal, which is the easiest way to learn it end to end.
The fastest path is:
create an Azure AI Search service,
put sample files in Blob Storage,
use the Import data wizard to create the data source, index, and indexer,
run test queries,
then optionally add vector search for RAG. Microsoft’s current portal quickstarts support both classic full-text search and integrated vectorization through the Import data wizard. (Microsoft Learn)
What you’re building
You’ll end up with:
a search service,
a storage container with documents,
a search index,
optionally an indexer that keeps the index updated,
and a search UI in the portal to test queries. Azure AI Search indexes store searchable documents, and indexers automate ingestion from supported data sources like Blob Storage. (Microsoft Learn)
Option A: simplest hands-on setup with the portal
Step 1: Create an Azure AI Search service
In Azure portal, create a new Azure AI Search resource. Pick your subscription, resource group, region, and pricing tier. Microsoft’s service-creation guide notes you create the service directly in the portal and choose region and tier there. (Microsoft Learn)
Step 2: Prepare sample data in Blob Storage
Create or use an Azure Storage account, then create a container and upload sample files. Microsoft’s full-text portal quickstart uses a Blob container named hotels-sample-data and sample JSON content, but you can also use your own files. (Microsoft Learn)
A simple path is:
Storage account
Blob container
upload JSON, PDFs, or text files
Step 3: Open the Import data wizard
Open your Azure AI Search service, then choose Import data. Microsoft documents this as the no-code path that can create the data source, optional enrichment/vectorization, inferred schema, and load content into an index. (Microsoft Learn)
Step 4: Choose your data source
Select Azure Blob Storage as the source and connect it to your container. Azure AI Search supports both push and pull ingestion models, and the Import wizard uses the pull/indexer path for supported sources. (Microsoft Learn)
Step 5: Pick search type
For a first lab, choose Keyword search. Microsoft’s current portal quickstart explicitly uses keyword search for the basic getting-started experience. (Microsoft Learn)
Step 6: Let the wizard create the index
The wizard will infer a schema and create an index. In Azure AI Search, the index is the searchable structure that stores documents and fields, and each document needs a unique key field. (Microsoft Learn)
Step 7: Run the indexer
The wizard can create and run an indexer, which automates loading content from the source into the index. Microsoft’s indexer documentation describes indexers as the automation layer for ingestion from supported data sources. (Microsoft Learn)
Step 8: Test queries
Go to Indexes, open your new index, and try some searches in Search Explorer. Azure AI Search supports full-text querying over the indexed content once documents are loaded. (Microsoft Learn)
What just got created
The portal flow usually creates:
a data source: connection to Blob Storage,
an index: searchable schema and content,
an indexer: scheduled or on-demand ingestion job.
Those are the main building blocks for classic portal-based setup. (Microsoft Learn)
Option B: hands-on setup for RAG and vector search
If your goal is chatbot/RAG, use the vector quickstart in the portal instead of the basic keyword-only wizard.
Step 1: Start with the Import data wizard for vectors
Microsoft’s vector portal quickstart says the wizard can do integrated vectorization, including chunking content and calling an embedding model at indexing and query time. (Microsoft Learn)
Step 2: Provide supported files
The vector quickstart uses text PDFs and simple images from Microsoft sample data, but you can also use your own files. (Microsoft Learn)
Step 3: Configure embeddings
For vector search, Azure AI Search stores vectors at the field level and can combine vector and nonvector fields in the same index. Microsoft recommends hybrid search for many production scenarios because vector and keyword queries run in parallel and return one merged result set. (Microsoft Learn)
Step 4: Run test vector or hybrid queries
Once the vector index is built, test either:
semantic similarity search,
or hybrid search with both text and vectors.
Microsoft’s vector overview says hybrid search often gives better results than vector-only or keyword-only search. (Microsoft Learn)
When to use indexers vs push ingestion
Use the portal/indexer approach when:
your content sits in supported sources like Blob Storage,
you want a fast setup,
you want scheduled ingestion.
Use push ingestion from code when:
your data changes very frequently,
you need tighter control over updates,
or your application already owns the ingestion process.
Microsoft’s ingestion guidance explains that indexers are the pull model, while push lets your app send documents directly and is better for low-latency sync scenarios. (Microsoft Learn)
A good first lab
A practical first exercise is:
create a search service,
upload 10–20 PDF or text files to Blob Storage,
run the Import data wizard,
create a basic keyword index,
test queries,
then repeat with the vector wizard and compare results.
That mirrors Microsoft’s current quickstart progression from full-text search to vector search and semantic ranking. (Microsoft Learn)
Common mistakes
The biggest ones are:
choosing the wrong tier or region when creating the service, since service creation is tied to those settings in the portal, (Microsoft Learn)
expecting Azure AI Search to search your files before they are loaded into an index, because queries run over indexed content, (Microsoft Learn)
skipping a unique key field in the index schema, which Azure AI Search requires for documents, (Microsoft Learn)
using vector-only search when hybrid would usually retrieve better business results. (Microsoft Learn)
Best next step after setup
After the basic setup works, the next useful upgrade is:
add semantic ranking, or
add integrated vectorization for RAG.
Microsoft provides separate quickstarts for both. (Microsoft Learn)
Here’s a practical banking chatbot HLD on Azure with the three things you asked for: components, data flow, and security controls.
1. Scope and goals
This design is for a banking chatbot that can answer grounded questions, retrieve approved internal knowledge, perform tightly controlled actions through backend APIs, and escalate sensitive cases to a human. On Azure, the common enterprise pattern is an application/orchestration layer in front of Azure OpenAI and Azure AI Search, with private networking and identity controls around the whole path. (Microsoft Learn)
Azure OpenAI Azure AI Search Banking APIs / Systems
(chat + (hybrid RAG) (accounts, cards, CRM,
embeddings) ticketing, fraud, etc.)
\ | /
\ | /
\ v /
\ Enterprise data /
\ (Blob, SharePoint, SQL) /
+-----------------------------+
Supporting:
- Microsoft Entra ID
- Azure Key Vault
- Azure Monitor / App Insights / Log Analytics
- Microsoft Sentinel
- Private Endpoints / VNet Integration
Microsoft’s current baseline enterprise chat architecture uses a secured app layer in front of model and retrieval services, and Azure AI Search is the recommended grounding layer for RAG with hybrid retrieval options. (Microsoft Learn)
3. Core components
A. Channels
The chatbot can be exposed through mobile banking, web banking, employee portal, or contact-center console. The UI should not call the model directly; it should go through a backend orchestrator so the bank can enforce policy, logging, and authorization centrally. That backend-first pattern is part of Microsoft’s baseline architecture. (Microsoft Learn)
B. API gateway / edge
Put a gateway and WAF in front of the chatbot for TLS termination, request filtering, DDoS protection, and traffic governance. This is consistent with Microsoft’s baseline Azure web/chat reference designs, which assume a secured edge in front of the application layer. (Microsoft Learn)
C. Chat orchestrator
This is the main control layer. It manages:
authentication and session state
prompt templates
retrieval requests
business-rule checks
tool calling to banking APIs
confidence scoring
citations/disclosures
escalation to humans
Microsoft’s enterprise chat reference architecture explicitly separates this orchestration layer from the model and data stores. (Microsoft Learn)
D. Azure OpenAI
Use Azure OpenAI for:
chat generation
embeddings for retrieval
Azure documents content filtering and abuse monitoring for Azure OpenAI / Azure Direct Models, which makes it suitable for enterprise guardrail layers, though that does not replace your own banking-specific controls. (Microsoft Learn)
E. Azure AI Search
Use Azure AI Search as the RAG layer for policies, product docs, SOPs, FAQs, forms, and knowledge articles. Azure AI Search supports hybrid retrieval with keyword, vector, and semantic ranking, plus chunking/enrichment patterns for PDFs and images. It also supports document-level security trimming patterns. (Microsoft Learn)
F. Enterprise data sources
Typical sources are:
Blob Storage
SharePoint
SQL / Cosmos-style operational data stores
document repositories
internal policy systems
These sources should feed an ingestion pipeline that extracts, chunks, enriches, and indexes content into Azure AI Search. Microsoft’s RAG guidance calls out chunking, OCR, document extraction, and enrichment as core parts of the pattern. (Microsoft Learn)
G. Banking systems / tools
The orchestrator should call approved backend APIs, not let the model talk directly to core banking systems. Examples:
account summary API
card freeze/unfreeze API
loan status API
CRM/ticketing API
fraud escalation workflow
This is an architectural recommendation rather than a Microsoft product rule, but it follows the same control-layer pattern in Microsoft’s baseline chat architecture. (Microsoft Learn)
4. End-to-end data flow
Flow 1: Knowledge question
Example: “What is the fee for an international wire?”
User sends a message from mobile/web.
Gateway forwards it to the orchestrator.
Orchestrator authenticates the user and applies policy checks.
Orchestrator sends a retrieval query to Azure AI Search.
Azure AI Search returns grounded chunks and metadata.
Orchestrator builds the prompt with citations and instructions.
Azure OpenAI generates the answer.
Orchestrator adds disclosure text and returns the response.
This is a standard RAG pattern: retrieve first, then generate with grounded context. Azure AI Search documentation explicitly describes this model. (Microsoft Learn)
Flow 2: Action request
Example: “Freeze my debit card.”
User sends the request.
Orchestrator authenticates and checks entitlements.
Orchestrator classifies this as an action, not just Q&A.
Orchestrator optionally uses the model to interpret intent.
Orchestrator calls the bank’s card-management API.
Backend system performs the action.
Orchestrator returns a confirmed result or escalates if needed.
The key design principle is that the model can help interpret intent, but the backend system remains the source of truth and enforcement. This is an architectural best practice built on the app-layer separation Microsoft recommends. (Microsoft Learn)
Orchestrator detects a sensitive topic or low confidence.
It blocks automated completion or limits the response.
It routes the case to a human banker/contact-center agent.
Logs and case metadata are stored for audit.
Human handoff is not a single Azure feature, but it is a recommended enterprise control pattern for regulated use cases where accuracy and accountability matter. Azure’s baseline architecture supports orchestrator-driven workflow and escalation patterns. (Microsoft Learn)
5. Security controls
Identity and access
Use Microsoft Entra ID for workforce identities and your customer identity layer for retail users. For retrieval, use identity-aware filtering and document-level access trimming so users only retrieve content they are allowed to see. Microsoft documents Entra-based auth and Azure AI Search security trimming for this purpose. (Microsoft Learn)
Private networking
Use private endpoints and VNet integration for Azure OpenAI, Azure AI Search, Key Vault, and the application tier where possible. Microsoft’s baseline chat architecture emphasizes private connectivity, and Key Vault supports Private Link integration. (Microsoft Learn)
Secrets and keys
Store secrets, certificates, and encryption keys in Azure Key Vault. Key Vault is designed for secure storage of secrets, keys, and certificates and supports logging and integration with Azure Monitor. (Microsoft Learn)
Managed identities
Prefer managed identities between Azure services instead of hard-coded secrets. Microsoft documents managed-identity-based authentication for Key Vault and uses passwordless patterns in Azure application architectures. (Microsoft Learn)
Content safety
Use Azure OpenAI’s built-in content filtering and abuse monitoring, but treat those as baseline controls rather than your only compliance layer. Banking-specific policies still belong in the orchestrator. Azure documents both abuse monitoring and configurable harm categories/severity concepts. (Microsoft Learn)
Data protection
Minimize prompt data, redact unnecessary PII before model calls, and keep regulated records in approved systems of record. Azure publishes data privacy/security information for Azure Direct Models, including Azure OpenAI. (Microsoft Learn)
Monitoring and audit
Send logs, traces, and security events to Azure Monitor / Application Insights / Log Analytics, and use Microsoft Sentinel for SIEM/SOC workflows. Key Vault also supports exporting logs to Azure Monitor. (Microsoft Learn)
6. Non-functional requirements
Availability
Deploy the app tier with redundancy and design for zone/region resilience where needed. Microsoft’s baseline chat architecture is explicitly aimed at secure, highly available, zone-redundant enterprise chat applications. (Microsoft Learn)
Scalability
Scale the stateless app/orchestrator tier horizontally, keep chat history in a dedicated store, and scale search/model capacity independently. This separation follows the Azure reference pattern where the app, model, and retrieval tiers are distinct. (Microsoft Learn)
Auditability
Every model call, retrieval event, tool call, and escalation path should be logged with correlation IDs. This is a design recommendation built on Azure’s monitoring stack and the needs of regulated environments. (Microsoft Learn)
7. Recommended deployment split
For a bank, split into two bots:
Customer bot
narrow scope
strict action permissions
early human escalation
only approved public/customer-facing knowledge
Employee copilot
broader internal knowledge
document-level access trimming
workflow tools for CRM and case systems
stronger audit controls
This split is an architectural recommendation because customer-facing and employee-facing risk profiles are usually different, while Azure’s identity and retrieval controls support both models. (Microsoft Learn)
8. HLD summary table
Layer
Main components
Purpose
Key controls
Channels
Mobile, web, contact center, employee portal
User interaction
Auth, session controls
Edge
API gateway, WAF
Secure entry point
TLS, DDoS, request filtering
App tier
Orchestrator on App Service/AKS
Prompting, policy, tool calling, handoff
Rate limits, PII redaction, audit
AI tier
Azure OpenAI
Response generation, embeddings
Content filtering, abuse monitoring
Retrieval tier
Azure AI Search
Grounding and citations
Hybrid search, ACL/security trimming
Data tier
Blob, SharePoint, SQL, docs
Knowledge sources
Access control, ingestion governance
Systems tier
Core banking APIs, CRM, fraud, cards
Trusted actions and transactions
API auth, least privilege
Security/ops
Entra ID, Key Vault, Monitor, Sentinel
Identity, secrets, monitoring
Private endpoints, logging, SIEM
The Azure-specific parts of this table are grounded in Microsoft’s official architecture, retrieval, identity, and Key Vault guidance. (Microsoft Learn)
9. Best one-line design
Use a secure orchestrator in front of Azure OpenAI and Azure AI Search, ground policy answers with RAG, route actions through approved banking APIs, and enforce identity, private networking, secrets management, logging, and human escalation throughout. (Microsoft Learn)
This structure follows Microsoft’s current baseline enterprise chat architecture for Azure, where the application layer sits in front of the model and retrieval services, uses private networking, and keeps orchestration separate from the model itself. Azure also recommends Azure AI Search as the retrieval layer for RAG, with support for hybrid retrieval, document-level security trimming, and private endpoints. (Microsoft Learn)
What each layer does
1. Channels and identity Customers access the bot through mobile banking, web banking, or a contact-center console. Use Microsoft Entra ID for workforce users and your bank’s customer identity stack for retail users, then pass identity and entitlement context to the orchestrator. Azure AI Search recommends Entra-based auth and role-based access because it gives centralized identity, conditional access, and stronger audit trails. (Microsoft Learn)
2. Chat orchestrator This is the most important layer. It handles conversation memory, prompt templates, rate limiting, policy checks, tool access, and handoff to a human agent. Microsoft’s baseline Azure chat reference architecture puts this orchestration layer between the UI and Azure OpenAI rather than letting clients call the model directly. (Microsoft Learn)
3. Azure OpenAI Use one deployment for the chat model and another for embeddings. The chat model generates answers; the embedding model helps retrieve relevant knowledge chunks. Azure documents content filtering and abuse monitoring as built-in safety controls, which is especially important for regulated customer-facing use. (Microsoft Learn)
4. Azure AI Search for grounding For banking, do not rely on the model’s memory for policies, fees, disclosures, or procedures. Put approved content into Azure AI Search and use hybrid retrieval so the chatbot answers with grounded content and citations. Microsoft’s current guidance explicitly recommends Azure AI Search for RAG and notes support for security trimming and private network isolation. (Microsoft Learn)
5. Banking systems and tools The chatbot should not directly expose raw core banking systems to the model. Instead, the orchestrator should call tightly scoped internal APIs for approved actions like “show recent transactions,” “freeze card,” or “open a support case.” That way the model suggests the action, but the backend enforces the rules.
Banking-specific design principles
Grounded answers only for policy and product questions Use RAG for fees, terms, product comparisons, and internal procedures. This reduces hallucinations and supports citations. Microsoft’s RAG guidance for Azure AI Search emphasizes grounding, citations, and security-aware retrieval. (Microsoft Learn)
Document-level access control If the chatbot is used by employees, access trimming matters a lot. A branch employee should not retrieve internal audit documents just because they ask. Azure AI Search supports document-level access control and security trimming patterns tied to identity. (Microsoft Learn)
Private networking by default For a bank, expose as little as possible publicly. Microsoft’s baseline Azure chat architecture uses private endpoints and VNet integration, and Azure OpenAI On Your Data guidance also calls out private networking and restricted access paths. (Microsoft Learn)
Human handoff for sensitive cases For fraud claims, hardship, complaints, suspicious activity, or low-confidence responses, the bot should escalate to a human banker or contact-center agent instead of improvising.
Audit everything Send logs, prompts, tool calls, retrieval events, and security events to Azure Monitor and Microsoft Sentinel. Sentinel is Microsoft’s cloud-native SIEM for detection, investigation, and response, which fits banking operational monitoring well. (Microsoft Learn)
Recommended banking use cases
Good first-wave use cases:
product FAQs
branch and ATM help
card controls like freeze/unfreeze
loan application status
internal employee knowledge assistant
secure document Q&A for policies and procedures
Use more caution with:
personalized financial advice
transaction disputes
fraud investigations
credit decisions
anything that creates legal or regulatory commitments
Suggested deployment pattern
For a bank, I’d recommend this split:
Customer bot
retail/mobile/web channels
heavily restricted tools
strict content policy
human handoff early
Employee copilot
internal knowledge access
stronger retrieval permissions
workflow tools for CRM/ticketing
document-level access trimming
This split reduces risk because customer-facing and employee-facing requirements are usually very different.
Minimal Azure stack
Frontend: Web app, mobile app, or contact-center console
A solid GenAI chatbot on Azure OpenAI usually looks like this:
User
↓
Web / Mobile / Teams UI
↓
Backend API / Orchestrator
├─ Auth (Microsoft Entra ID)
├─ Prompt assembly + guardrails
├─ Conversation state
└─ Tool calling / business logic
↓
Azure OpenAI
├─ Chat model
└─ Embedding model
↓
Azure AI Search
├─ Keyword + vector + semantic retrieval
└─ Citations / grounding docs
↓
Enterprise data sources
├─ Blob / SharePoint / SQL / Cosmos DB
└─ Ingestion + chunking pipeline
For Azure, the most common production pattern is RAG: the app retrieves relevant chunks from your data with Azure AI Search, then sends those chunks to Azure OpenAI so answers stay grounded instead of relying only on model memory. Microsoft specifically recommends Azure AI Search as an index store for RAG, and its current docs distinguish classic RAG from newer agentic retrieval patterns. (Microsoft Learn)
Core components
Frontend A web app, mobile app, or Teams app handles chat UI, file uploads, citations, and feedback.
Backend / orchestrator This is the “brain” of the app. It manages auth, session history, prompt templates, retrieval calls, tool use, rate limiting, and logging. In Microsoft’s baseline enterprise chat architecture, the app layer sits in front of the model and retrieval services rather than having the client talk to the model directly. (Microsoft Learn)
Azure OpenAI Use one deployment for chat and usually another for embeddings. The chat model generates the answer; the embedding model converts documents and queries into vectors for retrieval. Azure OpenAI “On Your Data” exists as a simpler way to ground answers in enterprise content, though Microsoft labels that path as “classic.” (Microsoft Learn)
Azure AI Search This is the retrieval layer. It supports vector search, semantic ranking, hybrid search, enrichment, and newer agentic retrieval features for chatbot scenarios. Microsoft’s current guidance says Azure AI Search is a recommended retrieval/index layer for RAG workloads. (Microsoft Learn)
Data ingestion pipeline Documents from Blob, SharePoint, SQL, PDFs, and other sources get extracted, chunked, enriched, and indexed. Azure AI Search supports enrichment for content such as PDFs and images that are not searchable in raw form. (Microsoft Learn)
Best-practice architecture
1. Start with RAG, not pure prompting
For an enterprise chatbot, keep company docs outside the prompt until query time. Store them in Azure AI Search, then retrieve only the relevant chunks for each question. Microsoft’s RAG guidance says this improves grounding and supports citations and better relevance. (Microsoft Learn)
2. Use hybrid retrieval
Use vector + keyword + semantic ranking together. Azure AI Search supports this combination, and it is usually stronger than relying on vectors alone for real-world business documents. (Microsoft Learn)
3. Add identity-aware filtering
If different users should see different documents, put Microsoft Entra ID in front of the app and apply Azure AI Search security filters or document-level access trimming. Microsoft documents this specifically for Azure OpenAI On Your Data with Azure AI Search. (Microsoft Learn)
4. Separate conversation memory from knowledge retrieval
Keep short-term chat history in app storage, but keep source-of-truth business content in the search index. This avoids bloated prompts and makes updates to your knowledge base easier. Microsoft’s baseline chat architecture separates the app/orchestration layer from the grounding data layer. (Microsoft Learn)
5. Prefer managed identity where possible
Microsoft’s Azure App Service RAG tutorial uses managed identities for passwordless authentication between services. That is the cleaner production pattern versus storing secrets in code. (Microsoft Learn)
Two good Azure patterns
Pattern A: Simpler RAG app
Use this when you want a straightforward chatbot fast.
App Service / AKS
↓
Backend API
↓
Azure AI Search
↓
Azure OpenAI
This is the easier option and matches Microsoft’s tutorial-style architecture for grounded chat apps. (Microsoft Learn)
Pattern B: Agent-style chatbot
Use this when you need tool use, more complex reasoning, or multi-step workflows.
UI
↓
Foundry Agent Service / custom orchestrator
├─ retrieval
├─ tools
├─ memory
└─ policy checks
↓
Azure OpenAI + Azure AI Search + enterprise APIs
Microsoft’s current architecture guidance includes Foundry Agent Service and a baseline Foundry chat reference architecture for enterprise chat applications. (Microsoft Learn)
What I’d recommend
For most teams:
Frontend: React or Teams app
Backend: App Service or AKS
LLM: Azure OpenAI
Retrieval: Azure AI Search
Identity: Entra ID
Secrets: Key Vault
Telemetry: Application Insights / Azure Monitor
Documents: Blob + ingestion pipeline
That gives you a practical, scalable architecture without too much complexity. Azure AI Search is the natural retrieval layer, and Azure’s current enterprise chat reference architectures are built around that same idea. (Microsoft Learn)
Common mistakes
Letting the frontend call the model directly
Sending entire documents to the model instead of retrieving chunks
Skipping citations
Mixing access control into prompt text instead of enforcing it in retrieval
Using only vector search when hybrid retrieval would work better
Here’s a thorough explanation of OADP — what it is, how it works, and how to use it.
What OADP is
The OpenShift API for Data Protection (OADP) product safeguards customer applications on OpenShift Container Platform. It offers comprehensive disaster recovery protection, covering OpenShift Container Platform applications, application-related cluster resources, persistent volumes, and internal images. OADP is also capable of backing up both containerized applications and virtual machines. However, OADP does not serve as a disaster recovery solution for etcd or OpenShift Operators.
In plain terms: OADP is the application-layer backup tool for OCP. Where etcd backup protects the cluster skeleton (all resource definitions), OADP protects what’s running inside namespaces — the actual workloads and their data.
OADP is the OpenShift API for Data Protection operator. This open source operator sets up and installs Velero on the OpenShift platform, allowing users to backup and restore applications.
ArchitectureHere’s a comprehensive explanation of OADP across all its key dimensions.
What OADP is
The OpenShift API for Data Protection (OADP) provides a comprehensive solution for backing up and restoring applications, persistent volumes, and custom resources across various environments. OADP is the OpenShift API for Data Protection operator — this open source operator sets up and installs Velero on the OpenShift platform, allowing users to backup and restore applications.
In short: OADP = Velero + OpenShift-specific plugins + OLM lifecycle management. Everything is driven by Kubernetes CRs.
What OADP protects
Data that can be protected with OADP includes Kubernetes resource objects, persistent volumes, and internal images. More specifically:
Kubernetes objects — all resources in selected namespaces: Deployments, Services, ConfigMaps, Secrets, Routes, PVCs, RoleBindings, etc.
Internal container images — images stored in the OCP internal registry (built by S2I/Tekton and not pushed externally)
Persistent volume data — via CSI snapshots, cloud-native snapshots, or file-system backup (Kopia)
OpenShift Virtualization VMs — OADP can quiesce VMs, snapshot their disks, and restore them fully
What it does NOT protect: OADP does not serve as a disaster recovery solution for etcd or OpenShift Operators. OADP support is applicable to customer workload namespaces and cluster scope resources. Full cluster backup and restore are not supported.
Core components
Component
Role
OADP Operator
Installs/manages Velero and all CRDs via OLM. Runs in openshift-adp
Velero
The backup engine — serialises K8s resources, coordinates PV backup
Node agent (Kopia)
DaemonSet on every node — handles file-level PV backup
openshift plugin
OCP-specific handling for Routes, SCCs, internal registry images
csi plugin
Integrates with CSI VolumeSnapshot API for fast PV snapshots
Step 1 — Install
Install from OperatorHub or via CLI:
cat <<EOF | oc apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: redhat-oadp-operator
namespace: openshift-adp
spec:
channel: stable-1.5
name: redhat-oadp-operator
source: redhat-operators
sourceNamespace: openshift-marketplace
installPlanApproval: Automatic
EOF
Step 2 — Configure via DataProtectionApplication CR
The DataProtectionApplication (DPA) is the master config CR. It tells OADP where to store backups, which plugins to load, and how to handle PV backup:
You can schedule backups at specified intervals. You can use hooks to run commands in a container on a pod, for example fsfreeze to freeze a file system. You can configure a hook to run before or after a backup or restore.
existingResourcePolicy: none # skip resources that already exist
For cross-cluster disaster recovery, point the destination cluster’s DPA at the same S3 bucket with accessMode: ReadOnly, then create the Restore CR. OADP auto-creates the target namespace — don’t pre-create it, as that causes SCC conflicts.
PV backup — three strategies
The underlying mechanism within OADP that allows the backup and restore of persistent volumes is either Restic, Kopia, CSI snapshots, or CSI dataMover. Backups are incremental by default.
Strategy
Speed
Works on-prem
How
CSI snapshots
Fastest
Yes (Ceph RBD/FS)
Label a VolumeSnapshotClass with velero.io/csi-volumesnapshot-class: "true"
Native cloud snapshots
Fast
No
Configure snapshotLocations in DPA
Kopia (file-system backup)
Slower, incremental
Yes (any PV)
Set defaultVolumesToFsBackup: true in Backup CR
OADP 1.3 includes a built-in Data Mover that uses Kopia as the uploader mechanism to read snapshot data and write to a Unified Repository, allowing you to restore stateful applications from a remote object store if a failure or cluster corruption occurs.
Key limits and best practices
Always excludeevents, pods, and replicasets from backups — they are recreated automatically
Test restores monthly — an untested backup is not a backup
Pair with etcd backup — OADP covers application data, etcd covers the cluster skeleton; both are needed for full DR
Use hooks for stateful apps (databases, message queues) to get crash-consistent backups
Monitor Velero’s Prometheus metrics at /metrics on the Velero pod and alert on backup.status.phase != Completed
Here’s a practical step-by-step OADP install for OpenShift, using AWS S3 as the backup location. This is the most common pattern and maps to Red Hat’s current OADP flow: install the OADP Operator, create the default credentials secret, then create a DataProtectionApplication (DPA). OADP is the supported OpenShift path for application backup/restore, and for PV snapshots your provider must support native snapshots or CSI snapshots. (Red Hat Documentation)
1. Prereqs
You need:
cluster-admin access
an S3 bucket
AWS credentials with access to the bucket
snapshot support if you want PV snapshots
oc logged into the cluster. OADP also requires a default credentials secret during installation. (Red Hat Documentation)
The Red Hat flow is to install the OADP Operator first, then configure credentials and the DPA. (Red Hat Documentation)
4. Create the AWS credentials file
Create a local file named credentials-velero:
cat <<'EOF' > credentials-velero
[default]
aws_access_key_id=YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key=YOUR_AWS_SECRET_ACCESS_KEY
EOF
Red Hat documents this credentials-velero pattern for AWS-backed OADP installs. (Red Hat Documentation)
5. Create the default OADP secret
Create the required secret in openshift-adp:
oc create secret generic cloud-credentials \
-n openshift-adp \
--from-file cloud=./credentials-velero
For AWS, the default secret name is cloud-credentials. Red Hat notes that the DPA install expects a default secret; otherwise installation fails. (Red Hat Documentation)
6. Create the DataProtectionApplication
Apply a DPA like this:
apiVersion: oadp.openshift.io/v1alpha1
kind: DataProtectionApplication
metadata:
name: dpa
namespace: openshift-adp
spec:
backupLocations:
- velero:
provider: aws
default: true
objectStorage:
bucket: YOUR_S3_BUCKET
prefix: ocp-backups
config:
region: us-east-1
snapshotLocations:
- velero:
provider: aws
config:
region: us-east-1
configuration:
velero:
defaultPlugins:
- openshift
- aws
- csi
Apply it:
oc apply -f dpa.yaml
The DPA is the main OADP custom resource that wires backup storage and snapshot locations, and current OpenShift docs describe these OADP objects as the supported app backup path. (Red Hat Documentation)
7. Wait for OADP to become ready
Check the DPA and pods:
oc get dpa -n openshift-adp
oc get pods -n openshift-adp
You want the DPA to move to a ready state before creating backups. Red Hat’s backup flow requires the DataProtectionApplication to be Ready before backup CRs are used. (Red Hat Documentation)
8. Create your first backup
Once OADP is ready, back up a namespace:
apiVersion: velero.io/v1
kind: Backup
metadata:
name: app-backup
namespace: openshift-adp
spec:
includedNamespaces:
- my-app
snapshotVolumes: true
ttl: 720h
Apply it:
oc apply -f backup.yaml
OADP uses Velero backup CRs for application backup and supports filtering by namespace, labels, or resource type. (Red Hat Documentation)
9. Check backup status
oc get backup -n openshift-adp
oc describe backup app-backup -n openshift-adp
This confirms whether the backup finished and whether volume snapshots were taken.
10. Optional: schedule automatic backups
apiVersion: velero.io/v1
kind: Schedule
metadata:
name: daily-backup
namespace: openshift-adp
spec:
schedule: "0 2 * * *"
template:
includedNamespaces:
- my-app
snapshotVolumes: true
ttl: 720h
Apply it:
oc apply -f schedule.yaml
OADP supports scheduled Velero backups through Schedule objects. (Red Hat Documentation)
11. Common mistakes
No default cloud-credentials secret
wrong bucket region
no snapshot support for your storage class
assuming OADP backs up etcd; it does not
installing into a namespace with an overly long name can cause secret-labeling issues in some OADP cases. (Red Hat Documentation)