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

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

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.

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.

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

Próximos passos​

Nesta página