Databricks AI Gateway (model access on Databricks)

Category: Infrastructure · Areas: api, infra

Description

Areas

api, infra

Platform

Platform-specific (Databricks). The Databricks realization of model-gateway: how that concern’s constraints are met when a Databricks App calls models through the workspace AI Gateway. The generic constraints (alias, owner, deploy gate, capability, eval-gated rebinds, attribution) live in model-gateway and are not restated here.

Boundary

Owns only the Databricks mechanics below. Identity (service principal vs on-behalf-of) and how settings reach the app belong to databricks-apps; access to a gateway service is a Unity Catalog grant governed by unity-catalog.

Constraints

A gateway service name is an ordinary per-target setting. It is required and validated at deploy like any other; how settings reach the app is databricks-apps’s rule.
Access to a gateway service is a Unity Catalog grant, issued by the module that creates the service (see unity-catalog).
The first deploy is two steps. The app’s service principal exists only after its first deploy, so grant it access after that deploy, then verify with a real call.
Send W3C traceparent on every model call so the product’s spans and the gateway’s land in one trace in the workspace’s trace table. Span content rules are o11y-otel’s.

Drift Signals (anti-patterns to reject in review)

A gateway grant applied by hand or from the product’s repository rather than by the module that owns the service
A first deploy treated as complete before the service principal has access
Model calls that carry no traceparent, leaving the gateway’s records unjoinable to the product’s

When to use

A product that calls models through the Databricks AI Gateway. Composable (no slot). Select it with model-gateway, databricks-apps and unity-catalog.

Artifact Impact

Selecting this concern requires these artifacts to change (a selected concern absent from them is drift):

TD: states how access to each gateway service is granted and in what order on first deploy
deployment-checklist: grants verified by a real call after the first deploy

ADR References

Selecting this concern needs no ADR; concerns.md records it. Write an ADR only when the project deviates from a constraint here.

Practices by activity

Agents working in any of these activities inherit the practices below through runtime work context, such as a DDx bead context digest.

The Databricks specifics only; the generic practices are in model-gateway.

Design

Name who creates each gateway service and issues its Unity Catalog grants.
Decide the identity per call path in databricks-apps; the gateway’s usage record should name the real caller.

Implementation

Send traceparent on every model call.

Deploy

Confirm the owning module applied the services and grants before the app that depends on them. The app’s service principal exists only after its first deploy, so a first deploy is two steps: deploy, then grant it access.
Verify by a real call, not by a merged grant.

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition: model-primary
Issuer: HELIX helix
Signing key: ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source: concerns/databricks-ai-gateway.md
Signed: 2026-10-22T18:09:54Z
Content digest: sha256:f6af7018…a0a63e7b

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON

{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-10-22T18:09:54Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/concerns/databricks-ai-gateway/",
        "digest": {
          "alg": "sha256",
          "value": "f6af701864f99857bc7856ba5a52b13a61fc778a0a898c0baa7bb231a0a63e7b"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "PanhPnkPACdbCvimZbYbL1PHxJ_9FACPdie-2GQofNwb-W6udUXTRK26jOd1P3FVE5L8TBxxbgETE1zSUXIWBA",
      "signed_at": "2026-10-22T18:09:54Z"
    }
  ]
}

attestation file · issuer keys