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​

Compreender a hierarquia de recursos do Lakebase ajuda você a gerenciar dependências no Terraform. Os recursos têm relações pai-filho: você cria um recurso pai antes dos filhos e exclui os filhos antes dos pais.

Project
  └── Branches (main, development, staging, etc.)
        ├── Endpoints (compute for executing queries)
        ├── Roles (Postgres roles)
        └── Databases (Postgres databases)

Neste guia rápido, você seguirá esta hierarquia criando primeiro um projeto, depois uma ramificação de desenvolvimento e, por fim, um endpoint para sua ramificação de desenvolvimento. Os branches permitem criar ambientes isolados de desenvolvimento e teste, além de testar aplicativos com conjuntos de dados realistas.

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​