Entidades de serviço de CI/CD

  • Artigo

Este artigo descreve como usar entidades de serviço para CI/CD com o Azure Databricks. Uma entidade de serviço é uma identidade criada para uso com ferramentas e aplicativos automatizados, incluindo:

Como melhor prática de segurança, o Databricks recomenda o uso de uma entidade de serviço e seu respectivo token em vez do usuário ou do token de acesso pessoal do Databricks para o usuário do workspace a fim de permitir o acesso das plataformas de CI/CD aos recursos do Azure Databricks. Alguns benefícios dessa abordagem incluem:

  • Você pode permitir e restringir o acesso aos recursos do Azure Databricks para uma entidade de serviço independentemente de um usuário. Por exemplo, isso permite que você proíba uma entidade de serviço de atuar como administrador no workspace do Azure Databricks enquanto ainda permite que outros usuários específicos no workspace continuem a atuar como administradores.
  • Os usuários podem proteger os tokens de acesso contra o acesso de plataformas de CI/CD.
  • Você pode desabilitar temporariamente ou excluir permanentemente uma entidade de serviço sem afetar outros usuários. Por exemplo, isso permite que você pause ou remova o acesso de uma entidade de serviço com suspeita de uso mal-intencionado.
  • Se um usuário sair da organização, você poderá removê-lo sem afetar nenhuma entidade de serviço.

Para conceder a uma plataforma de CI/CD acesso ao workspace do Azure Databricks, faça o seguinte:

Escolha um dos seguintes mecanismos de autenticação do MS Entra com suporte com uma conexão de serviço:

Requisitos

  • O token OAuth do Azure Databricks ou o token do Microsoft Entra ID para uma entidade de serviço gerenciada do Azure Databricks ou uma entidade de serviço gerenciada do Microsoft Entra ID. Para criar uma entidade de serviço gerenciada do Azure Databricks ou a entidade de serviço gerenciada do Microsoft Entra ID e seu token OAuth do Azure Databricks ou o token do Microsoft Entra ID, confira Gerenciar entidades de serviço.
  • Uma conta com seu provedor Git.

Configurar o GitHub Actions

O GitHub Actions precisa poder acessar o workspace do Azure Databricks. Se você quiser usar as pastas Git do Azure Databricks, o workspace também precisará acessar o GitHub.

Para permitir que o GitHub Actions acesse seu workspace do Azure Databricks, você deve fornecer informações sobre sua entidade de serviço gerenciada do Azure Databricks ou a entidade de serviço gerenciada do Microsoft Entra ID para o GitHub Actions. Isso pode incluir informações como a ID do aplicativo (cliente), a ID do diretório (locatário) de uma entidade de serviço gerenciada do Microsoft Entra ID, a entidade de serviço gerenciada do Azure Databricks ou o segredo do cliente da entidade de serviço gerenciada do Microsoft Entra ID ou o valor access_token de uma entidade de serviço gerenciada do Azure Databricks, dependendo dos requisitos da ação do GitHub. Para obter mais informações, confira Gerenciar entidades de serviço e a documentação do GitHub Actions.

Caso você também deseje permitir que o workspace do Azure Databricks acesse o GitHub ao usar as pastas Git do Azure Databricks, adicione o token de acesso pessoal do GitHub de um usuário do computador do GitHub ao workspace.

Fornecer informações sobre sua entidade de serviço ao GitHub Actions

Esta seção descreve como permitir que o GitHub Actions acesse seu workspace do Azure Databricks.

Como melhor prática de segurança, o Databricks recomenda que você não insira informações sobre sua entidade de serviço diretamente no corpo de um arquivo do GitHub Actions. Você deve fornecer essas informações ao GitHub Actions usando segredos criptografados do GitHub.

O GitHub Actions, como os que o Databricks lista em Integração e entrega contínuas usando o GitHub Actions, depende de vários segredos criptografados do GitHub, como:

  • DATABRICKS_HOST, que é o valor https:// seguido pelo nome da instância do workspace, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • AZURE_CREDENTIALS, que é um documento JSON que representa a saída da executar da CLI do Azure para obter informações sobre uma entidade de serviço gerenciada do Microsoft Entra ID. Para obter mais informações, confira a documentação da Ação do GitHub.
  • AZURE_SP_APPLICATION_ID, que é o valor do ID do Aplicativo (cliente) para uma entidade de serviço gerenciada do Microsoft Entra ID.
  • AZURE_SP_TENANT_ID, que é o valor do ID do Diretório (locatário) para uma entidade de serviço gerenciado Microsoft Entra ID.
  • AZURE_SP_CLIENT_SECRET, que é o valor do Valor do segredo do cliente para uma entidade de serviço gerenciada do Microsoft Entra ID.

Para obter mais informações sobre quais segredos criptografados do GitHub são necessários para uma Ação do GitHub, confira Gerenciar entidades de serviço e a documentação dessa Ação do GitHub.

Para adicionar esses segredos criptografados do GitHub ao repositório do GitHub, confira Como criar segredos criptografados para um repositório na documentação do GitHub. Se quiser obter outras abordagens para adicionar esses segredos do repositório do GitHub, confira Segredos criptografados na documentação do GitHub.

Adicionar o token de acesso pessoal do GitHub de um usuário do computador do GitHub ao workspace do Azure Databricks

Esta seção descreve como habilitar seu workspace do Azure Databricks para acessar o GitHub com as pastas Git do Azure Databricks. Essa é uma tarefa opcional em cenários de CI/CD.

Como melhor prática de segurança, o Databricks recomenda que você use usuários de computador do GitHub em vez de contas pessoais do GitHub, por muitos dos mesmos motivos pelos quais você deve usar uma entidade de serviço em vez de um usuário do Azure Databricks. Para adicionar o token de acesso pessoal do GitHub de um usuário do computador do GitHub ao workspace do Azure Databricks, faça o seguinte:

  1. Crie um usuário do computador do GitHub, se você ainda não tiver um disponível. Um usuário do computador do GitHub é uma conta pessoal do GitHub, separada da sua conta pessoal do GitHub, que você pode usar para automatizar a atividade no GitHub. Crie uma conta do GitHub separada para usar como um usuário do computador do GitHub, se você ainda não tiver uma disponível.

    Observação

    Ao criar uma conta do GitHub separada como um usuário do computador do GitHub, você não pode associá-la ao endereço de email da sua conta pessoal do GitHub. Nesse caso, pergunte ao administrador de email da organização como obter um endereço de email separado que você possa associar a essa nova conta do GitHub separada como um usuário do computador do GitHub.

    Pergunte ao administrador da conta da organização como gerenciar o endereço de email separado, o usuário do computador do GitHub associado e os tokens de acesso pessoal do GitHub na organização.

  2. Forneça ao usuário do computador do GitHub o acesso ao repositório do GitHub. Confira Convidar uma equipe ou uma pessoa na documentação do GitHub. Para aceitar o convite, primeiro você precisa sair da sua conta pessoal do GitHub e depois entrar novamente como o usuário do computador do GitHub.

  3. Entre no GitHub como o usuário do computador e crie um token de acesso pessoal do GitHub para o usuário do computador. Confira Criar um token de acesso pessoal na documentação do GitHub. Permita que o token de acesso pessoal acesse o repositório do GitHub.

  4. Reúna o token do Microsoft Entra ID para sua entidade de serviço, o nome de usuário do computador do GitHub e, em seguida, Adicione as credenciais do provedor Git a um workspace do Azure Databricks.

Configurar o Azure Pipelines

O Azure Pipelines precisa poder acessar o workspace do Azure Databricks. Se você também quiser usar as pastas Git do Azure Databricks, o workspace precisará conseguir acessar o Azure Pipelines.

Os arquivos do pipeline YAML do Azure Pipelines dependem de variáveis de ambiente para acessar seu workspace do Azure Databricks. Essas variáveis de ambiente incluem as seguintes:

  • DATABRICKS_HOST, que é o valor https:// seguido pelo nome da instância do workspace, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • DATABRICKS_TOKEN, que é o valor do valor token_value que você copiou após a criação do token do Microsoft Entra ID para a entidade de serviço gerenciada do Microsoft Entra ID.

Para adicionar essas variáveis de ambiente ao pipeline do Azure, confira Usar segredos do Azure Key Vault no Azure Pipelines e Definir variáveis secretas na documentação do Azure.

Consulte também o seguinte blog do Databricks:

Opcional para cenários de CI/CD: se o workspace usar as pastas Git do Azure Databricks e você quiser habilitar o workspace para acessar o Azure Pipelines, reúna:

  • O token do Microsoft Entra ID para sua entidade de serviço
  • Seu nome de usuário do Azure Pipelines

Em seguida, Adicionar credenciais de provedor Git a um workspace do Azure Databricks.

Configurar a CI/CD do GitLab

A CI/CD do GitLab precisa poder acessar o workspace do Azure Databricks. Caso você também deseje usar as pastas Git do Azure Databricks, o workspace precisará conseguir acessar a CI/CD do GitLab.

Para acessar seu workspace do Azure Databricks, os arquivos .gitlab-ci.yml da CI/CD do GitLab, como o que faz parte do Modelo Básico do Python em dbx, use variáveis personalizadas de CI/CD, como:

  • DATABRICKS_HOST, que é o valor https:// seguido pelo nome da instância do workspace, por exemplo adb-1234567890123456.7.azuredatabricks.net.
  • DATABRICKS_TOKEN, que é o valor do token_value que você copiou depois de criar o token do Microsoft Entra ID para a entidade de serviço.

Para adicionar essas variáveis personalizadas ao seu projeto de CI/CD do GitLab, consulte Adicionar uma variável de CI/CD a um projeto na documentação de CI/CD do GitLab.

Se o seu workspace usar as pastas Git do Databricks e você quiser habilitá-lo para acessar o CI/CD do GitLab, reúna:

  • O token do Microsoft Entra ID para sua entidade de serviço
  • Seu nome de usuário de CI/CD do GitLab

Em seguida, Adicionar credenciais de provedor Git a um workspace do Azure Databricks.

Adicionar credenciais de provedor Git a um workspace do Azure Databricks

Esta seção descreve como habilitar seu workspace do Azure Databricks para acessar o provedor Git com as pastas Git do Azure Databricks. Isso é opcional em cenários de CI/CD. Por exemplo, talvez você queira apenas que o provedor Git acesse seu workspace do Azure Databricks, mas não queira usar as pastas Git do Azure Databricks no workspace com o provedor Git. Se for esse o caso, ignore esta seção.

Antes de começar, reúna as seguintes informações e ferramentas:

  • O token do Microsoft Entra ID para sua entidade de serviço.
  • O nome de usuário associado ao seu provedor Git.
  • O token de acesso associado ao usuário para seu provedor Git.

Observação

Para o Azure Pipelines, consulte Usar tokens de acesso pessoal no site do Azure.

  • CLI do Databricks versão 0.205 ou superior. Consulte O que é a CLI do Databricks?. Você não pode usar a interface do usuário do Azure Databricks.
  • Um perfil de configuração do Azure Databricks no seu arquivo .databrickscfg, com os campos do perfil configurados corretamente para o host relacionado representando o URL por workspace do seu Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net, e token representando o token do Microsoft Entra ID para a sua entidade de serviço. (Não use o token de acesso pessoal do Databricks para o usuário do seu workspace.) Confira Autenticação de token de acesso pessoal do Azure Databricks.

Use a CLI do Databricks para executar o comando a seguir:

databricks git-credentials create <git-provider-short-name> --git-username <git-provider-user-name> --personal-access-token <git-provider-access-token> -p <profile-name>
  • Use um dos seguintes como <git-provider-short-name>:
    • Para o GitHub, use GitHub.
    • Para o Azure Pipelines, use AzureDevOpsServices.
    • Para a CI/CD do GitLab, use GitLab.
  • Substitua <git-provider-user-name> pelo nome de usuário associado ao seu provedor de Git.
  • Substitua <git-provider-access-token> pelo token de acesso associado ao usuário para o seu provedor de Git.
  • Substitua <profile-name> pelo nome do perfil de configuração do Azure Databricks no seu arquivo .databrickscfg.

Dica

Para confirmar se a chamada foi bem-sucedida, você pode executar um dos seguintes comandos da CLI do Databricks e revisar a saída:

databricks git-credentials list -p <profile-name>

databricks git-credentials get <credential-id> -p <profile-name>