Immutable folder support in DABs by andrewnester · Pull Request #5254 · databricks/cli

andrewnester · 2026-05-15T09:56:18Z

Changes

Added support for deploying bundles to immutable folders in the workspace

Enabled by using

bundle:
  deployment: 
    immutable_folder: true

Why

Tests

Added an acceptance tests

eng-dev-ecosystem-bot · 2026-05-28T11:17:06Z

Integration test report

Commit: 3a0ec41

Run: 28019874707

	Env	🟨KNOWN	✅pass	🙈skip	Time
🟨	aws linux	1	216	99	3:18
🟨	aws windows	1	218	97	2:45
🟨	aws-ucws linux	1	297	18	3:26
🟨	aws-ucws windows	1	299	16	3:50
🟨	azure linux	1	216	98	3:19
🟨	azure windows	1	218	96	2:44
🟨	azure-ucws linux	1	299	15	3:57
🟨	azure-ucws windows	1	301	13	3:56
🟨	gcp linux	1	215	100	2:52
🟨	gcp windows	1	217	98	2:31

	Test Name	aws linux	aws windows	aws-ucws linux	aws-ucws windows	azure linux	azure windows	azure-ucws linux	azure-ucws windows	gcp linux	gcp windows
🟨	TestAccept	🟨K	🟨K	🟨K	🟨K	🟨K	🟨K	🟨K	🟨K	🟨K	🟨K

github-actions · 2026-06-01T11:35:34Z

Approval status: pending

`/acceptance/bundle/` - needs approval

23 files changed
Suggested: @denik
Also eligible: @pietern, @janniklasrose, @shreyas-goenka, @lennartkats-db, @anton-107

`/bundle/` - needs approval

26 files changed
Suggested: @denik
Also eligible: @pietern, @janniklasrose, @shreyas-goenka, @lennartkats-db, @anton-107

`/cmd/bundle/` - needs approval

Files: cmd/bundle/utils/process.go
Suggested: @denik
Also eligible: @pietern, @janniklasrose, @shreyas-goenka, @lennartkats-db, @anton-107

`/libs/sync/` - needs approval

Files: libs/sync/sync.go
Suggested: @simonfaltum
Also eligible: @tanmay-db, @Divyansh-db, @renaudhartert-db, @parthban-db, @hectorcast-db, @tejaskochar-db, @mihaimitrea-db, @chrisst, @rauchy

General files (require maintainer)

Files: acceptance/bin/print_requests.py, libs/testserver/handlers.go
Based on git history:

@denik -- recent work in bundle/phases/, bundle/config/mutator/, bundle/config/

_{Any maintainer (@anton-107, @denik, @pietern, @shreyas-goenka, @simonfaltum, @renaudhartert-db) can approve all areas.

See OWNERS for ownership rules.}

shreyas-goenka

Minor comments - other than the bit where we use metadata.json

shreyas-goenka · 2026-06-02T16:30:01Z

@@ -15,6 +15,9 @@ type Bundle struct {

 type Workspace struct {
 	FilePath string `json:"file_path"`
+	// SnapshotPath is the workspace path of the immutable snapshot uploaded
+	// during deployment. Only populated for bundles with bundle.immutable = true.
+	SnapshotPath string `json:"snapshot_path,omitempty"`


Will the UI use the immutable snapshot path? In that case we'll need to add it to DMS as well.

shreyas-goenka · 2026-06-02T16:44:42Z


 				// Perform resolution only if the path starts with one of the specified prefixes.
 				if slices.ContainsFunc(prefixes, path.HasPrefix) {
+					if slices.Contains(m.excludePaths, path.String()) {


very nitpicky: Make this more robust? This matches substrings - so "abc" would match "abc" and "abcd". Normally in the codebase - paths refer to exact paths, not patterns or substrings.

pietern

I see the existing tests pass against cloud, but recommend including a testserver implementation already. Makes it easier to iterate.

pietern · 2026-06-16T12:42:07Z

+		}
+		return 0
+	})
+	return files, nil


The logic that collects the list of files looks very similar to what we do in libs/sync. Any chance we can let that pkg take care of building the list and we refer to it here? This set of files is also configured as b.Files for telemetry. If we chase the path that sets it we might be able to reuse it?

shreyas-goenka · 2026-06-19T12:13:58Z

+		}
+
+		// The real API uses the workspace user UUID (not email) in the snapshot path,
+		// matching service-principal identities used in cloud acceptance tests.


optional: Should we also use UUIDs here for better fidelity? The benefits are minor if we have cloud coverage. The difference being users have CAN_MANAGE always on their home directory but that's likely not true for /Users/userId?

shreyas-goenka · 2026-06-19T12:27:36Z

            Whether to fail on active runs. If this is set to true a deployment that is running can be interrupted.
+        "immutable_folder":
+          "description": |-
+            Whether to upload bundle files and artifacts as a single immutable snapshot. When true, all files are packaged into a zip and uploaded via the snapshot API, and workspace.file_path and workspace.artifact_path are set to the returned content-addressed path. The validate and plan commands make no mutative API calls when this is enabled.


Snapshots API is internal. We should not refer to this in the docs.

shreyas-goenka · 2026-06-19T12:30:36Z

+func (m *translateResourcePaths) Name() string { return "snapshot.TranslateResourcePaths" }
+
+func (m *translateResourcePaths) Apply(_ context.Context, b *bundle.Bundle) diag.Diagnostics {
+	localPrefix := b.SyncRootPath + "/"


Maybe strings.TrimSuffix("/") as well to account for trailing /? Or is that not possible?

shreyas-goenka · 2026-06-19T12:33:34Z

+func (s *loadState) Name() string { return "snapshot.LoadState" }
+
+func (s *saveState) Apply(ctx context.Context, b *bundle.Bundle) diag.Diagnostics {
+	if b.Config.Workspace.SnapshotPath == "" {


Do we not need to store this remotely? The code reads like it only does local storage but we need it in remote as well.

This sounds like something we can add to resources.json

shreyas-goenka · 2026-06-19T12:34:21Z

+
+// SaveState writes the snapshot path to the local deployment state directory
+// so it can be recovered during destroy without reading metadata.json.
+func SaveState() bundle.Mutator {


Consider integrating this with deployment WAL? If we can record the snapshot upload event we can avoid reuploading it on a subsequent deployment since it already exists.

We can't really, can we? The deployment WAL calculated before the execution of deployment as part of plan but we build and upload later in the phase

I assume during deployments we write to WAL so surely we should be able to do that during / after file upload? Otherwise do how do we capture if the plan was partially applied.

I could be misunderstanding the WAL - I'm not familiar with it (will look into it) - I just assumed it records actions as we do them.

Sorry, I misunderstood you and thought you're talking about execution graph and not WAL :) WAL indeed makes sense but it's currently limitted to only creation of resources. I think it might worth expanding it generally to more steps of deploy but this is outside of the scope

shreyas-goenka · 2026-06-19T12:37:21Z

+>>> [CLI] jobs get [NUMID]
+"/Workspace/Users/[UUID]/.snapshots/test-bundle-immutable-no-artifacts-[UNIQUE_NAME]/[SNAPSHOT_HASH]/src/files/src/notebook"
+
+>>> [CLI] bundle destroy --auto-approve


can we assert that destroy deletes the snapshot? Even when .databricks is removed?

shreyas-goenka · 2026-06-19T12:40:23Z

 		// Updates (dynamic): resources.* (strings) (resolves variable references to their actual values)
 		// Resolves variable references in 'resources' using bundle, workspace, and variables prefixes
-		mutator.ResolveVariableReferencesOnlyResources(),
+		resourceResolver,


why this diff?

shreyas-goenka · 2026-06-19T12:42:55Z

@@ -0,0 +1,16 @@
+Local = false


we can run locally as well? As long as we fix the snapshot API impl in test server?

pietern · 2026-06-23T06:46:34Z

+}
+
+func (m *overrideImmutableFolder) Apply(ctx context.Context, b *bundle.Bundle) diag.Diagnostics {
+	if env.Get(ctx, "DATABRICKS_IMMUTABLE_FOLDER") == "" {


For later: move to bundle/env to centralize all env vars we use, and infix with _BUNDLE_.

pietern · 2026-06-23T06:53:10Z

 	state.Files = fl

+	// Persist the snapshot path so destroy on a different machine can find it.
+	state.SnapshotPath = b.Config.Workspace.SnapshotPath


This state file is not needed for destroy today because we remove the file path recursively.

Storing a different path means there is proper state to keep track of.

Can this be implemented as a (hidden?) direct engine resource instead? Then we keep track of it next to the other state, benefit from the WAL, can auto-resolve paths on deployment, etc.

Agreed, this might be useful. The only limitation I see it is that this will be only available for direct engine while now it's both.
Also I believe we don't strictly need this in the version revision of the feature and can follow up with this later

Immutable folder support in DABs

b685ec2

andrewnester requested a review from pietern May 15, 2026 09:56

andrewnester temporarily deployed to test-trigger-is May 15, 2026 09:56 — with GitHub Actions Inactive

andrewnester added 2 commits May 28, 2026 11:03

remove unused snapshot path method

a429b26

added an acceptance test

e7c1968

andrewnester temporarily deployed to test-trigger-is May 28, 2026 10:01 — with GitHub Actions Inactive

fix for notebook import

67914d0

andrewnester temporarily deployed to test-trigger-is May 28, 2026 10:19 — with GitHub Actions Inactive

removed unused function

549492a

andrewnester temporarily deployed to test-trigger-is May 28, 2026 10:41 — with GitHub Actions Inactive

andrewnester marked this pull request as ready for review June 1, 2026 11:34

fix schema + unit test

aedfdb0

andrewnester temporarily deployed to test-trigger-is June 1, 2026 11:39 — with GitHub Actions Inactive

andrewnester requested a review from denik June 2, 2026 10:01

shreyas-goenka reviewed Jun 2, 2026

View reviewed changes

andrewnester and others added 2 commits June 9, 2026 12:49

use immutable_folder config

eddec61

Merge branch 'main' into demo-immutable

27a6b02

andrewnester temporarily deployed to test-trigger-is June 9, 2026 10:51 — with GitHub Actions Inactive

remove merge conflict

4a9bcd9

andrewnester temporarily deployed to test-trigger-is June 9, 2026 10:53 — with GitHub Actions Inactive

fix empty artifact path + tests

ebd26ea

fixed test config

5efe1da

andrewnester temporarily deployed to test-trigger-is June 9, 2026 13:09 — with GitHub Actions Inactive

pietern reviewed Jun 16, 2026

View reviewed changes

andrewnester and others added 2 commits June 18, 2026 16:06

fixes

6215a49

Merge branch 'main' into demo-immutable

7b44126

andrewnester requested review from pietern and shreyas-goenka June 18, 2026 14:08

andrewnester temporarily deployed to test-trigger-is June 18, 2026 14:09 — with GitHub Actions Inactive

andrewnester added 2 commits June 18, 2026 18:49

fix fmt

be6dec3

fix annotations

0f1ed52

andrewnester temporarily deployed to test-trigger-is June 18, 2026 16:50 — with GitHub Actions Inactive

andrewnester added 2 commits June 18, 2026 18:56

fix lint

d978559

do not call set permissions on immutable ws root

9a6c898

andrewnester temporarily deployed to test-trigger-is June 18, 2026 17:00 — with GitHub Actions Inactive

shreyas-goenka reviewed Jun 19, 2026

View reviewed changes

addressed feedback

079998b

andrewnester temporarily deployed to test-trigger-is June 22, 2026 08:40 — with GitHub Actions Inactive

andrewnester requested a review from shreyas-goenka June 22, 2026 08:41

pietern reviewed Jun 23, 2026

View reviewed changes

no destroy + acl + fix for empty path

c6b1ff5

andrewnester temporarily deployed to test-trigger-is June 23, 2026 10:11 — with GitHub Actions Inactive

pr feedback

3a0ec41

andrewnester temporarily deployed to test-trigger-is June 23, 2026 10:31 — with GitHub Actions Inactive

Conversation

andrewnester commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Why

Tests

Uh oh!

eng-dev-ecosystem-bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Integration test report

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approval status: pending

/acceptance/bundle/ - needs approval

/bundle/ - needs approval

/cmd/bundle/ - needs approval

/libs/sync/ - needs approval

General files (require maintainer)

Uh oh!

shreyas-goenka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pietern left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shreyas-goenka Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

andrewnester commented May 15, 2026 •

edited

Loading

eng-dev-ecosystem-bot commented May 28, 2026 •

edited

Loading

github-actions Bot commented Jun 1, 2026 •

edited

Loading

`/acceptance/bundle/` - needs approval

`/bundle/` - needs approval

`/cmd/bundle/` - needs approval

`/libs/sync/` - needs approval

shreyas-goenka Jun 19, 2026 •

edited

Loading