# Configure Azure AI provider Configure an Omnia Provider to call an Azure AI (Azure OpenAI) deployment, authenticating with Azure AD Workload Identity or a service principal. Azure AI Foundry hosts the `openai` and `claude` wire protocols. The examples use `openai`; set `spec.type: claude` to run Anthropic models. `gemini` on Azure is rejected at admission. ## Prerequisites - An AKS cluster with OIDC issuer enabled - An Azure AI (Azure OpenAI) resource with a model deployed - `az` CLI installed and authenticated - Omnia operator installed in the cluster - A Workspace whose namespace is `agents` (the examples use that namespace) ## Option 1: workload identity (recommended) The agent pod authenticates as a managed identity, so no credential is stored in the cluster. ### 1. Create a managed identity ```bash az identity create \ --name omnia-azure-ai \ --resource-group my-resource-group \ --location eastus ``` Note the `clientId` from the output. ### 2. Assign the cognitive services role ```bash az role assignment create \ --assignee \ --role "Cognitive Services OpenAI User" \ --scope /subscriptions//resourceGroups//providers/Microsoft.CognitiveServices/accounts/ ``` ### 3. Establish a federated credential Get the OIDC issuer URL from your AKS cluster: ```bash az aks show \ --name my-cluster \ --resource-group my-resource-group \ --query "oidcIssuerProfile.issuerUrl" -o tsv ``` Create the federated credential. The subject names the ServiceAccount that your agent pods run as; this page creates `azure-ai` in the next step: ```bash az identity federated-credential create \ --name omnia-federated \ --identity-name omnia-azure-ai \ --resource-group my-resource-group \ --issuer \ --subject system:serviceaccount:agents:azure-ai \ --audiences api://AzureADTokenExchange ``` ### 4. Create the service account and attach it to your agents Agent pods do not use the chart's `serviceAccount` value, which belongs to the operator. Create the ServiceAccount yourself and annotate it with the managed identity's client ID: ```yaml apiVersion: v1 kind: ServiceAccount metadata: name: azure-ai namespace: agents annotations: azure.workload.identity/client-id: ``` Then make the agents run as it, with the `azure.workload.identity/use` label on the pod. To do this for every agent in the workspace, set `spec.runtime` on the Workspace: ```yaml spec: runtime: serviceAccountName: azure-ai podLabels: azure.workload.identity/use: "true" ``` To do it for one agent, set `spec.podOverrides` on the AgentRuntime instead: ```yaml spec: podOverrides: serviceAccountName: azure-ai labels: azure.workload.identity/use: "true" ``` An AgentRuntime that sets its own `serviceAccountName` ignores the Workspace defaults entirely, labels included, so repeat the label there. ### 5. Create the provider ```yaml apiVersion: omnia.altairalabs.ai/v1alpha1 kind: Provider metadata: name: azure-openai namespace: agents spec: type: openai # The name of your Azure deployment, not the model family model: gpt-4o platform: type: azure endpoint: https://my-resource.openai.azure.com auth: type: workloadIdentity capabilities: - text - streaming - tools - json ``` ### 6. Verify ```bash kubectl get provider azure-openai -n agents -o wide kubectl get provider azure-openai -n agents -o jsonpath='{.status.conditions}' | jq . ``` The `AuthConfigured` and `Ready` conditions should be `True`. `AuthConfigured` is `True` for any `workloadIdentity` Provider and does not check the federation, so send a message to an agent that uses the Provider to prove the identity works. ## Option 2: service principal For development or environments without Workload Identity, use service principal credentials. ### 1. Create a service principal ```bash az ad sp create-for-rbac \ --name omnia-azure-ai-sp \ --role "Cognitive Services OpenAI User" \ --scopes /subscriptions//resourceGroups//providers/Microsoft.CognitiveServices/accounts/ ``` ### 2. Create a secret ```bash kubectl create secret generic azure-credentials \ --namespace agents \ --from-literal=AZURE_CLIENT_ID= \ --from-literal=AZURE_CLIENT_SECRET= \ --from-literal=AZURE_TENANT_ID= ``` ### 3. Create the provider ```yaml apiVersion: omnia.altairalabs.ai/v1alpha1 kind: Provider metadata: name: azure-openai namespace: agents spec: type: openai # The name of your Azure deployment, not the model family model: gpt-4o platform: type: azure endpoint: https://my-resource.openai.azure.com auth: type: servicePrincipal credentialsSecretRef: name: azure-credentials capabilities: - text - streaming - tools - json ``` The controller sets `AuthConfigured` to `False` if the Secret is missing or lacks one of the three keys. ## Attach the Provider to an agent Reference the Provider from an AgentRuntime: ```yaml apiVersion: omnia.altairalabs.ai/v1alpha1 kind: AgentRuntime metadata: name: my-agent namespace: agents spec: promptPackRef: name: my-prompts providers: - name: default providerRef: name: azure-openai facades: - type: websocket port: 8080 ``` ## Troubleshooting ### Endpoint URL or model name Set `platform.endpoint` to the URL of your Azure resource, for example `https://my-resource.openai.azure.com`. Omnia appends `/openai/deployments/` and the `api-version` query itself, so do not include either. A trailing slash is trimmed. `spec.model` must match the name of the deployment in Azure. ### Identity not federated A missing federation does not change any Provider condition. The agent's LLM calls fail instead. Check that the federated credential exists: ```bash az identity federated-credential list \ --identity-name omnia-azure-ai \ --resource-group my-resource-group ``` Ensure the `subject` matches `system:serviceaccount::`, where the ServiceAccount is the one the agent pod runs as. Then confirm the pod carries the `azure.workload.identity/use` label. ### Role assignment missing Verify the managed identity or service principal has the correct role: ```bash az role assignment list \ --assignee \ --scope /subscriptions//resourceGroups//providers/Microsoft.CognitiveServices/accounts/ ``` ### Checking provider conditions ```bash kubectl describe provider azure-openai -n agents ``` Look at the `Conditions` section for `AuthConfigured`, `CredentialConfigured`, and `Ready`. ## Related pages - [Provider CRD Reference](/reference/core/provider/) - [Workspace CRD Reference](/reference/core/workspace/#runtime) - [Configure AWS Bedrock Provider](/how-to/providers/configure-bedrock-provider/) - [Configure GCP Vertex AI Provider](/how-to/providers/configure-vertex-provider/)