Actualización de la configuración de Terraform para usar recursos de escalado automático

Esta guía le guía a través de la actualización de una configuración de Terraform existente para usar los recursos de escalado automático de Lakebase (databricks_postgres_project, databricks_postgres_branch, databricks_postgres_endpoint, databricks_postgres_catalog, databricks_postgres_synced_table).

Cuando esto se aplica

Antes de seguir esta guía, confirme que la instancia de Lakebase se ha actualizado al escalado automático. Desde el 12 de marzo de 2026, se crean nuevas instancias de Lakebase creadas a través de la API de instancia de base de datos como proyectos de escalado automático: la configuración de Terraform es la única parte que sigue haciendo referencia a ellas mediante databricks_database_instance. Las instancias aprovisionadas existentes también se actualizan automáticamente al escalado automático a partir de junio de 2026. En ambos casos, los pasos de actualización de configuración de Terraform son los mismos. Consulte la sección "Confirmar que la instancia está en escalado automático" a continuación para averiguar si la instancia de base de datos se ha migrado correctamente o aún no.

Funcionamiento de la actualización

La actualización se realiza en contexto. Los datos no se mueven ni copian. Terraform detiene el seguimiento de los recursos aprovisionados e inicia la administración de la misma base de datos subyacente a través de los recursos de escalado automático, lo que permite desbloquear funcionalidades como la escala a cero y la bifurcación.

El cambio requiere exactamente dos terraform apply invocaciones: una para adoptar los recursos de Autoscaling y otra para eliminar los recursos Provisioned del estado de Terraform.

Para conocer las diferencias conceptuales entre el escalado automático y aprovisionado, consulte Escalado automático de forma predeterminada. En esta página solo se trata la actualización de configuración de Terraform.

Prerequisites

Note

El comportamiento de Lakebase Terraform depende de la versión del proveedor:

  • Sin detección de deriva: Terraform no detecta cambios realizados a través de la interfaz, la CLI o la API. Aplica actualizaciones basadas en los cambios en tu configuración de Terraform.
  • Con detección de deriva: terraform plan detecta cambios en campos spec gestionados realizados fuera de Terraform. Revisa el primer plan de conciliación antes de aplicarlo. Consulta Detección de estado y deriva de Terraform para Lakebase para obtener orientación sobre el despliegue y resolver diferencias persistentes.

Antes de comenzar, necesita lo siguiente:

  • Terraform 1.7 o superior. El import bloque y el removed bloque juntos requieren Terraform 1.7+.
  • Una entidad de servicio configurada para la autenticación OAuth de máquina a máquina (M2M) con el permiso CAN MANAGE en el proyecto. Consulte Autorizar el acceso de una entidad de servicio a Azure Databricks con OAuth y Administrar permisos de proyecto.
  • Una base de datos de Lakebase existente administrada actualmente por Terraform como databricks_database_instance. Si la configuración incluye una instancia secundaria, un databricks_database_database_catalog o un databricks_database_synced_database_table, esta guía también los abarca. Consulte la sección "Confirmar que la instancia está en escalado automático" a continuación para averiguar si la instancia de base de datos se ha migrado correctamente o aún no.
  • Si tiene una tabla sincronizada que actualizar a Autoscaling Terraform, esta guía asume que la tabla Delta de origen ya existe en Unity Catalog con una columna id INTEGER NOT NULL. Esta guía hace referencia a ella como main.default.orders; sustituya el nombre completo de la tabla de origen real.

Cambiar una aplicación de un recurso databricks_database_instance a uno databricks_postgres_project aún no se contempla.

Confirmación de que la instancia está en escalado automático

Antes de actualizar la configuración de Terraform, confirme que la actualización al escalado automático se ha completado para la instancia de base de datos. Los import bloques del paso 2 adoptan un proyecto de escalado automático, ramas y puntos de conexión que solo existen una vez finalizada la actualización.

Para comprobarlo:

  1. Abra la página Provisioned en la aplicación Lakebase, busque su instancia y haga clic para ir a la página de la instancia.
  2. Un banner en la página de instancia confirma si la actualización se ha completado correctamente.
  3. Haga clic en "Ir a la interfaz de usuario de escalado automático". Cuando se encuentre en la página del proyecto de la interfaz de usuario de escalado automático, haga clic en "Configuración". Localice el nombre del recurso y haga clic en el icono de dos cuadrados situado junto al campo «Nombre del recurso» para copiar el nombre del recurso del proyecto de escalado automático. La usará para hacer referencia a los recursos en el bloque de importación de Terraform.

Si la actualización aún no ha finalizado, espere hasta que lo haga antes de continuar. Para solicitar una actualización rápida, póngase en contacto con el equipo de su cuenta o con el soporte técnico de Databricks.

Mapeo de recursos

provisionado Autoscaling
Padre databricks_database_instance databricks_postgres_project además de una production rama creada implícitamente
Punto de conexión de lectura y escritura de la instancia primaria databricks_postgres_endpoint con endpoint_id = "primary" en la production rama
Alta disponibilidad de la instancia primaria (node_count, secundarias legibles) un group de proceso en el spec del punto de conexión production
Hijo databricks_database_instance (opcional) databricks_postgres_branch cuyo branch_id es igual al de la instancia hija name
Punto de conexión de lectura y escritura de la instancia secundaria databricks_postgres_endpoint con endpoint_id = "primary" en la rama secundaria
databricks_database_database_catalog (opcional) databricks_postgres_catalog con el mismo catalog_id
databricks_database_synced_database_table (opcional) databricks_postgres_synced_table con el mismo synced_table_id

Cada instancia aprovisionada corresponde a una rama llamada production en su proyecto de escalado automático. Una instancia secundaria es la excepción: se asigna a una rama separada cuyo branch_id es igual al name de la instancia secundaria.

El ID del proyecto es el de la instancia principalname, en minúsculas; si el nombre contiene letras mayúsculas, el ID del proyecto es su forma en minúsculas. Confírmelo en la interfaz de usuario de Databricks antes de importarlo. Todos los identificadores de importación de ramas usan ese identificador de proyecto como segmento del proyecto, incluso para la rama secundaria.

Paso 1: Estado inicial (aprovisionado)

La configuración inicial tiene este aspecto. Los nombres my-instance, my-child, my-catalog, my_dby main.default.orders son marcadores de posición; use los nombres que ya tengan los recursos reales. La instancia raíz aquí es HA (una principal y una secundaria legible); si la suya no lo es, omita node_count y enable_readable_secondaries. Los bloques de tablas sincronizadas y de catálogo son opcionales: mantenga solo los que ya usa la configuración.

terraform {
  required_providers {
    databricks = {
      source = "databricks/databricks"
    }
  }
}

resource "databricks_database_instance" "root" {
  name     = "my-instance"
  capacity = "CU_2"
  node_count                  = 2
  enable_readable_secondaries = true
}

resource "databricks_database_instance" "child" {
  name     = "my-child"
  capacity = "CU_2"
  parent_instance_ref = {
    name = databricks_database_instance.root.name
  }
}

resource "databricks_database_database_catalog" "cat" {
  name                          = "my-catalog"
  database_instance_name        = databricks_database_instance.root.name
  database_name                 = "my_db"
  create_database_if_not_exists = true
}

resource "databricks_database_synced_database_table" "syt" {
  name                  = "my-catalog.default.orders_synced"
  logical_database_name = databricks_database_database_catalog.cat.database_name
  spec = {
    scheduling_policy                  = "SNAPSHOT"
    source_table_full_name             = "main.default.orders"
    primary_key_columns                = ["id"]
    create_database_objects_if_missing = true
    new_pipeline_spec = {
      storage_catalog = "main"
      storage_schema  = "default"
    }
  }
}

Paso 2 (Aplicar 1): adoptar los recursos de escalado automático

Agregue los nuevos recursos de escalado automático junto con los existentes aprovisionados. Mantén los bloques existentes databricks_database_instance en la configuración. El proyecto y ambas ramas usan un bloque import. Los dos endpoints (el de la rama production y el de la rama hija) usan replace_existing = true para adoptar los endpoints existentes. terraform plan muestra los endpoints como "se crearán", lo cual se espera durante la migración. Los endpoints existentes se conservan tal cual.

Note

Si tu configuración actual establece spec = null en recursos databricks_postgres_project o databricks_postgres_branch, la detección de deriva puede mostrar una diferencia persistente entre null y un objeto de especificación vacío. Configura spec = {} para resolver la diferencia. Cambiar solo spec = null a spec = {} no cambia la configuración del Project o rama existente. Para otros recursos y ramas restauradas por instantáneas, véase Detección de estado y deriva de Terraform para Lakebase.

# In Lakebase Autoscaling, the parent database instance is represented
# by a project plus an implicitly created "production" branch.
resource "databricks_postgres_project" "root" {
  project_id = "my-instance"  # use the ID from section "Confirm your instance is on Autoscaling"
  spec       = {}
}

# Branch corresponding to the parent database_instance.
resource "databricks_postgres_branch" "production" {
  branch_id = "production"
  parent    = databricks_postgres_project.root.name
  spec      = {}
}

# Branch corresponding to the child database_instance.
resource "databricks_postgres_branch" "child" {
  branch_id = "my-child"
  parent    = databricks_postgres_project.root.name
  spec      = {}
  # Keep spec empty during adoption. Setting any spec field causes
  # Terraform to write that value on apply. Fields like source_branch,
  # source_branch_lsn, and endpoint_type are immutable in Lakebase —
  # specifying them forces Terraform to replace (delete and recreate) the
  # resource instead of importing it cleanly. After adoption is complete
  # you can populate mutable fields (such as is_protected) to manage the
  # branch going forward. To look up the source branch, read it from
  # Branch.status.source_branch.
}

# The child branch's primary read-write endpoint.
# Pick one of the spec variants from the tabs below.
resource "databricks_postgres_endpoint" "child_rw_endpoint" {
  endpoint_id = "primary"
  parent      = databricks_postgres_branch.child.name
  spec = {
    endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
  }
  replace_existing = true
}

# The production branch's primary read-write endpoint. Because the parent
# instance is HA, its HA carries over here as a compute `group` (see the
# "Preserving HA" note below). If your parent instance isn't HA, drop the
# `group` and `no_suspension` and keep only `endpoint_type`. If
resource "databricks_postgres_endpoint" "production_rw_endpoint" {
  endpoint_id = "primary"
  parent      = databricks_postgres_branch.production.name
  spec = {
    endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
    no_suspension = true
    group = {
      min                         = 2
      max                         = 2
      enable_readable_secondaries = true
    }
  }
  replace_existing = true
}

# Import the project. Postgres resources use the canonical
# "projects/{project_id}" form as the import ID, where project_id is
# the resource name from section "Confirm your instance is on Autoscaling",
# with "projects/" prefix stripped off.
import {
  to = databricks_postgres_project.root
  id = "projects/my-instance"
}

# Import the production branch. The Provisioned parent always maps to
# a branch named "production" on the new project.
# Use the resource name from section "Confirm your instance is on Autoscaling",
# append "/branches/production" to it.
import {
  to = databricks_postgres_branch.production
  id = "projects/my-instance/branches/production"
}

# Import the child branch. Use the resource name from section
# "Confirm your instance is on Autoscaling", same as when importing
# the "production" branch above. The branch segment is the child instance's name.
import {
  to = databricks_postgres_branch.child
  id = "projects/my-instance/branches/my-child"
}

# The catalog. Pin `catalog_id` to the same name your
# databricks_database_database_catalog already uses, written as a
# literal so the new resource does not depend on the old one. `spec
# = null` is required during adoption — see the "Why spec = null on
# catalog and synced table" note below.
resource "databricks_postgres_catalog" "cat" {
  catalog_id = "my-catalog"
  spec       = null
}

import {
  to = databricks_postgres_catalog.cat
  id = "catalogs/my-catalog"
}

# The synced table. Pin `synced_table_id` to the same fully-qualified
# name your databricks_database_synced_database_table already uses,
# again as a literal.
# `depends_on` is required to build the correct Terraform dependency graph,
# for correct resource management.
resource "databricks_postgres_synced_table" "syt" {
  synced_table_id = "my-catalog.default.orders_synced"
  spec            = null
  depends_on = [
    databricks_postgres_catalog.cat
  ]
}

import {
  to = databricks_postgres_synced_table.syt
  id = "synced_tables/my-catalog.default.orders_synced"
}

Para el punto de conexión spec, elija una de las siguientes variantes.

Note

Por qué spec = null en el catálogo y en la tabla sincronizada. Actualmente, después de terraform import, el spec del catálogo y de la tabla sincronizada se devuelve vacío desde la operación Read del proveedor (los campos de entrada dentro de spec se tratan como de solo escritura). Si deja spec rellenado en HCL, Terraform compara el HCL rellenado con el estado vacío y planea destruir y volver a crear el recurso. Al establecer spec = null, Terraform no tiene nada que comparar, por lo que la importación se conserva. Los datos no se tocan: el servidor ya tiene la configuración correcta desde el momento en que se crearon los recursos aprovisionados. Los campos de especificación también están IMMUTABLE en estos recursos, por lo que, aunque pudieras asignar valores en HCL, no podrías cambiarlos después. Los puntos de conexión, los proyectos y las ramas no necesitan spec = null porque su spec realiza correctamente el recorrido de ida y vuelta mediante Read.

Importar solo los recursos de escalado automático

Adopte el punto de conexión existente tal cual. No hay ningún cambio de comportamiento en el servidor durante la adopción.

spec = {
  endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
}

Uso de la característica de escalado automático durante la importación

Adopte el punto de conexión secundario y reemplace su intervalo de Autoscaling en el mismo terraform apply. Después de la actualización de la plataforma, el punto de conexión ya usa escalado automático con un intervalo predeterminado: CU MÍN. 8 para un punto de conexión adoptado desde una instancia CU_2, con el escalado a cero desactivado. Al establecer límites aquí, se reemplaza ese intervalo predeterminado y, en puntos de conexión sin alta disponibilidad, puede habilitar el escalado a cero sin aplicar los cambios por separado. Consulte Tamaño de proceso para saber por qué MIN es 8 y cómo elegir valores MIN y MAX.

spec = {
  endpoint_type            = "ENDPOINT_TYPE_READ_WRITE"
  autoscaling_limit_min_cu = 4
  autoscaling_limit_max_cu = 16
}

Note

Conservación de la alta disponibilidad. El punto de conexión production anterior conserva la alta disponibilidad de la instancia primaria como un group de proceso: min y max son iguales al node_count de la instancia, y enable_readable_secondaries coincide con la instancia. Los puntos de conexión de alta disponibilidad deben establecer no_suspension = true, por lo que un punto de conexión de alta disponibilidad tampoco puede escalar a cero.

Cualquiera de las opciones es una única terraform apply.

Ejecute terraform apply.

Paso 3 (Aplicar 2): Quite los recursos de Provisioned del estado de Terraform

Una vez que esté seguro de que los recursos de escalado automático administran correctamente la base de datos, quite los bloques originales databricks_database_instance del estado de Terraform. Use un removed bloque con lifecycle.destroy = false para que Terraform deje de administrar el recurso aprovisionado sin eliminar ningún dato.

Quite los databricks_database_instance bloques y los databricks_database_database_catalog / databricks_database_synced_database_table bloques de la configuración y agregue un removed {} bloque para cada uno.

removed {
  from = databricks_database_synced_database_table.syt
  lifecycle {
    destroy = false
  }
}

removed {
  from = databricks_database_database_catalog.cat
  lifecycle {
    destroy = false
  }
}

removed {
  from = databricks_database_instance.child
  lifecycle {
    destroy = false  # it is crucial to set destroy = false. Not doing so results in your database being deleted.
  }
}

removed {
  from = databricks_database_instance.root
  lifecycle {
    destroy = false
  }
}

Ejecute terraform apply.

En la salida del plan, verá líneas como:

# databricks_database_instance.root will no longer be managed by Terraform, but will not be destroyed
# (destroy = false is set in the configuration)
...
... and similar entry for each of the resource you have used removed block for.
...

Esto es lo esperado. Los datos permanecen. Terraform simplemente detiene el seguimiento del recurso aprovisionado y ahora administra la base de datos a través de los recursos de escalado automático que ha adoptado en el paso 2.

Roles y bases de datos de Postgres

Una vez que los recursos de escalado automático están en su configuración, puede usar Terraform para crear y actualizar roles y bases de datos de Postgres en adelante a través de databricks_postgres_role y databricks_postgres_database. Los roles y las bases de datos que ya existen en su base de datos, pero no están declarados en Terraform, no se eliminarán: Terraform solo destruye los recursos que rastrea en el estado. Todavía no se admite la importación de roles y bases de datos que existían antes de la actualización de configuración. Consulte las páginas de referencia databricks_postgres_role y databricks_postgres_database, o la configuración típica de un proyecto de Lakebase con Terraform para ver un ejemplo completo.

Al igual que la rama production y el endpoint primary, todos los proyectos de Autoscaling también tienen un rol y una base de datos creados implícitamente.

Lo que ahora puede hacer tras actualizarse

Una vez que el proyecto se administra como escalado automático, puede hacer cosas que no estaban disponibles en Aprovisionado. Algunos aspectos destacados:

Para obtener una configuración completa de Terraform lista para producción que use muchos de ellos juntos, consulte Configuración del proyecto de Typical Lakebase con Terraform.

Recursos adicionales