Limites de pastas do Git no Azure Databricks e referência

Esta página aborda limites de tamanho, recursos com suporte, considerações de segurança e comportamento de CI/CD para pastas Git do Databricks. Para obter limites gerais de recursos do Databricks, consulte os limites de recursos. Para saber mais sobre os tipos de ativos com suporte em pastas Git, consulte tipos de ativo com suporte em pastas Git.

Limites de arquivos e repositórios

Azure Databricks não impõe um limite no tamanho do repositório. No entanto, os seguintes limites se aplicam:

  • As ramificações de trabalho são limitadas a 1 GB.
  • Não é possível exibir arquivos com mais de 10 MB na interface do usuário do Azure Databricks.
  • Cada operação git dá suporte a até 2 GB de memória e 4 GB de gravações de disco.
  • Arquivos de workspace individuais têm limites de tamanho separados. Confira Limitações.

O Databricks recomenda manter o número total de ativos e arquivos do workspace abaixo de 20.000.

Como os limites se aplicam por operação, a clonagem de um repositório de 5 GB falha, mas a clonagem de um repositório de 3 GB e, posteriormente, a adição de 2 GB é bem-sucedida. Se o repositório exceder esses limites, você poderá receber um erro ou um tempo limite durante a clonagem, embora a operação ainda possa ser concluída em segundo plano.

Para trabalhar com repositórios maiores, experimente sparse checkout ou comandos do Git CLI. Para gravar arquivos temporários que não persistem após o desligamento do cluster, use $TEMPDIR. Isso evita exceder os limites de tamanho do branch e oferece melhor desempenho do que gravar em um CWD (diretório de trabalho) no sistema de arquivos do workspace. Consulte Onde devo escrever arquivos temporários no Azure Databricks?.

As ramificações locais podem permanecer na pasta Git associada por até 30 dias após a exclusão do branch remoto. Para remover completamente um branch local, exclua o repositório.

Reduzir o tamanho do repositório

Se o repositório exceder os limites de tamanho devido a arquivos grandes, adicioná-los .gitignore não reduzirá o tamanho do repositório. Os arquivos já confirmados no Git permanecem no histórico do repositório mesmo quando adicionados a .gitignore.

Para reduzir o tamanho do repositório:

  • Use ferramentas git como git filter-repo ou BFG Repo-Cleaner para remover arquivos grandes do histórico de confirmação. Isso reescreve o histórico e requer o envio forçado para seu repositório remoto.
  • Clone apenas diretórios específicos. Consulte a seção Configurar o modo de check-out esparso.
  • Mover código não relacionado para repositórios separados.

Para obter mais informações, consulte Ressocimento de dados confidenciais de um repositório na documentação do GitHub.

Suporte ao Monorepo

O Databricks recomenda não criar pastas Git apoiadas por monorepos — repositórios Git grandes e de organização única com milhares de arquivos em muitos projetos. Clonar um monorepo pode exceder os limites de memória e disco do Git e desacelerar as operações do Git. Se o repositório contiver vários projetos, considere separá-lo ou usar o checkout esparso para limitar quais diretórios são clonados. Consulte a seção Configurar o modo de check-out esparso.

Configuração

Nem todos os recursos padrão do Git funcionam em pastas Git e o conteúdo é armazenado de forma diferente do que em um clone local. Os tópicos a seguir explicam como o armazenamento funciona, quais servidores têm suporte e como recursos como .gitignore e submódulos se comportam.

Armazenamento de conteúdo do repositório

Azure Databricks clona temporariamente o conteúdo do repositório para o disco no plano de controle. O banco de dados do plano de controle armazena arquivos de notebook como aqueles no workspace principal. Os arquivos que não são de notebook são armazenados em disco por até 30 dias.

Servidores Git locais e auto-hospedados

As pastas Git do Databricks dão suporte a GitHub Enterprise, Bitbucket Server, Azure DevOps Server e GitLab Autogerenciados se o servidor estiver acessível à Internet. Consulte o Servidor proxy do Git para pastas Git para integração no local.

Para integrar com um Servidor bitbucket, GitHub Enterprise Server ou instância autogerenciada do GitLab que não seja acessível à Internet, entre em contato com sua equipe de conta Azure Databricks.

Tipos de ativos com suporte

Para obter detalhes sobre tipos de ativos com suporte, consulte tipos de ativo com suporte em pastas git.

Suporte ao arquivo .gitignore

As pastas Git suportam .gitignore arquivos. Para impedir que o Git rastreie um arquivo, adicione o nome do arquivo (incluindo a extensão) a um .gitignore arquivo. Crie um ou use um arquivo existente clonado do repositório remoto.

.gitignore funciona apenas para arquivos não rastreados. Adicionar a .gitignore um arquivo já confirmado não o remove do histórico do Git nem reduz o tamanho do repositório. Para remover arquivos confirmados, consulte Reduzir o tamanho do repositório.

Suporte a submódulo do Git

As pastas Git Padrão não dão suporte a submódulos git, mas pastas Git com acesso à CLI do Git podem usá-las. Consulte Usar comandos da CLI do Git (Beta).

Suporte do Azure Data Factory

Azure Data Factory (ADF) dá suporte a pastas Git.

Gerenciamento de fonte

Algumas operações funcionam de forma diferente em pastas Git do que em um fluxo de trabalho Git padrão, especialmente em relação a notebooks e exclusão de ramos.

Dashboards de notebooks e mudanças de branch

Azure Databricks blocos de anotações no formato de origem não armazenam informações do painel.

Para preservar dashboards, altere o formato do notebook para .ipynb (formato Jupyter), que oferece suporte a definições de painel e visualização automaticamente. Para preservar dados de visualização, submeta o notebook com resultados.

Consulte Gerenciar confirmações de saída do notebook IPYNB.

Suporte à mesclagem de branch

As pastas do Git dão suporte à mesclagem de branches. Você também pode criar uma solicitação pull e mesclar através do seu provedor Git.

Excluindo branches

Para excluir uma ramificação, você deve trabalhar em seu provedor do Git.

Precedência de dependência em Python

Bibliotecas de Python em uma pasta do Git têm precedência sobre bibliotecas armazenadas em outro lugar. Por exemplo, se uma biblioteca estiver instalada em sua computação do Databricks e existir uma biblioteca com o mesmo nome em uma pasta Git, a biblioteca de pastas git será importada. Consulte precedência da biblioteca de Python.

Segurança, autenticação e tokens

Azure Databricks armazena as credenciais do Git no plano de controle, não em seu ambiente local. Os tópicos a seguir abordam como o conteúdo da pasta Git é criptografado, como os tokens são armazenados e auditados e o que fazer se você encontrar problemas de autenticação.

Problema com uma política de acesso condicional (CAP) para Microsoft Entra ID

Você poderá receber um erro de "acesso negado" ao clonar um repositório se:

  • Seu workspace Azure Databricks usa Azure DevOps com autenticação Microsoft Entra ID.
  • Você habilitou uma política de acesso condicional em Azure DevOps e uma política de acesso condicional Microsoft Entra ID.

Para resolver isso, adicione uma exclusão à política de acesso condicional (CAP) para endereços IP ou usuários do Azure Databricks.

Para obter mais informações, confira Políticas de acesso condicional.

Lista de Permissão com tokens do Microsoft Entra ID

Se você usar Microsoft Entra ID para autenticar com Azure DevOps, a lista de permissões padrão restringirá as URLs do Git a:

  • dev.azure.com
  • visualstudio.com

Para obter mais informações, consulte listas de permissões de URL do Git.

Criptografia de pasta do Git

Azure Databricks criptografa o conteúdo da pasta Git usando uma chave padrão. As chaves gerenciadas pelo cliente só têm suporte para criptografar credenciais do Git.

Armazenamento e acesso de tokens do GitHub

  • O plano de controle Azure Databricks armazena tokens de autenticação. Os funcionários só podem acessá-los por meio de credenciais temporárias auditadas.
  • Azure Databricks registra a criação e exclusão de tokens, mas não monitora seu uso. O log de operações do Git permite auditar o uso do token pelo aplicativo Azure Databricks.
  • GitHub Enterprise audita o uso do token. Outros serviços Git também podem oferecer auditoria de servidor.

Assinatura de confirmação do GPG

As pastas git não dão suporte à assinatura de commits por GPG.

Suporte a SSH

As pastas Git dão suporte apenas a HTTPS, não ao SSH.

Azure DevOps erros de locação cruzada

Ao se conectar ao DevOps em um locatário separado, você poderá ver Unable to parse credentials from Azure Active Directory account. Se o projeto de Azure DevOps estiver em um locatário Microsoft Entra ID diferente do Azure Databricks, use um token de acesso Azure DevOps. Consulte o token de acesso pessoal.

CI/CD e MLOps

Se você executar trabalhos em arquivos em uma pasta Git, esteja ciente de como as operações do Git podem afetar o estado do notebook e os experimentos do MLflow de maneiras que podem não ser óbvias.

As alterações de entrada apagam o estado do notebook

As operações do Git que alteram o código-fonte do notebook resultam na perda do estado do notebook, incluindo saídas das células, comentários, histórico de versão e widgets. Por exemplo, git pull pode alterar o código-fonte do notebook, exigindo que os repositórios Git sobrescrevam o notebook existente. Operações como git commit, pushou criar um novo branch, não afetam o código-fonte e preservam o estado do notebook.

Importante

Os experimentos do MLflow não funcionam em pastas Git com o Databricks Runtime 14.x ou anterior.

Experimentos do MLflow em pastas Git

Existem dois tipos de experimentos do MLflow: workspace e notebook. Confira Organizar execuções de treinamento com experimentos do MLflow.

  • Experimentos do workspace: você não pode criar experimentos do MLflow do workspace em pastas Git. O MLflow de log é executado em um experimento criado em uma pasta de workspace regular. Para colaboração com vários usuários, use uma pasta de workspace compartilhada.

  • Experimentos de notebook: você pode criar experimentos de notebook em uma pasta Git do Databricks. Se você verificar seu notebook no controle do código-fonte como um .ipynb arquivo, o MLflow executará o log em um experimento criado automaticamente. O controle do código-fonte não inclui o experimento ou suas execuções. Consulte Criar experimento de bloco de anotações.

Evitar a perda de dados em experimentos do MLflow

Os experimentos de MLflow do notebook criados usando Trabalhos do Lakeflow com código-fonte em um repositório remoto são armazenados no armazenamento temporário. Esses experimentos persistem inicialmente após a execução do fluxo de trabalho, mas correm o risco de exclusão durante a limpeza agendada. O Databricks recomenda o uso de experimentos do MLflow no workspace com os trabalhos e as fontes remotas do Git.

Aviso

Alternar para um ramo que não contém o notebook pode resultar na perda dos dados de experimento do MLflow associados. Essa perda se tornará permanente se você não visitar a ramificação anterior dentro de 30 dias.

Para recuperar dados de experimento ausentes antes da expiração de 30 dias, restaure o nome original do bloco de anotações, abra o bloco de anotações e clique no ícone Experimento no painel direito. Isso aciona mlflow.get_experiment_by_name(), recupera o experimento e executa o teste. Após 30 dias, Azure Databricks limpa experimentos órfãos do MLflow para conformidade com o RGPD.

Para evitar a perda de dados, evite renomear notebooks em um repositório. Se você renomear um bloco de anotações, clique imediatamente no ícone de experimento no painel direito.

Executando trabalhos durante operações do Git

Durante uma operação git, alguns notebooks podem ser atualizados enquanto outros ainda não estão, causando um comportamento imprevisível.

Por exemplo, se notebook A chama notebook Z usando %run e um trabalho for iniciado durante uma operação Git, o trabalho poderá executar o mais recente notebook A com o mais antigo notebook Z. O trabalho pode falhar ou executar notebooks de commits diferentes.

Para evitar isso, configure tarefas de trabalho para usar seu provedor Git como a origem em vez de um caminho de workspace. Consulte Usar o Git com Trabalhos do Lakeflow.

Próximas Etapas 

  • Last updated on