Introduzione a Terraform per Lakebase

Questa guida illustra come iniziare a usare Terraform per gestire le risorse di Lakebase usando il provider Terraform di Azure Databricks. Si creerà un progetto, si aggiungerà un ramo di sviluppo e un endpoint e quindi li si eliminerà al termine. Si tratta di un flusso di lavoro tipico per la gestione degli ambienti di sviluppo e test.

Prerequisiti

Prima di iniziare, è necessario disporre di quanto segue:

• Terraform installato (versione 1.0 o successiva). Vedere Installare Terraform.
• Un'entità servizio configurata per l'autenticazione da computer a computer (M2M) OAuth con l'autorizzazione CAN MANAGE per il progetto Lakebase. Questa guida richiede CAN MANAGE (CAN USE non è sufficiente perché non consente la creazione o l'aggiornamento delle risorse). Consulta Autorizzare l'accesso dell'entità servizio ad Azure Databricks con OAuth e Gestisci le autorizzazioni del progetto.

Semantica terraform di scalabilità automatica di Lakebase

Le risorse di scalabilità automatica di Lakebase usano la semantica Terraform con campi spec/status per la gestione dello stato dichiarativo. Il spec campo definisce lo stato desiderato, mentre il status campo mostra lo stato corrente.

Gerarchia delle risorse

Le risorse Lakebase seguono una gerarchia padre-figlio: si creano le risorse padre prima delle risorse figlio e si eliminano le risorse figlio prima delle risorse padre. Per il modello di risorse completo (progetti, rami, calcolo, database e altro ancora), vedere Modalità di organizzazione dei progetti.

Ordine delle operazioni per questa guida: Project → Branch → Endpoint

Guida introduttiva: Gestire un progetto Lakebase con Terraform

Seguire questa procedura per creare un progetto di lavoro completo con un ramo di sviluppo e un endpoint di calcolo:

1. Configurare l'autenticazione

Configurare il provider Azure Databricks per l'autenticazione usando l'entità servizio configurata nei prerequisiti. Le risorse di Lakebase richiedono l'autenticazione OAuth, quindi si impostano le variabili di ambiente per le credenziali OAuth dell'entità servizio:

export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_CLIENT_ID="your-service-principal-client-id"
export DATABRICKS_CLIENT_SECRET="your-service-principal-secret"

Configurare quindi il provider per usare queste variabili di ambiente:

terraform {
  required_version = ">= 1.0"

  required_providers {
    databricks = {
      source  = "databricks/databricks"
      version = "~> 1.0"
    }
  }
}

provider "databricks" {
  # Automatically uses DATABRICKS_HOST, DATABRICKS_CLIENT_ID,
  # and DATABRICKS_CLIENT_SECRET from environment variables
}

Per altre opzioni di autenticazione e informazioni dettagliate sulla configurazione di OAuth, vedere Autorizzare l'accesso dell'entità servizio ad Azure Databricks con OAuth e Databricks Terraform provider.

2. Creare un progetto

Un progetto è la risorsa di primo livello che contiene rami, endpoint, database e ruoli.

Creare un progetto di base:

resource "databricks_postgres_project" "app" {
  project_id = "my-app"
  spec = {
    pg_version   = 17
    display_name = "My Application"
  }
}

Eseguire questi comandi per formattare la configurazione e creare il progetto:

terraform fmt
terraform apply

3. Ottenere un progetto

Ottenere informazioni sul progetto appena creato usando un'origine dati:

data "databricks_postgres_project" "this" {
  name = databricks_postgres_project.app.name
}

output "project_name" {
  value = data.databricks_postgres_project.this.name
}

output "project_pg_version" {
  value = try(data.databricks_postgres_project.this.status.pg_version, null)
}

output "project_display_name" {
  value = try(data.databricks_postgres_project.this.status.display_name, null)
}

Eseguire questi comandi per applicare la configurazione e visualizzare i dettagli del progetto:

terraform apply
terraform output

4. Creare un ramo

I rami forniscono ambienti di database isolati all'interno di un progetto.

In questo esempio viene creato un ramo di sviluppo:

resource "databricks_postgres_branch" "dev" {
  branch_id = "dev"
  parent    = databricks_postgres_project.app.name
  spec = {
    no_expiry = true
  }
}

output "dev_branch_name" {
  value = databricks_postgres_branch.dev.name
}

Eseguire questi comandi per creare il ramo e visualizzarne il nome:

terraform apply
terraform output dev_branch_name

5. Creare un endpoint

Gli endpoint forniscono risorse di calcolo per l'esecuzione di query su un ramo.

Assumi la proprietà dell'endpoint primario del branch di sviluppo e applica la tua configurazione ad esso.

resource "databricks_postgres_endpoint" "dev_primary" {
  endpoint_id = "primary"
  parent      = databricks_postgres_branch.dev.name
  spec = {
    endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
  }
  replace_existing = true
}

output "dev_endpoint_name" {
  value = databricks_postgres_endpoint.dev_primary.name
}

Eseguire questi comandi per applicare la configurazione e visualizzare il nome dell'endpoint:

terraform apply
terraform output dev_endpoint_name

Per altri modelli di endpoint, incluse le repliche di sola lettura e la scalabilità automatica personalizzata, consultare il riferimento databricks_postgres_endpoint.

6. Elencare gli endpoint

Elencare gli endpoint nel ramo di sviluppo per visualizzare i dettagli sull'endpoint di lettura/scrittura creato:

data "databricks_postgres_endpoints" "dev" {
  parent = databricks_postgres_branch.dev.name
}

output "dev_endpoint_names" {
  value = [for e in data.databricks_postgres_endpoints.dev.endpoints : e.name]
}

output "dev_endpoint_types" {
  value = [
    for e in data.databricks_postgres_endpoints.dev.endpoints :
    try(e.status.endpoint_type, null)
  ]
}

Eseguire questi comandi per applicare la configurazione e visualizzare i dettagli dell'endpoint:

terraform apply
terraform output dev_endpoint_names
terraform output dev_endpoint_types

7. Elencare i rami

Elencare tutti i rami nel progetto. Verranno restituiti due rami: il ramo di produzione creato automaticamente con il progetto e il ramo di sviluppo creato in un passaggio precedente:

data "databricks_postgres_branches" "all" {
  parent = databricks_postgres_project.app.name
}

output "branch_names" {
  value = [for b in data.databricks_postgres_branches.all.branches : b.name]
}

Eseguire questi comandi per applicare la configurazione e visualizzare i nomi dei rami:

terraform apply
terraform output branch_names

8. Eliminare un ramo

Eliminare ora il ramo di sviluppo creato in precedenza. Si tratta di un flusso di lavoro tipico: creare un ramo per lo sviluppo o il test ed eliminarlo al termine.

Quando si elimina un ramo, eliminare tutti gli endpoint associati e quindi eliminare definitivamente il ramo.

8.1 Eliminare definitivamente l'endpoint

Eliminare l'endpoint per il ramo di sviluppo:

terraform destroy -target=databricks_postgres_endpoint.dev_primary

8.2 Distruggere il ramo

Eliminare definitivamente il ramo di sviluppo:

terraform destroy -target=databricks_postgres_branch.dev

8.3 Rimuovere dalla configurazione

Dopo l'eliminazione definitiva mirata, rimuovere o impostare come commento i blocchi di risorse dai file di configurazione per impedire a Terraform di ricrearli:

• Rimuovere databricks_postgres_branch.dev e i suoi output
• Rimuovere databricks_postgres_endpoint.dev_primary e i suoi output
• Aggiornare tutte le origini dati che fanno riferimento al ramo eliminato (ad esempio, list_endpoints.tf)

Riconciliare quindi lo stato:

terraform apply

Serializzare le risorse sorelle con depends_on

Lakebase elabora un solo ruolo, un database o un'operazione endpoint alla volta all'interno di un singolo ramo. Se si dichiarano due risorse di pari livello di questi tipi nello stesso ramo e Terraform non dispone già di un margine di dipendenza tra di essi (ad esempio, un database che fa riferimento a un ruolo tramite spec.role), Terraform tenta di crearli in parallelo e uno ha esito negativo con un errore di conflitto-operazioni.

La correzione consiste nell'aggiungere un elemento esplicito depends_on in modo che Terraform serializzi l'applicazione:

resource "databricks_postgres_role" "schema_owner" {
  role_id = "schemamigrator"
  parent  = databricks_postgres_branch.main.name
  spec = {
    postgres_role    = "schemamigrator"
    membership_roles = ["DATABRICKS_SUPERUSER"]
  }
}

resource "databricks_postgres_role" "application" {
  role_id = "application"
  parent  = databricks_postgres_branch.main.name
  spec = {
    postgres_role = "application"
  }

  depends_on = [databricks_postgres_role.schema_owner]
}

Passaggi successivi

• databricks_postgres_project nel Registro Terraform. Punto di ingresso per le risorse Lakebase. La barra laterale del Registro di sistema si collega da qui a postgres_branch, postgres_endpoint, postgres_rolee postgres_database.
• Provider Terraform di Azure Databricks
• Gestire i progetti Lakebase
• Esercitazione sullo sviluppo basato su rami