onelake-catalog-govern-cli

> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry > `x-ms-fabric-skill: onelake-catalog-govern-cli` (`az rest`: `--headers "x-ms-fabric-skill=onelake-catalog-govern-cli"`), > including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway. > **CRITICAL NOTES** > 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering > 2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering # OneLake Catalog Govern — CLI (mode dispatcher) One skill for the whole OneLake Catalog **Govern** family. The governance persona detail lives in four **mode references** loaded on demand. This top-level file exists to do three things and nothing else: 1. **Pick the mode** (the table below). 2. **Surface the safety boundary and the irreversible-write gates** so they are never diluted inside a large reference (see [Irreversible operations](#step-2--irreversible-operations--must-do-gates-read-before-any-write)). 3. **Load exactly one mode reference** and follow it. ## Must/Prefer/Avoid ### MUST DO - Start with the audit cell for the caller's permission tier before any remediation. - Apply the operation-specific confirmation gate in Step 2 before every destructive, irreversible, or broad write. - Use the exact Fabric Admin, Core, Power BI, or Graph API surface documented for the selected procedure; do not treat a `401` or `403` as permission to bypass RBAC. - State scope, exclusions, pagination completeness, and freshness caveats with every governance statistic. ### PREFER - Use least-privileged Core or Power BI APIs for data-owner actions instead of requiring tenant-admin rights. - Report findings as evidence, consequence, recommended action, priority, and effort rather than returning an inventory dump. - Sequence ownership and access-scope fixes before bulk assignment or labeling. ### AVOID - Do not mutate a tenant from an audit mode. - Do not invent write APIs for endorsement, DLP policy, admin item deletion, or third-party item-identity assignment. - Do not report asynchronous `202` responses as successful completion. ## Step 1 — Pick the mode **Two axes → a 2×2 grid.** Tier (which API surface you can reach) × action (audit vs. remediate). Each cell covers all three Govern pillars (health / protect / trust). | | **Audit** (read-only) | **Remediate** (write) | |---|---|---| | **Fabric Admin** — `/v1/admin/*`, **Fabric tenant admin only** | `admin-audit` | `admin-remediate` | | **Data owner / Operational admin** — Core API + workspace/domain/capacity admins, no tenant admin | `dataowner-audit` | `dataowner-remediate` | | Mode | Load this reference | Persona / permission tier | Scope | Reads | Writes | |---|---|---|---|---|---| | **admin-audit** | [references/admin-audit.md](references/admin-audit.md) | **Fabric tenant admin** (`/v1/admin/*`) | Whole tenant | ✅ | ❌ | | **admin-remediate** | [references/admin-remediate.md](references/admin-remediate.md) | **Fabric tenant admin only** — every `/v1/admin/*` write requires the Fabric administrator role; **domain & capacity admins do NOT qualify** | Whole tenant | ✅ | ✅ | | **dataowner-audit** | [references/dataowner-audit.md](references/dataowner-audit.md) | **Non-admin** workspace or domain owner (Core API only) | Workspaces the caller administers (widen to accessible on request) | ✅ | ❌ | | **dataowner-remediate** | [references/dataowner-remediate.md](references/dataowner-remediate.md) | **Data owner who is also a domain / workspace / capacity admin** — Core & Power BI API writes, **no tenant admin** | Objects the caller has the role on | ✅ | ✅ (self-service) | ### Routing rules - **Start with an audit mode.** Never remediate before establishing the current state. Audit → remediate within the **same tier** unless the caller's rights change. - **Choose the tier by the API surface the caller can reach**, not by job title: a **Fabric tenant admin** who needs `/v1/admin/*` → the `admin-*` cell; a data owner acting through workspace/domain/capacity roles → the `dataowner-*` cell. - **"Fix / assign / apply / create / delete"** → a **remediate** cell. Tenant-wide writes (create/delete domain, bulk domain assignment, domain roles, bulk labels, certification) → `admin-remediate`. Single-workspace `assignToDomain` or `assignToCapacity`, applying tags, setting descriptions, refresh, and item identity → `dataowner-remediate` (these need object-scoped roles, not tenant admin). - The read/write split is a **safety boundary**: an audit mode must not mutate a tenant even if a prompt asks it to. If you are in an audit mode and the user asks for a write, switch to the matching remediate mode explicitly — do not improvise a write. > **Tier = API surface, not role title.** The `admin-*` modes call `/v1/admin/*` and require the **Fabric tenant administrator** role (Fabric admin / Power Platform admin / M365 global admin) — **domain, capacity and workspace admins do NOT qualify**, even for their own domain. The `dataowner-*` modes use the Core/Power BI APIs scoped to roles the caller already holds on specific objects. A domain/WS/capacity admin who is *not* a Fabric tenant admin therefore lives entirely in the `dataowner-*` cells; they cross into `admin-*` **only if they are separately granted the Fabric tenant admin role**. Roles are **scope branches inside** a mode; only a different **API surface** justifies a separate mode. > ⚠️ **Known Fabric gap — scoped governance has no non-admin API.** A **domain admin** or **workspace admin** who is *not* a Fabric tenant admin currently has **no API path** to their scoped governance posture: `/v1/admin/*` rejects them (it needs the tenant Fabric admin role — see the [Assign Domain Workspaces](https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/assign-domain-workspaces-by-ids#permissions) permission note), and the Core API has **no** endpoint that lists the workspaces in a domain or returns a domain's governance state. `dataowner-audit` can only report on workspaces the caller can directly access — not "my whole domain." If a domain/WS admin asks for their scoped govern details, **state this limitation up front** and do not route them into an `admin-*` mode that will 401/403. ## Step 2 — Irreversible operations — MUST-DO gates (read before any write) > ⚠️ **Why this lives here and not only in the mode reference.** These are terminal, > hard-to-undo acts. When such an instruction sits as one line among dozens inside a > large reference file, it gets read but silently skipped. It is repeated here, in the > auto-loaded dispatcher body, so the gate fires **before** the write — not after. > Full procedures remain in the remediate mode references ([admin-remediate.md](references/admin-remediate.md), [dataowner-remediate.md](references/dataowner-remediate.md)); this is the checklist, not a substitute. Before executing any of these in **either** remediate mode, the gate MUST pass. The **Mode** column shows which cell owns the operation: | Irreversible / terminal act | Mode | Gate that MUST fire first | |---|---|---| | **Delete a domain** (`DELETE /v1/admin/domains/{id}`) | admin | Check for subdomains (`parentDomainId`) **and** assigned-workspace counts for the domain and every subdomain. If any workspaces would be orphaned, STOP and get explicit user confirmation naming the affected domains/workspaces. The REST API has **no** cascade-block — the check is yours. See [domain-crud.md § Deleting a Domain](references/admin-remediate/domain-crud.md#deleting-a-domain--the-portal-vs-api-safety-gap). | | **Delete a tag** definition | admin | Report how many items carry it first — deletion detaches it everywhere with **no undo**. | | **Bulk-assign workspaces to a domain** | admin | Check each target's current `domainId` and warn before **silently overriding** an existing assignment. Dry-run the target list first. | | **Remove a principal from a domain role** | admin | Confirm it will not leave the domain **ownerless**; name the principal being removed. | | **Bulk sensitivity-label change** | admin | Dry-run: show the exact affected item list and before/after label, get confirmation. **No service principal / managed identity** — the call will fail. | | **Write a tenant setting** (e.g. enable certification) | admin | Read the current value and show it, then the proposed value — tenant-wide blast radius. | | **Assign / unassign one workspace to a domain** | dataowner | A move is a **reassignment** — confirm the current `domainId` and name the domain it is leaving. Needs domain-contributor **and** workspace-Admin; say which is missing on failure. | | **Reassign item ownership** (item identity, preview) | dataowner | Assigns to the **caller** only; needs Write on the item and its children. Confirm the intended identity. | | **Assign a workspace to a capacity** | dataowner | Needs workspace Admin plus capacity Contributor/Admin. Async `202` — do **not** report success from the 202 alone; poll to a terminal state. | > **Do not promise a remediation that has no write API.** Endorsement, DLP policies, and item *deletion* by a tenant admin have **no** write route. For those, produce a contact list of who *can* act — see [references/admin-remediate/no-write-api-escalation.md § Route a Finding to Someone Who Can Fix It](references/admin-remediate/no-write-api-escalation.md#route-a-finding-to-someone-who-can-fix-it-escalation-lists). ## Step 3 — Load the reference and proceed Load only the one mode reference matching Step 1 and follow it end to end. Shared background and every leaf procedure are indexed here so each file is one hop from this dispatcher. References are leaves: after loading one, return to this index when another procedure is needed. ### Shared governance references - [Govern pillars](references/govern-pillars.md) — the three pillars, what "good" looks like, and reporting conventions - [Governance data sources](references/govern-data-sources.md) — verified API field coverage, product blind spots, and reporting conventions - [Governance roles](references/govern-roles.md) — permission tiers, domain/workspace roles, and insight refresh lag - [Catalog concepts](references/catalog-concepts.md) — the entity model and API-backed versus conceptual terms - `../../common/COMMON-CORE.md` — repository-level Fabric REST patterns, auth, and pagination - `../../common/COMMON-CLI.md` — repository-level CLI implementation (`az rest`, pagination, auth recipes) ### Mode dispatchers - [Admin audit](references/admin-audit.md) — tenant-wide read-only governance assessment - [Admin audit scope](references/admin-audit-scope.md) — governable denominator, exclusions, and known blind spots - [Admin audit assessment](references/admin-audit-assessment.md) — end-to-end evaluative workflow, prioritization, and deliverable contract - [Admin remediate](references/admin-remediate.md) — tenant-wide guarded writes through Admin APIs - [Data-owner audit](references/dataowner-audit.md) — caller-scoped read-only checks through Core APIs - [Data-owner remediate](references/dataowner-remediate.md) — least-privileged writes through Core and Power BI APIs ### Admin audit procedures - [Domain health](references/admin-audit/health-domains.md) — assignment, ownership, contributor scope, and metadata - [Workspace health](references/admin-audit/health-workspaces.md) — empty/inactive workspaces and admin bus factor - [Capacity health](references/admin-audit/health-capacity.md) — capacity state, ownership, and domain alignment - [Item inventory](references/admin-audit/item-inventory.md) — Admin versus scanner inventory and field coverage - [Item health](references/admin-audit/health-item.md) — ownership, staleness, and refresh state - [Protect coverage](references/admin-audit/protect-labels-dlp.md) — sensitivity labels and DLP visibility - [Trust curation](references/admin-audit/trust-curation.md) — descriptions, endorsement, and tag coverage ### Admin remediation procedures - [Domain lifecycle](references/admin-remediate/domain-crud.md) — create, update, and safely delete domains - [Workspace assignment](references/admin-remediate/domain-assign-workspaces.md) — choose and dry-run bulk assignment methods - [Domain roles](references/admin-remediate/domain-roles.md) — assign admins and contributors - [Tags](references/admin-remediate/tags.md) — manage tenant tag definitions - [Item sensitivity labels](references/admin-remediate/item-sensitivity-label.md) — guarded bulk label changes - [Domain default labels](references/admin-remediate/domain-default-label.md) — prevent new unlabeled backlog - [Trust remediation](references/admin-remediate/trust-curate.md) — certification enablement and delegated actions - [No-write escalation](references/admin-remediate/no-write-api-escalation.md) — identify missing APIs and named owners who can act ### Data-owner procedures - [Data-owner workspace health](references/dataowner-audit/health-workspaces.md) — empty and inactive workspace checks within caller scope ## Examples ```text Audit our tenant's OneLake catalog governance posture and prioritize the findings. ``` ```text Which workspaces I administer are not assigned to a domain? ``` ```text Show a dry run for assigning these workspaces to the Finance domain, including current assignments. ``` ```text Find unlabeled items tenant-wide and explain which remediations require a tenant admin versus a data owner. ```