Deploy — AKS host + Databricks workspace

This is the recommended day-1 deployment for a team: a small Kirimana control plane runs on AKS in your Azure subscription, and all data work is dispatched to your Databricks workspace. Kirimana does not run its own warehouse or metastore for the Databricks target — Unity Catalog is the catalog, your ADLS storage is the storage. Fewer moving parts to operate.

+---------------------+         +----------------------+
| Kirimana AKS host   |  ---->  | Databricks workspace |
| (web UI, API,       |         | (Unity Catalog,      |
|  MCP server)        |         |  Workflows,          |
+---------------------+         |  SQL Warehouses)     |
        |                       +----------------------+
        | service-principal token
        v
+---------------------+
| Azure Key Vault     |
| (SP secret, tokens) |
+---------------------+

One platform operator runs this once per team; everyone else onboards afterwards with a git clone (engineers) or a browser (everyone else).

Prerequisites

Requirement	Notes
`az` CLI, authenticated	Rights to create resource groups + RBAC bindings in the target subscription
A Databricks workspace	Premium tier, Unity Catalog enabled, a serverless SQL warehouse running
An Entra ID tenant	Same tenant for the workspace and the service principal
A DW project repo on GitHub	Created via `kiri init ... --remote ... --push`, see the quickstart
An invitation	Kirimana is in private beta; deployment support is invitation-gated

Step 1 — Service principal: the execution identity

Kirimana’s execution identity in the workspace is an Azure AD service principal — not a personal access token, not a user account. This is least-privilege by construction: the SP gets exactly the Unity Catalog grants Kirimana needs to do its job, and nothing it doesn’t.

Provision (or have your platform team provision):

Field	Value
Type	Microsoft Entra ID app registration, e.g. `kirimana-<env>-sp`
Credential	Client secret (rotate every 90 days) or federated credential
Workspace assignment	Added as a workspace user (not admin)
Unity Catalog grants	`USE CATALOG`, `USE SCHEMA`, `CREATE SCHEMA`, `CREATE TABLE`, `MODIFY` on the Kirimana catalog
Storage role	`Storage Blob Data Contributor` on the storage account
Workflows	`Can Manage` permission, so Kirimana can register scheduled jobs

The setup wizard

You don’t wire this by hand. Whoever provisioned the workspace fills in a single handoff file with the workspace URL, catalog, warehouse id, SP client id, and vault references — then you run the wizard:

kiri databricks setup --handoff kirimana-databricks-handoff.yml

The wizard validates the file, runs the health probes (below), and writes the resolved values into your project’s kiri.yml and Azure Key Vault. If a step fails, it prints the specific acceptance criterion that wasn’t satisfied — for example “SP cannot CREATE TABLE in the catalog” — so you can go back to whoever owns the workspace with a precise ask instead of a vague “it doesn’t work”.

Step 2 — Secrets: Key Vault + vault refs

Secrets never live in kiri.yml or the repo. The pattern:

The SP secret is stored in Azure Key Vault.
kiri.yml references it by name:

targets:
  prod:
    adapter: databricks
    host: https://adb-xxxx.azuredatabricks.net
    token: ${vault:databricks/prod:token}
    warehouse_id: w-abc123
    catalog: acme_prod
    schema: bronze

You put values into the vault through the CLI:

kirimana vault put databricks/prod:token --value <SP_TOKEN>

Vault refs resolve at run time, so kiri.yml is safe to commit — which it must be, because the config file is the deployment contract your team reviews in pull requests.

Step 3 — Deploy the control plane to AKS

One command provisions the infrastructure and Helm-installs the Kirimana chart:

az login
az account set --subscription <your-platform-subscription>

kirimana deploy \
  --cloud=azure \
  --topology=same \
  --postgres=managed \
  --region=swedencentral \
  --github-app-id <APP_ID> \
  --github-app-key-path ~/Downloads/kirimana-app.private-key.pem \
  --auth-issuer https://login.microsoftonline.com/<tenant-id>/v2.0 \
  --auth-client-id <azure-ad-app-client-id> \
  --domain kirimana.<your-domain>.com

What it does, in order:

Validates your az session has rights to create a resource group, AKS, Postgres, and Key Vault.
Shows a plan of what it is about to provision and asks for confirmation before applying (~10–15 min): resource group, a 3-node AKS cluster, Azure DB for PostgreSQL Flexible Server, Key Vault with private endpoint, public IP + DNS + Let’s Encrypt certificates, and the workload-identity binding chain AKS → Key Vault → Postgres → Databricks SP.
Pushes the GitHub App credentials and OIDC config to Key Vault.
Helm-installs the Kirimana chart.
Waits for readiness probes (~3 min) and prints your URL: https://kirimana.<your-domain>.com.

The GitHub App credentials let Kirimana commit kiri.yml edits and open pull requests on operators’ behalf — a GitHub App, not a personal access token, is required for production. The --auth-issuer / --auth-client-id pair wires web-app sign-in to your Entra tenant; note this App Registration is separate from the Databricks SP — end users sign into the web app with it, the SP signs into Databricks.

If your organisation pre-provisions infrastructure, pass --existing-aks=<id> --existing-postgres=<id> instead of letting the deploy create them.

Step 4 — Health checks

Verify the whole chain before inviting the team:

kiri databricks health --target prod

Probe	Verifies
`platform-adapter`	`SELECT 1` succeeds on the SQL warehouse
`workflows-adapter`	The SP authenticates against the workspace API
`vault-scope`	Every vault ref in `kiri.yml` resolves
`catalog-accessible`	`USE CATALOG`
`schema-creatable`	`CREATE SCHEMA`
`table-writeable`	`CREATE TABLE`
`table-modifyable`	`MODIFY`
`table-selectable`	`SELECT`
`workflows-can-manage`	The SP can manage jobs

Any FAIL is a blocker, and each one prints the exact GRANT statement that fixes it. For end-to-end diagnosis of the deployed stack — Key Vault path, workload-identity binding, and workspace permissions in one pass — run:

kirimana doctor

Step 5 — The team shape

With the control plane up, the team splits into two onboarding paths — and this is the point of the topology:

Engineers install the CLI, clone the DW project repo, and work the git loop: branch, kiri contract new, kiri lint, push, PR. Once a PR merges, the control plane’s GitOps loop applies it to the workspace. Engineers never hold production credentials — the SP in Key Vault does the applying.

Everyone else — data stewards, domain owners, BI analysts — installs nothing. They sign in to https://kirimana.<your-domain>.com with their corporate identity (Entra ID, Okta, Google Workspace) and work in the browser: browse sources and PII flags, propose kiri.yml changes (which open PRs for review), approve pending changes, and trigger applies with live progress.

Access is role-based, mapped from your identity provider’s groups:

Role	What it allows
`viewer`	Read contracts, lineage, audit log
`author`	Viewer + create and edit contracts in dev/test
`approver`	Viewer + approve diffs and promotions in their domain
`platform_admin`	Everything + RBAC config and production deploys

If a user sees “Access denied” after sign-in, they haven’t been added to the right group yet — a one-line fix for the platform operator.

Troubleshooting

kirimana deploy fails with a permissions error. Your az session lacks rights to create RBAC bindings. Have an admin grant Owner on the target subscription, or pre-create AKS + Postgres and pass them via --existing-aks / --existing-postgres.

Web users see OIDC error: invalid_redirect_uri. The deployed URL isn’t registered in your IdP. Add https://kirimana.<your-domain>.com/api/auth/callback/<provider> to the App Registration’s redirect URIs.

The control plane can’t reach Databricks. Three layers, checked in order by kirimana doctor: the SP token is in Key Vault at the right path, the workload identity is bound in the cluster, and the SP has the Unity Catalog + workspace permissions listed above.