Gerenciar o Lakebase com pacotes de automação declarativa
Este guia ajuda você a começar com Pacotes de Automação Declarativa para gerenciar recursos Lakebase usando infraestrutura como código. Você criará um projeto Lakebase, adicionará uma ramificação de desenvolvimento e endpoint, e aprenderá como gerenciar esses recursos de forma declarativa. Este é um fluxo de trabalho típico para o gerenciamento programático de recursos Databricks em ambientes de desenvolvimento e teste.
Para obter a referência completa do recurso de pacote e todas as opções de configuração disponíveis, consulte recurso de pacote.
postgres_projects é o recurso DABs para escala automática Lakebase . Se você já possui automação usando database_instances, ela continuará funcionando, mas novas instâncias serão criadas como projetos de escalonamento automático Lakebase em vez de instâncias de provisionamento Lakebase . Veja a opção de dimensionamento automático por default.
Pré-requisitos
Antes de começar, você precisa de:
- Databricks CLI versão 0.287.0 ou acima. Para verificar sua versão instalada, execute
databricks -v. Para instalar a Databricks CLI, consulte Instalar ou atualizar a Databricks CLI. Os recursospostgres_catalogsepostgres_synced_tablesexigem a Databricks CLI versão 1.0.0 ou acima. - Autenticação configurada para seu workspace Databricks . Este guia utiliza a autenticação OAuth de usuário para máquina (U2M). Consulte o tutorial "Configurar o acesso ao seu workspace na CLI Databricks .
- CAN MANAGE a permissão em projetos do Lakebase. Consulte as permissões de gerenciamento do projeto.
hierarquia de recursos
Os recursos Lakebase seguem uma hierarquia pai-filho: você cria o recurso pai antes dos filhos. 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
1. Criar uma configuração de pacote
Inicialize um pacote configurável usando o padrão -minimal default . Isso cria uma pasta de pacote com um databricks.yml e obtém sua configuração CLI (incluindo o host workspace ).
databricks bundle init default-minimal
Quando solicitado, insira um nome para o seu projeto de pacote (por exemplo, lakebase-bundle). A CLI cria um diretório com esse nome. Acesse o diretório do pacote:
cd lakebase-bundle
Modifique seu arquivo databricks.yml para definir um projeto, branch e endpoint do Lakebase. Adicione ou atualize a seção resources (e o nome do pacote, se desejar). Por exemplo:
bundle:
name: lakebase-app
resources:
postgres_projects:
my_app:
project_id: 'my-app'
display_name: 'My Application'
pg_version: 17
postgres_branches:
dev_branch:
parent: ${resources.postgres_projects.my_app.id}
branch_id: 'dev'
no_expiry: true
postgres_endpoints:
dev_endpoint:
parent: ${resources.postgres_branches.dev_branch.id}
endpoint_id: 'primary'
endpoint_type: 'ENDPOINT_TYPE_READ_WRITE'
autoscaling_limit_min_cu: 0.5
autoscaling_limit_max_cu: 2
replace_existing: true
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.
Por padrão, a exclusão de um projeto Lakebase o exclui suavemente. O projeto é retido por 7 dias, após os quais o Lakebase o exclui permanentemente. Para excluir permanentemente o projeto imediatamente, passe --purge para o comando da CLI delete-project (não bundle destroy, que não tem o sinalizador --purge). Consulte o Passo 6 para obter detalhes.
Sobre o endpoint : Ao criar um projeto Lakebase, Databricks provisiona automaticamente uma branch de produção default com um endpoint de leitura e gravação. No entanto, quaisquer branches adicionais que você criar (como a branch dev acima) devem ter seu endpoint definido explicitamente na configuração do seu pacote.
Os valores project_id, branch_id e endpoint_id devem seguir as regras de nomenclatura de recursos (por exemplo, 1–63 caracteres, letras minúsculas, números e hífenes).
2. Valide o pacote
Verifique se a configuração do pacote é válida:
databricks bundle validate
Se um resumo da configuração do pacote for retornado, a validação foi bem-sucedida. Se algum erro for retornado, corrija-o e repita este passo. Consulte o comando `databricks bundle validate`.
3. implantar o feixe
Implante o projeto Lakebase em seu workspace Databricks :
databricks bundle deploy
Isso cria:
- Um projeto Lakebase chamado "my-app"
- Uma ramificação de produção default com um endpoint de leitura e gravação (criada automaticamente).
- Uma ramificação de desenvolvimento chamada "dev"
- Um endpoint primário para a branch de desenvolvimento com escalonamento automático de 0,5 a 2 CUs.
Veja pacote de databricks implantado.
4. Verifique a implantação
Confirme se os recursos foram criados:
- No seu workspace Databricks , navegue até Lakebase → Projetos .
- Clique em Minha Candidatura .
- Verifique se você vê duas ramificações:
- produção (padrão) - Criado automaticamente com 1 CU computeprimária
- dev - Criado pelo seu pacote com computede escalonamento automático de 0,5 a 2 CUs
5. Atualize a configuração
Para modificar seu recurso, atualize o arquivo databricks.yml e reimplemente:
databricks bundle validate
databricks bundle deploy
O pacote atualizará apenas o recurso que foi alterado.
6. Limpar recurso
Quando terminar de usar o projeto Lakebase, você pode excluí-lo para liberar recursos.
Use databricks bundle destroy para desativar os recursos criados pelo pacote:
databricks bundle destroy
Isso acarreta a exclusão do projeto e de todos os seus branches, endpoints e bancos de dados, além de limpar o estado de implantação do pacote. Por default, o projeto é excluído de forma reversível e retido por 7 dias, após os quais o Lakebase o exclui permanentemente. Você pode recuperar o projeto durante o período de retenção.
Para excluir apenas o projeto imediatamente, sem remover os outros recursos no pacote ou esperar pelo período de retenção, use a CLI do Databricks com --purge:
databricks postgres delete-project projects/my-app --purge
--purge exclui o projeto permanentemente imediatamente em vez de excluí-lo de forma reversível. Excluir o projeto desta forma não atualiza o estado de implantação do pacote.
A criação de um novo projeto com o mesmo project_id que um projeto excluído temporariamente durante o período de retenção de 7 dias falha. Para reutilizar o mesmo ID de projeto, recupere o projeto existente primeiro, force uma exclusão permanente com --purge ou aguarde o término do período de retenção.
Para recuperar um projeto excluído temporariamente antes que o período de retenção de 7 dias expire, use a CLI ou a API.
Para evitar a exclusão acidental de um projeto de produção, adicione um bloco lifecycle ao recurso postgres_projects em seu pacote:
resources:
postgres_projects:
my_app:
project_id: 'my-app'
lifecycle:
prevent_destroy: true
Isso faz com que as operações de pacote falhem com um erro se tentarem destruir o recurso. Remova prevent_destroy: true quando você intencionalmente quiser excluir o projeto.
substituições de recurso
A configuração do pacote usa substituições para referenciar o recurso:
${resources.postgres_projects.my_app.id}- Faz referência ao nome do recurso do projeto Lakebase${resources.postgres_branches.dev_branch.id}- Faz referência ao nome do recurso da ramificação
Isso garante a ordenação correta das dependências durante a implantação. Para obter mais informações sobre substituições de pacotes, consulte Substituições.
Recurso disponível
Para a lista completa de recursos do Lakebase suportados em pacotes e suas opções de configuração, consulte recursos de pacote (postgres_projects, postgres_branches, postgres_endpoints, postgres_catalogs, postgres_synced_tables, postgres_roles, postgres_databases).
gerenciar permissões do projeto
Os projetos do Lakebase oferecem suporte aos níveis de permissão CAN_CREATE, CAN_USE e CAN_MANAGE. Todos os usuários do workspace têm CAN_CREATE por default, assim, você atribui apenas CAN_USE ou CAN_MANAGE em um pacote. Para obter detalhes sobre cada nível, consulte ACLs de projeto do Lakebase.
Declare as permissões do projeto usando o campo permissions em um recurso postgres_projects. Cada entrada concede um nível de permissão a um usuário, grupo ou entidade de serviço:
postgres_projects:
my_project:
project_id: my-project
permissions:
- service_principal_name: <sp-application-id>
level: CAN_MANAGE
Você também pode gerenciar permissões separadamente usando a API de permissões, CLI ou SDK.