Introdução ao Terraform para Lakebase

Este guia ajuda você a começar a usar o Terraform para gerenciar recursos do Lakebase usando o provedor terraform do Azure Databricks. Você criará um projeto, adicionará um branch de desenvolvimento e um endpoint e os excluirá quando terminar. Esse é um fluxo de trabalho típico para gerenciar ambientes de desenvolvimento e teste.

Dica

Este guia aborda um subconjunto de comandos do Terraform disponíveis. Para obter a referência completa do recurso e todas as opções de configuração disponíveis, consulte a documentação do provedor do Azure Databricks no Registro terraform.

Pré-requisitos

Antes de começar, você precisa de:

Semântica do Terraform de dimensionamento automático do Lakebase

Os recursos de dimensionamento automático do Lakebase usam a semântica Terraform com campos de especificação/status para gerenciamento de estado declarativo. O spec campo define o estado desejado, enquanto o status campo mostra o estado atual.

Importante

Importante: detecção de descompasso e alterações fora do Terraform

As alterações feitas nos recursos do Lakebase fora do Terraform (usando a interface do usuário, a CLI ou a API) não são detectadas pela detecção de descompasso padrão do Terraform.

Para obter detalhes completos sobre como os campos de especificação/status funcionam, comportamento de detecção de descompasso e 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 recursos pai antes dos filhos e exclui os filhos antes dos pais. Para obter o modelo de recurso completo (projetos, branches, computação, bancos de dados e muito mais), consulte Como os projetos são organizados.

Ordem das operações deste guia: Projeto → Branch → Endpoint

Início Rápido: Gerenciar um projeto do Lakebase com o Terraform

Siga estes passos para criar um projeto completo com um branch de desenvolvimento e um endpoint de computação:

1. Configurar a autenticação

Configure o provedor do Azure Databricks para autenticar usando a entidade de serviço configurada nos pré-requisitos. Os recursos do Lakebase exigem autenticação OAuth, portanto, você define variáveis de ambiente para as credenciais OAuth do principal de serviço:

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 essas variáveis de 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
}

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 Azure Databricks com o provedor OAuth e o Databricks Terraform.

2. Criar um projeto

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

Observação

Quando você cria um projeto, Azure Databricks provisiona automaticamente um branch padrão chamado production com um ponto de extremidade de computação de leitura/gravação chamado primary. Para configurar qualquer recurso (por exemplo, para habilitar a alta disponibilidade no ponto de extremidade), declare uma correspondência databricks_postgres_branch ou databricks_postgres_endpoint com replace_existing = true. O Terraform assume a propriedade do recurso existente ao corresponder-se com essas IDs conhecidas.

Crie um projeto básico:

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:

terraform fmt
terraform apply

3. Obter um projeto

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

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

As fontes de dados retornam valores no status campo. 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 exibir os detalhes do projeto:

terraform apply
terraform output

4. Criar um branch

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

Observação

Um branch padrão production é criado automaticamente quando você cria um projeto e inclui um ponto de extremidade de leitura/gravação implícito chamado primary. Quando você cria branches adicionais, como o branch dev abaixo, cada novo branch também obtém seu próprio endpoint de leitura/gravação implícito primary. A etapa 5 mostra como colocar esse ponto de extremidade sob gerência do Terraform.

Neste exemplo, você cria um branch de desenvolvimento:

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 o branch e exibir seu nome:

terraform apply
terraform output dev_branch_name

5. Criar um ponto de extremidade

Os pontos de extremidade fornecem recursos de computação para executar consultas em uma ramificação.

Observação

Cada branch criado inclui um ponto de extremidade de leitura e gravação que é criado implicitamente chamado primary. Para trazê-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 para assumir a propriedade do ponto de extremidade existente ao invés de tentar criar um novo. Sem replace_existing, a aplicação falha com um erro de operações conflitantes.

Assuma controle sobre a endpoint primária do branch de desenvolvimento e aplique sua configuração a ela.

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 exibir o nome do ponto de extremidade:

terraform apply
terraform output dev_endpoint_name

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

6. Listar pontos de extremidade

Liste os endpoints em seu ramo de desenvolvimento para exibir detalhes sobre o endpoint de leitura/gravação que você criou.

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 exibir os detalhes do ponto de extremidade:

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 de infraestrutura), o Terraform mostra "Alterações nas Saídas" e atualiza o estado sem modificar os recursos.

7. Listar branches

Liste todas as ramificações em seu projeto. Isso retorna dois branches: o branch de produção que foi criado automaticamente com seu projeto e o branch de desenvolvimento que você criou em uma etapa anterior:

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 exibir os nomes de branch:

terraform apply
terraform output branch_names

8. Excluir um ramo

Agora, exclua o branch de desenvolvimento criado anteriormente. Esse é um fluxo de trabalho típico: criar um branch para desenvolvimento ou teste e excluí-lo quando terminar.

Ao excluir uma ramificação, destrua os pontos de extremidade associados e, em seguida, destrua a ramificação.

8.1 Destruir o ponto de extremidade

Remova o endpoint do branch de desenvolvimento.

terraform destroy -target=databricks_postgres_endpoint.dev_primary

8.2 Destruir o ramo

Destrua o branch de desenvolvimento:

terraform destroy -target=databricks_postgres_branch.dev

8.3 Remover da configuração

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

  • Remover databricks_postgres_branch.dev e suas saídas
  • Remover databricks_postgres_endpoint.dev_primary e suas saídas
  • Atualizar quaisquer fontes de dados que façam referência ao branch excluído (por exemplo, list_endpoints.tf)

Em seguida, reconcilie o estado:

terraform apply

Dica

Alternativa: remover tudo de uma vez

Você também pode remover os blocos de recursos da sua configuração primeiro e, em seguida, executar terraform apply. O Terraform planeja destruir os recursos. Essa abordagem mostra a você todo o plano de destruição antes de ser executado.

Serializar recursos irmãos com depends_on

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

A correção é adicionar um elemento depends_on explícito para que o Terraform serialize a aplicação:

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óximas etapas

  • Last updated on