| → / Space | Next slide |
| ← | Previous slide |
| Home | First slide |
| End | Last slide |
| Swipe | Touch navigation |
Companion to the Well-Architected Agent README and simple guide. Community project, provided as is; not an official Databricks product.
Secure defaults are opt-in, settings live in three places (cloud, account, workspace), and each new workspace is rebuilt by hand from a different starting point.
IP access lists off, serverless egress unrestricted, Unity Catalog not assigned, audit logs not delivered.
A checklist says "done". Nothing records which API call or Terraform resource proved it.
Teams copy an old folder, change a few values, and inherit its gaps.
Not a hosted service, not an LLM judging your setup, and not a tool that applies anything. It prescribes; you decide what to apply and run it yourself.
| Principle | In practice |
|---|---|
| Deterministic | Findings come from rules in the catalog. No timestamps, stable sort: safe for CI gates. |
| Grounded | Every check cites an official doc (the loader refuses one that doesn't) and the tested Terraform that fixes it. |
| Never guesses | A fact it can't see is UNKNOWN, with how to collect it. Never a false pass or fail. |
| Pattern-first | Scored against an architecture, not a flat list, with the upgrade path to the next one. |
| Advisory | Read-only. Fixes are Terraform or CLI for a person to apply. |
terraform show -json, before or after applyaz, gcloud and databricks loginsNetwork in one root, workspace in another, guardrails in a third? Pass each plan; facts merge in any order.
An account-level fact no plan contains (audit log delivery, for example) can be set with --set path=value after you check it in the account console.
wa-agent diagram turns any plan or state into a Mermaid architecture diagram and a resource manifest.
A baseline is what the workspace is supposed to be. Classic means compute runs in a VNet or VPC you bring; serverless means it runs in the Databricks serverless compute plane.
| Baseline | What it is | Azure | Google Cloud | AWS |
|---|---|---|---|---|
serverless | No customer network; a VNet or VPC only for a private front-end | serverless | serverless-ws + guardrails | serverless-ws + guardrails, or the SRA |
classic-no-pl | Your network, no Private Link; public front-end limited to your IPs | non-pl | infra4db + byovpc-ws, or lpw | databricks-aws-production + guardrails |
classic-backend-pl | Back-end Private Link only; public front-end limited to your IPs | assess only | assess only | assess only |
classic-full-pl | Front-end and back-end Private Link; public access off, or on for selected clients | full-private | byovpc-psc-*, or lpw | databricks-aws-production + guardrails, or the SRA |
classic-dep | Data exfiltration protection: controlled egress | hub-spoke firewall, assessed | VPC Service Controls, assessed | the SRA, isolated network |
classic-full-pl. Azure and GCP classic-dep are assessed against the Databricks data exfiltration protection guides.IP access lists from your known ranges (corporate egress, VPN, automation, your Terraform runner). On AWS, context-based ingress limited to them also counts. 0.0.0.0/0 is refused.
A network policy in RESTRICTED_ACCESS, enforced, bound to the workspace, so serverless compute reaches only the destinations you allow.
A metastore assigned to the workspace: one governance layer for data, AI and access.
Required in every baseline on every cloud; they can't be waived, and every build turns them on.
| Option | Adds |
|---|---|
public-access | On classic-full-pl: keeps the public front-end on for selected clients, behind your IP ranges; front-end Private Link stays. |
cmk | Customer-managed keys for managed services, workspace storage and disks. |
data-leak | Notebook export, results download and the notebook table clipboard turned off. |
context-ingress | Allow and deny rules on identity, request type and network source, on top of IP access lists. |
storage-lockdown, storage-private | Azure: workspace storage firewall and service endpoint policy; private endpoints from serverless to your storage. |
--option <id>); options you don't choose show as recommended. Where a build has no setting for an option, the run book lists it as a manual step.A baseline whose compute mode differs from the workspace (say, serverless on a classic workspace) is flagged: moving between them means a new workspace.
With no --baseline, the workspace is scored against the pattern it is detected as, with the upgrade path to the next tier.
wa-agent show classic-full-pl lists every control by area (Network, Storage, Unity Catalog and so on), required or recommended, with its options and builds.
Catch gaps in a plan before anything exists: collect tfplan, then assess.
new writes the folder; you run terraform apply; verify checks the state did what the baseline requires.
collect live reads it with allow-listed read commands only; assess scores it. Azure and Google Cloud; on AWS, use the workspace's Terraform state.
assess --format json --fail-on-gaps fails the build on any required gap.
# 1 · before deploying (any cloud) terraform show -json tf.plan > plan.json uv run wa-agent collect tfplan --cloud aws --plan plan.json -o ws.facts.json uv run wa-agent assess --cloud aws --facts ws.facts.json --baseline classic-full-pl # 2 · after apply uv run wa-agent verify --tf-json state.json --baseline classic-full-pl --option cmk # 3 · a running workspace (Azure, GCP) uv run wa-agent doctor --workspace <name-or-url> uv run wa-agent collect live --cloud gcp --workspace <name-or-url> -o ws.facts.json uv run wa-agent assess --cloud gcp --facts ws.facts.json
doctor --workspace resolves the workspace, matches your CLI logins, tries each data source and says how to fix what's missing, before you scan.
| Section | What's in it |
|---|---|
| Prescription | Every gap in order: required before recommended, then by severity. |
| Gaps against target | Each failed check: evidence, planning-guide phase, official docs, the repo fix. |
| Beyond target | What the workspace does above its baseline. |
| Not evaluable | What it couldn't see, and the access or plan that would show it. |
| Passed, not applicable | The rest, so nothing is silently skipped. |
| Coverage by phase | Organized by the Databricks production planning guide. |
AZ-ING-001 — IP access lists restrict the public front-end required · high · security · phase 4 Network · fix: in_place Evidence access.ip_access_lists_enabled = false from databricks workspace-conf get-status enableIpAccessLists Fix (ground-truth repo, tested) module "workspace" { enable_ip_access_lists = true allowed_ip_ranges = ["203.0.113.0/24"] }
uv run wa-agent demo prints a full report from a real, sanitized Azure workspace. No setup, no cloud access.
uv run wa-agent new --cloud aws --baseline classic-full-pl \ --build awsdb4u --option cmk --out ./my-ws \ --set region=us-west-2 \ --set allowed_ip_ranges='["203.0.113.0/24"]'
| In the folder | Purpose |
|---|---|
terraform/ | The repo's tested Terraform, copied as-is (never state or local tfvars) |
inputs-*.tfvars | Required values; anything you didn't answer is a REPLACE_ME_* |
stage-N-*.tfvars | The baseline's settings, one file per stage, in apply order |
README.md | Run book: sign in, plan, assess the plan, apply, verify |
The run book can't turn on IP access lists without them, so new asks and never invents a default.
Account IDs and client secrets come from TF_VAR_* and DATABRICKS_* variables; they are never written to a file.
Later roots read values such as workspace_url from the previous root's terraform output. CI resolves every emitted value against the real Terraform, for every build and option.
One build per baseline from adb4u/deployments: non-pl, full-private, and serverless (no VNet, the same ARM call as the SRA serverless module).
new-vpc and existing-vpc (standard creation: Databricks creates the IAM roles and firewall rules) or lpw, the least-privilege workspace, for teams that must create those themselves. serverless-ws for serverless.
awsdb4u: databricks-aws-production or serverless-ws, then workspace-guardrails. Or sra, the Databricks Security Reference Architecture, which is also the only classic-dep build.
Pinned to a full commit and never copied (it has its own licence). The run book clones that commit; the folder holds only your inputs and stage settings. CI checks that the variables the catalog records still match the SRA at that commit.
The SRA keeps the public front-end on, limited to your IP ranges by context-based ingress, so its private builds list "public access off" as a known gap. Choose public-access to hold the workspace to that design.
| Capability | Azure | Google Cloud | AWS |
|---|---|---|---|
| Plan and state review | yes | yes | yes |
| Architecture diagram | yes | yes | yes |
| New workspace and verify | yes | yes | yes (awsdb4u, sra) |
| Live, read-only scan | yes | yes | no, by design: checked from Terraform state |
| Data exfiltration protection | hub-spoke firewall, assessed | VPC Service Controls and restricted.googleapis.com, assessed | no internet path or a firewall, S3 endpoint policy; built with the SRA |
tested deployed and verified by the repo owner (the default). validated terraform validate and mock-provider tests only, not yet applied. The new workspace-guardrails and serverless-ws roots on GCP and AWS are labelled validated.
Checks map to cloud-neutral controls, by phase of the Databricks production planning guide and by pillar of the Well-Architected Lakehouse framework.
The agent has no LLM inside, so it works the same under any assistant. Your assistant calls its tools over MCP and relays the report. Every tool is read-only and none writes files.
# register once (doctor prints this with your path)
claude mcp add --scope user databricks-wa -- \
uv run --quiet --frozen --project /abs/path/well-architected-agent wa-agent-mcp
Also Codex CLI, Cursor, Gemini CLI and VS Code: the repo includes their configs.
list_baselines describe_baseline list_patterns preflight collect_live collect_tfplan assess verify diagram new_workspace
"What does classic-full-pl require, and what does the cmk option add?"
"Preflight workspace prod-ws, then assess it against classic-full-pl with public-access, and list the required gaps."
"Assess ./tf.plan.json against serverless before I apply, and draw what it deploys."
"Compare the awsdb4u and sra builds of classic-full-pl on AWS."
The bundled AGENTS.md tells assistants to relay findings unchanged, ask you for the baseline, options and IP ranges, and never apply anything.
Only allow-listed read commands can run (READ_ONLY_COMMANDS, one table per cloud). It never runs Terraform and never overwrites a file. Tests enforce all three.
Every check cites an official doc and, where it exists, the tested Terraform here. Every fact records the command or resource it came from.
The agent prescribes. Choosing what to apply, and when, is yours.
| Runs on your machine | No hosted service, no account to create. macOS, Windows and Linux, tested in CI on all three. |
| No telemetry | The only network calls are read-only calls to your tenant through your own CLI logins. |
| No credentials handled | It never asks for, stores or prints keys or tokens. |
| Safe to share | doctor output is redacted: IDs, AWS account IDs and ARNs, names, emails, tokens. |
| Your data stays local | Facts and reports go only where you choose and are git-ignored by default. Through an assistant, results go to that assistant's model provider under its terms. |
Back-end-only Private Link everywhere, and data exfiltration protection on Azure (hub-spoke) and Google Cloud (VPC Service Controls), are scored against the official guides; the repo has no root for them.
Resource IDs exist only after apply, so a few resources are matched by address name. Live scans match exactly. A VPC managed in another root makes its checks not evaluable until you add that plan.
The agent follows egress to the firewall and checks it has rules and logs; it doesn't compare each destination with the published Databricks list.
The check passes on enforced ingress rules; ingress_dry_run is for testing and doesn't count. The report gives the Terraform to add them, starting in dry run.
Audit log delivery, for example, often lives in another root: add that plan, or set the fact after checking the account console.
Plans before apply, state after. There is no live AWS scan: a running workspace is checked from its terraform show -json state.
brew install uv or winget install astral-sh.uv, then git clone https://github.com/bhavink/databricks.git and cd databricks/well-architected-agent. uv brings everything else.
uv run wa-agent demo: a full report from a real, sanitized workspace, with no setup and no cloud access.
uv run wa-agent doctor checks tools and logins; then assess a plan, scan a workspace, or run new for a fresh one. Every command has --help.
adb4u, gcpdb4u, awsdb4u.Open an issue and paste the output of wa-agent doctor: it's redacted for you.