Skip to content

XAIBackend

Experimental

This API is experimental and may change without notice.

An Azure AI Services account, a pinned Azure OpenAI model deployment, and account-scoped inference access for an App Service managed identity.

API

Property Value
Group azure.platform.example.org
Kind XAIBackend
Plural xaibackends
Scope Namespaced
Versions v1alpha1 (referenceable)
Source compositions/apis/azure/ai-backend/schema.yaml

Spec

Field Type Required Default Description
accountName immutable string yes — Globally unique Azure AI Services account name.
appServiceRef object yes — XAppService selected by Kubernetes metadata.name whose identity receives inference access.
    appServiceRef.name string yes — Kubernetes metadata.name of the XAppService whose system-assigned identity receives inference access.
deployment object yes — Model deployment configuration.
    deployment.model object yes — Model catalog configuration.
        deployment.model.format string no OpenAI Model API format used by the deployment.
        deployment.model.name string yes — Azure model catalog identifier.
        deployment.model.version string yes — Pinned Azure model version.
    deployment.name string yes — Name of the model deployment.
    deployment.sku object no {} —
        deployment.sku.capacity integer no 1 Deployment capacity in thousands of tokens per minute.
        deployment.sku.name string no Standard Azure model deployment SKU.
location string no swedencentral Azure region for the AI Services account.
name immutable string yes — Logical name of the Azure AI backend.
resourceGroupRef object yes — Resource group hosting the Azure AI Services account.
    resourceGroupRef.name string yes — Logical name of the XResourceGroup.

Fields marked immutable are fixed once the resource is created; changing one is rejected by the API server. An immutable object pins the fields nested under it too. To change one, delete the resource and create it again.

Example

appServiceRef.name is the referenced XAppService's Kubernetes metadata.name, which may differ from spec.name. The XAppService must have systemAssignedIdentity enabled. The account name must be globally unique, and the model/version/SKU must be available in the selected region. The advisor uses the account's services.ai.azure.com endpoint with Microsoft Entra authentication.

kind: XAIBackend
metadata:
  name: appadvisor
spec:
  name: appadvisor
  accountName: ai-appadvisor-lsdev
  resourceGroupRef:
    name: app-hosting-advisor
  appServiceRef:
    name: appadvisor
  location: swedencentral
  deployment:
    name: gpt-4.1-mini
    model:
      format: OpenAI
      name: gpt-4.1-mini
      version: "2025-04-14"
    sku:
      name: Standard
      capacity: 10
---
# The image tag is updated by the app-hosting-advisor workflow on main.
apiVersion: azure.platform.example.org/v1alpha1
kind: XAppService
metadata:
  name: appadvisor
spec:
  name: appadvisor
  resourceGroupRef:
    name: app-hosting-advisor
  image: ghcr.io/sjovang/azure-crossplane-demo/app-hosting-advisor:sha-e37184c
  port: 8080
  size: small
  location: swedencentral
  systemAssignedIdentity: true
  customDomain:
    hostname: appadvisor.demo.liasis.dev
    dnsZone: demo.liasis.dev
    dnsZoneResourceGroup: rg-public-dns
  envVars:
    GITHUB_REPOSITORY: sjovang/azure-crossplane-demo

Taken from teams/app-hosting-advisor/infrastructure.yaml, which is applied to the cluster by Flux, so it cannot drift from a working manifest.

Status

Populated by Crossplane once the underlying Azure resources exist. Every composite in this repository exposes the provisioned Azure resource ID as status.id.

Field Type Required Default Description
deploymentName string no — Name of the deployed model.
endpoint string no — Azure AI Services inference endpoint.
id string no — Azure AI Services account resource ID.

Common problems

Model deployment is not created.

Cause. The model version or deployment SKU is unavailable in the account's region, or the subscription lacks model quota.

Fix. Choose an available model/version and SKU for the selected Azure region, then verify the subscription's deployment quota.

The advisor receives an inference authorization error.

Cause. The App Service identity lacks the role assignment, or the assignment has not propagated yet.

Fix. Confirm the identity is enabled and inspect the appServiceRoleAssignment composed resource; allow time for Azure RBAC propagation.

Reference