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.

dica

Este guia abrange um subconjunto dos comandos Terraform disponíveis. 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 Lakebase seguem uma hierarquia pai-filho: você cria um recurso pai antes dos filhos e exclui os filhos antes dos pais. Para o modelo completo de recursos (projetos, filiais, computação, bancos de dados e muito mais), consulte Projetos.

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 um branch default chamado production com um endpoint compute de leitura e gravação chamado primary. Para configurar qualquer recurso (por exemplo, para habilitar alta disponibilidade no endpoint), declare um databricks_postgres_branch ou databricks_postgres_endpoint correspondente com replace_existing = true. O Terraform assume a propriedade do recurso existente ao fazer a correspondência com base nos IDs conhecidos.

Criar um projeto básico:

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

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

Bash
terraform fmt
terraform apply

enable_pg_native_login = false é o default para novos projetos. Para permitir que as funções nativas do Postgres se conectem com senhas estáticas, defina-o como true. Consulte Gerenciar conexões de senha.

cuidado

Por default, remover um databricks_postgres_project de sua configuração e executar terraform apply exclui suavemente o projeto. Ele é retido por 7 dias. Para excluir permanentemente o projeto imediatamente, adicione purge_on_delete = true ao bloco de recurso antes de removê-lo. Consulte Passo 9: excluir um projeto para obter detalhes.

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

Um branch default production é criado automaticamente quando você cria um projeto e inclui um endpoint de leitura-gravação implícito chamado primary. Ao criar branches adicionais como o branch dev abaixo, cada novo branch também recebe seu próprio endpoint de leitura-gravação implícito primary . O passo 5 mostra como colocar esse endpoint sob o gerenciamento Terraform .

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

Cada ramificação que você cria inclui um endpoint de leitura e gravação criado implicitamente chamado primary. Para colocá-lo sob o gerenciamento do Terraform e aplicar sua própria configuração a ele, declare um recurso databricks_postgres_endpoint com endpoint_id = "primary" e defina replace_existing = true. Isso instrui o Terraform a assumir a propriedade do endpoint existente em vez de tentar criar um novo. Sem replace_existing, a aplicação falha com um erro de operações conflitantes.

Assuma a responsabilidade pelo endpoint principal da branch de desenvolvimento e aplique sua configuração a ele:

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

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

Bash
terraform apply
terraform output dev_endpoint_name

Para outros padrões endpoint , incluindo réplicas somente leitura e dimensionamento automático personalizado, consulte a referência databricks_postgres_endpoint .

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.

O senhor exclui recursos removendo suas declarações de sua configuração e executando terraform apply. O Terraform planeja destruir os recursos que não são mais declarados.

Remova o seguinte de seus arquivos de configuração:

  • O recurso databricks_postgres_branch.dev e suas saídas.
  • O recurso databricks_postgres_endpoint.dev_primary e suas saídas.
  • Qualquer fonte de dados que faz referência ao branch excluído. Por exemplo, o bloco data "databricks_postgres_endpoints" "dev" do passo 6 (e suas saídas dev_endpoint_names e dev_endpoint_types), porque seu parent = databricks_postgres_branch.dev.name falha assim que o branch desaparece.

Em seguida, aplique a alteração:

Bash
terraform apply

Revise o plano de destruição antes de confirmar.

nota

O Terraform destrói o endpoint antes do branch por conta própria. O parent = databricks_postgres_branch.dev.name do endpoint cria uma dependência, então o Terraform ordena as operações corretamente sem nenhuma configuração extra.

9. Exclua um projeto​

Quando você remove um databricks_postgres_project de sua configuração e executa terraform apply, o Terraform exclui suavemente o projeto por default. O projeto é retido por 7 dias, período durante o qual você pode recuperá-lo. Após esse período, o Lakebase o exclui permanentemente.

Para excluir o projeto e todos os recursos filhos, remova-os de sua configuração e execute:

Bash
terraform apply

O Terraform usa o gráfico de dependência para destruir recursos na ordem correta. Revise o plano de destruição antes de confirmar.

Para excluir permanentemente o projeto imediatamente, defina purge_on_delete = true no recurso antes de removê-lo de sua configuração:

Hcl
resource "databricks_postgres_project" "app" {
  project_id      = "my-app"
  purge_on_delete = true  # Permanently delete on apply. Omit to soft-delete (7-day retention).
  spec = {
    pg_version   = 17
    display_name = "My Application"
  }
}

Execute terraform apply para enviar o sinalizador para o estado, em seguida, remova o recurso de sua configuração e execute terraform apply novamente.

nota

A criação de um novo projeto com o mesmo project_id que um projeto excluído suavemente durante o período de retenção de 7 dias falha. Para reutilizar o mesmo ID de projeto, primeiro recupere o projeto existente, force uma exclusão permanente com purge_on_delete = true ou aguarde o período de retenção expirar.

Para recuperar um projeto excluído suavemente antes que o período de retenção de 7 dias expire, use a CLI ou a API.

dica

Para evitar a exclusão acidental de um projeto de produção, adicione um bloco lifecycle:

Hcl
resource "databricks_postgres_project" "app" {
  project_id = "my-app"
  spec       = { ... }

  lifecycle {
    prevent_destroy = true
  }
}

Isso faz com que terraform apply falhe com um erro em vez de excluir o projeto. Remova prevent_destroy = true quando quiser destruir intencionalmente o recurso.

Serializar recurso irmão com depends_on​

Lakebase processa apenas uma função, banco de dados ou operação endpoint por vez em uma única ramificação. Se você declarar dois recursos irmãos desses tipos no mesmo branch, e Terraform ainda não tiver uma aresta de dependência entre eles (por exemplo, um banco de dados referenciando uma função através de spec.role), Terraform tentará criá-los em paralelo e um deles falhará com um erro de operações conflitantes.

A solução é adicionar um depends_on explícito para que o Terraform serialize o apply:

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

Recursos adicionais​

Nesta página