Skip to main content
Last updated on

Terraform state and drift detection for Lakebase

This page explains how Terraform manages the configuration of Lakebase Projects, Branches, Endpoints, Roles, and Databases, and how to reconcile existing resources after upgrading to a provider version that supports drift detection.

Provider versions without drift detection do not detect changes made through the UI, CLI, or API. They apply updates based on changes to your Terraform configuration. The drift and reconciliation guidance below applies to provider versions that support drift detection.

How spec and status work​

These resources use a spec/status model: the spec field defines the resource configuration Terraform manages, and status reports the resource's current state, including values you haven't configured in Terraform. During refresh, managed spec fields reflect their current backend values, so terraform plan can detect changes made through the UI, CLI, or API and propose restoring your configuration.

Omitted fields generally remain outside Terraform management. Input-only fields, immutable fields, and collections have resource-specific behavior. See the resource-specific reference pages before removing fields from a spec: Terraform provider reference.

Use shared Terraform state storage when collaborating on the same resources.

Reconcile existing resources after rollout​

Resources created before Lakebase supported drift detection can show initial in-place updates even when their current values already match your Terraform configuration. Review the proposed changes before applying: an apply sets resource values to those declared in your Terraform configuration.

warning

Investigate any unexpected resource replacement before applying. The drift detection rollout alone is not expected to require replacement.

  1. Run terraform plan after upgrading to a provider version that supports drift detection. Review the first plan before applying it.

  2. For each difference, decide which value you want the resource to have. To use the value declared in your Terraform configuration, leave that field in spec unchanged and apply the reviewed plan. To keep the current value returned by Lakebase, set that value in spec and run terraform plan again.

  3. Replace spec = null with a valid non-null spec. Null specs can produce persistent differences against the object returned during refresh; repeated applies do not resolve those differences. For minimal valid specs, see the resource-specific pages in the Terraform provider reference.

  4. Review the following before applying:

    • Role memberships: Terraform updates replace the complete membership list with spec.membership_roles. Include every membership you want to keep, such as membership_roles = ["DATABRICKS_SUPERUSER"]. Omitting the field can clear all memberships.
    • Branch expiration: Prefer to use a fixed expire_time instead of relative ttl; see the Branch reference.

  5. Apply the reviewed plan, then run terraform plan again to check that the resources converge.

Handle an inconsistency error​

Differences in how values are formatted can cause a provider inconsistency error after apply. If the returned value matches your intended setting, use it in spec and run terraform plan again. Review the new plan before applying.

important

If the field is immutable or the error persists, capture the error and plan output, then contact Databricks Support.

Recover after a partially completed apply​

terraform apply can return an error after some changes have already completed in Lakebase. Recovery depends on whether Terraform was updating an existing resource or creating a new one.

If the error indicates a temporary service issue, check the Databricks status page and wait until the issue is resolved before retrying.

If an update failed, run terraform plan. Review any remaining changes and apply them if needed. Run terraform plan again to check the result.

If creation failed, the resource may already exist in Lakebase without being recorded in Terraform state:

  1. Check whether the resource exists in Lakebase and whether it is recorded in Terraform state.
  2. If it exists in Lakebase but is absent from Terraform state, import it using the resource reference's import instructions and limitations.
  3. Run terraform plan and review the proposed changes before applying.

After importing, you can manage or delete the resource through Terraform.

On this page