Set up EasyFabric with an AI agent

The fastest way to bootstrap a new EasyFabric project is the /setup-easyfabric skill for Claude Code. It downloads a versioned platform release into an empty folder, asks five interview questions, patches the YAMLA simple way to write configurations. It's basically a list that computers can read easily. configuration, bootstraps Microsoft Entra, Azure and Azure DevOps for you, and closes with a short checklist of the remaining Microsoft FabricAn all-in-one data and analytics platform from Microsoft. Think of it as a "digital warehouse" for all your company's information. portal clicks and pipelineAn automated "conveyor belt" that moves data from one place to another or performs a task automatically. runs.

You move from an empty folder to a configured, pushed repository and a first deploy in a single guided session.

New to these terms?

This page assumes you're comfortable with words like SPN, service connection, Key Vault, lakehouseA place where you store both "raw" data (like files) and "organized" data (like tables). It combines the best of a File Cabinet and a Database. and medallion. If any of those are new, skim the Jargon Buster first — it's a one-page glossary written for newcomers.

No Claude Code?

The same release artefacts are downloadable directly — see Without Claude Code further down this page for the manual runbook.

What you'll need

• Claude Code installed and signed in.
• An empty folder for the new project (the agent refuses to extract on top of existing EasyFabric files).
• Python 3 on PATH (used by the bundled fetch/patch helpers — stdlib only, nothing to install).
• The Azure CLI (az), signed in via az login, with the azure-devops extension. This is a hard requirement — the agent's preflight check refuses to continue without it, because the bootstrap scripts drive everything through az.
• An email address to own the EasyFabric license (the agent asks for it early and registers it right away, so the activation email — carrying your apiClientId and apiSecret — is waiting in your inbox by the time the agent asks you to paste them near the end of the session).
• Access to your Microsoft Entra tenant, Azure subscription, Microsoft Fabric capacity, and Azure DevOps project. You don't need everything created up front — the agent flags missing values as <<TBD>> and lists them in the closing checklist.

Running the agent

From the empty target folder, launch Claude Code and paste this single line:

Download https://api.appdm.net/api/skill/setup-easyfabric.zip, extract it to a temp folder, and follow the instructions in setup-easyfabric/SKILL.md.

Claude downloads the skill bundle, unpacks it, reads SKILL.md, and walks the stages below. You can interrupt, redirect or accept defaults at any point.

To pin a specific version, swap setup-easyfabric.zip for setup-easyfabric-<version>.zip — the same naming scheme as the platform release manifest at api.appdm.net/api/skill/versions.json.

1. Answer the interview

The interview is exactly five questions:

1. Platform name — the short name used in all resource names (e.g. Acme).
2. License email — the address that will own the EasyFabric license (one license per email).
3. Environments — pick from dev / tst / acc / prd (default: dev + prd).
4. Azure DevOps organization — auto-detected from your az devops config where possible; you just confirm.
5. Azure DevOps project — offered as a pick-list from your organization.

Everything else is derived, and shown to you as a table of defaults before anything is written: resource groups rg-<platform>-<env>, service connections sc-<platform>-<env>, Fabric workspaces fb-<platform>-<env>, Key Vaults kv-<platform>-<env>-<4 random hex chars> (KV names are globally unique — the suffix avoids collisions), location westeurope, agent pool Azure Pipelines, and lakehouses Bronze / Silver / Gold / Meta. Values like the tenant ID and app registration client ID aren't asked at all — they come out of the bootstrap scripts in the next stage. Want a different name for anything? Just say so and the agent overrides that one value.

Anything not yet known becomes a <<TBD: name>> placeholder you can fill in later.

2. Review the patched files

The agent surgically updates the YAML config that came out of the release zip:

• Generator/Dataplatform/DP/Configuration/dp.<env>.yaml — environment description, service connection, resource group, tenant, app registration, Key Vault, workspace names (EasyFabric resolves the workspace GUID at runtime from the name), tabular model name.
• Yml/environments/<env>.yaml — environment name and description, location, service connection.
• Yml/variables/global.yaml — default pool and default agent.

Per-environment files that don't exist yet are seeded from the nearest sibling. Indentation, quoting and comments in the originals are preserved.

3. Let the bootstrap scripts do the heavy lifting

Two bundled scripts (both idempotent — re-running is a no-op for anything already created) automate the Entra, Azure and DevOps setup:

1. Microsoft Entra + Azure — bootstrap-entra-azure.py creates the app registration and service principal (EasyFabric-<platform>), mints a client secret, creates one resource group per environment, and grants the deploy SPN Contributor + Role Based Access Control Administrator on each RG. See Which rights the SPN needs for the exact role list.
2. Azure DevOps — bootstrap-devops.py creates the Git repo, does the git init and first push from the configured folder, creates a secret-based Azure RM service connection per environment using the SPN from the previous step (the tooling has no federated-identity path — if your organization requires workload identity federation, convert the connection manually afterwards), creates a variable group easyfabric-<env> (workspace name, Key Vault name, SPN secret as a secure variable), and registers the two pipelines: easyfabric-infrastructure (Yml/infrastructure.yml) and easyfabric-<platform>-build (Yml/main_build.yaml).

4. Finish the checklist

The agent closes with a short list of the steps only you can do:

1. Microsoft Fabric portal — four clicks, all [PORTAL] by design (see Why workspaces are pre-created): assign a capacity, create each workspace with the exact name from the interview, add the service principal as Workspace Admin on each workspace, and — once per tenant — enable the Service principals can call Fabric public APIs setting.
2. Run easyfabric-infrastructure for each environment — the pipeline creates the Key Vault, grants the SPN its scoped Key Vault Secrets User role, writes the SPN client secret into the KV, verifies workspace access, and creates the Bronze, Silver, Gold and Meta lakehouses. No manual KV or lakehouse work.
3. Paste your API credentials — open the activation email sent to your license address, click the link, and paste the resulting apiClientId / apiSecret when the agent asks. The agent writes them into apiConfig.yaml, commits and pushes. If your release zip shipped with the shared demo credentials pre-filled, the agent detects this and warns you: the demo key is shared and time-limited, so for a real project it is replaced here with your own — you can only keep it if you say you're just trying the demo.
4. Run easyfabric-<platform>-build — the first deploy.

Any remaining <<TBD>> placeholders are listed at the end with file and line, so nothing slips through.

After setup

Once both pipelines have run green:

1. Verify the Bronze, Silver, Gold and Meta lakehouses appear in the Fabric workspace.
2. Check the easyfabric-<platform>-build run for the deployed notebooks and semantic modelThe "brain" of your data that tells Power BI how different pieces of information relate to each other..

From there, follow the Basics section to add your first source system and table.

Troubleshooting

• "Target folder not empty" — the agent refuses to write into a folder containing Generator, Yml, FabricBuilds, DM or .git. Either run in a fresh folder or pass --allow-non-empty when re-running the install helper.
• SHA-256 mismatch — the release manifest was likely updated mid-fetch. Re-run /setup-easyfabric to retry with the current manifest.
• Cloudflare 403 — the fetch helper sends a custom user agent so this should not happen; if it does, check that outbound HTTPS to api.appdm.net is permitted.
• Status of the release feed — visit api.appdm.net/api/status to confirm the platform release feed and all EasyFabric API endpoints are healthy.

Without Claude Code

If you can't run Claude Code at all, the same artefacts are downloadable directly:

# Platform release (the YAML/notebook/config bundle that gets patched)
# Pick the version from the manifest, then substitute it in the zip name
curl https://api.appdm.net/api/platform/versions.json
curl -O https://api.appdm.net/api/platform/easyfabric-platform-<version>.zip
unzip easyfabric-platform-<version>.zip

# Skill bundle (read SKILL.md as a runbook; the Python helpers are stdlib only)
curl -O https://api.appdm.net/api/skill/setup-easyfabric.zip
unzip setup-easyfabric.zip

You then walk the steps in setup-easyfabric/SKILL.md and setup-easyfabric/REFERENCE.md yourself, calling scripts/fetch-release.py, scripts/patch-config.py, scripts/bootstrap-entra-azure.py and scripts/bootstrap-devops.py from the command line and answering the interview questions in a JSON file. The agent path is strongly recommended — it removes the easiest places to make a typo (tenant GUIDs, workspace names, service connection names).

The two appendix sections below (workspace pre-creation rationale and exact SPN rights) apply to both routes.

Why workspaces are pre-created manually

EasyFabric deliberately does not create Microsoft Fabric workspaces for you. A human creates each workspace once in the Fabric portal, then adds the service principal as Workspace Admin. The agent derives the workspace names (fb-<platform>-<env>) and writes them into the YAML config, so what you create in the portal matches what the pipelines expect.

This is a least-privilege choice for the service principal that runs your deploy pipeline:

Permission the SPN needs	Where it's granted	Scope
Call Fabric REST APIs at all	Tenant setting Service principals can call Fabric public APIs (auth-only gate; enabled by default on new tenants)	Tenant, but grants no data access on its own
Everything inside a workspace — create lakehouses, items, run jobs, read/write OneLake, manage permissions	Workspace Admin role on each workspace	One workspace at a time
(Skipped) Create workspaces, connections, deploymentThe process of "pushing a button" to make your configuration actual, working software in the cloud. pipelines anywhere	Tenant setting Service principals can create workspaces, connections, and deployment pipelines — leave off	Tenant-wide privilege the SPN does not need

With pre-created workspaces, the SPN can do anything inside the workspaces you've granted it — full CRUD on Lakehouses, Warehouses, notebooks, pipelines, semantic models, OneLake data, item permissions — but cannot create new workspaces, cannot create cloud connections, and cannot touch admin APIs elsewhere in the tenant. If the SPN credentials are ever compromised, the blast radius is bounded to those workspaces, not the tenant.

The portal steps you do once, per environment:

1. Assign a Fabric capacity (F-SKU or trial) in the workspace region.
2. Create the workspace with the exact name from the interview (case-sensitive — it must match the YAML; default fb-<platform>-<env>) and assign it to the capacity.
3. Open the workspace → Manage access → add your service principal with role Admin.

And once per tenant: enable the Service principals can call Fabric public APIs setting in the admin portal.

The four lakehouses (Bronze, Silver, Gold, Meta) are not a portal step — the easyfabric-infrastructure pipeline creates them for you.

If the SPN doesn't appear in the Manage access picker, it isn't in the security group allowed by Service principals can call Fabric public APIs. Add it to that group and retry.

Which rights the SPN needs

The "deploy SPN" is the Microsoft Entra service principal behind each environment's Azure DevOps service connection — the identity that runs the bundled pipelines (Yml/infrastructure.yml, Yml/main_build.yaml). It's the SPN that bootstrap-entra-azure.py creates for you (app registration EasyFabric-<platform>). Below is the full list of rights it needs and the exact scope for each.

Microsoft Entra

No tenant-level roles required. The SPN just needs to exist as an app registration with a credential. Membership in the security group allowed by the Fabric tenant setting Service principals can call Fabric public APIs is required and is the only tenant-wide gate.

Azure

In the agent flow this is all done by bootstrap-entra-azure.py, running as your signed-in az identity (which needs the rights to create the app registration and assign roles — Application Administrator or Cloud Application Administrator on the Entra side, Owner or Contributor + User Access Administrator on the Azure side). If you're following the manual runbook instead, the equivalent one-time commands per env are:

# Create the resource group the env will live in
az group create --name rg-<platform>-<env> --location <region>

# Grant the deploy SPN scoped rights on that RG
RG_ID=$(az group show --name rg-<platform>-<env> --query id -o tsv)
az role assignment create --assignee <appId> --role "Contributor" --scope "$RG_ID"
az role assignment create --assignee <appId> --role "Role Based Access Control Administrator" --scope "$RG_ID"

That's the full Azure setup — one az group create and two role assignments, scoped to one resource group, per environment. Everything else (the Key Vault, the Key Vault Secrets User role on it, tags) is provisioned by the infrastructure pipeline.

Resulting role set for the deploy SPN, per env:

Role	Scope	Granted by	Used for
Contributor	Resource group	bootstrap-entra-azure.py (or a human, in the manual runbook)	Creating the Key Vault, tagging
Role Based Access Control Administrator	Resource group	bootstrap-entra-azure.py (or a human, in the manual runbook)	Granting the SPN the next role on its own KV
Key Vault Secrets User	The Key Vault	infrastructure.yml, automatically	Reading the SPN client secret at deploy time

Zero-manual alternative. If you'd rather not create resource groups up front at all, grant the deploy SPN Contributor + Role Based Access Control Administrator at subscription scope instead. The pipeline will then create the RG itself. Only do this when the subscription is dedicated to EasyFabric — in a shared subscription, the SPN can touch anything in it.

Microsoft Fabric

Role	Scope	Granted by	Used for
Membership in the Service principals can call Fabric public APIs security group	Tenant (auth gate only)	Tenant admin, one-time	Authenticating against Fabric REST APIs
Workspace Admin	Each pre-created workspace	Human (workspace owner), one-time per workspace	Creating lakehouses, deploying notebooks/semantic models, reading/writing OneLake, etc.

The Fabric tenant settings Service principals can create workspaces, connections, and deployment pipelines and Service principals can access admin APIs are deliberately left off — the SPN doesn't need them and they would be tenant-wide privilege.

Azure DevOps

The service connection (one per env, created by bootstrap-devops.py as a secret-based Azure RM connection — or by az devops service-endpoint azurerm create in the manual runbook) needs to be authorised for pipelines. After it exists, run:

az devops service-endpoint update --id <id> --enable-for-all

If you prefer per-pipeline authorisation over enable-for-all, authorise each pipeline against the service connection individually in the Azure DevOps UI.

Summary

The deploy SPN's full blast radius for one environment, after all setup is done:

• Azure: one resource group + one Key Vault inside it (read secrets, manage resources in the RG). Cannot touch anything else in the subscription.
• Fabric: one workspace (full admin inside). Cannot create workspaces, cannot touch other workspaces, cannot touch admin APIs.
• Entra: no roles at all beyond existing as an app registration.

Lose the SPN credentials and the worst-case impact is one environment, not the tenant.