Infer Docker registry host from workspace profile

[yolocs]

🥞 Stacked PR (generated by git ns)

Use this link to review incremental changes.

• auth-docker-infer-region-hosts [Files changed]

---

Changes

Docker setup now needs only a workspace profile. The CLI resolves the workspace ID, obtains the workspace region from its metastore summary, derives the full Artifact Registry hostname, and configures Docker for that host:

$ databricks auth docker configure --profile PROD
Configured Docker credential helper for 1234567890123456.container.us-west-2.cloud.databricks.com
Updated Docker config: /Users/alice/.docker/config.json
Installed Docker credential helper: /usr/local/bin/docker-credential-databricks

Users no longer need to look up and supply the workspace home region. The existing --region flag remains available for compatibility, emits a deprecation warning when used, and is scheduled for removal in the next release.

The new read-only host command returns both the derived registry hostname and whether Docker is already configured to use the Databricks credential helper:

$ databricks auth docker host --profile PROD
Registry host: 1234567890123456.container.us-west-2.cloud.databricks.com
Credential helper configured: YES

Structured output makes the result available to scripts without reconstructing the hostname:

$ databricks auth docker host --profile PROD --output json
{
  "host": "1234567890123456.container.us-west-2.cloud.databricks.com",
  "configured": true
}

Both commands now turn an invalid OAuth refresh token into a direct recovery step instead of exposing the underlying token request:

$ databricks auth docker host --profile EXPIRED
Error: A new access token could not be retrieved because the refresh token is invalid. To reauthenticate, run the following command:
  $ databricks auth login --profile EXPIRED

Profiles whose host is not a Databricks workspace domain fail before any workspace request or Docker configuration change:

$ databricks auth docker host --profile CUSTOM
Error: profile "CUSTOM" does not target a supported Databricks workspace host. Select a workspace profile, or create one with databricks auth login --host <workspace-url> --profile <name>

To run these flows end to end against the acceptance test server, a workspace served from http://127.0.0.1 maps to a .localhost registry DNS zone (e.g. 900800700600.container.us-west-2.localhost). This is the same local-testing exception OAuth login already makes for http://127.0.0.1 hosts. The credential helper returns tokens for .localhost registries only to profiles on http://127.0.0.1, so a real workspace's token never reaches a local registry. The test server also gains a default metastore_summary handler.

Why

Workspace profiles do not expose the home region directly, and asking users to discover it separately made Docker setup unnecessarily error-prone. The workspace metastore already provides the matching region, so the CLI can derive the correct registry host from the selected profile and expose that same result for later commands and automation.

The error handling keeps authentication and profile-selection failures actionable, especially when a saved OAuth session has expired or an account profile is selected accidentally.

Tests

Acceptance tests in acceptance/cmd/auth/docker/ now run the real flow against the test server, without --region and without rewriting the profile mid-test:

• configure: host reports the helper as not configured; configure resolves the workspace ID (SCIM) and region (metastore summary), saves workspace_id to the profile, and writes the exact Docker config; host --output json reports it as configured; docker-credential-databricks get returns a token. Recorded requests show which API calls each step makes. A rerun leaves the Docker config unchanged, and the deprecated --region flag makes no API calls.
• configure-errors: unsupported flags, conflicting profile selectors, a non-Databricks host, and a duplicate workspace_id all fail without creating the Docker config or changing profiles.
• host: text and JSON output, credsStore detection, and the profile is never modified.
• token: cached vs. refreshed token, unknown workspace, non-registry host, --profile rejected, a test-server registry never matching a remote profile, duplicate profiles.
• invalid-refresh-token: host, configure, and token all print the re-login command, and no Docker config is created.

Unit tests that walked these flows through mocks were removed. The remaining ones cover what the test server can't reach: shim install ordering, the PATH warning, metastore failures, and the workspace_id = none sentinel.

• go test ./acceptance -run 'TestAccept/cmd/auth' -count=1 (129 passed)
• go test ./cmd/auth/... ./libs/dockercredentials/... ./libs/testserver/...
• ./task lint-q, ./task fmt-q, ./task ws

This pull request and its description were written by Isaac.

[eng-dev-ecosystem-bot]

Integration test report

Commit: 3a91fa6

Run: 35892694001

	Env	✅​pass	🙈​skip	Time
✅​	aws linux	276	21	5:50
✅​	aws windows	278	19	4:20
✅​	azure linux	275	21	6:43
✅​	azure windows	277	19	5:07
✅​	gcp linux	276	21	5:57
✅​	gcp windows	278	19	4:29

Top 3 slowest tests (at least 2 minutes):

duration	env	testname
3:31	azure windows	TestAccept
3:29	aws windows	TestAccept
3:26	gcp windows	TestAccept

[github-actions]

Approval status: pending

/cmd/auth/ - needs approval

7 files changed
Suggested: @simonfaltum
Also eligible: @renaudhartert-db, @hectorcast-db, @parthban-db, @tanmay-db, @Divyansh-db, @tejaskochar-db, @mihaimitrea-db, @chrisst, @rauchy

General files (require maintainer)

6 files changed
Based on git history:

• @pietern -- recent work in cmd/auth/docker/, libs/dockercredentials/, .nextchanges/cli/

_{Any maintainer (@andrewnester, @anton-107, @denik, @pietern, @shreyas-goenka, @simonfaltum, @renaudhartert-db, @janniklasrose, @lennartkats-db, @rugpanov, @rclarey) can approve all areas.
See OWNERS for ownership rules.}

[pietern]

The tests in this PR mock pretty much everything and then go through e2e flows.

I recommend testing the units independently and reserving e2e for acc tests.

[yolocs]

The tests in this PR mock pretty much everything and then go through e2e flows.

I recommend testing the units independently and reserving e2e for acc tests.

@pietern

I restructured the unit tests to exercise each component directly, covering host derivation, helper status, output formats, errors, and config immutability.

I couldn’t add a successful host acceptance test without a much larger change because the logic depends on the profile’s workspace domain. I believe the existing configure acceptance test still provides solid end-to-end coverage of the Docker helper flow.