Pular para o conteúdo principal
Última atualização em

Comece com Terraform para Lakebase

Este guia ajuda você a começar com Terraform para gerenciar o recurso Lakebase usando o provedor Databricks Terraform . Você criará um projeto, adicionará uma ramificação de desenvolvimento e um endpoint e, em seguida, os excluirá quando terminar. Este é um fluxo de trabalho típico para gerenciar ambientes de desenvolvimento e teste.

Para obter a referência completa dos recursos e todas as opções de configuração disponíveis, consulte a documentação do provedorDatabricks no Terraform Registry.

Pré-requisitos​

Antes de começar, você precisa de:

Semântica Terraform com dimensionamento automático do Lakebase​

O recurso de escalonamento automático do Lakebase usa a semântica Terraform com campos spec/status para gerenciamento de estado declarativo. O campo spec define o estado desejado, enquanto o campo status mostra o estado atual.

info

Importante: Detecção de desvios e alterações fora do Terraform.

Alterações feitas no recurso Lakebase fora do Terraform (usando a interface do usuário, CLI ou API) não são detectadas pela detecção de desvios padrão do Terraform.

Para obter detalhes completos sobre como os campos spec/status funcionam, o comportamento de detecção de desvios e os requisitos de gerenciamento de estado, consulte a documentação do recurso databricks_postgres_project .

hierarquia de recursos​

Os recursos do Lakebase seguem uma hierarquia pai-filho: você cria um recurso pai antes dos filhos e exclui os filhos antes dos pais. Para obter informações completas sobre o modelo de recursos (projetos, filiais, computação, bancos de dados e muito mais), consulte Como os projetos são organizados.

Ordem de operações para este guia: Projeto → Filial → endpoint

Início rápido: gerencie um projeto Lakebase com Terraform​

Siga estes passos para criar um projeto completo e funcional com uma ramificação de desenvolvimento e endpoint compute :

1. Configurar autenticação​

Configure o provedor Databricks para autenticar usando a entidade de serviço que você configurou nos pré-requisitos. O recurso Lakebase requer autenticação OAuth , então você define a variável de ambiente para as credenciais OAuth da sua entidade de serviço:

Bash
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"

Em seguida, configure seu provedor para usar estas variáveis de ambiente:

Terraform
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
}

Para obter mais opções de autenticação e detalhes sobre a configuração do OAuth, consulte Autorizar o acesso da entidade de serviço ao Databricks com OAuth e o provedor Terraform do Databricks.

2. Criar um projeto​

Um projeto é o recurso de nível superior que contém ramificações, endpoints, bancos de dados e funções.

nota

Ao criar um projeto, Databricks provisiona automaticamente uma ramificação de produção default com um endpoint compute de leitura e gravação. Tanto a filial quanto o endpoint são criados com IDs gerados automaticamente.

Criar um projeto básico:

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

Execute estes comandos para formatar sua configuração e criar o projeto:

Bash
terraform fmt
terraform apply

3. Consiga um projeto​

Obtenha informações sobre o projeto que você acabou de criar usando uma fonte de dados:

Hcl
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)
}
dica

fonte de dados retorna valores no campo status . Use try() para acessar com segurança campos que podem não estar disponíveis em todas as versões do provedor.

Execute estes comandos para aplicar a configuração e view os detalhes do projeto:

Bash
terraform apply
terraform output

4. Crie uma ramificação​

Os branches fornecem ambientes de banco de dados isolados dentro de um projeto.

nota

Uma ramificação de produção default é criada automaticamente com seu projeto e inclui um endpoint de leitura e gravação. Ao criar branches adicionais para desenvolvimento, teste ou outros ambientes, um endpoint não é incluído automaticamente. Você deve criar um endpoint, conforme mostrado na etapa 5.

Neste exemplo, você cria uma ramificação de desenvolvimento:

Hcl
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
}

Execute estes comandos para criar a ramificação e view seu nome:

Bash
terraform apply
terraform output dev_branch_name

5. Crie um endpoint​

O endpoint fornece recursos compute para executar consultas em uma ramificação.

nota

A branch de produção default criada com seu projeto já inclui um endpoint de leitura e gravação. Esta seção mostra como criar um endpoint para a branch de desenvolvimento que você criou na etapa anterior.

Crie um endpoint de leitura e gravação para o branch de desenvolvimento:

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

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

Execute estes comandos para criar o endpoint e view seu nome:

Bash
terraform apply
terraform output dev_endpoint_name

6. Listar endpoints​

Liste o endpoint em sua branch de desenvolvimento para view detalhes sobre o endpoint de leitura/gravação que você criou:

Hcl
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)
  ]
}

Execute estes comandos para aplicar a configuração e view os detalhes endpoint :

Bash
terraform apply
terraform output dev_endpoint_names
terraform output dev_endpoint_types
dica

Quando você executa terraform apply e apenas as saídas mudam (sem alterações na infraestrutura), Terraform mostra "Alterações nas Saídas" e atualiza o estado sem modificar o recurso.

7. Liste as filiais​

Liste todas as ramificações do seu projeto. Isso retorna duas ramificações: a ramificação de produção que foi criada automaticamente com seu projeto e a ramificação de desenvolvimento que você criou em uma etapa anterior:

Hcl
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]
}

Execute estes comandos para aplicar a configuração e view os nomes das ramificações:

Bash
terraform apply
terraform output branch_names

8. Excluir um ramo​

Agora exclua a ramificação de desenvolvimento que você criou anteriormente. Este é um fluxo de trabalho típico: criar uma ramificação para desenvolvimento ou teste e excluí-la quando terminar.

Ao excluir uma ramificação, destrua qualquer endpoint associado e, em seguida, destrua a ramificação.

8.1 Destrua o endpoint​

Destrua o endpoint da branch de desenvolvimento:

Bash
terraform destroy -target=databricks_postgres_endpoint.dev_primary

8.2 Destrua o ramo​

Destruir a ramificação de desenvolvimento:

Bash
terraform destroy -target=databricks_postgres_branch.dev

8.3 Remover da configuração​

Após a destruição direcionada, remova ou comente os blocos de recursos dos seus arquivos de configuração para impedir que Terraform os recrie:

  • Remova databricks_postgres_branch.dev e suas saídas
  • Remova databricks_postgres_endpoint.dev_primary e suas saídas
  • Atualize qualquer fonte de dados que faça referência ao branch excluído (por exemplo, list_endpoints.tf)

Em seguida, reconcilie o estado:

Bash
terraform apply
dica

Alternativa: Remover tudo de uma vez

Você também pode remover os blocos de recurso da sua configuração primeiro e depois executar terraform apply. Terraform irá planejar a destruição do recurso. Essa abordagem mostra o plano de destruição completo antes de sua execução.

Próximos passos​