用于 CI/CD 的服务主体

项目
05/03/2024

本文介绍如何将 CI/CD 的服务主体与 Azure Databricks 结合使用。服务主体是为与自动化工具和应用程序一起使用而创建的标识，包括：

CI/CD 平台，例如 GitHub Actions、Azure Pipelines 和 GitLab CI/CD
数据管道中的 Airflow
Jenkins

Databricks 建议使用服务主体及其令牌（而不是 Azure Databricks 用户或工作区用户的 Databricks 个人访问令牌）为 CI/CD 平台提供对 Azure Databricks 资源的访问权限，这是安全最佳做法。这种做法的一些好处如下：

可以独立于用户授予和限制服务主体对 Azure Databricks 资源的访问权限。例如，这让你可以禁止服务主体在 Azure Databricks 工作区中充当管理员，同时仍允许工作区中的其他特定用户继续充当管理员。
用户可以保护他们的访问令牌免受 CI/CD 平台访问。
可暂时禁用或永久删除服务主体，而不影响其他用户。例如，这让你可以暂停或删除你怀疑正以恶意方式使用的服务主体的访问权限。
如果某位用户离开组织，你可删除该用户，而不会影响任何服务主体。

要为 CI/CD 平台授予对 Azure Databricks 工作区的访问权限，请执行以下操作：

创建 Azure Databricks 托管服务主体或 Microsoft Entra ID 托管服务主体。
根据 CI/CD 平台支持的访问令牌类型，为 Azure Databricks OAuth 托管服务主体生成 Azure Databricks OAuth 令牌或 Microsoft Entra ID 令牌。有关详细信息，请参阅你的 CI/CD 平台的文档。
将此 Azure Databricks OAuth 令牌或 Microsoft Entra ID 令牌提供给 CI/CD 平台。

若要完成步骤 1 至 2，请参阅管理服务主体。

要完成步骤 3，请完成本文中的说明。

（可选）如果还要在 CI/CD 平台方案中将 Azure Databricks 工作区与 Azure Databricks Git 文件夹配合使用，请参阅将 Git 提供程序凭据添加到 Azure Databricks 工作区。例如，你可能希望 Git 提供程序访问工作区，并且还希望将工作区中的 Azure Databricks Git 文件夹与 Git 提供程序配合使用。但是，无需使用 Azure Databricks Git 文件夹，就能将工作区与 CI/CD 平台配合使用。

要求

Azure Databricks 托管服务主体或 Microsoft Entra ID 托管服务主体的 Azure Databricks OAuth 令牌或 Microsoft Entra ID 令牌。若要创建 Azure Databricks 托管服务主体或 Microsoft Entra ID 托管服务主体及其 Azure Databricks OAuth 令牌或 Microsoft Entra ID 令牌，请参阅管理服务主体。
Git 提供程序的帐户。

设置 GitHub Actions

GitHub Actions 必须能够访问 Azure Databricks 工作区。如果要使用 Azure Databricks Git 文件夹，则工作区还必须能够访问 GitHub。

要使 GitHub Actions 能够访问 Azure Databricks 工作区，必须向 GitHub Actions 提供有关 Azure Databricks 托管服务主体或 Microsoft Entra ID 托管服务主体的信息。这包括以下信息： Microsoft Entra ID 托管服务主体的应用程序（客户端）ID、目录（租户）ID、Azure Databricks 托管服务主体或 Microsoft Entra ID 托管服务主体的客户端密码或 Azure Databricks 托管服务主体的 access_token 值，具体取决于 GitHub Action 的要求。有关详细信息，请参阅管理服务主体和 GitHub Action 的文档。

如果还想要在使用 Azure Databricks Git 文件夹时使 Azure Databricks 工作区能够访问 GitHub，则必须将 GitHub 计算机用户的 GitHub 个人访问令牌添加到工作区。

向 GitHub Actions 提供有关服务主体的信息

本部分介绍如何使 GitHub Actions 能够访问 Azure Databricks 工作区。

作为安全最佳做法，Databricks 建议不要将有关服务主体的信息直接输入到 GitHub Actions 文件的正文中。应改为使用 GitHub 加密机密向 GitHub Actions 提供此信息。

GitHub Actions（例如 Databricks 在使用 GitHub Actions 进行持续集成和交付中列出的那些操作）依赖于各种 GitHub 加密机密，例如：

DATABRICKS_HOST，这是 https:// 值，后跟工作区实例名称，例如 adb-1234567890123456.7.azuredatabricks.net。
AZURE_CREDENTIALS，这是一个 JSON 文档，表示运行 Azure CLI 以获取有关 Microsoft Entra ID 托管服务主体的信息的输出。有关详细信息，请参阅 GitHub Action 的文档。
AZURE_SP_APPLICATION_ID，这是 Microsoft Entra ID 托管服务主体的应用程序(客户端) ID 的值。
AZURE_SP_TENANT_ID，这是 Microsoft Entra ID 托管服务主体的目录(租户) ID 的值。
AZURE_SP_CLIENT_SECRET，这是 Microsoft Entra ID 托管服务主体的客户端机密的值的值。

有关 GitHub Action 需要哪些 GitHub 加密机密的详细信息，请参阅管理服务主体和该 GitHub Action 的文档。

要将这些 GitHub 加密机密添加到 GitHub 存储库，请参阅 GitHub 文档中的为存储库创建加密机密。有关添加这些 GitHub 存储库机密的其他方法，请参阅 GitHub 文档中的加密机密。

将 GitHub 计算机用户的 GitHub 个人访问令牌添加到 Azure Databricks 工作区

本部分介绍如何使 Azure Databricks 工作区能够使用 Azure Databricks Git 文件夹访问 GitHub。这是 CI/CD 方案中的可选任务。

作为一种安全最佳做法，Databricks 建议使用 GitHub 计算机用户（而不是 GitHub 个人帐户），这与你应使用服务主体（而不是 Azure Databricks 用户）的原因差不多。要将 GitHub 计算机用户的 GitHub 个人访问令牌添加到 Azure Databricks 工作区，请执行以下操作：

如果还没有可用的 GitHub 计算机用户，请创建一个。 GitHub 计算机用户是 GitHub 个人帐户（独立于你自己的 GitHub 个人帐户），可使用该账户在 GitHub 上自动执行活动。新建单独的 GitHub 帐户以用作 GitHub 计算机用户（如果还没有可用帐户）。

注意

新建单独的 GitHub 帐户作为 GitHub 计算机用户时，无法将其与你自己的 GitHub 个人帐户的电子邮件地址相关联。请咨询组织的电子邮件管理员，了解如何获取一个单独的电子邮件地址，以将其与这个作为 GitHub 计算机用户的新的单独的 GitHub 帐户关联。

请咨询组织的帐户管理员，了解如何在组织内管理单独的电子邮件地址及其关联的 GitHub 计算机用户和 GitHub 个人访问令牌。
授予 GitHub 计算机用户对 GitHub 存储库的访问权限。请参阅 GitHub 文档中的邀请团队或人员。要接受邀请，可能需要先注销 GitHub 个人帐户，然后以 GitHub 计算机用户身份重新登录。
以计算机用户身份登录 GitHub，然后为该计算机用户创建 GitHub 个人访问令牌。请参阅 GitHub 文档中的创建个人访问令牌。请务必向 GitHub 个人访问令牌授予存储库访问权限。
收集你的服务主体的 Microsoft Entra ID 令牌和你的 GitHub 计算机用户名，然后按照将 Git 提供程序凭据添加到 Azure Databricks 工作区进行操作。

设置 Azure Pipelines

Azure Pipelines 必须能够访问 Azure Databricks 工作区。如果还想使用 Azure Databricks Git 文件夹，则工作区还必须能够访问 Azure Pipelines。

Azure Pipelines YAML 管道文件依赖于环境变量来访问 Azure Databricks 工作区。这些环境变量包括：

DATABRICKS_HOST，这是 https:// 值，后跟工作区实例名称，例如 adb-1234567890123456.7.azuredatabricks.net。
DATABRICKS_TOKEN，这是在为 Microsoft Entra ID 托管服务主体创建 Microsoft Entra ID 令牌后复制的 token_value 值。

要将这些环境变量添加到 Azure 管道，请参阅 Azure 文档中的在 Azure Pipelines 中使用 Azure 键值机密和设置机密变量。

另请参阅以下 Databricks 博客：

使用 Databricks Notebooks 和 Azure DevOps 在 Databricks 上实现 CI/CD

对于 CI/CD 方案可选：如果工作区使用 Azure Databricks Git 文件夹，并且希望使工作区能够访问 Azure Pipelines，请收集：

你的服务主体的 Microsoft Entra ID 令牌
Azure Pipelines 用户名

然后将 Git 提供程序凭据添加到 Azure Databricks 工作区。

设置 GitLab CI/CD

GitLab CI/CD 必须能够访问 Azure Databricks 工作区。如果还想使用 Azure Databricks Git 文件夹，则工作区还必须能够访问 GitLab CI/CD。

若要访问 Azure Databricks 工作区，GitLab CI/CD .gitlab-ci.yml 文件（如 dbx 中的基本 Python 模板中的文件）依赖于自定义 CI/CD 变量，例如：

DATABRICKS_HOST，这是 https:// 值，后跟工作区实例名称，例如 adb-1234567890123456.7.azuredatabricks.net。
DATABRICKS_TOKEN，它是你在为服务主体创建 Microsoft Entra ID 令牌后复制的 token_value 值。

要将这些自定义变量添加到 GitLab CI/CD 项目，请参阅 GitLab CI/CD 文档中的将 CI/CD 变量添加到项目。

如果工作区使用 Databricks Git 文件夹，并且希望使工作区能够访问 GitLab CI/CD，请收集：

你的服务主体的 Microsoft Entra ID 令牌
GitLab CI/CD 用户名

然后将 Git 提供程序凭据添加到 Azure Databricks 工作区。

将 Git 提供程序凭据添加到 Azure Databricks 工作区

本部分介绍如何使 Azure Databricks 工作区能够访问 Azure Databricks Git 文件夹的 Git 提供程序。这在 CI/CD 方案中是可选的。例如，你可能只希望 Git 提供程序访问 Azure Databricks 工作区，但不希望在工作区中将 Azure Databricks Git 文件夹与 Git 提供程序配合使用。如果是，则跳过此部分。

开始之前，请收集以下信息和工具：

你的服务主体的 Microsoft Entra ID 令牌。
与 Git 提供程序关联的用户名。
与 Git 提供程序的用户关联的访问令牌。

注意

对于 Azure Pipelines，请参阅 Azure 网站上的使用个人访问令牌。

Databricks CLI 0.205 或更高版本。请参阅什么是 Databricks CLI？。不能使用 Azure Databricks 用户界面。
.databrickscfg 文件中的 Azure Databricks 配置文件，其中该配置文件的以下相关字段已经过正确设置：用于表示 Azure Databricks 每工作区 URL 的 host（例如 https://adb-1234567890123456.7.azuredatabricks.net），以及用于表示服务主体的 Microsoft Entra ID 令牌的 token。（请勿为工作区用户使用 Databricks 个人访问令牌。）请参阅 Azure Databricks 个人访问令牌身份验证。

使用 Databricks CLI 运行以下命令：

databricks git-credentials create <git-provider-short-name> --git-username <git-provider-user-name> --personal-access-token <git-provider-access-token> -p <profile-name>

为 <git-provider-short-name> 使用下列其中一个：
- 对于 GitHub，请使用 GitHub。
- 对于 Azure Pipelines，请使用 AzureDevOpsServices。
- 对于 GitLab CI/CD，请使用 GitLab。
使用具有与 Git 提供程序关联的用户名替换 <git-provider-user-name>。
使用具有与 Git 提供程序的用户关联的访问令牌替换 <git-provider-access-token>。
使用将 .databrickscfg 文件中 Azure Databricks 配置文件的名称替换 <profile-name>。

提示

若要确认调用成功，可以运行以下 Databricks CLI 命令之一，并查看输出：

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

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