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

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

az role assignment create \
  --assignee <managed-identity-client-id> \
  --role "Cognitive Services OpenAI User" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>

3. Establish a federated credential

Get the OIDC issuer URL from your AKS cluster:

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:

az identity federated-credential create \
  --name omnia-federated \
  --identity-name omnia-azure-ai \
  --resource-group my-resource-group \
  --issuer <oidc-issuer-url> \
  --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:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: azure-ai
  namespace: agents
  annotations:
    azure.workload.identity/client-id: <managed-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:

spec:
  runtime:
    serviceAccountName: azure-ai
    podLabels:
      azure.workload.identity/use: "true"

To do it for one agent, set spec.podOverrides on the AgentRuntime instead:

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

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

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

az ad sp create-for-rbac \
  --name omnia-azure-ai-sp \
  --role "Cognitive Services OpenAI User" \
  --scopes /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>

2. Create a secret

kubectl create secret generic azure-credentials \
  --namespace agents \
  --from-literal=AZURE_CLIENT_ID=<app-id> \
  --from-literal=AZURE_CLIENT_SECRET=<password> \
  --from-literal=AZURE_TENANT_ID=<tenant-id>

3. Create the provider

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:

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/<spec.model> 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:

az identity federated-credential list \
  --identity-name omnia-azure-ai \
  --resource-group my-resource-group

Ensure the subject matches system:serviceaccount:<namespace>:<service-account-name>, 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:

az role assignment list \
  --assignee <client-id> \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>

Checking provider conditions

kubectl describe provider azure-openai -n agents

Look at the Conditions section for AuthConfigured, CredentialConfigured, and Ready.