Terraform CDK Databricks 提供程序

注意

本文介绍了 Databricks 既不提供也不支持的适用于 Terraform 的云开发工具包 (CDKTF)。 若要联系提供商,请参阅 Terraform 社区

本文介绍如何使用 Python 以及 Terraform CDK Databricks 提供程序适用于 Terraform 的云开发工具包 (CDKTF)。 CDKTF 是一个第三方基础结构即代码 (IaC) 平台,使你能够通过使用熟悉的编程语言、工具和工程实践来创建、部署和管理 Azure Databricks 资源。 虽然本文介绍的是如何使用 Python,但 CDKTF 还支持 TypeScript、Java、C# 和 Go 等语言。

Terraform CDK Databricks 提供程序基于 Databricks Terraform 提供程序。 有关详细信息,请参阅 Terraform 云。 CDKTF 基于 AWS 云开发工具包 (AWS CDK)

要求

必须具有 Azure Databricks 工作区,因为本文会将资源部署到现有工作区中。

在本地开发计算机上,必须安装以下组件:

  • Terraform,1.1 版或更高版本。 若要检查是否已安装 Terraform,并检查安装的版本,请从终端或通过 PowerShell 运行命令 terraform -v安装 Terraform(如果尚未安装)。

    terraform -v
    
  • Node.js,16.13 版或更高版本,以及 npm。 若要检查是否已安装 Node.js 和 npm,并检查安装的版本,请运行命令 node -vnpm -v。 Node.js 的最新版本已包含 npm使用节点版本管理器 (nvm) 安装 Node.js 和 npm(如果尚未安装 Node.js 和 npm)。

    node -v
    npm -v
    
  • CDKTF CLI。 若要检查是否已安装 CDKTF CLI,并检查安装的版本,请运行命令 cdktf --version使用 npm 安装 CDKTF CLI(如果尚未安装)。

    cdktf --version
    

    提示

    还可以使用 Homebrew 在 macOS 上安装 CDKTF CLI。 请参阅安装 CDKTF

  • Python 版本 3.7 或更高版本以及 pipenv 版本 2021.5.29 或更高版本。 若要检查是否已安装 Python 和 pipenv,并检查安装的版本,请运行命令 python --versionpipenv --version安装 Python安装 pipenv(如果尚未安装)。

    python --version
    pipenv --version
    
  • 为要使用的受支持身份验证类型配置 Azure Databricks 身份验证。 请参阅 Databricks Terraform 提供程序文档中的身份验证

步骤 1:创建 CDKTF 项目

在此步骤中,将在本地开发计算机上为 CDKTF 项目设置必要的目录结构。 然后在此目录结构中创建 CDKTF 项目。

  1. 为 CDKTF 项目创建一个空目录,然后切换到该目录。 在终端或通过 PowerShell 运行以下命令:

    Unix、linux 和 macOS

    mkdir cdktf-demo
    cd cdktf-demo
    

    Windows

    md cdktf-demo
    cd cdktf-demo
    
  2. 运行以下命令创建 CDKTF 项目:

    cdktf init --template=python --local
    
  3. 提示输入“项目名称”时,通过按 Enter 接受 cdktf-demo 的默认项目名称。

  4. 提示输入“项目描述”时,通过按 Enter 接受默认项目描述。

  5. 如果提示“是否要从现有的 Terraform 项目开始”,请输入 N 并按 Enter。

  6. 如果提示“是否要将故障报告发送给 CDKTF 团队”,请输入 n 并按 Enter。

CDKTF 在 cdktf-demo 目录中创建了以下文件和子目录:

  • .gitignore,它是文件和目录列表,如果要将此项目推送到远程 Git 存储库中,Git 会忽略这些文件和目录。
  • cdktf.json,它包含 CDKTF 项目的配置设置。 有关配置设置的详细信息,请参阅配置文件
  • help,它包含可以采取的使用 CDKTF 项目的后续步骤相关信息。
  • main-test.py,它包含可为 CDKTF 项目编写的支持单元测试。 有关单元测试的详细信息,请参阅单元测试
  • main.py,它包含为 CDKTF 项目编写的 Python 代码。
  • PipfilePipfile.lock,它们管理 CDKTF 项目的代码依赖项。

步骤 2:定义资源

在此步骤中,将使用 Terraform CDK Databricks 提供程序定义笔记本和运行该笔记本的作业。

  1. 安装项目依赖项:使用 pipenv,将 Terraform CDK Databricks 提供程序安装到 CDKTF 项目中,以生成 Azure Databricks 资源。 为此,请运行以下内容:

    pipenv install cdktf-cdktf-provider-databricks
    
  2. main.py 文件的内容替换为以下代码。 此代码使用 Azure Databricks 工作区对 CDKTF 进行身份验证,然后生成笔记本以及运行该笔记本的作业。 若要查看此代码的语法文档,请参阅适用于 PythonTerraform CDK Databricks 提供程序构造参考

    #!/usr/bin/env python
    from constructs import Construct
    from cdktf import (
      App, TerraformStack, TerraformOutput
    )
    from cdktf_cdktf_provider_databricks import (
      data_databricks_current_user,
      job, notebook, provider
    )
    import vars
    from base64 import b64encode
    
    class MyStack(TerraformStack):
      def __init__(self, scope: Construct, ns: str):
        super().__init__(scope, ns)
    
        provider.DatabricksProvider(
          scope = self,
          id    = "databricksAuth"
        )
    
        current_user = data_databricks_current_user.DataDatabricksCurrentUser(
          scope     = self,
          id_       = "currentUser"
        )
    
        # Define the notebook.
        my_notebook = notebook.Notebook(
          scope          = self,
          id_            = "notebook",
          path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
          language       = "PYTHON",
          content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
        )
    
        # Define the job to run the notebook.
        my_job = job.Job(
          scope = self,
          id_ = "job",
          name = f"{vars.resource_prefix}-job",
          task = [ 
            job.JobTask(
              task_key = f"{vars.resource_prefix}-task",
              new_cluster = job.JobTaskNewCluster(
                num_workers   = vars.num_workers,
                spark_version = vars.spark_version,
                node_type_id  = vars.node_type_id
              ),
              notebook_task = job.JobTaskNotebookTask(
                notebook_path = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py"
              ),
              email_notifications = job.JobTaskEmailNotifications(
                on_success = [ current_user.user_name ],
                on_failure = [ current_user.user_name ]
              )
            )
          ]
        )
    
        # Output the notebook and job URLs.
        TerraformOutput(
          scope = self,
          id    = "Notebook URL",
          value = my_notebook.url
        )
    
        TerraformOutput(
          scope = self,
          id    = "Job URL",
          value = my_job.url
        )
    
    app = App()
    MyStack(app, "cdktf-demo")
    app.synth()
    
  3. main.py 所在的目录中创建一个名为 vars.py 的文件。 将以下值替换为你自己的值,以指定资源前缀和群集设置,例如辅助角色数Spark 运行时版本字符串节点类型

    #!/usr/bin/env python
    resource_prefix = "cdktf-demo"
    num_workers     = 1
    spark_version   = "14.3.x-scala2.12"
    node_type_id    = "Standard_D3_v2"
    

步骤 3:部署资源

在此步骤中,将使用 CDKTF CLI 将定义的笔记本和运行该笔记本的作业部署到现有的 Azure Databricks 工作区中。

  1. 生成 CDKTF 项目的等效 Terraform 代码。 为此,请运行 cdktf synth 命令。

    cdktf synth
    
  2. 在进行更改之前,可以查看挂起的资源更改。 运行以下内容:

    cdktf diff
    
  3. 通过运行 cdktf deploy 命令部署笔记本和作业。

    cdktf deploy
    
  4. 当提示批准时,按 Enter。 Terraform 将创建笔记本和作业并将其部署到工作区中。

步骤 4:与资源交互

在此步骤中,将在运行指定笔记本的 Azure Databricks 工作区中运行作业。

  1. 若要查看作业将在工作区中运行的笔记本,请复制 cdk deploy 命令输出中显示的“笔记本 URL”链接,并将其粘贴到 Web 浏览器的地址栏中。
  2. 若要查看在工作区中运行笔记本的作业,请复制 cdk deploy 命令输出中显示的“作业 URL”链接,并将其粘贴到 Web 浏览器的地址栏中。
  3. 若要运行作业,请单击作业页上的“立即运行”按钮。

(可选)步骤 5:对资源进行更改

在此可选步骤中,将更改笔记本的代码、重新部署已更改的笔记本,然后使用作业重新运行已更改的笔记本。

如果不想对笔记本进行任何更改,请跳到步骤 6:清理

  1. main.py 文件中,更改以下内容中的 notebook 变量声明:

    my_notebook = notebook.Notebook(
      scope          = self,
      id_            = "notebook",
      path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
      language       = "PYTHON",
      content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
    )
    

    更改为以下内容:

    my_notebook = notebook.Notebook(
      scope          = self,
      id_            = "notebook",
      path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
      language       = "PYTHON",
      content_base64 = b64encode(b'''
    data = [
       { "Category": 'A', "ID": 1, "Value": 121.44 },
       { "Category": 'B', "ID": 2, "Value": 300.01 },
       { "Category": 'C', "ID": 3, "Value": 10.99 },
       { "Category": 'E', "ID": 4, "Value": 33.87}
    ]
    
    df = spark.createDataFrame(data)
    
    display(df)
    ''').decode("UTF-8")
    )
    

    注意

    请确保三引号 (''') 之间的代码行与代码编辑器的边缘对齐,如下所示。 否则,Terraform 将会在笔记本中插入额外的空格,这可能会导致新的 Python 代码无法运行。

  2. 重新生成 CDKTF 项目的等效 Terraform 代码。 为此,请运行以下内容:

    cdktf synth
    
  3. 在进行更改之前,可以查看挂起的资源更改。 运行以下内容:

    cdktf diff
    
  4. 通过运行 cdktf deploy 命令部署笔记本更改。

    cdktf deploy
    
  5. 当提示批准时,按 Enter。 Terraform 将更改笔记本的内容。

  6. 若要查看作业将在工作区中运行的已更改笔记本,请刷新先前打开的笔记本,或复制 cdk deploy 命令输出中显示的“笔记本 URL”链接,并将其粘贴到 Web 浏览器的地址栏中。

  7. 若要查看在工作区中运行已更改笔记本的作业,请刷新先前打开的作业,或复制 cdk deploy 命令输出中显示的“作业 URL”链接,并将其粘贴到 Web 浏览器的地址栏中。

  8. 若要运行作业,请单击作业页上的“立即运行”按钮。

步骤 6:清理

在此步骤中,将使用 CDKTF CLI 从 Azure Databricks 工作区中删除笔记本和作业。

  1. 通过运行 cdktf destroy 命令从工作区中删除资源:

    cdktf destroy
    
  2. 当提示批准时,按 Enter。 Terraform 将从工作区中删除资源。

测试

你可以在部署 CDKTF 项目之前对其进行测试。 请参阅 CDKTF 文档中的单元测试

对于基于 Python 的 CDKTF 项目,可以使用 Python 测试框架 pytest 以及 cdktf 包的 Testing 类编写和运行测试。 名为 test_main.py 的以下示例文件测试本文中前面的 main.py 文件中的 CDKTF 代码。 第一个测试检查项目的笔记本是否将包含笔记本内容的预期 Base64 编码表示形式。 第二个测试检查项目的作业是否将包含预期的作业名称。 若要运行这些测试,请从项目的根目录运行 pytest 命令。

from cdktf import App, Testing
from cdktf_cdktf_provider_databricks import job, notebook
from main import MyStack

class TestMain:
  app = App()
  stack = MyStack(app, "cdktf-demo")
  synthesized = Testing.synth(stack)

  def test_notebook_should_have_expected_base64_content(self):
    assert Testing.to_have_resource_with_properties(
      received = self.synthesized,
      resource_type = notebook.Notebook.TF_RESOURCE_TYPE,
      properties = {
        "content_base64": "ZGlzcGxheShzcGFyay5yYW5nZSgxMCkp"
      }
    )

  def test_job_should_have_expected_job_name(self):
    assert Testing.to_have_resource_with_properties(
      received = self.synthesized,
      resource_type = job.Job.TF_RESOURCE_TYPE,
      properties = {
        "name": "cdktf-demo-job"
      }
    )

更多资源