Customer workspace installation

Fabric Runway installs inside the customer's Databricks workspace. The customer owns the App, Lakebase database, Unity Catalog Volumes, secret scope, identities, and audit ledger. The installer uses a Databricks Asset Bundle and Fabric Harness; it does not introduce a second deploy engine.

What the installer creates

pnpm customer:deploy builds the standalone console and asks Harness to validate and deploy deploy/databricks/customer/databricks.yml. The bundle creates:

• a fabric_runway schema in the selected Unity Catalog catalog;
• managed artifacts and audit Volumes;
• a protected Lakebase production branch, read/write endpoint, App role, and database;
• the Databricks App with Lakebase, Volume, and secret resource bindings;
• CAN_USE permission for the selected workspace administration group.

No secret value is written to bundle variables, generated app.yaml, Platform action parameters, events, or logs. The bundle binds existing secret keys by reference.

Prerequisites

Use Node.js 22+, pnpm, and an authenticated Databricks CLI profile. The installer identity needs permission to create Apps, Lakebase resources, schemas, managed Volumes, and App resource grants in the selected catalog. The preparation machine needs HTTPS access to the official Databricks CLI GitHub release asset. Preparation pins the certified Linux release, verifies Databricks' published SHA-256, and packages it in sub-10 MB chunks for the managed App runtime; the running App does not download tools from the internet.

Create the customer secret scope and three keys before installation:

databricks secrets create-scope runway-production --profile CUSTOMER
databricks secrets put-secret runway-production runway-secret-command-key --profile CUSTOMER
databricks secrets put-secret runway-production runway-experiments-api-key --profile CUSTOMER
databricks secrets put-secret runway-production runway-evidence-signing-private-key --profile CUSTOMER

runway-secret-command-key must be an independently generated 32-byte AES key encoded as base64 (for example, openssl rand -base64 32). Do not paste it into shell history or commit it; pipe the generator directly into the Databricks CLI or use its interactive input. runway-evidence-signing-private-key must be a dedicated Ed25519 private key in PEM form. Keep its public key and the manifest keyId in the customer's audit key registry so exported release reports can be independently verified.

Configuration

Tenant means an internal business unit or platform boundary inside this enterprise installation. Map Databricks user or group principals to roles, and map every releasable App/gate to a versioned Fabric Experiments dataset:

export RUNWAY_DATABRICKS_PROFILE=CUSTOMER
export RUNWAY_APP_NAME=fabric-runway
export RUNWAY_SECRET_SCOPE=runway-production
export RUNWAY_GOVERNANCE_CATALOG=main
export RUNWAY_ADMIN_GROUP=platform-admins
export RUNWAY_PLATFORM_ADMIN_TENANT_ID=payments
export RUNWAY_ORG_ID=payments
export RUNWAY_EXPERIMENTS_URL=https://experiments.example.internal
export RUNWAY_EXPERIMENTS_ORGANIZATION_ID=org_enterprise
export RUNWAY_EXPERIMENTS_ORGANIZATION_SLUG=enterprise-platform
export RUNWAY_TENANTS_JSON='[
  {"id":"payments","name":"Payments Platform","members":[
    {"principal":"platform-admins","role":"admin"},
    {"principal":"release-reviewers","role":"reviewer"},
    {"principal":"harness-release-agent","role":"operator","principalType":"agent"}
  ]}
]'
export RUNWAY_EXPERIMENT_TARGETS_JSON='[
  {"tenantId":"payments","appId":"app_example","gate":"eval-suite","datasetId":"ds_release","version":7,
   "evaluatorNames":["qa-correctness-reference","relevance"]}
]'

RUNWAY_ORG_ID selects the tenant shown when someone opens the App root or follows a stale tenant URL. It defaults to RUNWAY_PLATFORM_ADMIN_TENANT_ID, and the installer rejects either value unless it identifies an entry in RUNWAY_TENANTS_JSON.

RUNWAY_EXPERIMENTS_ORGANIZATION_ID is the immutable organization id returned by Fabric Experiments GET /api/v1/tenants/me; the optional slug controls human-facing evidence links. Runway tenant ids represent internal business units and intentionally do not need to match the Fabric Experiments organization id. Each target also names the concrete Experiments evaluators; the Runway gate is a stable governance label and is not assumed to be an evaluator name.

When Fabric Experiments is itself hosted as a Databricks App, grant the Runway App service principal CAN_USE on that Experiments App. Runway sends a freshly resolved App OAuth token to the Databricks gateway and the organization-scoped Experiments API key to the typed API; neither token is stored in a governed action or event. A non-Databricks Experiments endpoint may ignore the additional upstream bearer while continuing to enforce its API key.

Certify the Experiments installation independently before using it as a required Runway gate. Its Harness evaluation worker needs USE CATALOG, USE SCHEMA, and SELECT plus MODIFY on its eval_scores table. These grants belong to the Experiments deployment—not Runway—and a missing grant must fail the evaluation rather than being converted into a passing release verdict.

Then deploy:

pnpm install --frozen-lockfile
pnpm customer:validate
pnpm customer:deploy

The validation command is read-only and is the repeatable preflight for identity, variable, resource-reference, and bundle configuration drift. Harness then runs bundle validation, bundle deployment, App startup, and snapshot activation. The installer idempotently grants the App service principal USE CATALOG and USE SCHEMA on the customer-selected artifact parents; the App resource bindings remain the source of WRITE VOLUME on the two Runway Volumes. Re-running the same command is the supported upgrade path; bundle and Platform action identities remain stable.

Every governed bundle attempt resolves a fresh short-lived App service-principal token at the Databricks adapter boundary. The credential stays outside action parameters, durable invocations, events, and logs; Fabric Harness remains the owner of bundle validation, deployment, activation, and destruction. CLI diagnostics are retained for governed recovery only after token and client secret redaction.

At startup the App reassembles and verifies the certified CLI archive in an isolated temporary directory, then points the Harness adapter at that executable. This avoids depending on the managed App image's older preinstalled CLI while preserving Harness' standard bundle command boundary.

Runway resolves the signed-in user's groups through the OBO current-user endpoint. It uses the Databricks Apps default iam.current-user:read and iam.access-control:read scopes, so the bundle does not request broader user API access. Group-derived grants fail closed if that lookup is unavailable; direct user membership remains usable.

First-run verification

1. Open the App through the Databricks Apps UI and confirm workspace identity attribution.
2. In Settings, review the event-sourced tenant policy, policy revision, trusted App worker id, seeded members, and platform-admin business-unit provisioning control.
3. In Artifact Registry, register a Harness-staged build and confirm its digest/provenance.
4. Deploy to a development or PR preview target from Apps.
5. Run the live certification suite, then exercise a real Experiments gate, approval, promotion, approval-cycle reopen, rollback, reconciliation, worker restart, signed evidence export, audit export, and restore drill. The disposable suite also provisions and retires a test business unit.

Trusted-worker rotation

The event-sourced allowlist and running App identity are deliberately reconciled in stages:

1. submit runway.policy_set with both the active and replacement worker ids;
2. deploy the App/worker configuration containing both ids;
3. verify the replacement claims a Platform Host lease and completes a harmless governed action;
4. switch execution to the replacement and confirm normal polling;
5. submit a new policy revision that removes the old id.

Runway rejects a policy update that removes every currently active App worker. If validation fails, keep the old id authorized and roll back the runtime; do not force a settings change out of band.

Production fails closed when Lakebase, App identity, Experiments mapping, trusted worker identity, or registered artifact provenance is absent. Development authentication flags are rejected.