We run Terraform as the system of record for Unity Catalog grants, with asset bundles handling a separate layer, and the split of responsibilities turned out to matter more than the tool choice.
The first lesson cost us real debugging time. databricks_grants is authoritative for the securable it points at. It manages the complete grant list on that object, so if two stacks or repos both declare grants on the same catalog, every apply of one silently reverts the other. The symptom is grants that seem to disappear randomly. The fix was organizational rather than technical, exactly one stack owns each securable's grants, and every other team adds grants by pull request to that owner.
Second, humans get access only through groups, with membership managed in the identity provider and synced down. Day-to-day access changes are then membership operations that never touch Terraform. The code changes only when a new group-to-privilege relationship appears, which is rare and worth the review. Service principals get their own explicit grants, since those represent workloads, not people.
Third, your Terraform and metadata-driven options are less opposed than they look. Grant definitions in Terraform are already metadata, maps of principal to privileges fed into for_each, and you can keep that config in YAML files the code reads. That gives you the centralized declarative model of the API approach while keeping plan diffs, code review, and drift detection for free, all things a custom REST engine has to rebuild. In our experience the custom engine only earns its complexity when you need approval workflows or self-service at a scale where pull requests become the bottleneck.
One trap to know about. Account-level roles are not databricks_grants at all but databricks_access_control_rule_set, and every apply replaces the whole rule set it names. Keep all grants for a given rule set path in one resource, and import anything that predates Terraform, because an apply that doesn't include an existing grant removes it.
Manual UI grants we treat as break-glass only. With one owner per securable, anything added by hand shows up in the next plan and either gets codified or reverted, which is exactly the audit trail you want.
How many teams will be requesting access in your setup? The single-owner pull request model holds up well to a point, and past that point the metadata layer in front of Terraform is where I'd invest.
